@george43g/mcp-kit 1.0.0 → 3.0.0

package/README.md

@@ -4,8 +4,95 @@ MCP server building blocks: a tool registry, a dispatcher with timeout / perf /
 abort / error-wrapping baked in, stdio + Streamable HTTP transports, `sanitize()`
 for untrusted content, and UUID-gated prompt-injection helpers.
 
-Not yet on npm. It is vendored into generated repos today; see `DEFERRED.md` #25
-in the template repo for the publish sequence.
+Peers: `zod` ^4 and `@george43g/robustness`. Upgrading from 2.x? See
+[Migrating from 2.x](#migrating-from-2x-to-300) — the wire schemas changed dialect.
+
+## Schemas: one Zod definition, JSON Schema 2020-12 on the wire
+
+Each tool declares a Zod `input` and `output`. `makeRegistry()` derives both
+wire schemas from them with `toMcpSchema()`; there is no hand-written JSON
+Schema path, so the schema a client sees cannot drift from the validator the
+dispatcher runs.
+
+```ts
+import { toMcpSchema } from "@george43g/mcp-kit";
+
+toMcpSchema(NoopInputSchema, "input", "noop");
+// → { type: "object", properties: { … }, required: [ … ] }   (no "$schema")
+```
+
+- **Dialect 2020-12, `$schema` stripped.** 2020-12 is MCP's default dialect,
+  and a schema with no label gives no client a dialect to refuse. mcp-kit 2.x
+  emitted draft-07 via `zod-to-json-schema`, and Claude Code 2.1.292 throws on
+  `"$schema": "http://json-schema.org/draft-07/schema#"` — every 2.x tool broke.
+- **`io` is real.** `inputSchema` describes what a caller may send (a
+  `.default()` field is optional); `outputSchema` describes what parsing yields
+  (that field is required, and objects carry `additionalProperties: false`).
+- **Unrepresentable types throw at `makeRegistry()`**, naming the tool:
+  `z.date()`, `z.bigint()`, an output-side `.transform()`. Use an ISO string, a
+  number, or move the transform out of the schema.
+- **The top level must be a `z.object`.** MCP requires `type: "object"`.
+- **Recursive schemas keep `$defs` / `$ref`** (or a root `$ref: "#"`): a cycle
+  cannot be inlined. That is valid 2020-12, and the conformance helper below
+  compiles it.
+
+## Per-request tool filter (scope gating)
+
+```ts
+const registry = makeRegistry(tools, {
+  filter: (tool, ctx) =>
+    !tool.name.startsWith("gmail_send") || (ctx.authInfo?.scopes.includes("gmail.send") ?? false),
+});
+
+server.setRequestHandler(ListToolsRequestSchema, async (_req, extra) => ({
+  tools: registry.toMcpTools(includeDevOnly, extra),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req, extra) =>
+  dispatch(req.params.name, req.params.arguments ?? {}, extra.signal, extra),
+);
+```
+
+- The filter lives on the **registry**, so the listing and the dispatcher apply
+  the same predicate. A refused call answers **exactly like an unknown tool**.
+  Hiding a tool from `tools/list` while it still answers by name is the hole
+  `devOnly` fell into once.
+- `ctx` is `{ authInfo?, sessionId?, requestInfo? }` — a subset of the SDK's
+  `RequestHandlerExtra`, so pass `extra` straight through. In-process calls (a
+  CLI, a test) pass nothing and the filter sees `{}`; decide what no `authInfo`
+  means for your tools.
+- Synchronous, evaluated per request. **A throwing filter counts as `false`**.
+
+## Testing: `@george43g/mcp-kit/testing`
+
+```ts
+import { assertMcpConformance, validateStructured } from "@george43g/mcp-kit/testing";
+
+it("every tool is accepted by a 2020-12 client", () => {
+  assertMcpConformance(makeAppRegistry(), {
+    samples: { noop: { input: [{ input: "x" }], output: [{ echo: "x", engine: "ts", durationMicros: 1 }] } },
+  });
+});
+
+it("noop's structuredContent matches its outputSchema", async () => {
+  const result = await callMcpTool("noop", { input: "x" });
+  expect(validateStructured(noopTool, result).errors).toEqual([]);
+});
+```
+
+- `assertMcpConformance(registry | definitions | Tool[])` compiles every input
+  and output schema under **Ajv2020 in strict mode** with no draft-07
+  meta-schema loaded — so a draft-07 label fails here exactly as it failed in
+  Claude Code. It collects every problem and throws one `McpConformanceError`.
+  A registry is checked in full: devOnly and filtered tools too.
+- `validateStructured(tool, result)` is the SDK client's own `tools/call` check:
+  structured content required unless `isError`, and validated against
+  `outputSchema` when present. It returns `{ valid, errors }`.
+- `ajv` / `ajv-formats` are dependencies of this package, imported only by this
+  entry. `@modelcontextprotocol/sdk` already depends on both, so they add nothing
+  to an install, and a server that never imports `/testing` never loads them.
+- `allowUnionTypes` is on: `type: ["string", "number"]` is valid 2020-12 (Zod
+  emits it for `z.union([z.string(), z.number()])`); Ajv's strict mode flags it
+  only as style.
 
 ## The dispatcher is the point
 
@@ -128,6 +215,60 @@ The marker matters more than it looks: a **silently** shortened document is
 indistinguishable from a document that really ended there, and a model reading it
 will answer confidently from the fragment it received.
 
+## Migrating from 2.x to 3.0.0
+
+**Why:** 2.x emitted draft-07 JSON Schema, and Claude Code 2.1.292+ (a
+2020-12-only client) throws on it, so every tool from every 2.x server failed in
+new sessions. 3.0.0 moves to Zod 4's native converter and 2020-12.
+
+Breaking changes, each with its migration:
+
+1. **`zod` is a peer, `^4`** (was a dependency, `^3.23`). Install `zod@^4` in
+   your app and drop `zod-to-json-schema`. Zod 4's `zod` root keeps `z.object`,
+   `.describe()`, `.default()`, `z.enum`, `z.infer`; see Zod's own v4 migration
+   guide for `.errors` → `.issues`, `z.string().email()` → `z.email()` (the old
+   form still works), and error-map changes.
+2. **Wire schemas are JSON Schema 2020-12 with no `$schema`** (were draft-07,
+   labelled). Clients that pinned draft-07 behaviour see 2020-12 keywords:
+   `prefixItems` for tuples, `$defs` for recursion. Nothing to do unless you
+   post-process `inputSchema` — and if you stripped `$schema` yourself as a
+   hot-fix, delete that code.
+3. **Input objects are open; output objects stay closed.** `inputSchema` is
+   the input side of the schema (`io: "input"`) and no longer carries
+   `additionalProperties: false`, so a client may send extra keys — the
+   dispatcher's Zod parse strips them, as before. `.default()` fields stay
+   optional on input (unchanged) and required on output. `outputSchema` keeps
+   `additionalProperties: false`, as in 2.x.
+4. **`makeRegistry()` throws at construction for an unrepresentable schema**,
+   naming the tool: `z.date()`, `z.bigint()`, `z.map()`, `z.set()`,
+   `z.symbol()`, `z.undefined()`, an output-side `.transform()`. 2.x emitted a
+   best-effort schema silently — `z.date()` became `{type: "string", format:
+   "date-time"}`, `z.map()` an array of pairs. **The common case is a `z.date()`
+   output field:** return `date.toISOString()` and declare
+   `z.string().datetime()` (or `z.iso.datetime()`).
+5. **`makeRegistry()` throws when a tool's input or output is not a
+   `z.object`** (MCP requires `type: "object"`). Wrap the value:
+   `z.object({ result: … })`.
+6. **`ToolRegistry` has a new required member, `allows(def, ctx?)`**, and
+   `toMcpTools()` takes an optional second argument. Only a hand-written
+   `ToolRegistry` implementation breaks; build it with `makeRegistry()`.
+7. **"Invalid arguments" text changes wording**: the per-field lines come from
+   Zod 4's messages (`Invalid input: expected string, received number`, was
+   `Expected string, received number`). Rendered output is not covered by
+   semver; listed because a test that snapshots the text will notice.
+8. **The SDK dependency floor is unchanged (`^1.29.0`)** — 1.29 already accepts
+   `zod ^3.25 || ^4`. Listed so nobody hunts for it.
+
+Additive, no action needed: `toMcpSchema()`, the registry `filter` option and
+the `ctx` argument to `dispatch`, and the `@george43g/mcp-kit/testing` entry.
+
+Add one test so this never regresses silently:
+
+```ts
+import { assertMcpConformance } from "@george43g/mcp-kit/testing";
+it("tools conform", () => void assertMcpConformance(makeAppRegistry()));
+```
+
 ## Upgrading to 1.0.0
 
 **One breaking change, and it affects you only if you register `devOnly` tools.**
@@ -145,6 +286,52 @@ buildDispatcher: 1 devOnly tool(s) registered with no devOnlyEnabled predicate:
 **Migration is one line** — pass the predicate, as shown in *Dev-only tools*
 above. If you have no `devOnly` tools, there is nothing to do.
 
+### Upgrading to 2.0.0 — declare `@george43g/robustness` yourself
+
+**`robustness` moved from `dependencies` to `peerDependencies`.** If your app
+already depends on `@george43g/robustness` directly — as every known consumer
+does, and as the generated template does — **there is nothing to do**. If it does
+not, add it.
+
+```jsonc
+// your package.json
+"dependencies": {
+  "@george43g/robustness": ">=0.13.0 <1"   // or a caret; any 0.x satisfies the peer
+}
+```
+
+**What this fixes, and it is not cosmetic.** As a plain dependency with a
+*floor*, mcp-kit could resolve its **own second copy** of robustness whenever the
+app's range and mcp-kit's stopped overlapping. The logger keeps prefix and file
+state at module scope, so two copies means **two independent loggers**:
+`setLogFilePrefix` in your app cannot reach the instance mcp-kit's `perf()` spans
+write through, and dispatch spans silently land in the shared `$TMPDIR/mcp/`
+bucket no matter how correctly your app brands itself.
+
+That was live in **1.0.0**, whose floor was `>=0.12.0 <1`: an app on `^0.11.0`
+that bumped mcp-kit alone got exactly this split. **2.0.0 removes the failure
+mode by construction** — a peer is supplied by the consumer, so there is only
+ever one instance. The peer range is deliberately wide (`>=0.11.0 <1`, every
+symbol mcp-kit imports exists at 0.11.0), so no consumer is forced to move.
+
+`tui-kit` has always declared robustness this way; mcp-kit was the outlier.
+
+Verify with the one line that settles it:
+
+```sh
+grep -oE "@george43g/robustness@[0-9.]+" pnpm-lock.yaml | sort -u
+```
+
+One line is correct. Two means something still resolves its own copy.
+
+**The generalisable lesson:** a plain dependency with a *wide* range behaves like
+a peer — right up until the ranges stop overlapping. Two individually safe
+changes (raising a floor, cutting a major) were jointly hazardous. Found by
+`up-bank-mcp`.
+Found by `up-bank-mcp` as range arithmetic over the published manifests.
+**Not yet observed in a resolved tree by anyone** — treat the ordering as cheap
+insurance rather than a reproduction.
+
 **Why a throw and not a flipped default.** Before 1.0.0, omitting the predicate
 left dev-only tools *callable* — hidden from `tools/list` and answering by name.
 Two consumers hit that independently, and one measured a dev-only log reader

package/dist/dispatch.d.ts

@@ -17,7 +17,7 @@
  * The exported `buildDispatcher` returns a function whose shape matches the
  * SDK's `CallToolRequest` handler.
  */
-import type { ContentBlock, ToolRegistry } from "./tool-registry.js";
+import type { ContentBlock, ToolFilterContext, ToolRegistry } from "./tool-registry.js";
 export interface ToolResult {
     content: ContentBlock[];
     structuredContent?: unknown;
@@ -73,6 +73,14 @@ 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>;
 export declare function buildDispatcher(opts: BuildDispatcherOptions): Dispatch;
 //# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgCrE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAUlG,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,QAAQ,CA6GtE"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAgCxF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,YAAY,CAAC;IACvB,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,CACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,WAAW,EACpB,GAAG,CAAC,EAAE,iBAAiB,KACpB,OAAO,CAAC,UAAU,CAAC,CAAC;AAYzB,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,QAAQ,CAiHtE"}

package/dist/dispatch.js

@@ -55,7 +55,9 @@ function defaultTimeoutMs() {
     return envNum("MCP_TOOL_TIMEOUT_DEFAULT_MS", 30_000);
 }
 function formatZodError(err) {
-    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) {
     // Make the ambiguous state unrepresentable, at construction, before a single
@@ -72,7 +74,7 @@ export function buildDispatcher(opts) {
         }
     }
     const fallback = defaultTimeoutMs();
-    return async (name, args, signal) => {
+    return async (name, args, signal, ctx = {}) => {
         noteActivity();
         opts.onCall?.(name);
         const def = opts.registry.get(name);
@@ -84,7 +86,11 @@ export function buildDispatcher(opts) {
         // 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);
-        if (!def || devGated) {
+        // 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 || filtered) {
             opts.onError?.(name, new Error("unknown_tool"));
             return {
                 content: [

package/dist/dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -4,8 +4,8 @@ export { type WrapInstructionsResult, wrapInstructions, wrapToolError, wrapUntru
 export type { BuildResourcesHandlerOptions, ResourceContent, ResourceHandlers, ResourceListEntry, ResourcesProvider, ResourceTemplate, } from "./resources.js";
 export { buildResourcesHandler } from "./resources.js";
 export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
-export type { AnyToolDefinition, ContentBlock, ToolDefinition, ToolRegistry, } from "./tool-registry.js";
-export { makeRegistry } from "./tool-registry.js";
+export type { AnyToolDefinition, AnyZodSchema, ContentBlock, MakeRegistryOptions, McpJsonSchema, McpSchemaIo, ToolDefinition, ToolFilter, ToolFilterContext, ToolRegistry, } 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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,4BAA4B,EAC5B,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,4BAA4B,EAC5B,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@ export { buildDispatcher } from "./dispatch.js";
 export { wrapInstructions, wrapToolError, wrapUntrusted, } from "./prompt-injection.js";
 export { buildResourcesHandler } from "./resources.js";
 export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
-export { makeRegistry } from "./tool-registry.js";
+export { makeRegistry, toMcpSchema } from "./tool-registry.js";
 export { startHttpServer } from "./transports/http.js";
 export { startStdio } from "./transports/stdio.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAO1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAEL,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAa1E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `@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 type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type AnyToolDefinition, type ToolRegistry } from "./tool-registry.js";
+/** Anything `assertMcpConformance` can check: a registry, its definitions, or a wire `tools/list`. */
+export type ConformanceSource = ToolRegistry | readonly AnyToolDefinition[] | readonly Tool[];
+/** Known-good values for one tool. Each must validate against the tool's wire schema. */
+export interface ConformanceSamples {
+    input?: readonly unknown[];
+    output?: readonly unknown[];
+}
+export interface ConformanceOptions {
+    /**
+     * Known-good values per tool name. Input samples are validated against
+     * `inputSchema`, output samples against `outputSchema` — under Ajv, i.e. as
+     * a client sees them. Catches a schema that compiles but rejects real data.
+     * A sample for a tool name that is not in the source is itself a failure, so
+     * a renamed tool cannot silently stop being checked.
+     */
+    samples?: Readonly<Record<string, ConformanceSamples>>;
+}
+export interface ConformanceReport {
+    /** Names of the tools checked, in source order. */
+    tools: string[];
+}
+export interface StructuredValidation {
+    valid: boolean;
+    /** One line per problem; empty when `valid`. */
+    errors: string[];
+}
+/** Thrown by `assertMcpConformance`; `problems` holds one line per failure. */
+export declare class McpConformanceError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * 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 declare function assertMcpConformance(source: ConformanceSource, opts?: ConformanceOptions): ConformanceReport;
+/**
+ * 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 declare function validateStructured(tool: Tool | AnyToolDefinition, result: {
+    structuredContent?: unknown;
+    isError?: boolean | undefined;
+} | Record<string, unknown>): StructuredValidation;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAG/D,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAU5B,sGAAsG;AACtG,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,SAAS,iBAAiB,EAAE,GAAG,SAAS,IAAI,EAAE,CAAC;AAE9F,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,+EAA+E;AAC/E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBACzB,QAAQ,EAAE,SAAS,MAAM,EAAE;CAOxC;AAuFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,EACzB,IAAI,GAAE,kBAAuB,GAC5B,iBAAiB,CA4DnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,GAAG,iBAAiB,EAG9B,MAAM,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/F,oBAAoB,CAmCtB"}

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