@datarealiser/mcp-tools

A curated, tag-driven subset of @datarealiser/api-client — only kernel-api endpoints whose route is explicitly tagged @mcpTool are reachable through this package. Built for mcp-server, so it can depend on this instead of the full api-client surface: a consumer of this package literally cannot call an endpoint nobody opted in, regardless of what api-client itself exposes — the safety boundary is enforced by what exists on McpToolsClient, not by code-review discipline in the consumer.

Tagging an endpoint

Endpoints are not tagged by default. To expose one:

1. Make sure its @datarealiser/api-client method has a real signature in src/types/apiClient.d.ts's DatarealiserApiClientMethods — add one if it's missing.

2. Add a tag directly above the route in kernel/src/routes/*.routes.ts:

   /**
    * @mcpTool getQuery
    * @mcpDescription Fetches one saved query's sql and declared params by name. Needs queries:manage.
    */
   router.get('/:name', ...);

   @mcpTool <name> must be the exact method name on DatarealiserApiClient (the two are 1:1 — this package only ever delegates, never reimplements). @mcpDescription is a single line; it becomes both the generated method's JSDoc and (conventionally) the MCP tool's own description in mcp-server/src/tools.ts.

3. Regenerate:

   npm run generate

   This rewrites src/index.js and src/index.d.ts from scratch — never hand-edit either. The generator fails loudly (naming the file/tag) if a tag has no matching signature in src/types/apiClient.d.ts, or if the same name is tagged twice.

Untagging: remove the @mcpTool/@mcpDescription comment and regenerate — the method disappears from McpToolsClient entirely, not just from wherever a consumer happened to be calling it.

Publishing

./publish.sh          # regenerates, smoke-tests, then npm publish
./publish.sh --dry-run

Bump "version" in package.json first, same as api-client/publish.sh.

Design notes

• Delegates to api-client, doesn't duplicate it. McpToolsClient wraps a real DatarealiserApiClient instance internally (dependencies in package.json); each generated method is a thin (...args) => this.#client.<name>(...args) passthrough. One HTTP/ auth/error-handling implementation to maintain (api-client's), not two.
• No MCP SDK dependency. This package only narrows which kernel-api calls are reachable — it knows nothing about the Model Context Protocol itself (no zod schemas, no registerTool wiring). That stays in mcp-server/src/tools.ts, which decides how each allowed method becomes an MCP tool (title, input schema, etc.). Keeping the layers separate means this package is reusable anywhere a curated kernel-api client is useful, not just from an MCP server.
• Ships a real .d.ts, unlike api-client (which ships none, by its own design choice — every consumer hand-maintains its own partial declaration). Since this package is generated, not hand-written, there was no reason to repeat that pattern: src/index.d.ts is always exactly in sync with src/index.js.