@cyanheads/mcp-ts-core 0.13.8 → 0.13.10

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js

@@ -3,11 +3,12 @@
  * Constructs Context (with `uri`), checks inline auth, validates params, formats response.
  * @module src/mcp-server/resources/utils/resourceHandlerFactory
  */
+import { resolveDeclaredFailure } from '../../../core/context.js';
 import { buildHandlerContext, handlerParentContext, resolveHandlerRequest, } from '../../handlerContext.js';
-import { isInputRequiredSignal } from '../../inputRequired.js';
+import { isInputRequiredSignal, sealThrown, } from '../../inputRequired.js';
 import { parseOutputContract } from '../../outputContract.js';
 import { withRequiredScopes } from '../../transports/auth/lib/authUtils.js';
-import { McpError } from '../../../types-global/errors.js';
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
 import { asRequestCancelled, ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
 import { measureResourceExecution } from '../../../utils/internal/performance.js';
 import { requestContextService } from '../../../utils/internal/requestContext.js';
@@ -62,9 +63,10 @@ function observableResourceUri(uri) {
  * - Checks inline `auth` scopes if defined
  * - Validates params via Zod schema
  * - Formats response via `format` or JSON default
- * - Catches errors and re-throws for the SDK
+ * - Catches errors and re-throws for the SDK, with the declared recovery filled
+ *   (#579) and the read's request id added (#576)
  */
-export function createResourceHandler(def, services, notifiers, inputGate) {
+export function createResourceHandler(def, services, notifiers, capabilities) {
     const mimeType = def.mimeType ?? 'application/json';
     const formatter = def.format ?? defaultResponseFormatter;
     const resourceName = def.name ?? def.uriTemplate;
@@ -74,7 +76,7 @@ export function createResourceHandler(def, services, notifiers, inputGate) {
         // The URI template already captures the named segments; anything else is
         // query-string / caller-supplied and belongs in metrics, not logs.
         const appContext = requestContextService.createRequestContext({
-            parentContext: handlerParentContext(request),
+            parentContext: handlerParentContext(serverContext),
             operation: 'HandleResourceRead',
             additionalContext: {
                 resourceName,
@@ -94,7 +96,7 @@ export function createResourceHandler(def, services, notifiers, inputGate) {
             // outcome, so a failure in either is a failed read. Closing the span when
             // the handler returned recorded those as successes (#346).
             return await measureResourceExecution(async (spanContext, recordOutput) => {
-                const ctx = buildHandlerContext(request, services, spanContext, def.errors, inputGate, uri);
+                const ctx = buildHandlerContext(request, services, spanContext, def.errors, capabilities, uri);
                 try {
                     // Handler may return sync or async.
                     const handlerResult = await def.handler(validatedParams, ctx);
@@ -115,8 +117,10 @@ export function createResourceHandler(def, services, notifiers, inputGate) {
                 catch (error) {
                     // Inside the measurement on purpose: the completion log's
                     // `metrics.errorCode` and the span's error-code attribute are
-                    // derived from what leaves this callback (#421).
-                    throw asRequestCancelled(error, request.signal);
+                    // derived from what leaves this callback (#421). An input-required
+                    // signal leaves with its `requestState` sealed when a key is
+                    // configured, so a sealing failure is a failed read like any other.
+                    throw asRequestCancelled(await sealThrown(error, services.requestState, serverContext), request.signal);
                 }
             }, { ...appContext, resourceName }, { uri: resourceUri, mimeType });
         }
@@ -128,13 +132,37 @@ export function createResourceHandler(def, services, notifiers, inputGate) {
             // an `McpError` carrying the reason and hint (#379).
             if (isInputRequiredSignal(error))
                 return error.result;
-            // Classify without logging — the SDK logs when it catches the thrown error.
-            if (error instanceof McpError) {
-                throw error;
-            }
-            const { code, message, data } = ErrorHandler.classifyOnly(error);
-            throw new McpError(code, message, data, { cause: error });
+            // Classified without logging: the completion record carries the code.
+            const { failure } = resolveDeclaredFailure(def.errors, asMcpError(error));
+            throw withRequestId(failure, appContext.requestId);
         }
     };
 }
+/** The thrown value as an `McpError`, classified by {@link ErrorHandler.classifyOnly} when it is not one. */
+function asMcpError(error) {
+    if (error instanceof McpError)
+        return error;
+    const { code, message, data } = ErrorHandler.classifyOnly(error);
+    return new McpError(code, message, data, { cause: error });
+}
+/**
+ * The error the SDK serializes into the read's JSON-RPC `error`, carrying the
+ * read's `requestId` as `data.requestId` (#576) — the id its completion record
+ * logs — so a failure reported from the client can be matched to that record.
+ * Set after the thrown data, so the framework's value replaces a thrown one.
+ *
+ * A `-32602` whose `data` is exactly `{ uri }` passes through untouched: it is
+ * the spec's resource-not-found shape, which clients recognize by that exact
+ * `data`.
+ */
+function withRequestId(error, requestId) {
+    const { data } = error;
+    const isResourceNotFound = error.code === JsonRpcErrorCode.InvalidParams &&
+        data !== undefined &&
+        typeof data.uri === 'string' &&
+        Object.keys(data).length === 1;
+    if (isResourceNotFound)
+        return error;
+    return new McpError(error.code, error.message, { ...data, requestId }, { cause: error });
+}
 //# sourceMappingURL=resourceHandlerFactory.js.map

package/dist/mcp-server/resources/utils/resourceHandlerFactory.js.map

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

package/dist/mcp-server/server.d.ts

@@ -12,6 +12,7 @@
 import { type Implementation, McpServer, type ServerNotifier } from '@modelcontextprotocol/server';
 import type { AppConfig } from '../config/index.js';
 import type { CacheHints } from './cacheHints.js';
+import { type RequestStateSealer } from './inputRequired.js';
 import type { PromptRegistry } from './prompts/prompt-registration.js';
 import type { ResourceRegistry } from './resources/resource-registration.js';
 import type { ToolRegistry } from './tools/tool-registration.js';
@@ -57,6 +58,14 @@ export interface McpServerDeps {
      */
     notifier?: ServerNotifier;
     promptRegistry: PromptRegistry;
+    /**
+     * The process's `requestState` sealer, built once from
+     * `MCP_REQUEST_STATE_KEY`. Its `verify` becomes the instance's
+     * `requestState.verify`, so every echoed state is checked before a handler
+     * runs, on the 2025-era shim's rounds as on 2026-07-28 retries. Absent when
+     * no key is configured, and the SDK then receives no `requestState` option.
+     */
+    requestState?: RequestStateSealer;
     resourceRegistry: ResourceRegistry;
     /**
      * Human-readable display name forwarded to `new McpServer({ serverInfo })`.

package/dist/mcp-server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,SAAS,EAET,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAC;AAExF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAI5E,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,mEAAmE;IACnE,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAuFrF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,KAAK,cAAc,EACnB,SAAS,EAET,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAC;AAExF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAI5E,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,mEAAmE;IACnE,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAuFrF"}

package/dist/mcp-server/server.js

@@ -10,7 +10,7 @@
  * @module src/mcp-server/server
  */
 import { McpServer, } from '@modelcontextprotocol/server';
-import { createInputRequiredGate } from './inputRequired.js';
+import { clientCapabilityView } from './inputRequired.js';
 import { installResourceSubscriptions } from './resources/resourceSubscriptions.js';
 import { logger } from '../utils/internal/logger.js';
 import { requestContextService } from '../utils/internal/requestContext.js';
@@ -58,31 +58,32 @@ export async function createMcpServerInstance(deps) {
         // `elicitation/create` round trips over the live session) on 2025-era
         // ones, so handlers are written once.
         inputRequired: { legacyShim: true },
+        ...(deps.requestState && { requestState: { verify: deps.requestState.verify } }),
     });
+    const era = deps.era ?? 'legacy';
     // The `resources/subscribe` registry is a 2025-era mechanism: the method
     // does not exist on 2026-07-28, where the client opts in through
     // `subscriptions/listen` and the SDK filters delivery. Installing it on a
     // modern instance would leave the registry permanently empty and silently
     // drop every `ctx.notifyResourceUpdated(uri)` — the notifiers read `undefined`
     // as "no subscription tracking on this connection" and emit unconditionally.
-    const subscriptions = (deps.era ?? 'legacy') === 'legacy' ? installResourceSubscriptions(server) : undefined;
-    // The capability gate on `ctx.requestInput(...)` is a 2025-era mechanism too:
-    // there the refusal comes from the SDK's legacy shim, above the handler
-    // callback, where a factory can no longer shape it into an error envelope
-    // (#379). A modern instance is gated by the SDK itself, before any result
-    // leaves, so it takes no gate.
-    const inputGate = (deps.era ?? 'legacy') === 'legacy'
-        ? createInputRequiredGate(() => server.server.getClientCapabilities())
-        : undefined;
+    const subscriptions = era === 'legacy' ? installResourceSubscriptions(server) : undefined;
+    // What the client declared, resolved per request from the source this era
+    // has (#580): the `initialize` value on a 2025-era instance, the request's
+    // envelope on a modern one. One view per instance feeds
+    // `ctx.clientCapabilities`, the filter over `ctx.inputs` (#496), and — on
+    // the 2025-era arm only, where the SDK's shim refusal cannot be shaped into
+    // an error envelope (#379) — the gate `ctx.requestInput` runs.
+    const capabilities = clientCapabilityView(era, server);
     try {
         logger.debug('Registering all MCP capabilities via registries...', context);
         // The bus reaches a modern instance only. Passing it to a legacy one would
         // route `ctx.notify*` away from the live session that can actually deliver
         // it — the 2025 era has no `subscriptions/listen` stream to publish to.
-        const bus = (deps.era ?? 'legacy') === 'modern' ? deps.notifier : undefined;
+        const bus = era === 'modern' ? deps.notifier : undefined;
         await Promise.all([
-            deps.toolRegistry.registerAll(server, subscriptions, bus, inputGate),
-            deps.resourceRegistry.registerAll(server, subscriptions, bus, inputGate),
+            deps.toolRegistry.registerAll(server, subscriptions, bus, capabilities),
+            deps.resourceRegistry.registerAll(server, subscriptions, bus, capabilities),
             deps.promptRegistry.registerAll(server),
         ]);
         logger.debug('All MCP capabilities registered successfully', context);

package/dist/mcp-server/server.js.map

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

package/dist/mcp-server/tools/tool-registration.d.ts

@@ -3,7 +3,7 @@
  * @module src/mcp-server/tools/tool-registration
  */
 import type { McpServer, ServerNotifier } from '@modelcontextprotocol/server';
-import type { InputRequiredGate } from '../inputRequired.js';
+import type { ClientCapabilityView } from '../inputRequired.js';
 import type { ResourceSubscriptions } from '../notifications.js';
 import type { AnyToolDefinition } from './utils/toolDefinition.js';
 import { type HandlerServices } from './utils/toolHandlerFactory.js';
@@ -20,8 +20,12 @@ export declare class ToolRegistry {
     /** Tracks registered tool names to detect duplicates at startup. */
     private readonly registeredNames;
     constructor(toolDefs: AnyToolDef[], services: HandlerServices);
-    /** Registers all tool definitions with the provided McpServer instance. */
-    registerAll(server: McpServer, subscriptions?: ResourceSubscriptions, bus?: ServerNotifier, inputGate?: InputRequiredGate): Promise<void>;
+    /**
+     * Registers all tool definitions with the provided McpServer instance.
+     * `capabilities` is the instance's view of what its client declared (#580),
+     * which every handler context resolves per request.
+     */
+    registerAll(server: McpServer, subscriptions?: ResourceSubscriptions, bus?: ServerNotifier, capabilities?: ClientCapabilityView): Promise<void>;
     /** Throws at startup if a tool with the same name was already registered. */
     private assertUniqueName;
     /** Registers a standard tool definition. */

package/dist/mcp-server/tools/tool-registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registration.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/tool-registration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAgB,MAAM,8BAA8B,CAAC;AAE5F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,gDAAgD,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAU3C,qBAAa,YAAY;IAKrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IAErD,YACmB,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,eAAe,EACxC;IAEJ,2EAA2E;IAC9D,WAAW,CACtB,MAAM,EAAE,SAAS,EACjB,aAAa,CAAC,EAAE,qBAAqB,EACrC,GAAG,CAAC,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA8Cf;IAED,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAUxB,4CAA4C;YAC9B,YAAY;CAkD3B"}
+{"version":3,"file":"tool-registration.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/tool-registration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAgB,MAAM,8BAA8B,CAAC;AAE5F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,gDAAgD,CAAC;AAMxD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAU3C,qBAAa,YAAY;IAKrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IAErD,YACmB,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,eAAe,EACxC;IAEJ;;;;OAIG;IACU,WAAW,CACtB,MAAM,EAAE,SAAS,EACjB,aAAa,CAAC,EAAE,qBAAqB,EACrC,GAAG,CAAC,EAAE,cAAc,EACpB,YAAY,CAAC,EAAE,oBAAoB,GAClC,OAAO,CAAC,IAAI,CAAC,CA8Cf;IAED,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAUxB,4CAA4C;YAC9B,YAAY;CAkD3B"}

package/dist/mcp-server/tools/tool-registration.js

@@ -21,8 +21,12 @@ export class ToolRegistry {
         this.toolDefs = toolDefs;
         this.services = services;
     }
-    /** Registers all tool definitions with the provided McpServer instance. */
-    async registerAll(server, subscriptions, bus, inputGate) {
+    /**
+     * Registers all tool definitions with the provided McpServer instance.
+     * `capabilities` is the instance's view of what its client declared (#580),
+     * which every handler context resolves per request.
+     */
+    async registerAll(server, subscriptions, bus, capabilities) {
         // Reset per-server uniqueness tracking — registries are shared across
         // per-request McpServer instances under HTTP serving.
         this.registeredNames.clear();
@@ -57,7 +61,7 @@ export class ToolRegistry {
         // `tools` capability, so a server with every tool disabled still answers
         // `tools/list` with an empty array rather than `-32601`.
         for (const toolDef of tools) {
-            await this.registerTool(server, toolDef, notifiers, inputGate);
+            await this.registerTool(server, toolDef, notifiers, capabilities);
         }
     }
     /** Throws at startup if a tool with the same name was already registered. */
@@ -69,7 +73,7 @@ export class ToolRegistry {
         this.registeredNames.add(name);
     }
     /** Registers a standard tool definition. */
-    async registerTool(server, tool, notifiers, inputGate) {
+    async registerTool(server, tool, notifiers, capabilities) {
         const registrationContext = requestContextService.createRequestContext({
             operation: 'ToolRegistry.registerTool',
             additionalContext: { toolName: tool.name },
@@ -77,7 +81,7 @@ export class ToolRegistry {
         logger.debug(`Registering tool: '${tool.name}'`, registrationContext);
         this.assertUniqueName(tool.name);
         await ErrorHandler.tryCatch(() => {
-            const handler = createToolHandler(tool, this.services, notifiers, inputGate);
+            const handler = createToolHandler(tool, this.services, notifiers, capabilities);
             const title = tool.title ?? tool.annotations?.title ?? deriveTitleFromName(tool.name);
             // Advertised verbatim; the same schema rejects the same arguments one
             // layer down, where a rejection can carry the framework's structured

package/dist/mcp-server/tools/tool-registration.js.map

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

package/dist/mcp-server/tools/utils/inputPrevalidation.d.ts

@@ -14,28 +14,47 @@
  *    in another case style (`max_results` for `maxResults`). Rewritten to the
  *    canonical key before parsing. A one-to-one mapping fixed ahead of time, not
  *    the nearest-key guess #232 rejected.
- * 3. **Representation repair (#234)** — a JSON-stringified array where an array
- *    was declared. Applied only *after* the parse has already failed, and kept
- *    only when it flips the arguments from invalid to valid: the author's schema
- *    is the sole arbiter, so a repair can never touch input that was already
- *    valid.
+ * 3. **Representation repair (#234, #479, #487)** — a JSON-stringified array or
+ *    object where one was declared, or an integer where a string was. Applied
+ *    only *after* the parse has already failed, and kept only when it flips the
+ *    arguments from invalid to valid: the author's schema is the sole arbiter,
+ *    so a repair can never touch input that was already valid.
+ *
+ * The drop runs first, so it also discards a key the alias stage would have
+ * resolved: an underscore spelling of a declared key (`_query`), a declared
+ * `_q` alias, an ignore-listed key a declared alias names. When the arguments
+ * then fail, repair included, the two stages run once more with the alias
+ * stage first, and that retry — with its own repair — is kept only if it
+ * validates (#563). A call the first order validates never reaches the retry,
+ * so the retry never changes which calls validate. A call neither order
+ * validates carries the retry's rejection, where the discarded keys reached
+ * their targets: a declared `_q` alias with a bad value is reported as
+ * validated under `query`, with the value's own failure, not as a dropped key
+ * beside a missing field.
  *
  * All three are on by default and each has a server-level switch on
  * `createApp({ input })` / `createWorkerHandler({ input })`. None of them
- * changes what `tools/list` advertises, and none appears in a response: a drop,
- * a rewrite, and a repair each emit one debug log and one counter increment
- * instead.
+ * changes what `tools/list` advertises. A call they rescue carries nothing
+ * about them in its response: a drop, a rewrite, and a repair each emit one
+ * debug log and one counter increment instead — for the attempt whose
+ * arguments the handler receives, never one the parse discarded. A call they
+ * cannot rescue is rejected with the rewrites and underscore-rule drops of the
+ * attempt whose rejection it carries reported (#468), since without them the caller cannot
+ * tell a bad value from a key that was moved or discarded; a repair the
+ * re-parse discarded leaves no trace there.
  *
- * The split between the two is deliberate. Counter attributes are bounded and
- * author- or framework-defined — the ignore-list entry that matched, the
- * declared key a rewrite resolved to — because a metric label carrying the
- * caller's own key text mints a permanent time series per spelling a client
- * invents (#114). The raw key and alias go to the debug log, which is where an
- * operator looks when a counter shows a new client artifact and where
- * cardinality costs nothing.
+ * The split between log and counter is deliberate. Counter attributes are
+ * bounded and author- or framework-defined — the ignore-list entry that
+ * matched, the declared key a rewrite resolved to — because a metric label
+ * carrying the caller's own key text mints a permanent time series per spelling
+ * a client invents (#114). The raw key and alias go to the debug log, which is
+ * where an operator looks when a counter shows a new client artifact and where
+ * cardinality costs nothing — and, on a rejection, back to the caller who sent
+ * them, since an error payload is per call rather than a permanent series.
  *
  * @module src/mcp-server/tools/utils/inputPrevalidation
  */
+import type { ZodError } from 'zod';
 import { type RequestContext } from '../../../utils/internal/requestContext.js';
 import type { AnyToolDefinition } from './toolDefinition.js';
 /**
@@ -54,8 +73,10 @@ export interface InputHandlingOptions {
     caseStyleAliases?: boolean;
     /**
      * Retry a failed parse once against repaired argument *values* — a
-     * JSON-stringified array parsed back into an array. `false` restores the
-     * single-parse behavior exactly. Default `true`.
+     * JSON-stringified array or object parsed back into what it encodes, or a
+     * safe integer sent where a string was expected turned into its decimal
+     * string. `false` turns the repair off, so each order of the key stages is
+     * parsed once, with the values as sent. Default `true`.
      */
     coerce?: boolean;
     /**
@@ -66,8 +87,89 @@ export interface InputHandlingOptions {
      */
     ignoreKeys?: readonly string[] | false;
 }
-/** One increment per repaired call, not per repaired value. */
-export declare function countCoerced(toolName: string, context: RequestContext | undefined): void;
+/**
+ * The repairs {@link repairRepresentations} performs, as `mcp.input.coercion`
+ * labels them, in the order a call's debug log names them — paired with how
+ * that log reads each one.
+ */
+declare const COERCION_KINDS: {
+    readonly stringified_array: 'a stringified array';
+    readonly stringified_object: 'a stringified object';
+    readonly integer_as_string: 'an integer sent for a string';
+};
+/** One repair {@link repairRepresentations} can perform. */
+export type CoercionKind = keyof typeof COERCION_KINDS;
+/** Which half of the alias stage rewrote a key. */
+type AliasKind = 'case_style' | 'declared';
+/** One Zod issue from a failed parse of the arguments. */
+type ArgumentIssue = ZodError['issues'][number];
+/**
+ * What the pre-parse stages changed that the caller wrote, reported on an
+ * argument rejection (#468) so a caller can tell a bad value from a key that
+ * was moved or discarded. Keys only, never values.
+ */
+export interface PrevalidationReport {
+    /** Root keys rewritten to their canonical spelling, in argument order. */
+    readonly aliased: ReadonlyArray<{
+        readonly alias: string;
+        readonly target: string;
+    }>;
+    /**
+     * Undeclared underscore-prefixed root keys the drop stage discarded, in
+     * argument order. An ignore-list drop is never listed: it is a client
+     * artifact the model did not write and cannot remove.
+     */
+    readonly ignored: readonly string[];
+}
+/**
+ * One key a pre-parse stage rewrote or dropped, as {@link recordPrevalidation}
+ * counts and logs it. `rule` is the ignore-list entry that matched, or
+ * {@link UNDERSCORE_RULE}.
+ */
+export type PrevalidationChange = {
+    readonly alias: string;
+    readonly aliasKind: AliasKind;
+    readonly kind: 'aliased';
+    readonly target: string;
+} | {
+    readonly key: string;
+    readonly kind: 'dropped';
+    readonly rule: string;
+};
+/** One ordering of the pre-parse stages — what {@link prevalidateToolArguments} hands the parse. */
+export interface PrevalidatedArguments {
+    /** The arguments to parse — the caller's own object when nothing applied. */
+    readonly args: unknown;
+    /**
+     * Every rewrite and drop, in the order the stages made them. Nothing is
+     * emitted while the stages run: the parse decides which attempt the handler
+     * receives, and {@link recordPrevalidation} emits that one.
+     */
+    readonly changes: readonly PrevalidationChange[];
+    /** Present only when a rewrite or an underscore-rule drop happened. */
+    readonly report?: PrevalidationReport;
+}
+/** What {@link repairRepresentations} produced. */
+export interface RepairedArguments {
+    /** The repaired arguments — the input itself when nothing was repairable. */
+    readonly args: unknown;
+    /** Each kind that fired at least once, in {@link COERCION_KINDS} order. */
+    readonly kinds: readonly CoercionKind[];
+}
+/**
+ * Emits one counter increment and one debug log per change an attempt made, in
+ * the order its stages made them. {@link parseToolArguments} calls it once per
+ * call, for the attempt whose arguments the handler receives — or, on a
+ * rejection, the first attempt, the one the rejection reports — so a key the
+ * alias-first retry rewrote never also counts as dropped (#563).
+ */
+export declare function recordPrevalidation(def: AnyToolDefinition, attempt: PrevalidatedArguments, context: RequestContext | undefined): void;
+/**
+ * One increment per repaired call and kind — a call repairing an array and an
+ * object adds one to each series, and one repairing three arrays adds one — and
+ * one debug log per call naming every kind that fired.
+ */
+export declare function countCoerced(toolName: string, kinds: readonly CoercionKind[], context: RequestContext | undefined): void;
 /**
  * `Max-Results`, `max_results`, and `maxResults` all fold to `maxresults`.
  *
@@ -77,18 +179,33 @@ export declare function countCoerced(toolName: string, context: RequestContext |
  */
 export declare function foldArgumentKey(key: string): string;
 /**
- * Runs the pre-parse half of the step — drop client-added keys, then rewrite
- * key aliases — and returns the arguments to parse.
+ * Runs the pre-parse half of the step in its first order — drop client-added
+ * keys, then rewrite key aliases — and returns the arguments to parse, with
+ * what the two stages changed that the caller wrote.
  *
- * Returns the caller's own object unchanged when nothing applied, so the common
- * path allocates nothing. Non-object arguments are handed straight back: the
- * schema's own rejection already says what arrived.
+ * `args` is the caller's own object when nothing applied. Non-object arguments
+ * are handed straight back: the schema's own rejection already says what
+ * arrived.
  */
-export declare function prevalidateToolArguments(def: AnyToolDefinition, args: unknown, options: InputHandlingOptions | undefined, context: RequestContext | undefined): unknown;
+export declare function prevalidateToolArguments(def: AnyToolDefinition, args: unknown, options: InputHandlingOptions | undefined): PrevalidatedArguments;
 /**
- * Parses back a string whose trimmed form is a JSON array, at each path the
- * failed parse's issues named. Keys are never added, dropped, or renamed, and
- * a value no issue points at is returned untouched.
+ * The retry for a call whose first attempt failed (#563): the same stages with
+ * the alias stage first, so a key the drop discarded — an underscore spelling
+ * of a declared key, a declared `_q` alias, an ignore-listed key a declared
+ * alias names — reaches the rewrite. An underscore-prefixed key the alias stage
+ * cannot resolve is still dropped after it.
+ *
+ * `undefined` when there is nothing to retry: the first attempt dropped no key,
+ * or this order hands the parse the same arguments, which would only repeat
+ * the first attempt's failure.
+ */
+export declare function prevalidateAliasFirst(def: AnyToolDefinition, args: unknown, first: PrevalidatedArguments, options: InputHandlingOptions | undefined): PrevalidatedArguments | undefined;
+/**
+ * Undoes a representation slip at each path the failed parse's issues named:
+ * a string whose trimmed form is a JSON array or object is parsed back into
+ * what it encodes (#234, #479), and a safe integer where a string was expected
+ * becomes its decimal string (#487). Keys are never added, dropped, or renamed,
+ * and a value no issue points at is returned untouched.
  *
  * **Targeted, not a full walk.** A rejection names exactly the values the schema
  * could not accept, and repairing anything else loses repairs that should have
@@ -96,19 +213,25 @@ export declare function prevalidateToolArguments(def: AnyToolDefinition, args: u
  * free-text field legitimately holding `"[1,2]"` would have both rewritten, the
  * re-parse would fail on the free-text field, and the whole call would be
  * rejected over a value that was valid all along. An `invalid_union` issue's
- * outer path counts like any other — that is the value the union rejected.
+ * outer path counts like any other — that is the value the union rejected, and
+ * the only one read: a number inside one branch of a union field stays as sent.
+ *
+ * **One pass, no stacking.** Only a value the first parse rejected is repaired,
+ * and at most once, so a value one repair produced is never repaired again — an
+ * integer inside a stringified array, a stringified field inside a stringified
+ * object. The caller re-parses once.
  *
- * `JSON.parse` is the exact inverse of the `JSON.stringify` that produced the
- * value, so this undoes a known encoding rather than matching a nearest
- * candidate — the distinction that makes it safe where nearest-key matching is
- * not (#232). Safety does not rest on that alone: {@link parseToolArguments}
- * runs this only after validation has already failed and keeps the result only
- * when it then passes.
+ * `JSON.parse` is the exact inverse of the `JSON.stringify` that produced a
+ * string, and `String(n)` of a safe integer is the digits the caller sent, so
+ * each repair undoes a known encoding rather than matching a nearest candidate —
+ * the distinction that makes it safe where nearest-key matching is not (#232).
+ * Safety does not rest on that alone: {@link parseToolArguments} runs this only
+ * after validation has already failed and keeps the result only when it then
+ * passes.
  *
- * Returns the argument itself when nothing was repairable, which is the signal
- * the caller uses to skip the second parse.
+ * `args` is the argument itself when nothing was repairable, which is the
+ * signal the caller uses to skip the second parse.
  */
-export declare function repairRepresentations(args: unknown, issues: ReadonlyArray<{
-    readonly path: ReadonlyArray<PropertyKey>;
-}>): unknown;
+export declare function repairRepresentations(args: unknown, issues: readonly ArgumentIssue[]): RepairedArguments;
+export {};
 //# sourceMappingURL=inputPrevalidation.d.ts.map

package/dist/mcp-server/tools/utils/inputPrevalidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inputPrevalidation.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/inputPrevalidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAMH,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,oCAAoC,CAAC;AAW5C,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,qBAAqB,CAAC;AAM9E;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;CACxC;AAoED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAexF;AA8CD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAyND;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,oBAAoB,GAAG,SAAS,EACzC,OAAO,EAAE,cAAc,GAAG,SAAS,GAClC,OAAO,CAcT;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,GACnE,OAAO,CAST"}
+{"version":3,"file":"inputPrevalidation.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/inputPrevalidation.ts"],"names":[],"mappings":"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"}