@george43g/mcp-kit 3.0.0 → 3.1.0

package/README.md

@@ -62,6 +62,78 @@ server.setRequestHandler(CallToolRequestSchema, async (req, extra) =>
   means for your tools.
 - Synchronous, evaluated per request. **A throwing filter counts as `false`**.
 
+### Refusing with a reason: `{ deny }` (3.1.0)
+
+`false` makes a tool look like it does not exist, which is right when its
+existence is the secret and a dead end when the caller could fix the problem.
+Return `{ deny: "reason" }` instead and the tool is hidden from `tools/list`
+the same way, but a `tools/call` to it gets the reason:
+
+```ts
+const registry = makeRegistry(tools, {
+  filter: (tool, ctx) =>
+    hasScopes(ctx, tool.scopes) ||
+    { deny: "not available. You may need to re-authenticate with additional scopes" },
+});
+
+await dispatch("gmail_send", { to: "…" });
+// → { isError: true, content: [{ type: "text", text:
+//     'Tool "gmail_send" failed: not available. You may need to re-authenticate with additional scopes' }] }
+```
+
+- The reason is wrapped like every other dispatcher error
+  (`Tool "<name>" failed: <deny>`). Write it as a sentence an agent can act on.
+- `false` keeps the unknown-tool wording, a throw still counts as `false`, and
+  so does `{ deny: "" }`: an empty reason tells the caller nothing.
+- A gated `devOnly` tool answers as unknown even if the filter would deny it
+  with a reason; the filter is not consulted for it.
+- `registry.allows()` still returns a boolean (`false` for `{ deny }`).
+  `registry.evaluate(def, ctx)` returns `{ allowed: true }` or
+  `{ allowed: false, deny? }`. It is optional on the `ToolRegistry` type, so a
+  hand-written 3.0 registry still compiles; the dispatcher falls back to
+  `allows()` for one, and its refusals then use the unknown-tool wording.
+
+## Strict arguments: `strictArgs` (3.1.0, off by default)
+
+Zod strips an argument the schema does not declare. So when an agent misspells
+an OPTIONAL argument, the call succeeds and the handler runs on the default as
+if the argument had never been sent. Nothing tells the agent it was ignored.
+`strictArgs` refuses the call instead, before parsing and before the handler:
+
+```ts
+const registry = makeRegistry(tools, { strictArgs: true }); // every tool
+const chat: ToolDefinition = { /* … */ strictArgs: false }; // a tool opts back out
+
+await dispatch("chat_history", { chatIdentifer: "x", cursor: "c" });
+// Tool "chat_history" failed: unknown argument chatIdentifer; did you mean chatIdentifier?
+// unknown argument cursor
+// Hint: Valid arguments: chatIdentifier, limit.
+```
+
+- **Set it on the registry, override it per tool.** `ToolDefinition.strictArgs`
+  wins over `makeRegistry`'s `strictArgs` in either direction.
+- **"Unknown" means "not in the advertised `inputSchema`'s top-level
+  `properties`."** So it behaves the same for a refined or transformed
+  `z.object` and for an intersection, which Zod merges into one object.
+- **The advertised `inputSchema` does not change.** No `additionalProperties:
+  false` is added; clients see the same open schema whether this is on or off.
+- **Valid input parses exactly as before.** The check only compares argument
+  names; parsing still runs the tool's own schema, so defaults and transforms
+  are untouched.
+- **Top level only.** A nested `z.object` still strips unknown keys. To reject
+  them, declare that field `z.strictObject(…)`; Zod then reports it as
+  `Invalid arguments: … Unrecognized key: "frm"`, without a suggestion.
+- **An input that declares itself open is not checked**: `z.looseObject`,
+  `.catchall()` or `z.record` at the top level has no unknown keys.
+- A suggestion is offered when a declared name is within 2 edits (insertion,
+  deletion, substitution or swapping two adjacent letters), and those edits
+  are at most half its length. At most 20 unknown keys are named per error.
+  Echoed keys have control characters and newlines replaced.
+- `registry.unknownArgs(def, args)` returns `[{ key, suggestion? }]`, and is
+  optional on the type for the same reason as `evaluate`. Without it, the
+  dispatcher still honours a tool's own `strictArgs: true`.
+- The error text is rendered output and is not covered by semver.
+
 ## Testing: `@george43g/mcp-kit/testing`
 
 ```ts

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, ToolFilterContext, ToolRegistry } from "./tool-registry.js";
+import { type ContentBlock, type ToolFilterContext, type ToolRegistry } from "./tool-registry.js";
 export interface ToolResult {
     content: ContentBlock[];
     structuredContent?: unknown;

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,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"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEtB,KAAK,YAAY,EAGlB,MAAM,oBAAoB,CAAC;AAiC5B,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;AA8CzB,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,QAAQ,CA2JtE"}

package/dist/dispatch.js

@@ -21,6 +21,8 @@ import { homedir } from "node:os";
 import { envNum, error as logError, warn as logWarn, noteActivity, perf, ToolTimeoutError, withTimeout, } from "@george43g/robustness";
 import { wrapToolError } from "./prompt-injection.js";
 import { sanitize } from "./sanitize.js";
+import { toMcpSchema, } from "./tool-registry.js";
+import { declaredArgs, findUnknownArgs } from "./unknown-args.js";
 /**
  * Replace the absolute home-directory prefix with `~` in anything headed for a
  * log sink.
@@ -59,6 +61,37 @@ function formatZodError(err) {
         .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) {
+    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();
+function declaredFor(def) {
+    if (!declaredCache.has(def)) {
+        declaredCache.set(def, declaredArgs(toMcpSchema(def.input, "input", def.name)));
+    }
+    return declaredCache.get(def) ?? null;
+}
+function unknownArgsHint(def) {
+    const declared = declaredFor(def) ?? [];
+    return declared.length === 0
+        ? "This tool takes no arguments."
+        : `Valid arguments: ${declared.join(", ")}.`;
+}
 export function buildDispatcher(opts) {
     // Make the ambiguous state unrepresentable, at construction, before a single
     // request can be served. See `devOnlyEnabled` above for why this is a throw
@@ -74,6 +107,21 @@ export function buildDispatcher(opts) {
         }
     }
     const fallback = defaultTimeoutMs();
+    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, ctx) => registry.evaluate
+        ? registry.evaluate(def, ctx)
+        : registry.allows(def, ctx)
+            ? { allowed: true }
+            : { allowed: false };
+    const unknownArgs = (def, args) => {
+        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);
@@ -89,8 +137,18 @@ export function buildDispatcher(opts) {
         // 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) {
+        // 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 = 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 || !decision.allowed) {
             opts.onError?.(name, new Error("unknown_tool"));
             return {
                 content: [
@@ -102,6 +160,21 @@ export function buildDispatcher(opts) {
                 isError: true,
             };
         }
+        // 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/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,7 +4,7 @@ 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, AnyZodSchema, ContentBlock, MakeRegistryOptions, McpJsonSchema, McpSchemaIo, ToolDefinition, ToolFilter, ToolFilterContext, ToolRegistry, } from "./tool-registry.js";
+export type { AnyToolDefinition, AnyZodSchema, ContentBlock, MakeRegistryOptions, McpJsonSchema, McpSchemaIo, ToolDefinition, ToolDeny, ToolFilter, ToolFilterContext, ToolFilterDecision, ToolFilterResult, ToolRegistry, UnknownArgument, } 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";

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,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"}
+{"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,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,eAAe,GAChB,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.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;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"}
+{"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;AAiB1E,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/tool-registry.d.ts

@@ -62,6 +62,12 @@ export interface ToolDefinition<TInput extends z.ZodType = AnyZodSchema, TOutput
     timeoutMs?: number;
     /** When true, only register the tool if `MCP_DEV=1`. Used for `get_logs`. */
     devOnly?: boolean;
+    /**
+     * Reject a call that carries an argument name this tool does not declare,
+     * before the handler runs. Overrides the registry's `strictArgs` for this
+     * tool, in either direction. See `MakeRegistryOptions.strictArgs`.
+     */
+    strictArgs?: boolean;
     /** Handler: receives parsed input + AbortSignal, returns structured output. */
     handler: (input: z.infer<TInput>, signal?: AbortSignal) => Promise<z.infer<TOutput>>;
     /**
@@ -101,8 +107,49 @@ export interface ToolFilterContext {
     requestInfo?: RequestInfo;
 }
 /**
- * Per-request tool gate: return `false` to hide a tool from `tools/list` AND
- * refuse calls to it.
+ * 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
@@ -112,7 +159,7 @@ export interface ToolFilterContext {
  * 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;
+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:
@@ -130,15 +177,53 @@ export interface MakeRegistryOptions<TDef extends AnyToolDefinition = AnyToolDef
      * 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;
     /**
      * Whether `def` passes the registry's filter for this request. Always `true`
-     * when no filter was configured; `false` when the filter throws.
+     * 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

package/dist/tool-registry.d.ts.map

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

package/dist/tool-registry.js

@@ -12,6 +12,7 @@
  * Schema path, so the wire contract cannot drift from the validator.
  */
 import { z } from "zod";
+import { declaredArgs, findUnknownArgs } from "./unknown-args.js";
 /**
  * Convert a Zod schema to the JSON Schema an MCP client accepts as a tool's
  * `inputSchema` / `outputSchema`.
@@ -54,6 +55,17 @@ export function toMcpSchema(schema, io, toolName) {
     }
     return json;
 }
+/** Read a filter's return value. Anything but `true` or a non-empty `{ deny }` is a plain refusal. */
+function decide(result) {
+    if (result === true)
+        return { allowed: true };
+    if (result !== null && typeof result === "object") {
+        const deny = result.deny;
+        if (typeof deny === "string" && deny.trim() !== "")
+            return { allowed: false, deny };
+    }
+    return { allowed: false };
+}
 export function makeRegistry(defs, opts = {}) {
     const byName = new Map(defs.map((d) => [d.name, d]));
     // Converted eagerly: a schema that cannot be represented throws HERE, at
@@ -70,25 +82,38 @@ export function makeRegistry(defs, opts = {}) {
             outputSchema: toMcpSchema(d.output, "output", d.name),
         },
     ]));
-    const { filter } = opts;
-    const allows = (def, ctx = {}) => {
+    const { filter, strictArgs = false } = opts;
+    // Derived from the wire schema computed above, once per definition.
+    const declared = new Map(defs.map((d) => [d, declaredArgs(wire.get(d).inputSchema)]));
+    const evaluate = (def, ctx = {}) => {
         if (!filter)
-            return true;
+            return { allowed: true };
         try {
             // Only definitions from `defs` reach here in practice; the dispatcher
             // looks them up through `get()`.
-            return filter(def, ctx) === true;
+            return decide(filter(def, ctx));
         }
         catch {
-            return false;
+            return { allowed: false };
         }
     };
+    const allows = (def, ctx) => evaluate(def, ctx).allowed;
     return {
         tools: defs,
         get(name) {
             return byName.get(name);
         },
         allows,
+        evaluate,
+        unknownArgs(def, args) {
+            if (!(def.strictArgs ?? strictArgs))
+                return [];
+            // A definition from outside `defs` has no precomputed entry; derive it.
+            const keys = declared.has(def)
+                ? (declared.get(def) ?? null)
+                : declaredArgs(toMcpSchema(def.input, "input", def.name));
+            return findUnknownArgs(keys, args);
+        },
         toMcpTools(includeDevOnly = false, ctx = {}) {
             return defs
                 .filter((d) => (includeDevOnly || !d.devOnly) && allows(d, ctx))

package/dist/tool-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AA4OlE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,WAAW,CAAC,MAAiB,EAAE,EAAe,EAAE,QAAiB;IAC/E,MAAM,KAAK,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,QAAQ,KAAK,EAAE,SAAS,CAAC;IAC1F,IAAI,IAA6B,CAAC;IAClC,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAG9E,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,0CAA2C,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI;YACvG,+GAA+G;YAC/G,0CAA0C,EAC5C,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACpB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,0DAA0D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;YAClH,mHAAmH,CACtH,CAAC;IACJ,CAAC;IACD,OAAO,IAAqB,CAAC;AAC/B,CAAC;AAED,sGAAsG;AACtG,SAAS,MAAM,CAAC,MAAe;IAC7B,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,GAAI,MAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACtF,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,OAAkC,EAAE;IAEpC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,yEAAyE;IACzE,uEAAuE;IACvE,sEAAsE;IACtE,mDAAmD;IACnD,MAAM,IAAI,GAAG,IAAI,GAAG,CAClB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACd,CAAC;QACD;YACE,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;YAClD,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC;SACnC;KACrB,CAAC,CACH,CAAC;IACF,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IAC5C,oEAAoE;IACpE,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,CAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAU,CAAC,WAA4B,CAAC,CAAC,CAAC,CACvF,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,GAAsB,EAAE,MAAyB,EAAE,EAAsB,EAAE;QAC3F,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,sEAAsE;YACtE,iCAAiC;YACjC,OAAO,MAAM,CAAC,MAAM,CAAC,GAAW,EAAE,GAAG,CAAC,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,GAAsB,EAAE,GAAuB,EAAW,EAAE,CAC1E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC;IAC7B,OAAO;QACL,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,IAAI;YACN,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM;QACN,QAAQ;QACR,WAAW,CAAC,GAAG,EAAE,IAAI;YACnB,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,IAAI,UAAU,CAAC;gBAAE,OAAO,EAAE,CAAC;YAC/C,wEAAwE;YACxE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAW,CAAC;gBACpC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAW,CAAC,IAAI,IAAI,CAAC;gBACrC,CAAC,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5D,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,UAAU,CAAC,cAAc,GAAG,KAAK,EAAE,MAAyB,EAAE;YAC5D,OAAO,IAAI;iBACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;iBAC/D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAS,CAAC,CAAC;QACrC,CAAC;KACF,CAAC;AACJ,CAAC"}

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": "3.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",

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, ToolFilterContext, 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
@@ -146,6 +155,40 @@ function formatZodError(err: ZodError): string {
     .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 {
   // Make the ambiguous state unrepresentable, at construction, before a single
   // request can be served. See `devOnlyEnabled` above for why this is a throw
@@ -164,6 +207,20 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
   }
 
   const fallback = defaultTimeoutMs();
+  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);
@@ -180,9 +237,21 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
     // 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);
+    // 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 };
 
-    if (!def || devGated || filtered) {
+    // `{ 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 || !decision.allowed) {
       opts.onError?.(name, new Error("unknown_tool"));
       return {
         content: [
@@ -195,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

@@ -29,9 +29,13 @@ export type {
   McpJsonSchema,
   McpSchemaIo,
   ToolDefinition,
+  ToolDeny,
   ToolFilter,
   ToolFilterContext,
+  ToolFilterDecision,
+  ToolFilterResult,
   ToolRegistry,
+  UnknownArgument,
 } from "./tool-registry.js";
 export { makeRegistry, toMcpSchema } from "./tool-registry.js";
 export type { HttpServerHandle, HttpServerOptions } from "./transports/http.js";

package/src/tool-registry.ts

@@ -15,6 +15,7 @@
 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.
@@ -63,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>>;
   /**
@@ -109,8 +116,48 @@ export interface ToolFilterContext {
 }
 
 /**
- * Per-request tool gate: return `false` to hide a tool from `tools/list` AND
- * refuse calls to it.
+ * 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
@@ -123,7 +170,7 @@ export interface ToolFilterContext {
 export type ToolFilter<TDef extends AnyToolDefinition = AnyToolDefinition> = (
   tool: TDef,
   ctx: ToolFilterContext,
-) => boolean;
+) => ToolFilterResult;
 
 /**
  * `TDef` lets a consumer carry its own per-tool metadata into the filter
@@ -142,6 +189,30 @@ export interface MakeRegistryOptions<TDef extends AnyToolDefinition = AnyToolDef
    * 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 {
@@ -149,9 +220,23 @@ export interface ToolRegistry {
   get(name: string): AnyToolDefinition | undefined;
   /**
    * Whether `def` passes the registry's filter for this request. Always `true`
-   * when no filter was configured; `false` when the filter throws.
+   * 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
@@ -216,6 +301,16 @@ export function toMcpSchema(schema: z.ZodType, io: McpSchemaIo, toolName?: strin
   return json as McpJsonSchema;
 }
 
+/** 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> = {},
@@ -237,23 +332,38 @@ export function makeRegistry<TDef extends AnyToolDefinition = AnyToolDefinition>
       } as unknown as Tool,
     ]),
   );
-  const { filter } = opts;
-  const allows = (def: AnyToolDefinition, ctx: ToolFilterContext = {}): boolean => {
-    if (!filter) return true;
+  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 filter(def as TDef, ctx) === true;
+      return decide(filter(def as TDef, ctx));
     } catch {
-      return false;
+      return { allowed: false };
     }
   };
+  const allows = (def: AnyToolDefinition, ctx?: ToolFilterContext): boolean =>
+    evaluate(def, ctx).allowed;
   return {
     tools: defs,
     get(name) {
       return byName.get(name);
     },
     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) && allows(d, ctx))

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;
+}