Add mcp endpoint
The code intelligence layer for AI coding agents. Semantic indexing, graph navigation, and repository intelligenceFrom the repository description
npx -y skills add artk0de/TeaRAGs-MCP --skill add-mcp-endpointAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
SKILL.md
10.7 KB, as published. Nobody here has run it
Add MCP Endpoint
Implementation Checklist (MUST complete in order)
- DTO created in
public/dto/<domain>.ts(via add-dto skill) - DTO re-exported via barrel chain:
dto/<domain>.ts→dto/index.ts→public/index.ts→api/index.ts - Work placed per
facade-discipline.mdthree-question tree: strategy (domains/explore/strategies/), query (domains/explore/queries/), ops (api/internal/ops/), or pure facade dispatcher - Facade method ≤ 20 lines (resolve → guard → [ensureStats] → dispatch →
finalize); no inline filter construction, no
Map/reduceaggregation, no indexing-mode branching - Filter building (if any) uses
registry.buildMergedFilter()— not hand-built{ must: [...] }shapes in the facade - Validation >5 lines extracted to named validator function
- App interface method added in
public/app.ts -
createApp()wiring added inpublic/app.ts(delegate to facade/ops/query/strategy) -
AppDepsupdated if new internal class introduced - Zod schema in
mcp/tools/schemas.ts - Tool registered in
mcp/tools/<domain>.ts - If reranking supported: tool name added to preset
tools[]arrays andgetSchemaDescriptorslist - Tests written next to implementation (strategy/query/ops test — not a facade test) and passing
- Docusaurus docs updated (
website/docs/api/tools.md+ relevant pages) -
CLAUDE.local.mdupdated - Build + full test suite passing
🛑 Each row = gate — do NOT proceed to next without finishing current.
Two-phase: define endpoint in core, then expose via MCP.
Phase 1: Core API Layer
1.1 Add DTO
Add request/response types in src/core/api/public/dto/<domain>.ts.
Choose the domain file:
| Domain file | Contains |
|---|---|
dto/explore.ts | Search types (SemanticSearchRequest, ExploreResponse, etc.) |
dto/ingest.ts | Indexing types (IndexOptions, IndexStats, ChangeStats, etc.) |
dto/collection.ts | Collection CRUD types (CreateCollectionRequest, CollectionInfo) |
dto/document.ts | Document add/delete types (AddDocumentsRequest, DeleteDocumentsRequest) |
None fit → create dto/<new-domain>.ts + add re-export to dto/index.ts.
DTO rules:
- Request types end with
Request(e.g.,SemanticSearchRequest) - Response types specific — no generic
Responsesuffix - Extend
CollectionReffor endpoints acceptingcollectionorpath - Extend
TypedFilterParamsfor endpoints with trajectory filters - Pure interfaces only (no classes, no logic)
- Import only from
contracts/orinfra/if needed
Export chain (MANDATORY):
- Type defined in
dto/<domain>.ts - Re-exported from
dto/index.ts(automatic if using existing domain file) - Re-exported through
public/index.ts→api/index.ts - If
contracts/types/app.tsre-exports this domain — add to its re-export list for backward compatibility
1.2 Add method to App interface
In src/core/api/public/app.ts:
-
Import new DTO from
./dto/index.js -
Add method signature to
Appinterface in matching category group, with comment pointing to internal implementation:
// -- <Category> (→ internal/<path>) --
newMethod: (request: NewRequest) => Promise<NewResponse>;
Existing categories: Search, Indexing, Collections, Documents, Schema descriptors, Drift monitoring. Create new category if none fit.
- Wire method in
createApp()in same file — delegate to appropriate internal class:
// In createApp() return object:
newMethod: async (req) => deps.<facade>.newMethod(req),
Method needs new dependency (new facade/ops class) → add to AppDeps interface
in same file, instantiate in createApp().
1.3 Implement in internal
MUST read .claude/rules/facade-discipline.md first. Facades = thin
dispatchers — MUST NEVER contain business logic. Facade method is last thing you
write, not first. Put work in correct class, then add ≤20-line dispatcher to
facade.
Where actual work lives (answer three questions in order; first "yes" wins):
| The method... | → Work goes in | Facade method |
|---|---|---|
| 1. Searches / ranks / scrolls chunks? | new strategy in domains/explore/strategies/ | resolve + guard + executeExplore(strategy, ctx) |
| 2. Aggregates data from Qdrant w/o vec search? | new query in domains/explore/queries/ | resolve + guard + this.<name>Query.run(collection) |
| 3. Mutates / branches indexing or CRUD? | new ops in api/internal/ops/ | resolve + guard + this.<name>Ops.run(...) |
| None of the above (pure forwarding 1-4 lines) | stays in facade as dispatcher | the one-liner itself (e.g. clearIndex) |
Existing ops (CollectionOps, DocumentOps) — MUST extend only if new
method belongs to same responsibility. New CRUD area MUST get new ops class.
MUST NEVER do in the facade (patterns facade-discipline.md explicitly
forbids):
- MUST NEVER inline Qdrant filter construction (
{ must: [...] }) in the facade. - MUST NEVER perform
Map/reduceaggregation in the facade. - MUST NEVER branch on indexing modes with multi-branch
if/elsein the facade. - MUST NEVER call parallel
scrollFilteredwith dedup in the facade. - MUST NEVER resolve presets in the facade.
Filter building (MUST): use
registry.buildMergedFilter(typedParams, rawFilter, level) from facade, pass
result via ExploreContext.filter into strategy. Facade MUST NEVER construct
filter shapes itself.
Validation (MUST): request-shape validation (mutex params, cross-field
rules) up to ~5 lines MAY live inline in facade as guard step. Past that, MUST
extract named validator function (e.g. validateFindByTaskIdRequest) into
api/errors.ts or alongside, and MUST throw typed errors per typed-errors.md.
After placing work, MUST update AppDeps in public/app.ts if new internal
class created, and MUST wire it in createApp().
1.4 Verify core layer
npx tsc --noEmit
npx vitest run tests/core/api/
Phase 2: MCP Tool Registration
2.1 Define Zod schema
In src/mcp/tools/schemas.ts:
For static schemas (no dynamic content from SchemaBuilder):
- Add new exported const (e.g.,
export const NewToolSchema = { ... }) - Use
z.string(),coerceNumber(),coerceBoolean()for params - Every field needs
.describe()with clear description for LLM consumers
For dynamic schemas (need SchemaBuilder for rerank presets/signals):
- Add to
createSearchSchemas()function - Use
schemaBuilder.buildRerankSchema(toolName)for rerank param - Use
typedFilterFields()for standard filters - Use
collectionPathFields()for collection/path resolution - Use
searchCommonFields()for query/limit/filter/pathPattern
Schema conventions:
export const NewToolSchema = {
// Required params first, then optional
requiredParam: z.string().describe("Clear description for AI agents"),
optionalParam: coerceNumber()
.optional()
.describe("Description with default value mention (default: 10)"),
};
2.2 Register the MCP tool
In appropriate src/mcp/tools/<domain>.ts file (explore, code, collection,
document), or create new file if needed:
server.registerTool(
"tool_name", // snake_case, matches MCP convention
{
description: "One-line description for tool discovery",
inputSchema: NewToolSchema,
},
async ({ input }) => {
try {
const result = await app.newMethod(input);
return formatMcpResponse(result); // or formatMcpText()
} catch (error) {
return formatMcpError(error);
}
},
);
Creating new tool file:
- Export
registerNewTools(server, deps)function - Call from
src/mcp/tools/index.tsinregisterAllTools()
2.3 Tool naming rules
- Tool names
snake_case(e.g.,semantic_search,index_codebase) - Match domain: search tools in explore.ts, index tools in code.ts
- Descriptions for AI agents — explicit about when to use tool
2.4 Response formatting
Use existing formatters from src/mcp/format.ts:
| Function | When |
|---|---|
formatMcpResponse(data) | JSON response (search results, collection info) |
formatMcpText(text) | Plain text response |
formatMcpError(error) | Error response |
appendDriftWarning(content, warning) | Add drift warning to response |
sanitizeRerank(input) | Clean rerank param from MCP input |
2.5 Update Docusaurus documentation
Update tools reference page website/docs/api/tools.md:
- Add tool to appropriate section table (Collection Management, Document Operations, Code Vectorization, or create new section)
- Non-trivial parameters → add parameters subsection under
## Search Parametersor new##section
Tool introduces new concept (new rerank preset, new filter type):
- Update relevant pages in
website/docs/usage/(filters.md, query-modes.md, git-enrichments.md) - Update
website/docs/agent-integration/search-strategies/if affects search workflows
Follow docusaurus rules from .claude/rules/documentation.md:
- Use
<MermaidTeaRAGs>for diagrams (not plain mermaid code blocks) - Use
<AiQuery>for example prompts (not blockquotes) - Use correct signal naming (chunk-level vs file-level)
2.6 Update CLAUDE.local.md
Update CLAUDE.local.md with:
- New tool name and description
- Parameters and their types
- Example usage
- Which rerank presets apply (if search tool)
2.7 Verify full stack
npx tsc --noEmit
npx vitest run
After code changes, request MCP server reconnect before integration testing with
mcp__tea-rags__* tools.
Checklist
Phase 2 checklist hoisted to top — see Implementation Checklist.