@george43g/mcp-kit 2.0.0 → 3.0.0

package/dist/tool-registry.d.ts

@@ -7,10 +7,13 @@
  *   - the ToolDefinition (registration metadata)
  *
  * The registry collects ToolDefinitions and converts them to the SDK's
- * `Tool[]` shape via `toMcpTools()`.
+ * `Tool[]` shape via `toMcpTools()`. Both wire schemas are DERIVED from the one
+ * Zod definition per tool by `toMcpSchema()`; there is no hand-written JSON
+ * Schema path, so the wire contract cannot drift from the validator.
  */
-import type { Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { ZodTypeAny, z } from "zod";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { RequestInfo, Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 /**
  * A single MCP content block a tool may emit.
  *
@@ -33,7 +36,15 @@ export type ContentBlock = {
     data: string;
     mimeType: string;
 };
-export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput extends ZodTypeAny = ZodTypeAny> {
+/**
+ * Any Zod schema, inferring `any` — the default for an unparameterised
+ * `ToolDefinition`, so a handler written against it is not forced to narrow
+ * `unknown`. This is what `ZodTypeAny` meant under Zod 3; Zod 4's `ZodTypeAny`
+ * (a deprecated compat alias) infers `unknown`, which would have made every
+ * bare `ToolDefinition` handler a type error on upgrade.
+ */
+export type AnyZodSchema = z.ZodType<any, any>;
+export interface ToolDefinition<TInput extends z.ZodType = AnyZodSchema, TOutput extends z.ZodType = AnyZodSchema> {
     /** Snake_case tool name, e.g. "health_check". */
     name: string;
     /** One-paragraph description shown to the LLM. */
@@ -68,11 +79,104 @@ export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput
     toContent?: (result: z.infer<TOutput>) => ContentBlock[];
 }
 export type AnyToolDefinition = ToolDefinition<any, any>;
+/**
+ * What a tool filter is told about the request it is answering.
+ *
+ * A structural subset of the SDK's `RequestHandlerExtra` — the second argument
+ * every `server.setRequestHandler` callback receives — so a handler can pass
+ * its `extra` straight through: `registry.toMcpTools(dev, extra)` and
+ * `dispatch(name, args, extra.signal, extra)`.
+ *
+ * Every field is optional because most calls carry none of them: stdio has no
+ * auth, and an in-process caller (a CLI, a REPL, a test) has no request at all.
+ * A filter that gates on scopes therefore sees `authInfo === undefined` there,
+ * and should decide deliberately what that means for its tools.
+ */
+export interface ToolFilterContext {
+    /** Validated access token, when the transport authenticated the request (HTTP + OAuth). */
+    authInfo?: AuthInfo;
+    /** Transport session id, when the transport has sessions. */
+    sessionId?: string;
+    /** The originating HTTP request's headers, when there was one. */
+    requestInfo?: RequestInfo;
+}
+/**
+ * Per-request tool gate: return `false` to hide a tool from `tools/list` AND
+ * refuse calls to it.
+ *
+ * Synchronous on purpose: it runs inside `toMcpTools()`, which is synchronous,
+ * and a scope check is a set lookup. Resolve anything slow (a token
+ * introspection) before the request reaches the registry — the HTTP transport's
+ * auth layer is where that belongs.
+ *
+ * A filter that THROWS is treated as `false` (fail closed): a bug in the gate
+ * must not expose the tool it was written to protect.
+ */
+export type ToolFilter<TDef extends AnyToolDefinition = AnyToolDefinition> = (tool: TDef, ctx: ToolFilterContext) => boolean;
+/**
+ * `TDef` lets a consumer carry its own per-tool metadata into the filter
+ * without a cast: declare `interface ScopedTool extends ToolDefinition { scopes:
+ * string[] }`, pass `ScopedTool[]`, and the filter receives `ScopedTool`.
+ *
+ * The filter is called on EVERY `toMcpTools()` / dispatch — never cached — so a
+ * predicate that reads live state (scopes granted by a re-auth a minute ago)
+ * sees the current value. Read that state inside the predicate.
+ */
+export interface MakeRegistryOptions<TDef extends AnyToolDefinition = AnyToolDefinition> {
+    /**
+     * Optional per-request gate, applied by BOTH `toMcpTools()` and the
+     * dispatcher. It lives on the registry rather than on either consumer so the
+     * listing and the call path cannot disagree: a filter that only hid a tool
+     * from `tools/list` would leave it callable by name (see `devOnly`).
+     */
+    filter?: ToolFilter<TDef>;
+}
 export interface ToolRegistry {
     readonly tools: readonly AnyToolDefinition[];
     get(name: string): AnyToolDefinition | undefined;
-    /** Convert all tools (or just enabled ones) to MCP SDK shape. */
-    toMcpTools(includeDevOnly?: boolean): Tool[];
+    /**
+     * Whether `def` passes the registry's filter for this request. Always `true`
+     * when no filter was configured; `false` when the filter throws.
+     */
+    allows(def: AnyToolDefinition, ctx?: ToolFilterContext): boolean;
+    /**
+     * Convert tools to MCP SDK shape: devOnly tools only when `includeDevOnly`,
+     * and only tools the filter allows for `ctx`. Schemas are converted once, at
+     * `makeRegistry()`, so a call here never throws for a schema problem.
+     */
+    toMcpTools(includeDevOnly?: boolean, ctx?: ToolFilterContext): Tool[];
 }
-export declare function makeRegistry(defs: AnyToolDefinition[]): ToolRegistry;
+/** Which side of a Zod schema to describe: what a caller sends, or what parsing yields. */
+export type McpSchemaIo = "input" | "output";
+/** A JSON Schema object as emitted by `toMcpSchema`: always `type: "object"` at the top. */
+export type McpJsonSchema = {
+    type: "object";
+    [key: string]: unknown;
+};
+/**
+ * Convert a Zod schema to the JSON Schema an MCP client accepts as a tool's
+ * `inputSchema` / `outputSchema`.
+ *
+ * - **Dialect: JSON Schema 2020-12**, the MCP default. Draft-07 output (what
+ *   `zod-to-json-schema` emitted, and what mcp-kit 2.x shipped) is rejected
+ *   outright by clients that only load the 2020-12 meta-schema — Claude Code
+ *   2.1.292 throws on `"$schema": "http://json-schema.org/draft-07/schema#"`.
+ * - **`$schema` is stripped.** 2020-12 is the dialect a schema without a label
+ *   is read as under MCP, and a schema with no label gives no client a dialect
+ *   to refuse.
+ * - **`io` matters.** `"input"` describes what a caller may send (a field with
+ *   a `.default()` is optional); `"output"` describes what parsing yields (the
+ *   same field is required, and objects are closed with
+ *   `additionalProperties: false`).
+ * - **Shared sub-schemas are inlined** (`reused: "inline"`). **Cycles are not
+ *   inlinable**, so a recursive schema still carries `$defs` / `$ref` (or a
+ *   root `$ref: "#"`). That is valid 2020-12 and kept as is.
+ * - **Unrepresentable types throw**: `z.date()`, `z.bigint()`, a transform on
+ *   the output side, and so on. The error names the tool, so a registry with a
+ *   bad schema fails at startup rather than at a client's first `tools/list`.
+ * - **The top level must be an object.** MCP requires `type: "object"` for both
+ *   schemas; anything else throws, naming the tool.
+ */
+export declare function toMcpSchema(schema: z.ZodType, io: McpSchemaIo, toolName?: string): McpJsonSchema;
+export declare function makeRegistry<TDef extends AnyToolDefinition = AnyToolDefinition>(defs: TDef[], opts?: MakeRegistryOptions<TDef>): ToolRegistry;
 //# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC,oEAAoE;GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,OAAO,SAAS,UAAU,GAAG,UAAU;IAEvC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,WAAW,EAAE,eAAe,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACrF;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;CAC1D;AAMD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACjD,iEAAiE;IACjE,UAAU,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,YAAY,CA0BpE"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/dist/tool-registry.js

@@ -7,31 +7,92 @@
  *   - the ToolDefinition (registration metadata)
  *
  * The registry collects ToolDefinitions and converts them to the SDK's
- * `Tool[]` shape via `toMcpTools()`.
+ * `Tool[]` shape via `toMcpTools()`. Both wire schemas are DERIVED from the one
+ * Zod definition per tool by `toMcpSchema()`; there is no hand-written JSON
+ * Schema path, so the wire contract cannot drift from the validator.
  */
-import { zodToJsonSchema } from "zod-to-json-schema";
-export function makeRegistry(defs) {
+import { z } from "zod";
+/**
+ * Convert a Zod schema to the JSON Schema an MCP client accepts as a tool's
+ * `inputSchema` / `outputSchema`.
+ *
+ * - **Dialect: JSON Schema 2020-12**, the MCP default. Draft-07 output (what
+ *   `zod-to-json-schema` emitted, and what mcp-kit 2.x shipped) is rejected
+ *   outright by clients that only load the 2020-12 meta-schema — Claude Code
+ *   2.1.292 throws on `"$schema": "http://json-schema.org/draft-07/schema#"`.
+ * - **`$schema` is stripped.** 2020-12 is the dialect a schema without a label
+ *   is read as under MCP, and a schema with no label gives no client a dialect
+ *   to refuse.
+ * - **`io` matters.** `"input"` describes what a caller may send (a field with
+ *   a `.default()` is optional); `"output"` describes what parsing yields (the
+ *   same field is required, and objects are closed with
+ *   `additionalProperties: false`).
+ * - **Shared sub-schemas are inlined** (`reused: "inline"`). **Cycles are not
+ *   inlinable**, so a recursive schema still carries `$defs` / `$ref` (or a
+ *   root `$ref: "#"`). That is valid 2020-12 and kept as is.
+ * - **Unrepresentable types throw**: `z.date()`, `z.bigint()`, a transform on
+ *   the output side, and so on. The error names the tool, so a registry with a
+ *   bad schema fails at startup rather than at a client's first `tools/list`.
+ * - **The top level must be an object.** MCP requires `type: "object"` for both
+ *   schemas; anything else throws, naming the tool.
+ */
+export function toMcpSchema(schema, io, toolName) {
+    const where = toolName === undefined ? `${io} schema` : `tool "${toolName}" ${io} schema`;
+    let json;
+    try {
+        json = z.toJSONSchema(schema, { target: "draft-2020-12", io, reused: "inline" });
+    }
+    catch (err) {
+        throw new Error(`toMcpSchema: ${where} cannot be represented in JSON Schema: ${err?.message ?? String(err)}. ` +
+            "Use a JSON-representable type (an ISO string instead of z.date(), a number or string instead of z.bigint()), " +
+            "or move the transform out of the schema.", { cause: err });
+    }
+    delete json.$schema;
+    if (json.type !== "object") {
+        throw new Error(`toMcpSchema: ${where} must be a Zod object (JSON Schema type "object"), got ${JSON.stringify(json.type ?? null)}. ` +
+            "MCP requires tool input and output schemas to describe an object; wrap the value, e.g. z.object({ result: ... }).");
+    }
+    return json;
+}
+export function makeRegistry(defs, opts = {}) {
     const byName = new Map(defs.map((d) => [d.name, d]));
+    // Converted eagerly: a schema that cannot be represented throws HERE, at
+    // startup, naming the tool, instead of on a client's first tools/list.
+    // Keyed by definition, not name, so two definitions sharing a name (a
+    // mistake, but representable) cannot swap schemas.
+    const wire = new Map(defs.map((d) => [
+        d,
+        {
+            name: d.name,
+            description: d.description,
+            annotations: d.annotations,
+            inputSchema: toMcpSchema(d.input, "input", d.name),
+            outputSchema: toMcpSchema(d.output, "output", d.name),
+        },
+    ]));
+    const { filter } = opts;
+    const allows = (def, ctx = {}) => {
+        if (!filter)
+            return true;
+        try {
+            // Only definitions from `defs` reach here in practice; the dispatcher
+            // looks them up through `get()`.
+            return filter(def, ctx) === true;
+        }
+        catch {
+            return false;
+        }
+    };
     return {
         tools: defs,
         get(name) {
             return byName.get(name);
         },
-        toMcpTools(includeDevOnly = false) {
+        allows,
+        toMcpTools(includeDevOnly = false, ctx = {}) {
             return defs
-                .filter((d) => includeDevOnly || !d.devOnly)
-                .map((d) => 
-            // The SDK Tool type narrows inputSchema/outputSchema to a JSON-
-            // schema with `type: "object"` literal; zodToJsonSchema returns
-            // the broader JsonSchema7Type union. Cast is safe because we
-            // only ever build Zod object schemas as tool I/O.
-            ({
-                name: d.name,
-                description: d.description,
-                annotations: d.annotations,
-                inputSchema: zodToJsonSchema(d.input),
-                outputSchema: zodToJsonSchema(d.output),
-            }));
+                .filter((d) => (includeDevOnly || !d.devOnly) && allows(d, ctx))
+                .map((d) => wire.get(d));
         },
     };
 }

package/dist/tool-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAsErD,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,IAAI;YACN,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,UAAU,CAAC,cAAc,GAAG,KAAK;YAC/B,OAAO,IAAI;iBACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;iBAC3C,GAAG,CACF,CAAC,CAAC,EAAE,EAAE;YACJ,gEAAgE;YAChE,gEAAgE;YAChE,6DAA6D;YAC7D,kDAAkD;YAClD,CAAC;gBACC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC;gBACrC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC;aACxC,CAAoB,CACxB,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@george43g/mcp-kit",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "MCP server building blocks: tool registry types, dispatcher with timeout/perf/abort/error-wrap baked in, stdio + Streamable HTTP transports, sanitize() for user content, UUID-gated prompt-injection helpers.",
   "type": "module",
   "license": "MIT",
@@ -33,10 +33,16 @@
       "import": "./dist/transports/stdio.js",
       "default": "./dist/transports/stdio.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "!dist/tsconfig.tsbuildinfo",
     "src",
     "!src/**/*.test.ts",
     "README.md",
@@ -52,8 +58,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.0",
-    "zod-to-json-schema": "^3.25.0"
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
   },
   "devDependencies": {
     "@george43g/robustness": "workspace:*",
@@ -67,9 +73,11 @@
     "semantic-release": "^24.2.0",
     "semantic-release-monorepo": "^8.0.2",
     "typescript": "^5.7.0",
-    "vitest": "^3.2.7"
+    "vitest": "^3.2.7",
+    "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@george43g/robustness": ">=0.11.0 <1"
+    "@george43g/robustness": ">=0.11.0 <1",
+    "zod": "^4.0.0"
   }
 }

package/src/dispatch.ts

@@ -31,7 +31,7 @@ import {
 import type { ZodError } from "zod";
 import { wrapToolError } from "./prompt-injection.js";
 import { sanitize } from "./sanitize.js";
-import type { ContentBlock, ToolRegistry } from "./tool-registry.js";
+import type { ContentBlock, ToolFilterContext, ToolRegistry } from "./tool-registry.js";
 
 /**
  * Replace the absolute home-directory prefix with `~` in anything headed for a
@@ -121,14 +121,29 @@ export interface BuildDispatcherOptions {
   devOnlyEnabled?: () => boolean;
 }
 
-export type Dispatch = (name: string, args: unknown, signal?: AbortSignal) => Promise<ToolResult>;
+/**
+ * Call a tool by name.
+ *
+ * `ctx` is what the registry's `filter` (see `makeRegistry`) is evaluated
+ * against. From an MCP `tools/call` handler, pass the handler's `extra`:
+ * `dispatch(name, args, extra.signal, extra)`. An in-process caller omits it,
+ * and the filter sees `{}`.
+ */
+export type Dispatch = (
+  name: string,
+  args: unknown,
+  signal?: AbortSignal,
+  ctx?: ToolFilterContext,
+) => Promise<ToolResult>;
 
 function defaultTimeoutMs(): number {
   return envNum("MCP_TOOL_TIMEOUT_DEFAULT_MS", 30_000);
 }
 
 function formatZodError(err: ZodError): string {
-  return err.errors.map((e) => `  - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
+  return err.issues
+    .map((e) => `  - ${e.path.map(String).join(".") || "(root)"}: ${e.message}`)
+    .join("\n");
 }
 
 export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
@@ -149,7 +164,7 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
   }
 
   const fallback = defaultTimeoutMs();
-  return async (name, args, signal) => {
+  return async (name, args, signal, ctx = {}) => {
     noteActivity();
     opts.onCall?.(name);
     const def = opts.registry.get(name);
@@ -162,8 +177,12 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
     // construction, which the readonly type discourages but does not prevent.
     // If that ever happens the tool is gated, not exposed.
     const devGated = def?.devOnly === true && !(opts.devOnlyEnabled?.() ?? false);
+    // The registry's per-request filter gates the CALL path with the same
+    // predicate that gates the listing. Hiding a tool from tools/list while it
+    // still answers by name is the hole `devOnly` already fell into once.
+    const filtered = def !== undefined && !opts.registry.allows(def, ctx);
 
-    if (!def || devGated) {
+    if (!def || devGated || filtered) {
       opts.onError?.(name, new Error("unknown_tool"));
       return {
         content: [

package/src/index.ts

@@ -23,11 +23,17 @@ export { buildResourcesHandler } from "./resources.js";
 export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
 export type {
   AnyToolDefinition,
+  AnyZodSchema,
   ContentBlock,
+  MakeRegistryOptions,
+  McpJsonSchema,
+  McpSchemaIo,
   ToolDefinition,
+  ToolFilter,
+  ToolFilterContext,
   ToolRegistry,
 } from "./tool-registry.js";
-export { makeRegistry } from "./tool-registry.js";
+export { makeRegistry, toMcpSchema } from "./tool-registry.js";
 export type { HttpServerHandle, HttpServerOptions } from "./transports/http.js";
 export { startHttpServer } from "./transports/http.js";
 export type { StartStdioOptions } from "./transports/stdio.js";