@george43g/mcp-kit 2.0.0 → 3.1.0

package/dist/testing.js

@@ -0,0 +1,230 @@
+/**
+ * `@george43g/mcp-kit/testing` — MCP wire-conformance checks for a consumer's
+ * test suite.
+ *
+ * Two questions, each one a client has actually failed on:
+ *
+ *  1. Does every tool's `inputSchema` / `outputSchema` compile in a client that
+ *     only speaks JSON Schema 2020-12? (`assertMcpConformance`) Claude Code
+ *     2.1.292 refused every mcp-kit 2.x tool because the schemas were labelled
+ *     draft-07.
+ *  2. Does a tool's `structuredContent` satisfy its own `outputSchema`?
+ *     (`validateStructured`) The SDK client runs exactly this check on every
+ *     `tools/call` and turns a mismatch into an error.
+ *
+ * A separate entry so Ajv is never loaded by a running server: nothing under
+ * the main entry imports this file. `ajv` and `ajv-formats` are regular
+ * dependencies of the package rather than optional peers because
+ * `@modelcontextprotocol/sdk` already depends on both (^8.17.1 / ^3.0.1) — they
+ * are in every consumer's install already, so declaring them adds no package,
+ * and a consumer's vitest needs no extra devDependency to use this entry.
+ */
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+import { toMcpSchema, } from "./tool-registry.js";
+// ajv-formats is CommonJS with `module.exports = plugin` and `.default = plugin`;
+// under NodeNext the default import is the module object, so take `.default`
+// when it is there.
+const addFormats = (addFormatsModule.default ??
+    addFormatsModule);
+const DIALECT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+/** Thrown by `assertMcpConformance`; `problems` holds one line per failure. */
+export class McpConformanceError extends Error {
+    problems;
+    constructor(problems) {
+        super(`MCP conformance failed (${problems.length} problem(s)):\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+        this.name = "McpConformanceError";
+        this.problems = problems;
+    }
+}
+/**
+ * The Ajv a 2020-12-only client effectively runs: strict mode, 2020-12 as the
+ * only meta-schema (no draft-07 is added, so a draft-07 `$schema` fails here
+ * exactly as it failed in the client), standard formats known.
+ *
+ * `allowUnionTypes` is the one relaxation, and it is not a relaxation of the
+ * spec: `type: ["string", "number"]` is valid 2020-12 — it is what Zod emits for
+ * `z.union([z.string(), z.number()])` — and Ajv's `strictTypes` flags it only
+ * as a style preference.
+ */
+function makeAjv() {
+    const ajv = new Ajv2020({ strict: true, allowUnionTypes: true, allErrors: true });
+    addFormats(ajv);
+    return ajv;
+}
+function formatAjvErrors(errors) {
+    return (errors ?? [])
+        .map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim())
+        .join("; ");
+}
+function isRegistry(source) {
+    return !Array.isArray(source) && typeof source.toMcpTools === "function";
+}
+function isDefinition(entry) {
+    return "input" in entry && "output" in entry;
+}
+/** Convert definitions to wire shape, recording a conversion throw as a problem. */
+function toWire(entry, problems) {
+    if (!isDefinition(entry))
+        return entry;
+    const wire = { name: entry.name };
+    for (const io of ["input", "output"]) {
+        try {
+            const schema = toMcpSchema(io === "input" ? entry.input : entry.output, io, entry.name);
+            if (io === "input")
+                wire.inputSchema = schema;
+            else
+                wire.outputSchema = schema;
+        }
+        catch (err) {
+            problems.push(err.message);
+        }
+    }
+    return wire;
+}
+function compileWireSchema(ajv, tool, field, schema, problems) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+        problems.push(`${tool}: ${field} is not a JSON Schema object.`);
+        return undefined;
+    }
+    const s = schema;
+    if (s.$schema !== undefined && s.$schema !== DIALECT_2020_12) {
+        problems.push(`${tool}: ${field} declares $schema ${JSON.stringify(s.$schema)}. A 2020-12-only client ` +
+            "(Claude Code 2.1.292+) refuses it. Emit 2020-12 with no $schema — mcp-kit's toMcpSchema() does.");
+    }
+    if (s.type !== "object") {
+        problems.push(`${tool}: ${field} has type ${JSON.stringify(s.type ?? null)}; MCP requires "object".`);
+    }
+    try {
+        return ajv.compile(s);
+    }
+    catch (err) {
+        problems.push(`${tool}: ${field} does not compile under Ajv2020 strict: ${err.message}`);
+        return undefined;
+    }
+}
+/**
+ * Throw `McpConformanceError` unless every tool's schemas would be accepted by a
+ * JSON Schema 2020-12 client, and every sample validates.
+ *
+ * Collects every problem before throwing, so one run shows them all.
+ *
+ * A `ToolRegistry` is checked in full — devOnly tools included and its
+ * `filter` ignored — because a hidden tool still ships a schema somebody's
+ * client will compile.
+ *
+ * Pass the result of a real `tools/list` (`Tool[]`) to check the wire output
+ * itself; pass definitions or a registry to check what `toMcpSchema` would emit.
+ */
+export function assertMcpConformance(source, opts = {}) {
+    const problems = [];
+    const entries = isRegistry(source) ? source.tools : source;
+    const ajv = makeAjv();
+    const seen = new Set();
+    const names = [];
+    const validators = new Map();
+    for (const entry of entries) {
+        const wire = toWire(entry, problems);
+        const name = typeof wire.name === "string" ? wire.name : "";
+        if (name === "") {
+            problems.push("A tool has no name.");
+            continue;
+        }
+        if (seen.has(name))
+            problems.push(`${name}: duplicate tool name.`);
+        seen.add(name);
+        names.push(name);
+        const v = {};
+        if (wire.inputSchema === undefined) {
+            if (!isDefinition(entry))
+                problems.push(`${name}: no inputSchema (MCP requires one).`);
+        }
+        else {
+            v.input = compileWireSchema(ajv, name, "inputSchema", wire.inputSchema, problems);
+        }
+        if (wire.outputSchema !== undefined) {
+            v.output = compileWireSchema(ajv, name, "outputSchema", wire.outputSchema, problems);
+        }
+        validators.set(name, v);
+    }
+    for (const [tool, samples] of Object.entries(opts.samples ?? {})) {
+        const v = validators.get(tool);
+        if (!v) {
+            problems.push(`samples given for "${tool}", which is not in the source.`);
+            continue;
+        }
+        for (const io of ["input", "output"]) {
+            const list = samples[io] ?? [];
+            if (list.length === 0)
+                continue;
+            const validate = v[io];
+            if (!validate) {
+                problems.push(`${tool}: ${io} samples given but there is no compiled ${io}Schema.`);
+                continue;
+            }
+            list.forEach((sample, i) => {
+                if (!validate(sample)) {
+                    problems.push(`${tool}: ${io} sample #${i} rejected: ${formatAjvErrors(validate.errors)}`);
+                }
+            });
+        }
+    }
+    if (problems.length > 0)
+        throw new McpConformanceError(problems);
+    return { tools: names };
+}
+/**
+ * Check a `tools/call` result the way the SDK client does before handing it to
+ * the model:
+ *
+ * - a tool with an `outputSchema` must return `structuredContent` unless the
+ *   result is an error;
+ * - `structuredContent`, when present, must validate against `outputSchema`
+ *   (under Ajv2020, strict).
+ *
+ * A tool with no `outputSchema` has nothing to check and is always valid.
+ * Accepts the wire `Tool` (from `tools/list`) or a `ToolDefinition`.
+ *
+ * Returns rather than throws, so a test reads
+ * `expect(validateStructured(tool, result).errors).toEqual([])` and the diff
+ * shows the reason.
+ */
+export function validateStructured(tool, 
+// `Record<string, unknown>` admits the SDK client's `callTool()` return type,
+// whose union includes the legacy `{ toolResult }` shape.
+result) {
+    const { structuredContent, isError } = result;
+    let outputSchema;
+    if (isDefinition(tool)) {
+        try {
+            outputSchema = toMcpSchema(tool.output, "output", tool.name);
+        }
+        catch (err) {
+            return { valid: false, errors: [err.message] };
+        }
+    }
+    else {
+        outputSchema = tool.outputSchema;
+    }
+    if (outputSchema === undefined)
+        return { valid: true, errors: [] };
+    if (!structuredContent && !isError) {
+        return {
+            valid: false,
+            errors: [`Tool ${tool.name} has an output schema but did not return structured content.`],
+        };
+    }
+    if (!structuredContent)
+        return { valid: true, errors: [] };
+    const problems = [];
+    const validate = compileWireSchema(makeAjv(), tool.name, "outputSchema", outputSchema, problems);
+    if (!validate)
+        return { valid: false, errors: problems };
+    if (validate(structuredContent))
+        return { valid: true, errors: [] };
+    return {
+        valid: false,
+        errors: (validate.errors ?? []).map((e) => `${tool.name}: structuredContent${e.instancePath} ${e.message ?? "is invalid"}`),
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,OAAO,EAA2C,MAAM,kBAAkB,CAAC;AACpF,OAAO,gBAAgB,MAAM,aAAa,CAAC;AAC3C,OAAO,EAIL,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,kFAAkF;AAClF,6EAA6E;AAC7E,oBAAoB;AACpB,MAAM,UAAU,GAAG,CAAE,gBAAqD,CAAC,OAAO;IAChF,gBAAgB,CAA8B,CAAC;AAEjD,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAiCvE,+EAA+E;AAC/E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,QAAQ,CAAoB;IACrC,YAAY,QAA2B;QACrC,KAAK,CACH,2BAA2B,QAAQ,CAAC,MAAM,kBAAkB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,SAAS,OAAO;IACd,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClF,UAAU,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,eAAe,CAAC,MAAwC;IAC/D,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;SAClB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,IAAI,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;SACrE,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAQD,SAAS,UAAU,CAAC,MAAyB;IAC3C,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAQ,MAAuB,CAAC,UAAU,KAAK,UAAU,CAAC;AAC7F,CAAC;AAED,SAAS,YAAY,CAAC,KAA+B;IACnD,OAAO,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC/C,CAAC;AAED,oFAAoF;AACpF,SAAS,MAAM,CAAC,KAA+B,EAAE,QAAkB;IACjE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,KAAiB,CAAC;IACnD,MAAM,IAAI,GAAa,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAC5C,KAAK,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAU,EAAE,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACxF,IAAI,EAAE,KAAK,OAAO;gBAAE,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;;gBACzC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,iBAAiB,CACxB,GAAY,EACZ,IAAY,EACZ,KAAqC,EACrC,MAAe,EACf,QAAkB;IAElB,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,KAAK,+BAA+B,CAAC,CAAC;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,GAAG,MAAiC,CAAC;IAC5C,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;QAC7D,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,KAAK,KAAK,qBAAqB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,0BAA0B;YACvF,iGAAiG,CACpG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,KAAK,KAAK,aAAa,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,0BAA0B,CACvF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,KAAK,KAAK,2CAA4C,GAAa,CAAC,OAAO,EAAE,CACrF,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAyB,EACzB,OAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,OAAO,GAA0C,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAClG,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAG,IAAI,GAAG,EAGvB,CAAC;IAEJ,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YACrC,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC;QACnE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEjB,MAAM,CAAC,GAAoF,EAAE,CAAC;QAC9F,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,sCAAsC,CAAC,CAAC;QACzF,CAAC;aAAM,CAAC;YACN,CAAC,CAAC,KAAK,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,CAAC,CAAC,MAAM,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QACvF,CAAC;QACD,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,QAAQ,CAAC,IAAI,CAAC,sBAAsB,IAAI,gCAAgC,CAAC,CAAC;YAC1E,SAAS;QACX,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAU,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAChC,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;YACvB,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,EAAE,2CAA2C,EAAE,SAAS,CAAC,CAAC;gBACpF,SAAS;YACX,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;gBACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtB,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,KAAK,EAAE,YAAY,CAAC,cAAc,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAC5E,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAA8B;AAC9B,8EAA8E;AAC9E,0DAA0D;AAC1D,MAAgG;IAEhG,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,MAGtC,CAAC;IACF,IAAI,YAAqB,CAAC;IAC1B,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAyB,CAAC;QACvF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAE,GAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;SAAM,CAAC;QACN,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACnC,CAAC;IACD,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEnE,IAAI,CAAC,iBAAiB,IAAI,CAAC,OAAO,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,CAAC,QAAQ,IAAI,CAAC,IAAI,8DAA8D,CAAC;SAC1F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,iBAAiB;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAE3D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;IACjG,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACzD,IAAI,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACpE,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,sBAAsB,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,OAAO,IAAI,YAAY,EAAE,CACvF;KACF,CAAC;AACJ,CAAC"}

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. */
@@ -51,6 +62,12 @@ export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput
     timeoutMs?: number;
     /** When true, only register the tool if `MCP_DEV=1`. Used for `get_logs`. */
     devOnly?: boolean;
+    /**
+     * Reject a call that carries an argument name this tool does not declare,
+     * before the handler runs. Overrides the registry's `strictArgs` for this
+     * tool, in either direction. See `MakeRegistryOptions.strictArgs`.
+     */
+    strictArgs?: boolean;
     /** Handler: receives parsed input + AbortSignal, returns structured output. */
     handler: (input: z.infer<TInput>, signal?: AbortSignal) => Promise<z.infer<TOutput>>;
     /**
@@ -68,11 +85,183 @@ 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;
+}
+/**
+ * A filter's refusal WITH a reason the caller may see. Returned instead of
+ * `false` when the caller can do something about it (re-authenticate, ask for
+ * a scope), so the refusal is recoverable instead of a dead end.
+ */
+export interface ToolDeny {
+    /**
+     * Shown to the caller as the error text of a `tools/call` to the tool,
+     * wrapped like every other dispatcher error:
+     * `Tool "<name>" failed: <deny>`. Must be non-empty; an empty string is
+     * treated as a plain `false`.
+     */
+    deny: string;
+}
+/** What a `ToolFilter` may return. */
+export type ToolFilterResult = boolean | ToolDeny;
+/**
+ * The registry's verdict on one tool for one request, from
+ * `ToolRegistry.evaluate`. `deny` is present only when the filter returned
+ * `{ deny }`; a plain `false`, a throw, or any other value has none, and the
+ * dispatcher then answers exactly as for an unknown tool.
+ */
+export type ToolFilterDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    deny?: string;
+};
+/** One argument name a strict tool does not declare, from `ToolRegistry.unknownArgs`. */
+export interface UnknownArgument {
+    /** The name as the caller sent it. */
+    key: string;
+    /** The declared argument it most likely meant (within 2 edits), if any. */
+    suggestion?: string;
+}
+/**
+ * Per-request tool gate. Return `true` to allow the tool, `false` to hide it
+ * from `tools/list` AND refuse calls to it as if it did not exist, or
+ * `{ deny: "reason" }` to hide it the same way but refuse a call with that
+ * reason instead of the unknown-tool wording.
+ *
+ * `false` is the right answer when the tool's existence is itself the secret;
+ * `{ deny }` when the caller can recover, e.g. gmail's
+ * `{ deny: "not available. You may need to re-authenticate with additional scopes" }`.
+ *
+ * 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) => ToolFilterResult;
+/**
+ * `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>;
+    /**
+     * Default for every tool's `strictArgs`; a tool's own `strictArgs` wins.
+     * Off unless set.
+     *
+     * When on, a call that names an argument the tool's advertised `inputSchema`
+     * does not list under its top-level `properties` is refused BEFORE parsing
+     * and before the handler, naming each unknown key with a "did you mean"
+     * suggestion when a declared key is within 2 edits:
+     * `unknown argument chatIdentifer; did you mean chatIdentifier?`.
+     * When off, Zod strips an unknown key silently and the handler runs as if
+     * the argument had not been sent, which is how a misspelled optional
+     * argument quietly falls back to its default.
+     *
+     * - The advertised `inputSchema` is unchanged: no `additionalProperties:
+     *   false` is added, so clients see the same open schema either way.
+     * - Valid input parses exactly as without it: the check only reads the
+     *   argument names, and parsing still runs the tool's own schema.
+     * - Top level only. A nested `z.object` still strips unknown keys; declare
+     *   it `z.strictObject` to reject them (Zod's own error, no suggestion).
+     * - A tool whose input declares itself open at the top level
+     *   (`z.looseObject`, `.catchall()`, `z.record`) has no unknown keys, and
+     *   the option does nothing for it.
+     */
+    strictArgs?: boolean;
+}
 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 returns `false` or
+     * `{ deny }`, or throws.
+     */
+    allows(def: AnyToolDefinition, ctx?: ToolFilterContext): boolean;
+    /**
+     * `allows`, plus the filter's `{ deny }` reason. Optional so a hand-written
+     * registry from 3.0 still type-checks; `makeRegistry()` always provides it,
+     * and the dispatcher falls back to `allows` without it.
+     */
+    evaluate?(def: AnyToolDefinition, ctx?: ToolFilterContext): ToolFilterDecision;
+    /**
+     * The argument names in `args` that `def` does not declare, when `def` is
+     * strict (its own `strictArgs`, else the registry's); `[]` otherwise, and
+     * `[]` when `args` is not a plain object. Optional for the same reason as
+     * `evaluate`; without it the dispatcher honours a tool's own `strictArgs`.
+     */
+    unknownArgs?(def: AnyToolDefinition, args: unknown): UnknownArgument[];
+    /**
+     * 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,117 @@
  *   - 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";
+import { declaredArgs, findUnknownArgs } from "./unknown-args.js";
+/**
+ * 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;
+}
+/** Read a filter's return value. Anything but `true` or a non-empty `{ deny }` is a plain refusal. */
+function decide(result) {
+    if (result === true)
+        return { allowed: true };
+    if (result !== null && typeof result === "object") {
+        const deny = result.deny;
+        if (typeof deny === "string" && deny.trim() !== "")
+            return { allowed: false, deny };
+    }
+    return { allowed: false };
+}
+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, strictArgs = false } = opts;
+    // Derived from the wire schema computed above, once per definition.
+    const declared = new Map(defs.map((d) => [d, declaredArgs(wire.get(d).inputSchema)]));
+    const evaluate = (def, ctx = {}) => {
+        if (!filter)
+            return { allowed: true };
+        try {
+            // Only definitions from `defs` reach here in practice; the dispatcher
+            // looks them up through `get()`.
+            return decide(filter(def, ctx));
+        }
+        catch {
+            return { allowed: false };
+        }
+    };
+    const allows = (def, ctx) => evaluate(def, ctx).allowed;
     return {
         tools: defs,
         get(name) {
             return byName.get(name);
         },
-        toMcpTools(includeDevOnly = false) {
+        allows,
+        evaluate,
+        unknownArgs(def, args) {
+            if (!(def.strictArgs ?? strictArgs))
+                return [];
+            // A definition from outside `defs` has no precomputed entry; derive it.
+            const keys = declared.has(def)
+                ? (declared.get(def) ?? null)
+                : declaredArgs(toMcpSchema(def.input, "input", def.name));
+            return findUnknownArgs(keys, args);
+        },
+        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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"}