@webpieces/mcp-server 0.4.789 → 0.4.791

package/src/WpMcpErrorTranslator.js

@@ -1,141 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WpMcpErrorTranslator = exports.McpDefaultToolCallRenderer = exports.McpHttpErrorDetail = exports.McpHttpErrorBody = exports.ModelVisibleToolError = exports.McpCorrelation = exports.McpErrorData = exports.MCP_REQUEST_ID_META_KEY = void 0;
+exports.WpMcpErrorTranslator = void 0;
 const server_1 = require("@modelcontextprotocol/server");
 const core_util_1 = require("@webpieces/core-util");
-const core_context_1 = require("@webpieces/core-context");
+const McpRegistry_1 = require("./McpRegistry");
+const McpToolCallRendering_1 = require("./McpToolCallRendering");
 const log = core_util_1.LogManager.getLogger('WpMcpErrorTranslator');
-/** `_meta` key carrying the Webpieces requestId on every tools/call result, success or failure. */
-exports.MCP_REQUEST_ID_META_KEY = 'webpieces/requestId';
-/** JSON-RPC error `data` so a user can quote the requestId of any protocol-level failure. */
-class McpErrorData {
-    requestId;
-    constructor(requestId) {
-        this.requestId = requestId;
-    }
-}
-exports.McpErrorData = McpErrorData;
-/**
- * The two per-request facts a renderer needs that are NOT the error: the JSON-RPC `id` it must echo,
- * and the tool being called. They are stamped into the request scope by `WpMcpServer` rather than
- * threaded through every renderer signature, because `requestId` already travels that way
- * ({@link WebpiecesCoreHeaders.REQUEST_ID}) and a second, parallel correlation parameter was a COPY
- * of the context — which is what the deleted `McpFailureScope` was.
- *
- * Context-only and never logged: the logging backends read `RequestContext` for correlation on every
- * record already, and this object exists purely so the renderers can be one-argument functions.
- */
-class McpCorrelation {
-    jsonRpcId;
-    toolName;
-    // webpieces-disable no-any-unknown -- ContextKey value types are per-key; this one is context-only
-    static KEY = core_util_1.ContextKey.untrusted('webpieces-mcp-correlation', undefined, false, 
-    /*isLogged*/ false);
-    constructor(jsonRpcId, toolName) {
-        this.jsonRpcId = jsonRpcId;
-        this.toolName = toolName;
-    }
-    /** Stamp what this request knows so far; `WpMcpServer` re-stamps once the tool name is known. */
-    // webpieces-disable no-function-outside-class -- static accessor trio for one context key
-    static stamp(correlation) {
-        core_context_1.RequestContext.putUntrusted(McpCorrelation.KEY, correlation);
-    }
-    /** A renderer reached before anything stamped (a failure with no parseable body) still renders. */
-    // webpieces-disable no-function-outside-class -- static accessor trio for one context key
-    static current() {
-        return core_context_1.RequestContext.getUntrusted(McpCorrelation.KEY) ?? new McpCorrelation(null);
-    }
-    /** The webpieces requestId of the request being served, as every MCP reply reports it. */
-    // webpieces-disable no-function-outside-class -- static accessor trio for one context key
-    static requestId() {
-        return core_context_1.RequestContext.getUntrusted(core_util_1.WebpiecesCoreHeaders.REQUEST_ID) ?? 'missing-request-id';
-    }
-}
-exports.McpCorrelation = McpCorrelation;
-/** The only error shape rendered into model-visible MCP tool content. */
-class ModelVisibleToolError {
-    kind;
-    message;
-    requestId;
-    field;
-    callerMessage;
-    errorCode;
-    retryAfterSeconds;
-    statusCode;
-    constructor(kind, message, requestId, field, callerMessage, errorCode, retryAfterSeconds, statusCode) {
-        this.kind = kind;
-        this.message = message;
-        this.requestId = requestId;
-        this.field = field;
-        this.callerMessage = callerMessage;
-        this.errorCode = errorCode;
-        this.retryAfterSeconds = retryAfterSeconds;
-        this.statusCode = statusCode;
-    }
-}
-exports.ModelVisibleToolError = ModelVisibleToolError;
-/** JSON-RPC error body written by the HTTP boundary before the SDK is involved. */
-class McpHttpErrorBody {
-    error;
-    id;
-    jsonrpc = '2.0';
-    constructor(error, id) {
-        this.error = error;
-        this.id = id;
-    }
-}
-exports.McpHttpErrorBody = McpHttpErrorBody;
-class McpHttpErrorDetail {
-    code;
-    message;
-    data;
-    constructor(code, message, data) {
-        this.code = code;
-        this.message = message;
-        this.data = data;
-    }
-}
-exports.McpHttpErrorDetail = McpHttpErrorDetail;
-/**
- * webpieces' DEFAULT `tools/call` rendering, as a public class so an app's own
- * {@link McpErrorTranslators} can DECLINE an error by delegating to it — the MCP twin of
- * `ApiErrorHttpMapper.toResponse` on the HTTP side.
- *
- * Published text comes only from {@link ApiErrorBoundary.encode}: this never puts an error's own
- * message in front of a model unless it is an `ApiEndUserError`.
- */
-class McpDefaultToolCallRenderer {
-    boundary = new core_util_1.ApiErrorBoundary();
-    toToolCallResult(error) {
-        const requestId = McpCorrelation.requestId();
-        const visible = this.modelVisible(this.boundary.encode(error), requestId);
-        const text = JSON.stringify(visible);
-        return {
-            content: [{ type: 'text', text }],
-            isError: true,
-            _meta: { [exports.MCP_REQUEST_ID_META_KEY]: requestId },
-        };
-    }
-    modelVisible(payload, requestId) {
-        switch (payload.kind) {
-            case 'end-user':
-                return new ModelVisibleToolError(payload.kind, payload.message, requestId, undefined, undefined, payload.errorCode);
-            case 'bad-request':
-                return new ModelVisibleToolError(payload.kind, payload.callerMessage ?? payload.message, requestId, payload.field, payload.callerMessage);
-            case 'coded':
-                return new ModelVisibleToolError(payload.kind, payload.message, requestId, undefined, undefined, payload.errorCode, undefined, payload.statusCode);
-            case 'implementation':
-                return new ModelVisibleToolError(payload.kind, `Internal error in tool ${McpCorrelation.current().toolName ?? 'unknown'} ` +
-                    `(requestId ${requestId}). This is a bug in the tool, not in your ` +
-                    'arguments; retrying with different arguments will not help.', requestId);
-            default:
-                return new ModelVisibleToolError(payload.kind, payload.message, requestId, undefined, undefined, undefined, payload.retryAfterSeconds);
-        }
-    }
-}
-exports.McpDefaultToolCallRenderer = McpDefaultToolCallRenderer;
 /**
- * The ONE place every MCP failure becomes a reply, mirroring `ApiErrorHttpMapper` for HTTP: an error
+ * The ONE place every MCP failure becomes a reply, mirroring `WebpiecesDefaultErrorTranslator` for HTTP: an error
  * in, the exact wire shape out. There is one method per BOUNDARY, and the MCP spec is what makes
  * them three rather than one:
  *
@@ -151,17 +23,14 @@ exports.McpDefaultToolCallRenderer = McpDefaultToolCallRenderer;
  */
 class WpMcpErrorTranslator {
     challenge;
-    appTranslators;
     boundary = new core_util_1.ApiErrorBoundary();
-    defaultToolCall = new McpDefaultToolCallRenderer();
+    defaultToolCall = new McpToolCallRendering_1.McpDefaultToolCallRenderer();
     /**
      * @param challenge - the `WWW-Authenticate` value for a 401, read lazily because
      *   `WpMcpServerConfig` is only fully validated at `bind(...)` time.
-     * @param appTranslators - the app's `tools/call` seam; `undefined` means webpieces renders all.
      */
-    constructor(challenge, appTranslators) {
+    constructor(challenge) {
         this.challenge = challenge;
-        this.appTranslators = appTranslators;
     }
     /**
      * Boundary #1: everything webpieces itself rejects before the SDK is involved — bearer
@@ -199,51 +68,52 @@ class WpMcpErrorTranslator {
      */
     toListError(error) {
         const payload = this.boundary.encode(error);
-        const requestId = McpCorrelation.requestId();
+        const requestId = McpToolCallRendering_1.McpCorrelation.requestId();
         if (payload.kind === 'bad-request') {
-            throw new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, payload.callerMessage ?? payload.message, new McpErrorData(requestId));
+            throw new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, payload.callerMessage ?? payload.message, new McpToolCallRendering_1.McpErrorData(requestId));
         }
         const message = payload.kind === 'end-user' ? payload.message : 'Internal Error';
-        throw new server_1.ProtocolError(server_1.ProtocolErrorCode.InternalError, message, new McpErrorData(requestId));
+        throw new server_1.ProtocolError(server_1.ProtocolErrorCode.InternalError, message, new McpToolCallRendering_1.McpErrorData(requestId));
     }
-    /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */
+    /** tools/call with a name no binding registered: a JSON-RPC protocol error in either MCP era. */
     unknownTool(toolName) {
-        const requestId = McpCorrelation.requestId();
+        const requestId = McpToolCallRendering_1.McpCorrelation.requestId();
         log.info(`Unknown MCP tool: ${toolName} requestId=${requestId}`);
-        return new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, `Unknown tool: ${toolName}`, new McpErrorData(requestId));
+        return new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, `Unknown tool: ${toolName}`, new McpToolCallRendering_1.McpErrorData(requestId));
     }
     /**
      * Boundary #3: every tools/call failure after the tool is found — an `isError: true` result the
      * model sees.
      *
-     * A registered {@link McpErrorTranslators} REPLACES the default and declines by delegating to
-     * {@link McpDefaultToolCallRenderer}, so "no translator registered" and "a translator that does
-     * not claim this error" produce byte-identical results.
+     * ONE unconditional line: {@link McpRegistry.getErrorTranslator} is never undefined, so there is
+     * no "was one registered" branch. A registered {@link McpErrorTranslator} REPLACES the default and
+     * declines by delegating to {@link McpDefaultToolCallRenderer}, so "no translator registered" and
+     * "a translator that does not claim this error" produce byte-identical results.
      */
     toToolCallResult(failure) {
-        const renderer = this.appTranslators;
-        if (!renderer)
-            return this.defaultToolCall.toToolCallResult(failure);
-        return this.withDefaultMeta(this.appOrDefault(renderer, failure));
+        return this.withDefaultMeta(this.appOrDefault(McpRegistry_1.McpRegistry.getErrorTranslator(), failure));
     }
     /** The `_meta` every tools/call result carries so a user can quote its requestId. */
     resultMeta(requestId) {
-        return { [exports.MCP_REQUEST_ID_META_KEY]: requestId };
+        return { [McpToolCallRendering_1.MCP_REQUEST_ID_META_KEY]: requestId };
     }
     /**
      * An app translator that THROWS must not replace the failure being reported: its own bug is
      * logged here and the ORIGINAL error still renders through the webpieces default, so the model
      * still gets a reply carrying the requestId.
+     *
+     * This is BUG CONTAINMENT, not a "did anyone register one" branch — the same shape as
+     * `ClientErrorTranslator.throwIfFailure` on the HTTP side.
      */
     appOrDefault(renderer, failure) {
         // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an app translator's own bug must not replace the failure it was asked to render
         try {
-            return renderer.toToolCallResult(failure);
+            return renderer.toWire(failure);
         }
         catch (err) {
             const error = (0, core_util_1.toError)(err);
-            log.error('Application McpErrorTranslators.toToolCallResult threw; rendering the webpieces default.', error);
-            return this.defaultToolCall.toToolCallResult(failure);
+            log.error('Application McpErrorTranslator.toWire threw; rendering the webpieces default.', error);
+            return this.defaultToolCall.toWire(failure);
         }
     }
     /**
@@ -254,12 +124,12 @@ class WpMcpErrorTranslator {
     withDefaultMeta(result) {
         if (result._meta !== undefined)
             return result;
-        return { ...result, _meta: this.resultMeta(McpCorrelation.requestId()) };
+        return { ...result, _meta: this.resultMeta(McpToolCallRendering_1.McpCorrelation.requestId()) };
     }
     httpError(status, code, message, headers) {
-        const correlation = McpCorrelation.current();
-        const requestId = McpCorrelation.requestId();
-        return new core_util_1.HttpResponseDto(new core_util_1.HttpResponseStatus(status, message), headers, new McpHttpErrorBody(new McpHttpErrorDetail(code, message, new McpErrorData(requestId)), correlation.jsonRpcId));
+        const correlation = McpToolCallRendering_1.McpCorrelation.current();
+        const requestId = McpToolCallRendering_1.McpCorrelation.requestId();
+        return new core_util_1.HttpResponseDto(new core_util_1.HttpResponseStatus(status, message), headers, new McpToolCallRendering_1.McpHttpErrorBody(new McpToolCallRendering_1.McpHttpErrorDetail(code, message, new McpToolCallRendering_1.McpErrorData(requestId)), correlation.jsonRpcId));
     }
 }
 exports.WpMcpErrorTranslator = WpMcpErrorTranslator;

package/src/WpMcpErrorTranslator.js.map

@@ -1 +1 @@
-{"version":3,"file":"WpMcpErrorTranslator.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/WpMcpErrorTranslator.ts"],"names":[],"mappings":"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","sourcesContent":["import { CallToolResult, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/server';\nimport {\n    ApiErrorBoundary,\n    ApiErrorPayload,\n    ContextKey,\n    DtoValue,\n    HttpHeader,\n    HttpResponseDto,\n    HttpResponseStatus,\n    LogManager,\n    toError,\n    WebpiecesCoreHeaders,\n} from '@webpieces/core-util';\nimport { RequestContext } from '@webpieces/core-context';\n\nconst log = LogManager.getLogger('WpMcpErrorTranslator');\n\n/** `_meta` key carrying the Webpieces requestId on every tools/call result, success or failure. */\nexport const MCP_REQUEST_ID_META_KEY = 'webpieces/requestId';\n\n/** JSON-RPC error `data` so a user can quote the requestId of any protocol-level failure. */\nexport class McpErrorData {\n    constructor(public readonly requestId: string) {}\n}\n\n/**\n * The two per-request facts a renderer needs that are NOT the error: the JSON-RPC `id` it must echo,\n * and the tool being called. They are stamped into the request scope by `WpMcpServer` rather than\n * threaded through every renderer signature, because `requestId` already travels that way\n * ({@link WebpiecesCoreHeaders.REQUEST_ID}) and a second, parallel correlation parameter was a COPY\n * of the context — which is what the deleted `McpFailureScope` was.\n *\n * Context-only and never logged: the logging backends read `RequestContext` for correlation on every\n * record already, and this object exists purely so the renderers can be one-argument functions.\n */\nexport class McpCorrelation {\n    // webpieces-disable no-any-unknown -- ContextKey value types are per-key; this one is context-only\n    static readonly KEY = ContextKey.untrusted<McpCorrelation>(\n        'webpieces-mcp-correlation',\n        undefined,\n        false,\n        /*isLogged*/ false,\n    );\n\n    constructor(\n        public readonly jsonRpcId: string | number | null,\n        public readonly toolName?: string,\n    ) {}\n\n    /** Stamp what this request knows so far; `WpMcpServer` re-stamps once the tool name is known. */\n    // webpieces-disable no-function-outside-class -- static accessor trio for one context key\n    static stamp(correlation: McpCorrelation): void {\n        RequestContext.putUntrusted(McpCorrelation.KEY, correlation);\n    }\n\n    /** A renderer reached before anything stamped (a failure with no parseable body) still renders. */\n    // webpieces-disable no-function-outside-class -- static accessor trio for one context key\n    static current(): McpCorrelation {\n        return RequestContext.getUntrusted(McpCorrelation.KEY) ?? new McpCorrelation(null);\n    }\n\n    /** The webpieces requestId of the request being served, as every MCP reply reports it. */\n    // webpieces-disable no-function-outside-class -- static accessor trio for one context key\n    static requestId(): string {\n        return RequestContext.getUntrusted(WebpiecesCoreHeaders.REQUEST_ID) ?? 'missing-request-id';\n    }\n}\n\n/** The only error shape rendered into model-visible MCP tool content. */\nexport class ModelVisibleToolError {\n    constructor(\n        public readonly kind: string,\n        public readonly message: string,\n        public readonly requestId: string,\n        public readonly field?: string,\n        public readonly callerMessage?: string,\n        public readonly errorCode?: string,\n        public readonly retryAfterSeconds?: number,\n        public readonly statusCode?: number,\n    ) {}\n}\n\n/** JSON-RPC error body written by the HTTP boundary before the SDK is involved. */\nexport class McpHttpErrorBody {\n    readonly jsonrpc = '2.0';\n    constructor(\n        public readonly error: McpHttpErrorDetail,\n        public readonly id: string | number | null,\n    ) {}\n}\n\nexport class McpHttpErrorDetail {\n    constructor(\n        public readonly code: number,\n        public readonly message: string,\n        public readonly data: McpErrorData,\n    ) {}\n}\n\n/**\n * The application's own `tools/call` error translation — the MCP twin of the `ErrorTranslators` an\n * app registers on `ClientRegistry` for the HTTP path. Register one with\n * `WpMcpServerConfig.setErrorTranslator(...)`; it is NOT a global, because `WpMcpServer` is\n * constructed by app code and two servers may run in one process.\n *\n * An app owns its error taxonomy and owns how those errors should be explained to a model, so a\n * claimed error yields the ENTIRE `CallToolResult` — content, `structuredContent`, `isError`, the lot.\n *\n * Contract:\n * - `error` is the RAW thrown value: an app must be able to `instanceof` its own error classes.\n *   `ApiErrorBoundary` never substitutes an object for the thrown error, so there is exactly one\n *   error value on this path.\n * - There is no \"not mine\" return. A registered translator REPLACES the webpieces default and\n *   declines by DELEGATING to it: `new McpDefaultToolCallRenderer().toToolCallResult(error)`.\n * - webpieces default-fills `_meta['webpieces/requestId']` only when the returned result has NO\n *   `_meta`. An app that sets `_meta` owns it untouched.\n * - scope is `tools/call` ONLY. The pre-SDK HTTP boundary and `tools/list` stay framework-owned:\n *   that boundary emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` MCP clients\n *   depend on for OAuth discovery, and an app rewriting it breaks connector onboarding.\n */\nexport interface McpErrorTranslators {\n    toToolCallResult(error: Error): CallToolResult;\n}\n\n/**\n * webpieces' DEFAULT `tools/call` rendering, as a public class so an app's own\n * {@link McpErrorTranslators} can DECLINE an error by delegating to it — the MCP twin of\n * `ApiErrorHttpMapper.toResponse` on the HTTP side.\n *\n * Published text comes only from {@link ApiErrorBoundary.encode}: this never puts an error's own\n * message in front of a model unless it is an `ApiEndUserError`.\n */\nexport class McpDefaultToolCallRenderer implements McpErrorTranslators {\n    private readonly boundary = new ApiErrorBoundary();\n\n    toToolCallResult(error: Error): CallToolResult {\n        const requestId = McpCorrelation.requestId();\n        const visible = this.modelVisible(this.boundary.encode(error), requestId);\n        const text = JSON.stringify(visible as DtoValue);\n        return {\n            content: [{ type: 'text', text }],\n            isError: true,\n            _meta: { [MCP_REQUEST_ID_META_KEY]: requestId },\n        };\n    }\n\n    private modelVisible(payload: ApiErrorPayload, requestId: string): ModelVisibleToolError {\n        switch (payload.kind) {\n            case 'end-user':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.message,\n                    requestId,\n                    undefined,\n                    undefined,\n                    payload.errorCode,\n                );\n            case 'bad-request':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.callerMessage ?? payload.message,\n                    requestId,\n                    payload.field,\n                    payload.callerMessage,\n                );\n            case 'coded':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.message,\n                    requestId,\n                    undefined,\n                    undefined,\n                    payload.errorCode,\n                    undefined,\n                    payload.statusCode,\n                );\n            case 'implementation':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    `Internal error in tool ${McpCorrelation.current().toolName ?? 'unknown'} ` +\n                        `(requestId ${requestId}). This is a bug in the tool, not in your ` +\n                        'arguments; retrying with different arguments will not help.',\n                    requestId,\n                );\n            default:\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.message,\n                    requestId,\n                    undefined,\n                    undefined,\n                    undefined,\n                    payload.retryAfterSeconds,\n                );\n        }\n    }\n}\n\n/**\n * The ONE place every MCP failure becomes a reply, mirroring `ApiErrorHttpMapper` for HTTP: an error\n * in, the exact wire shape out. There is one method per BOUNDARY, and the MCP spec is what makes\n * them three rather than one:\n *\n * | Boundary                       | Who writes HTTP | Failure shape                       |\n * |--------------------------------|-----------------|-------------------------------------|\n * | pre-SDK bearer / Origin / body | **webpieces**   | `HttpResponseDto<McpHttpErrorBody>` |\n * | `tools/list`                   | the SDK         | `throw ProtocolError`               |\n * | `tools/call`                   | the SDK         | `CallToolResult` with `isError`     |\n *\n * Classification and published text are the shared {@link ApiErrorBoundary} rules. Operator logging\n * is NOT here: `LogApiCall` wraps each of those boundaries in `WpMcpServer`, so every failure gets\n * exactly one `[API-server-resp-*]` line with the request and the identity on it.\n */\nexport class WpMcpErrorTranslator {\n    private readonly boundary = new ApiErrorBoundary();\n    private readonly defaultToolCall = new McpDefaultToolCallRenderer();\n\n    /**\n     * @param challenge - the `WWW-Authenticate` value for a 401, read lazily because\n     *   `WpMcpServerConfig` is only fully validated at `bind(...)` time.\n     * @param appTranslators - the app's `tools/call` seam; `undefined` means webpieces renders all.\n     */\n    constructor(\n        private readonly challenge: () => string,\n        private readonly appTranslators?: McpErrorTranslators,\n    ) {}\n\n    /**\n     * Boundary #1: everything webpieces itself rejects before the SDK is involved — bearer\n     * verification, `Origin`, a malformed body. This is 401/403/400/500 today and any status\n     * tomorrow, so it produces a VALUE like every other API in the framework and `WpMcpServer` hands\n     * it to the shared express writer. The BODY stays JSON-RPC shaped because an MCP client expects\n     * that; `HttpResponseDto` is generic, and its header LIST carries `WWW-Authenticate`.\n     */\n    toBearerBoundaryResponse(error: Error): HttpResponseDto<McpHttpErrorBody> {\n        const payload = this.boundary.encode(error);\n        const generic = payload.message;\n        switch (payload.kind) {\n            case 'unauthorized':\n                return this.httpError(401, -32_000, generic, [\n                    new HttpHeader('WWW-Authenticate', this.challenge()),\n                ]);\n            case 'forbidden':\n                return this.httpError(403, -32_000, generic, []);\n            case 'bad-request':\n                return this.httpError(400, ProtocolErrorCode.ParseError, generic, []);\n            default:\n                return this.httpError(500, ProtocolErrorCode.InternalError, 'Internal Error', []);\n        }\n    }\n\n    /**\n     * Boundary #2: `tools/list` has no tool-result channel, so a failure IS a JSON-RPC error. It\n     * THROWS rather than returning a value the caller must remember to throw, and is typed `never`\n     * so the compiler knows the call is terminal.\n     *\n     * This is LOAD-BEARING for disclosure, not defence in depth. Measured on\n     * `@modelcontextprotocol/server` 2.0.0 and pinned by `McpSdkForeignThrow.spec.ts`: the SDK wraps\n     * a foreign (non-`ProtocolError`) throw in `-32603` but copies its `message` onto the wire\n     * VERBATIM. So a `tools/list` handler that lets any error escape un-translated publishes that\n     * error's operator text to the caller.\n     */\n    toListError(error: Error): never {\n        const payload = this.boundary.encode(error);\n        const requestId = McpCorrelation.requestId();\n        if (payload.kind === 'bad-request') {\n            throw new ProtocolError(\n                ProtocolErrorCode.InvalidParams,\n                payload.callerMessage ?? payload.message,\n                new McpErrorData(requestId),\n            );\n        }\n        const message = payload.kind === 'end-user' ? payload.message : 'Internal Error';\n        throw new ProtocolError(\n            ProtocolErrorCode.InternalError,\n            message,\n            new McpErrorData(requestId),\n        );\n    }\n\n    /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */\n    unknownTool(toolName: string): ProtocolError {\n        const requestId = McpCorrelation.requestId();\n        log.info(`Unknown MCP tool: ${toolName} requestId=${requestId}`);\n        return new ProtocolError(\n            ProtocolErrorCode.InvalidParams,\n            `Unknown tool: ${toolName}`,\n            new McpErrorData(requestId),\n        );\n    }\n\n    /**\n     * Boundary #3: every tools/call failure after the tool is found — an `isError: true` result the\n     * model sees.\n     *\n     * A registered {@link McpErrorTranslators} REPLACES the default and declines by delegating to\n     * {@link McpDefaultToolCallRenderer}, so \"no translator registered\" and \"a translator that does\n     * not claim this error\" produce byte-identical results.\n     */\n    toToolCallResult(failure: Error): CallToolResult {\n        const renderer = this.appTranslators;\n        if (!renderer) return this.defaultToolCall.toToolCallResult(failure);\n        return this.withDefaultMeta(this.appOrDefault(renderer, failure));\n    }\n\n    /** The `_meta` every tools/call result carries so a user can quote its requestId. */\n    resultMeta(requestId: string): Record<string, string> {\n        return { [MCP_REQUEST_ID_META_KEY]: requestId };\n    }\n\n    /**\n     * An app translator that THROWS must not replace the failure being reported: its own bug is\n     * logged here and the ORIGINAL error still renders through the webpieces default, so the model\n     * still gets a reply carrying the requestId.\n     */\n    private appOrDefault(renderer: McpErrorTranslators, failure: Error): CallToolResult {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an app translator's own bug must not replace the failure it was asked to render\n        try {\n            return renderer.toToolCallResult(failure);\n        } catch (err: unknown) {\n            const error = toError(err);\n            log.error(\n                'Application McpErrorTranslators.toToolCallResult threw; rendering the webpieces default.',\n                error,\n            );\n            return this.defaultToolCall.toToolCallResult(failure);\n        }\n    }\n\n    /**\n     * webpieces fills `_meta` only when the app left it off, keeping the README's \"every reply\n     * carries the requestId\" promise a DEFAULT rather than a restriction: an app that set `_meta`\n     * keeps it byte-for-byte.\n     */\n    private withDefaultMeta(result: CallToolResult): CallToolResult {\n        if (result._meta !== undefined) return result;\n        return { ...result, _meta: this.resultMeta(McpCorrelation.requestId()) };\n    }\n\n    private httpError(\n        status: number,\n        code: number,\n        message: string,\n        headers: HttpHeader[],\n    ): HttpResponseDto<McpHttpErrorBody> {\n        const correlation = McpCorrelation.current();\n        const requestId = McpCorrelation.requestId();\n        return new HttpResponseDto<McpHttpErrorBody>(\n            new HttpResponseStatus(status, message),\n            headers,\n            new McpHttpErrorBody(\n                new McpHttpErrorDetail(code, message, new McpErrorData(requestId)),\n                correlation.jsonRpcId,\n            ),\n        );\n    }\n}\n"]}
+{"version":3,"file":"WpMcpErrorTranslator.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/WpMcpErrorTranslator.ts"],"names":[],"mappings":"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","sourcesContent":["import { CallToolResult, ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/server';\nimport {\n    ApiErrorBoundary,\n    HttpHeader,\n    HttpResponseDto,\n    HttpResponseStatus,\n    LogManager,\n    toError,\n} from '@webpieces/core-util';\nimport { McpRegistry } from './McpRegistry';\nimport {\n    McpCorrelation,\n    McpDefaultToolCallRenderer,\n    McpErrorData,\n    McpErrorTranslator,\n    McpHttpErrorBody,\n    McpHttpErrorDetail,\n    MCP_REQUEST_ID_META_KEY,\n} from './McpToolCallRendering';\n\nconst log = LogManager.getLogger('WpMcpErrorTranslator');\n\n/**\n * The ONE place every MCP failure becomes a reply, mirroring `WebpiecesDefaultErrorTranslator` for HTTP: an error\n * in, the exact wire shape out. There is one method per BOUNDARY, and the MCP spec is what makes\n * them three rather than one:\n *\n * | Boundary                       | Who writes HTTP | Failure shape                       |\n * |--------------------------------|-----------------|-------------------------------------|\n * | pre-SDK bearer / Origin / body | **webpieces**   | `HttpResponseDto<McpHttpErrorBody>` |\n * | `tools/list`                   | the SDK         | `throw ProtocolError`               |\n * | `tools/call`                   | the SDK         | `CallToolResult` with `isError`     |\n *\n * Classification and published text are the shared {@link ApiErrorBoundary} rules. Operator logging\n * is NOT here: `LogApiCall` wraps each of those boundaries in `WpMcpServer`, so every failure gets\n * exactly one `[API-server-resp-*]` line with the request and the identity on it.\n */\nexport class WpMcpErrorTranslator {\n    private readonly boundary = new ApiErrorBoundary();\n    private readonly defaultToolCall = new McpDefaultToolCallRenderer();\n\n    /**\n     * @param challenge - the `WWW-Authenticate` value for a 401, read lazily because\n     *   `WpMcpServerConfig` is only fully validated at `bind(...)` time.\n     */\n    constructor(private readonly challenge: () => string) {}\n\n    /**\n     * Boundary #1: everything webpieces itself rejects before the SDK is involved — bearer\n     * verification, `Origin`, a malformed body. This is 401/403/400/500 today and any status\n     * tomorrow, so it produces a VALUE like every other API in the framework and `WpMcpServer` hands\n     * it to the shared express writer. The BODY stays JSON-RPC shaped because an MCP client expects\n     * that; `HttpResponseDto` is generic, and its header LIST carries `WWW-Authenticate`.\n     */\n    toBearerBoundaryResponse(error: Error): HttpResponseDto<McpHttpErrorBody> {\n        const payload = this.boundary.encode(error);\n        const generic = payload.message;\n        switch (payload.kind) {\n            case 'unauthorized':\n                return this.httpError(401, -32_000, generic, [\n                    new HttpHeader('WWW-Authenticate', this.challenge()),\n                ]);\n            case 'forbidden':\n                return this.httpError(403, -32_000, generic, []);\n            case 'bad-request':\n                return this.httpError(400, ProtocolErrorCode.ParseError, generic, []);\n            default:\n                return this.httpError(500, ProtocolErrorCode.InternalError, 'Internal Error', []);\n        }\n    }\n\n    /**\n     * Boundary #2: `tools/list` has no tool-result channel, so a failure IS a JSON-RPC error. It\n     * THROWS rather than returning a value the caller must remember to throw, and is typed `never`\n     * so the compiler knows the call is terminal.\n     *\n     * This is LOAD-BEARING for disclosure, not defence in depth. Measured on\n     * `@modelcontextprotocol/server` 2.0.0 and pinned by `McpSdkForeignThrow.spec.ts`: the SDK wraps\n     * a foreign (non-`ProtocolError`) throw in `-32603` but copies its `message` onto the wire\n     * VERBATIM. So a `tools/list` handler that lets any error escape un-translated publishes that\n     * error's operator text to the caller.\n     */\n    toListError(error: Error): never {\n        const payload = this.boundary.encode(error);\n        const requestId = McpCorrelation.requestId();\n        if (payload.kind === 'bad-request') {\n            throw new ProtocolError(\n                ProtocolErrorCode.InvalidParams,\n                payload.callerMessage ?? payload.message,\n                new McpErrorData(requestId),\n            );\n        }\n        const message = payload.kind === 'end-user' ? payload.message : 'Internal Error';\n        throw new ProtocolError(\n            ProtocolErrorCode.InternalError,\n            message,\n            new McpErrorData(requestId),\n        );\n    }\n\n    /** tools/call with a name no binding registered: a JSON-RPC protocol error in either MCP era. */\n    unknownTool(toolName: string): ProtocolError {\n        const requestId = McpCorrelation.requestId();\n        log.info(`Unknown MCP tool: ${toolName} requestId=${requestId}`);\n        return new ProtocolError(\n            ProtocolErrorCode.InvalidParams,\n            `Unknown tool: ${toolName}`,\n            new McpErrorData(requestId),\n        );\n    }\n\n    /**\n     * Boundary #3: every tools/call failure after the tool is found — an `isError: true` result the\n     * model sees.\n     *\n     * ONE unconditional line: {@link McpRegistry.getErrorTranslator} is never undefined, so there is\n     * no \"was one registered\" branch. A registered {@link McpErrorTranslator} REPLACES the default and\n     * declines by delegating to {@link McpDefaultToolCallRenderer}, so \"no translator registered\" and\n     * \"a translator that does not claim this error\" produce byte-identical results.\n     */\n    toToolCallResult(failure: Error): CallToolResult {\n        return this.withDefaultMeta(this.appOrDefault(McpRegistry.getErrorTranslator(), failure));\n    }\n\n    /** The `_meta` every tools/call result carries so a user can quote its requestId. */\n    resultMeta(requestId: string): Record<string, string> {\n        return { [MCP_REQUEST_ID_META_KEY]: requestId };\n    }\n\n    /**\n     * An app translator that THROWS must not replace the failure being reported: its own bug is\n     * logged here and the ORIGINAL error still renders through the webpieces default, so the model\n     * still gets a reply carrying the requestId.\n     *\n     * This is BUG CONTAINMENT, not a \"did anyone register one\" branch — the same shape as\n     * `ClientErrorTranslator.throwIfFailure` on the HTTP side.\n     */\n    private appOrDefault(renderer: McpErrorTranslator, failure: Error): CallToolResult {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an app translator's own bug must not replace the failure it was asked to render\n        try {\n            return renderer.toWire(failure);\n        } catch (err: unknown) {\n            const error = toError(err);\n            log.error(\n                'Application McpErrorTranslator.toWire threw; rendering the webpieces default.',\n                error,\n            );\n            return this.defaultToolCall.toWire(failure);\n        }\n    }\n\n    /**\n     * webpieces fills `_meta` only when the app left it off, keeping the README's \"every reply\n     * carries the requestId\" promise a DEFAULT rather than a restriction: an app that set `_meta`\n     * keeps it byte-for-byte.\n     */\n    private withDefaultMeta(result: CallToolResult): CallToolResult {\n        if (result._meta !== undefined) return result;\n        return { ...result, _meta: this.resultMeta(McpCorrelation.requestId()) };\n    }\n\n    private httpError(\n        status: number,\n        code: number,\n        message: string,\n        headers: HttpHeader[],\n    ): HttpResponseDto<McpHttpErrorBody> {\n        const correlation = McpCorrelation.current();\n        const requestId = McpCorrelation.requestId();\n        return new HttpResponseDto<McpHttpErrorBody>(\n            new HttpResponseStatus(status, message),\n            headers,\n            new McpHttpErrorBody(\n                new McpHttpErrorDetail(code, message, new McpErrorData(requestId)),\n                correlation.jsonRpcId,\n            ),\n        );\n    }\n}\n"]}

package/src/WpMcpServer.d.ts

@@ -2,7 +2,12 @@ import { Express } from 'express';
 import { McpProtectedResourceMetadata, WpMcpServerConfig } from './McpAuth';
 import { McpBindOptions } from './McpBindOptions';
 /**
- * Modern-only MCP 2026-07-28 adapter around the official SDK's request-scoped HTTP handler.
+ * MCP adapter around the official SDK's request-scoped HTTP handler, serving BOTH wire eras from
+ * one tool registry: modern (2026-07-28, per-request `_meta` envelope) and legacy (the 2025-11-25
+ * family, negotiated by `initialize`). The SDK routes each request to the leg its shape selects and
+ * negotiates the revision; only a revision no era knows is refused. Pinning one era instead made
+ * every shipping client unreachable (issue #969), and the MCP lifecycle spec is explicit that a
+ * server answers with a revision it supports rather than erroring.
  *
  * Error boundary: every failure is mapped by the one `WpMcpErrorTranslator`, and each entry point
  * has exactly one catch that only delegates to it: the bind HTTP handler
@@ -22,7 +27,7 @@ export declare class WpMcpServer<TGrant, TMintRequest> {
      */
     private readonly logApiCall;
     private readonly responseWriter;
-    /** tools/call gives the app's translators first refusal; every other reply stays framework-owned. */
+    /** tools/call reads `McpRegistry`; every other reply stays framework-owned. See McpErrorTranslator. */
     private readonly translator;
     private registry?;
     private handler?;

package/src/WpMcpServer.js

@@ -12,6 +12,7 @@ const McpAuth_1 = require("./McpAuth");
 const McpApiDispatcher_1 = require("./McpApiDispatcher");
 const McpInvocationContext_1 = require("./McpInvocationContext");
 const McpToolRegistry_1 = require("./McpToolRegistry");
+const McpToolCallRendering_1 = require("./McpToolCallRendering");
 const WpMcpErrorTranslator_1 = require("./WpMcpErrorTranslator");
 const log = core_util_1.LogManager.getLogger('WpMcpServer');
 /**
@@ -56,7 +57,12 @@ class WpSdkMcpServer extends server_1.McpServer {
     }
 }
 /**
- * Modern-only MCP 2026-07-28 adapter around the official SDK's request-scoped HTTP handler.
+ * MCP adapter around the official SDK's request-scoped HTTP handler, serving BOTH wire eras from
+ * one tool registry: modern (2026-07-28, per-request `_meta` envelope) and legacy (the 2025-11-25
+ * family, negotiated by `initialize`). The SDK routes each request to the leg its shape selects and
+ * negotiates the revision; only a revision no era knows is refused. Pinning one era instead made
+ * every shipping client unreachable (issue #969), and the MCP lifecycle spec is explicit that a
+ * server answers with a revision it supports rather than erroring.
  *
  * Error boundary: every failure is mapped by the one `WpMcpErrorTranslator`, and each entry point
  * has exactly one catch that only delegates to it: the bind HTTP handler
@@ -76,7 +82,7 @@ class WpMcpServer {
      */
     logApiCall = new core_util_1.LogApiCallImpl(new core_context_1.RequestContextApiCallContext());
     responseWriter = new http_server_1.ExpressResponseWriter();
-    /** tools/call gives the app's translators first refusal; every other reply stays framework-owned. */
+    /** tools/call reads `McpRegistry`; every other reply stays framework-owned. See McpErrorTranslator. */
     translator;
     registry;
     handler;
@@ -86,7 +92,7 @@ class WpMcpServer {
     revision;
     constructor(config) {
         this.config = config;
-        this.translator = new WpMcpErrorTranslator_1.WpMcpErrorTranslator(() => this.challenge(), config.errorTranslator);
+        this.translator = new WpMcpErrorTranslator_1.WpMcpErrorTranslator(() => this.challenge());
     }
     /**
      * Mounts this MCP endpoint on `app`: POST at `options.endpointPath`, plus a 405 (`Allow: POST`)
@@ -131,9 +137,11 @@ class WpMcpServer {
         (bodyError, req, res, _next) => {
             void this.handleBodyFailure(bodyError, req, res);
         });
-        // Registered AFTER the POST route so POST still wins. MCP 2026-07-28 has no session GET
-        // (`subscriptions/listen` is a POST method), so every other method is a method error — and a
-        // discovery probe gets that instead of Express' bare 404.
+        // Registered AFTER the POST route so POST still wins. NEITHER era served here has a session
+        // GET: 2026-07-28 has none at all (`subscriptions/listen` is a POST method), and the legacy
+        // leg is the SDK's STATELESS fallback, which answers the 2025 session GET/DELETE with the
+        // same 405. So every other method is a method error — and a discovery probe gets that
+        // instead of Express' bare 404.
         app.all(options.endpointPath, (_req, res) => {
             res.setHeader('Allow', 'POST');
             res.status(405).json(new McpMethodNotAllowedBody());
@@ -155,7 +163,9 @@ class WpMcpServer {
     }
     createHandler(options, responseMode) {
         return (0, server_1.createMcpHandler)((context) => this.buildSdkServer(context, options), {
-            legacy: 'reject',
+            // Both eras, one factory: `stateless` serves 2025-era traffic through a fresh
+            // instance of the SAME McpServerFactory, so the two eras can never drift apart.
+            legacy: 'stateless',
             responseMode,
             bus: options.deployment.bus,
             maxSubscriptions: options.maxSubscriptions,
@@ -168,7 +178,7 @@ class WpMcpServer {
         res.setHeader('X-Accel-Buffering', 'no');
         await core_context_1.RequestContext.run(async () => {
             new core_context_1.RequestContextHeaders().fillFromRequest(this.toHttpRequest(req));
-            WpMcpErrorTranslator_1.McpCorrelation.stamp(this.correlationOf(req));
+            McpToolCallRendering_1.McpCorrelation.stamp(this.correlationOf(req));
             // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP HTTP entry point; delegates only to WpMcpErrorTranslator
             try {
                 await this.logEdge('serve', () => this.serveExpress(req, res, options));
@@ -183,7 +193,7 @@ class WpMcpServer {
     async handleBodyFailure(cause, req, res) {
         await core_context_1.RequestContext.run(async () => {
             new core_context_1.RequestContextHeaders().fillFromRequest(this.toHttpRequest(req));
-            WpMcpErrorTranslator_1.McpCorrelation.stamp(this.correlationOf(req));
+            McpToolCallRendering_1.McpCorrelation.stamp(this.correlationOf(req));
             // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP body entry point; delegates only to WpMcpErrorTranslator
             try {
                 await this.logEdge('body', () => this.rejectBody(cause));
@@ -254,9 +264,12 @@ class WpMcpServer {
         return disconnected.signal;
     }
     buildSdkServer(context, options) {
+        // The era is the SDK's to decide and BOTH are served; what is not negotiable is that the
+        // request came through `bind`'s HTTP boundary, which is where the external bearer is
+        // verified. A factory call without it is a wiring mistake, never a client's doing.
         const authentication = context.authInfo?.extra?.['webpiecesAuthentication'];
-        if (context.era !== 'modern' || !(authentication instanceof McpPostAuthentication)) {
-            throw new core_util_1.ApiImplementationError('WpMcpServer serves only MCP 2026-07-28 requests authenticated by its bind boundary.');
+        if (!(authentication instanceof McpPostAuthentication)) {
+            throw new core_util_1.ApiImplementationError('WpMcpServer serves only MCP requests authenticated by its bind boundary.');
         }
         const registry = this.requireRegistry();
         const server = new WpSdkMcpServer({ name: this.config.name, version: `${this.config.version}+${this.revision}` }, {
@@ -307,14 +320,14 @@ class WpMcpServer {
      */
     async handleCallTool(server, request, authentication, sdkContext) {
         const name = request.params.name;
-        WpMcpErrorTranslator_1.McpCorrelation.stamp(new WpMcpErrorTranslator_1.McpCorrelation(sdkContext.mcpReq.id, name));
+        McpToolCallRendering_1.McpCorrelation.stamp(new McpToolCallRendering_1.McpCorrelation(sdkContext.mcpReq.id, name));
         const tool = this.requireRegistry().find(name);
         if (!tool)
             throw this.translator.unknownTool(name);
         // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP tools/call entry point; delegates only to WpMcpErrorTranslator
         try {
             const result = await this.callTool(tool, request, authentication, sdkContext);
-            result._meta = this.translator.resultMeta(WpMcpErrorTranslator_1.McpCorrelation.requestId());
+            result._meta = this.translator.resultMeta(McpToolCallRendering_1.McpCorrelation.requestId());
             return server.server.projectCallToolResult(result, tool.outputSchema);
         }
         catch (err) {
@@ -425,7 +438,7 @@ class WpMcpServer {
         const id = body?.['id'];
         const params = this.bodyObject(body?.['params']);
         const name = params?.['name'];
-        return new WpMcpErrorTranslator_1.McpCorrelation(typeof id === 'string' || typeof id === 'number' ? id : null, typeof name === 'string' ? name : undefined);
+        return new McpToolCallRendering_1.McpCorrelation(typeof id === 'string' || typeof id === 'number' ? id : null, typeof name === 'string' ? name : undefined);
     }
     challenge() {
         return `Bearer resource_metadata="${this.config.resourceMetadataUrl}"`;