agentsclimarketplace

Add mcp endpoint

Skill artk0de/TeaRAGs-MCP/.claude/skills/add-mcp-endpoint

The code intelligence layer for AI coding agents. Semantic indexing, graph navigation, and repository intelligenceFrom the repository description

Install
npx -y skills add artk0de/TeaRAGs-MCP --skill add-mcp-endpoint

Assembled 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.md three-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/reduce aggregation, 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 in public/app.ts (delegate to facade/ops/query/strategy)
  • AppDeps updated 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 and getSchemaDescriptors list
  • 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.md updated
  • 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 fileContains
dto/explore.tsSearch types (SemanticSearchRequest, ExploreResponse, etc.)
dto/ingest.tsIndexing types (IndexOptions, IndexStats, ChangeStats, etc.)
dto/collection.tsCollection CRUD types (CreateCollectionRequest, CollectionInfo)
dto/document.tsDocument 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 Response suffix
  • Extend CollectionRef for endpoints accepting collection or path
  • Extend TypedFilterParams for endpoints with trajectory filters
  • Pure interfaces only (no classes, no logic)
  • Import only from contracts/ or infra/ if needed

Export chain (MANDATORY):

  1. Type defined in dto/<domain>.ts
  2. Re-exported from dto/index.ts (automatic if using existing domain file)
  3. Re-exported through public/index.ts → api/index.ts
  4. If contracts/types/app.ts re-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:

  1. Import new DTO from ./dto/index.js

  2. Add method signature to App interface 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.

  1. 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 inFacade 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 dispatcherthe 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/reduce aggregation in the facade.
  • MUST NEVER branch on indexing modes with multi-branch if/else in the facade.
  • MUST NEVER call parallel scrollFiltered with 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:

  1. Export registerNewTools(server, deps) function
  2. Call from src/mcp/tools/index.ts in registerAllTools()

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:

FunctionWhen
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:

  1. Add tool to appropriate section table (Collection Management, Document Operations, Code Vectorization, or create new section)
  2. Non-trivial parameters → add parameters subsection under ## Search Parameters or 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.

Keep looking

Skills are one crate of 613,872. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.