@george43g/mcp-kit 2.0.0 → 3.1.0

package/dist/unknown-args.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `strictArgs` support: which argument names a tool declares, which a call
+ * sent that it does not, and "did you mean …?" for each.
+ *
+ * Internal: nothing here is re-exported from the package. A general
+ * string-suggestion helper is not what mcp-kit is for, and every export is
+ * surface to keep stable.
+ */
+import type { McpJsonSchema, UnknownArgument } from "./tool-registry.js";
+/**
+ * Optimal-string-alignment distance: Levenshtein plus adjacent transposition,
+ * so `chatIdentifer` → `chatIdentifier` is 1 and `limti` → `limit` is 1.
+ *
+ * Returns `max + 1` as soon as the distance is known to exceed `max`, so a
+ * long unrelated key costs one row, not a full matrix.
+ */
+export declare function editDistance(a: string, b: string, max?: number): number;
+/**
+ * The closest candidate within 2 edits, or `undefined`.
+ *
+ * Two guards against noise: the distance must also be at most half the
+ * candidate's length (so `q` does not suggest `id`), and a tie goes to the
+ * candidate listed first, so the suggestion is deterministic.
+ */
+export declare function closestMatch(input: string, candidates: Iterable<string>): string | undefined;
+/**
+ * The top-level argument names an input wire schema declares, or `null` when
+ * the schema declares itself open (`additionalProperties` other than `false`,
+ * `patternProperties`, or `propertyNames`), in which case no name is unknown.
+ *
+ * Read from the wire schema rather than the Zod object so that "unknown" means
+ * exactly "not advertised to the client", for every Zod shape that converts to
+ * a top-level object: a refined or transformed `z.object`, and an intersection,
+ * which Zod 4 merges into one `properties` map.
+ */
+export declare function declaredArgs(inputSchema: McpJsonSchema): readonly string[] | null;
+/** Keys of `args` not in `declared`, each with its nearest declared name. */
+export declare function findUnknownArgs(declared: readonly string[] | null, args: unknown): UnknownArgument[];
+//# sourceMappingURL=unknown-args.d.ts.map

package/dist/unknown-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-args.d.ts","sourceRoot":"","sources":["../src/unknown-args.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,SAA2B,GAAG,MAAM,CAqBzF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAY5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAWjF;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,EAClC,IAAI,EAAE,OAAO,GACZ,eAAe,EAAE,CAYnB"}

package/dist/unknown-args.js

@@ -0,0 +1,96 @@
+/**
+ * `strictArgs` support: which argument names a tool declares, which a call
+ * sent that it does not, and "did you mean …?" for each.
+ *
+ * Internal: nothing here is re-exported from the package. A general
+ * string-suggestion helper is not what mcp-kit is for, and every export is
+ * surface to keep stable.
+ */
+/**
+ * Optimal-string-alignment distance: Levenshtein plus adjacent transposition,
+ * so `chatIdentifer` → `chatIdentifier` is 1 and `limti` → `limit` is 1.
+ *
+ * Returns `max + 1` as soon as the distance is known to exceed `max`, so a
+ * long unrelated key costs one row, not a full matrix.
+ */
+export function editDistance(a, b, max = Number.POSITIVE_INFINITY) {
+    if (Math.abs(a.length - b.length) > max)
+        return max + 1;
+    let prev2 = [];
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        let rowMin = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let d = Math.min((prev[j] ?? 0) + 1, (cur[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                d = Math.min(d, (prev2[j - 2] ?? 0) + 1);
+            }
+            cur[j] = d;
+            if (d < rowMin)
+                rowMin = d;
+        }
+        if (rowMin > max)
+            return max + 1;
+        prev2 = prev;
+        prev = cur;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * The closest candidate within 2 edits, or `undefined`.
+ *
+ * Two guards against noise: the distance must also be at most half the
+ * candidate's length (so `q` does not suggest `id`), and a tie goes to the
+ * candidate listed first, so the suggestion is deterministic.
+ */
+export function closestMatch(input, candidates) {
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const limit = Math.min(2, Math.floor(candidate.length / 2));
+        const d = editDistance(input, candidate, limit);
+        if (d <= limit && d < bestDistance) {
+            best = candidate;
+            bestDistance = d;
+        }
+    }
+    return best;
+}
+/**
+ * The top-level argument names an input wire schema declares, or `null` when
+ * the schema declares itself open (`additionalProperties` other than `false`,
+ * `patternProperties`, or `propertyNames`), in which case no name is unknown.
+ *
+ * Read from the wire schema rather than the Zod object so that "unknown" means
+ * exactly "not advertised to the client", for every Zod shape that converts to
+ * a top-level object: a refined or transformed `z.object`, and an intersection,
+ * which Zod 4 merges into one `properties` map.
+ */
+export function declaredArgs(inputSchema) {
+    const extra = inputSchema.additionalProperties;
+    if ((extra !== undefined && extra !== false) ||
+        inputSchema.patternProperties !== undefined ||
+        inputSchema.propertyNames !== undefined) {
+        return null;
+    }
+    const props = inputSchema.properties;
+    return props !== null && typeof props === "object" ? Object.keys(props) : [];
+}
+/** Keys of `args` not in `declared`, each with its nearest declared name. */
+export function findUnknownArgs(declared, args) {
+    if (declared === null || args === null || typeof args !== "object" || Array.isArray(args)) {
+        return [];
+    }
+    const known = new Set(declared);
+    const out = [];
+    for (const key of Object.keys(args)) {
+        if (known.has(key))
+            continue;
+        const suggestion = closestMatch(key, declared);
+        out.push(suggestion === undefined ? { key } : { key, suggestion });
+    }
+    return out;
+}
+//# sourceMappingURL=unknown-args.js.map

package/dist/unknown-args.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@george43g/mcp-kit",
-  "version": "2.0.0",
+  "version": "3.1.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,16 @@ 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 AnyToolDefinition,
+  type ContentBlock,
+  type ToolFilterContext,
+  type ToolFilterDecision,
+  type ToolRegistry,
+  toMcpSchema,
+  type UnknownArgument,
+} from "./tool-registry.js";
+import { declaredArgs, findUnknownArgs } from "./unknown-args.js";
 
 /**
  * Replace the absolute home-directory prefix with `~` in anything headed for a
@@ -121,14 +130,63 @@ 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");
+}
+
+/** At most this many unknown keys are named in one error; the rest are counted. */
+const MAX_UNKNOWN_REPORTED = 20;
+
+function formatUnknownArgs(unknown: UnknownArgument[]): string {
+  const lines = unknown.slice(0, MAX_UNKNOWN_REPORTED).map(({ key, suggestion }) => {
+    // The key is caller-supplied and echoed back: neutralise control characters,
+    // including the newlines sanitize() keeps, so a key cannot forge a line.
+    const shown = (sanitize(key, 128) ?? "").replace(/[\t\n\r]/g, "\uFFFD");
+    return suggestion === undefined
+      ? `unknown argument ${shown}`
+      : `unknown argument ${shown}; did you mean ${suggestion}?`;
+  });
+  const rest = unknown.length - MAX_UNKNOWN_REPORTED;
+  if (rest > 0) lines.push(`and ${rest} more unknown argument(s)`);
+  return lines.join("\n");
+}
+
+// Declared top-level argument names per definition, derived from the wire
+// input schema on first need. Weak so a definition can still be collected.
+const declaredCache = new WeakMap<AnyToolDefinition, readonly string[] | null>();
+function declaredFor(def: AnyToolDefinition): readonly string[] | null {
+  if (!declaredCache.has(def)) {
+    declaredCache.set(def, declaredArgs(toMcpSchema(def.input, "input", def.name)));
+  }
+  return declaredCache.get(def) ?? null;
+}
+
+function unknownArgsHint(def: AnyToolDefinition): string {
+  const declared = declaredFor(def) ?? [];
+  return declared.length === 0
+    ? "This tool takes no arguments."
+    : `Valid arguments: ${declared.join(", ")}.`;
 }
 
 export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
@@ -149,7 +207,21 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
   }
 
   const fallback = defaultTimeoutMs();
-  return async (name, args, signal) => {
+  const { registry } = opts;
+  // A registry built by `makeRegistry()` has both methods; a hand-written one
+  // from 3.0 may not, and still gets the boolean gate and per-tool strictArgs.
+  const evaluate = (def: AnyToolDefinition, ctx: ToolFilterContext): ToolFilterDecision =>
+    registry.evaluate
+      ? registry.evaluate(def, ctx)
+      : registry.allows(def, ctx)
+        ? { allowed: true }
+        : { allowed: false };
+  const unknownArgs = (def: AnyToolDefinition, args: unknown): UnknownArgument[] => {
+    if (registry.unknownArgs) return registry.unknownArgs(def, args);
+    if (def.strictArgs !== true) return [];
+    return findUnknownArgs(declaredFor(def), args);
+  };
+  return async (name, args, signal, ctx = {}) => {
     noteActivity();
     opts.onCall?.(name);
     const def = opts.registry.get(name);
@@ -162,8 +234,24 @@ 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.
+    // Evaluated only for a tool that exists and is not dev-gated, so a deny
+    // reason can never reveal a dev-only tool.
+    const decision: ToolFilterDecision =
+      def !== undefined && !devGated ? evaluate(def, ctx) : { allowed: false };
+
+    // `{ deny }`: the filter chose to tell the caller why, so it can recover.
+    if (!decision.allowed && decision.deny !== undefined) {
+      opts.onError?.(name, new Error("tool_denied"));
+      return {
+        content: [{ type: "text", text: wrapToolError(name, decision.deny) }],
+        isError: true,
+      };
+    }
 
-    if (!def || devGated) {
+    if (!def || !decision.allowed) {
       opts.onError?.(name, new Error("unknown_tool"));
       return {
         content: [
@@ -176,6 +264,22 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
       };
     }
 
+    // strictArgs: refuse an undeclared argument name before parsing, because
+    // parsing would strip it silently and run the handler without it.
+    const unknown = unknownArgs(def, args ?? {});
+    if (unknown.length > 0) {
+      opts.onError?.(name, new Error("unknown_arguments"));
+      return {
+        content: [
+          {
+            type: "text",
+            text: wrapToolError(name, formatUnknownArgs(unknown), unknownArgsHint(def)),
+          },
+        ],
+        isError: true,
+      };
+    }
+
     const parsed = def.input.safeParse(args ?? {});
     if (!parsed.success) {
       opts.onError?.(name, parsed.error);

package/src/index.ts

@@ -23,11 +23,21 @@ export { buildResourcesHandler } from "./resources.js";
 export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
 export type {
   AnyToolDefinition,
+  AnyZodSchema,
   ContentBlock,
+  MakeRegistryOptions,
+  McpJsonSchema,
+  McpSchemaIo,
   ToolDefinition,
+  ToolDeny,
+  ToolFilter,
+  ToolFilterContext,
+  ToolFilterDecision,
+  ToolFilterResult,
   ToolRegistry,
+  UnknownArgument,
 } 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";

package/src/testing.ts

@@ -0,0 +1,303 @@
+/**
+ * `@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 { Ajv2020, type ErrorObject, type ValidateFunction } from "ajv/dist/2020.js";
+import addFormatsModule from "ajv-formats";
+import {
+  type AnyToolDefinition,
+  type McpJsonSchema,
+  type ToolRegistry,
+  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 as unknown as { default?: unknown }).default ??
+  addFormatsModule) as (ajv: Ajv2020) => Ajv2020;
+
+const DIALECT_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+
+/** 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 class McpConformanceError extends Error {
+  readonly problems: readonly string[];
+  constructor(problems: readonly string[]) {
+    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(): Ajv2020 {
+  const ajv = new Ajv2020({ strict: true, allowUnionTypes: true, allErrors: true });
+  addFormats(ajv);
+  return ajv;
+}
+
+function formatAjvErrors(errors: ErrorObject[] | null | undefined): string {
+  return (errors ?? [])
+    .map((e) => `${e.instancePath || "(root)"} ${e.message ?? ""}`.trim())
+    .join("; ");
+}
+
+interface WireTool {
+  name: string;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+}
+
+function isRegistry(source: ConformanceSource): source is ToolRegistry {
+  return !Array.isArray(source) && typeof (source as ToolRegistry).toMcpTools === "function";
+}
+
+function isDefinition(entry: AnyToolDefinition | Tool): entry is AnyToolDefinition {
+  return "input" in entry && "output" in entry;
+}
+
+/** Convert definitions to wire shape, recording a conversion throw as a problem. */
+function toWire(entry: AnyToolDefinition | Tool, problems: string[]): WireTool {
+  if (!isDefinition(entry)) return entry as WireTool;
+  const wire: WireTool = { name: entry.name };
+  for (const io of ["input", "output"] as const) {
+    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 as Error).message);
+    }
+  }
+  return wire;
+}
+
+function compileWireSchema(
+  ajv: Ajv2020,
+  tool: string,
+  field: "inputSchema" | "outputSchema",
+  schema: unknown,
+  problems: string[],
+): ValidateFunction | undefined {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    problems.push(`${tool}: ${field} is not a JSON Schema object.`);
+    return undefined;
+  }
+  const s = schema as Record<string, unknown>;
+  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 as Error).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: ConformanceSource,
+  opts: ConformanceOptions = {},
+): ConformanceReport {
+  const problems: string[] = [];
+  const entries: readonly (AnyToolDefinition | Tool)[] = isRegistry(source) ? source.tools : source;
+  const ajv = makeAjv();
+  const seen = new Set<string>();
+  const names: string[] = [];
+  const validators = new Map<
+    string,
+    { input?: ValidateFunction | undefined; output?: ValidateFunction | undefined }
+  >();
+
+  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: { input?: ValidateFunction | undefined; output?: ValidateFunction | undefined } = {};
+    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"] as const) {
+      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: Tool | AnyToolDefinition,
+  // `Record<string, unknown>` admits the SDK client's `callTool()` return type,
+  // whose union includes the legacy `{ toolResult }` shape.
+  result: { structuredContent?: unknown; isError?: boolean | undefined } | Record<string, unknown>,
+): StructuredValidation {
+  const { structuredContent, isError } = result as {
+    structuredContent?: unknown;
+    isError?: boolean;
+  };
+  let outputSchema: unknown;
+  if (isDefinition(tool)) {
+    try {
+      outputSchema = toMcpSchema(tool.output, "output", tool.name) satisfies McpJsonSchema;
+    } catch (err) {
+      return { valid: false, errors: [(err as Error).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: string[] = [];
+  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"}`,
+    ),
+  };
+}