@george43g/mcp-kit 1.0.0 → 3.0.0

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"}`,
+    ),
+  };
+}

package/src/tool-registry.ts

@@ -7,12 +7,14 @@
  *   - 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 { zodToJsonSchema } from "zod-to-json-schema";
+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.
@@ -31,9 +33,18 @@ export type ContentBlock =
   /** `data` is RAW base64 — no `data:` URI prefix, and not a path. */
   | { type: "image"; data: string; mimeType: string };
 
+/**
+ * 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 ZodTypeAny = ZodTypeAny,
-  TOutput extends ZodTypeAny = ZodTypeAny,
+  TInput extends z.ZodType = AnyZodSchema,
+  TOutput extends z.ZodType = AnyZodSchema,
 > {
   /** Snake_case tool name, e.g. "health_check". */
   name: string;
@@ -75,37 +86,178 @@ export interface ToolDefinition<
 // boundary alias used internally.
 export type AnyToolDefinition = ToolDefinition<any, any>;
 
+/**
+ * What a tool filter is told about the request it is answering.
+ *
+ * A structural subset of the SDK's `RequestHandlerExtra` — the second argument
+ * every `server.setRequestHandler` callback receives — so a handler can pass
+ * its `extra` straight through: `registry.toMcpTools(dev, extra)` and
+ * `dispatch(name, args, extra.signal, extra)`.
+ *
+ * Every field is optional because most calls carry none of them: stdio has no
+ * auth, and an in-process caller (a CLI, a REPL, a test) has no request at all.
+ * A filter that gates on scopes therefore sees `authInfo === undefined` there,
+ * and should decide deliberately what that means for its tools.
+ */
+export interface ToolFilterContext {
+  /** Validated access token, when the transport authenticated the request (HTTP + OAuth). */
+  authInfo?: AuthInfo;
+  /** Transport session id, when the transport has sessions. */
+  sessionId?: string;
+  /** The originating HTTP request's headers, when there was one. */
+  requestInfo?: RequestInfo;
+}
+
+/**
+ * Per-request tool gate: return `false` to hide a tool from `tools/list` AND
+ * refuse calls to it.
+ *
+ * Synchronous on purpose: it runs inside `toMcpTools()`, which is synchronous,
+ * and a scope check is a set lookup. Resolve anything slow (a token
+ * introspection) before the request reaches the registry — the HTTP transport's
+ * auth layer is where that belongs.
+ *
+ * A filter that THROWS is treated as `false` (fail closed): a bug in the gate
+ * must not expose the tool it was written to protect.
+ */
+export type ToolFilter<TDef extends AnyToolDefinition = AnyToolDefinition> = (
+  tool: TDef,
+  ctx: ToolFilterContext,
+) => boolean;
+
+/**
+ * `TDef` lets a consumer carry its own per-tool metadata into the filter
+ * without a cast: declare `interface ScopedTool extends ToolDefinition { scopes:
+ * string[] }`, pass `ScopedTool[]`, and the filter receives `ScopedTool`.
+ *
+ * The filter is called on EVERY `toMcpTools()` / dispatch — never cached — so a
+ * predicate that reads live state (scopes granted by a re-auth a minute ago)
+ * sees the current value. Read that state inside the predicate.
+ */
+export interface MakeRegistryOptions<TDef extends AnyToolDefinition = AnyToolDefinition> {
+  /**
+   * Optional per-request gate, applied by BOTH `toMcpTools()` and the
+   * dispatcher. It lives on the registry rather than on either consumer so the
+   * listing and the call path cannot disagree: a filter that only hid a tool
+   * from `tools/list` would leave it callable by name (see `devOnly`).
+   */
+  filter?: ToolFilter<TDef>;
+}
+
 export interface ToolRegistry {
   readonly tools: readonly AnyToolDefinition[];
   get(name: string): AnyToolDefinition | undefined;
-  /** Convert all tools (or just enabled ones) to MCP SDK shape. */
-  toMcpTools(includeDevOnly?: boolean): Tool[];
+  /**
+   * Whether `def` passes the registry's filter for this request. Always `true`
+   * when no filter was configured; `false` when the filter throws.
+   */
+  allows(def: AnyToolDefinition, ctx?: ToolFilterContext): boolean;
+  /**
+   * Convert tools to MCP SDK shape: devOnly tools only when `includeDevOnly`,
+   * and only tools the filter allows for `ctx`. Schemas are converted once, at
+   * `makeRegistry()`, so a call here never throws for a schema problem.
+   */
+  toMcpTools(includeDevOnly?: boolean, ctx?: ToolFilterContext): Tool[];
 }
 
-export 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 function toMcpSchema(schema: z.ZodType, io: McpSchemaIo, toolName?: string): McpJsonSchema {
+  const where = toolName === undefined ? `${io} schema` : `tool "${toolName}" ${io} schema`;
+  let json: Record<string, unknown>;
+  try {
+    json = z.toJSONSchema(schema, { target: "draft-2020-12", io, reused: "inline" }) as Record<
+      string,
+      unknown
+    >;
+  } catch (err) {
+    throw new Error(
+      `toMcpSchema: ${where} cannot be represented in JSON Schema: ${(err as Error)?.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 as McpJsonSchema;
+}
+
+export function makeRegistry<TDef extends AnyToolDefinition = AnyToolDefinition>(
+  defs: TDef[],
+  opts: MakeRegistryOptions<TDef> = {},
+): ToolRegistry {
   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),
+      } as unknown as Tool,
+    ]),
+  );
+  const { filter } = opts;
+  const allows = (def: AnyToolDefinition, ctx: ToolFilterContext = {}): boolean => {
+    if (!filter) return true;
+    try {
+      // Only definitions from `defs` reach here in practice; the dispatcher
+      // looks them up through `get()`.
+      return filter(def as TDef, ctx) === true;
+    } catch {
+      return false;
+    }
+  };
   return {
     tools: defs,
     get(name) {
       return byName.get(name);
     },
-    toMcpTools(includeDevOnly = false): Tool[] {
+    allows,
+    toMcpTools(includeDevOnly = false, ctx: ToolFilterContext = {}): Tool[] {
       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),
-            }) as unknown as Tool,
-        );
+        .filter((d) => (includeDevOnly || !d.devOnly) && allows(d, ctx))
+        .map((d) => wire.get(d) as Tool);
     },
   };
 }