@george43g/mcp-kit 2.0.0 → 3.1.0

package/src/tool-registry.ts

@@ -7,12 +7,15 @@
  *   - 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";
+import { declaredArgs, findUnknownArgs } from "./unknown-args.js";
 
 /**
  * A single MCP content block a tool may emit.
@@ -31,9 +34,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;
@@ -52,6 +64,12 @@ export interface ToolDefinition<
   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>>;
   /**
@@ -75,37 +93,281 @@ 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;
+}
+
+/**
+ * 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[];
+}
+
+/** 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(defs: AnyToolDefinition[]): ToolRegistry {
+/** Read a filter's return value. Anything but `true` or a non-empty `{ deny }` is a plain refusal. */
+function decide(result: unknown): ToolFilterDecision {
+  if (result === true) return { allowed: true };
+  if (result !== null && typeof result === "object") {
+    const deny = (result as { deny?: unknown }).deny;
+    if (typeof deny === "string" && deny.trim() !== "") return { allowed: false, deny };
+  }
+  return { allowed: false };
+}
+
+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, 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) as Tool).inputSchema as McpJsonSchema)]),
+  );
+  const evaluate = (def: AnyToolDefinition, ctx: ToolFilterContext = {}): ToolFilterDecision => {
+    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 as TDef, ctx));
+    } catch {
+      return { allowed: false };
+    }
+  };
+  const allows = (def: AnyToolDefinition, ctx?: ToolFilterContext): boolean =>
+    evaluate(def, ctx).allowed;
   return {
     tools: defs,
     get(name) {
       return byName.get(name);
     },
-    toMcpTools(includeDevOnly = false): Tool[] {
+    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 as TDef)
+        ? (declared.get(def as TDef) ?? null)
+        : declaredArgs(toMcpSchema(def.input, "input", def.name));
+      return findUnknownArgs(keys, args);
+    },
+    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);
     },
   };
 }

package/src/unknown-args.ts

@@ -0,0 +1,102 @@
+/**
+ * `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 function editDistance(a: string, b: string, max = Number.POSITIVE_INFINITY): number {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev2: number[] = [];
+  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: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined;
+  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: McpJsonSchema): readonly string[] | null {
+  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: readonly string[] | null,
+  args: unknown,
+): UnknownArgument[] {
+  if (declared === null || args === null || typeof args !== "object" || Array.isArray(args)) {
+    return [];
+  }
+  const known = new Set(declared);
+  const out: UnknownArgument[] = [];
+  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;
+}