@webpieces/mcp-server 0.4.790 → 0.4.791

package/src/McpToolCallRendering.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpDefaultToolCallRenderer = exports.McpHttpErrorDetail = exports.McpHttpErrorBody = exports.ModelVisibleToolError = exports.McpCorrelation = exports.McpErrorData = exports.MCP_REQUEST_ID_META_KEY = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const core_context_1 = require("@webpieces/core-context");
+/** `_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, and what {@link McpRegistry} holds until an app installs
+ * its own. Public so an app's own {@link McpErrorTranslator} can DECLINE an error by delegating to it
+ * — the MCP twin of `WebpiecesDefaultErrorTranslator.toWire` 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();
+    toWire(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;
+//# sourceMappingURL=McpToolCallRendering.js.map

package/src/McpToolCallRendering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolCallRendering.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpToolCallRendering.ts"],"names":[],"mappings":"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","sourcesContent":["import { CallToolResult } from '@modelcontextprotocol/server';\nimport {\n    ApiErrorBoundary,\n    ApiErrorPayload,\n    ContextKey,\n    DtoValue,\n    WebpiecesCoreHeaders,\n} from '@webpieces/core-util';\nimport { RequestContext } from '@webpieces/core-context';\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 `ErrorTranslator` an app\n * registers on `ClientRegistry` for HTTP and the `IpcErrorTranslator` it registers on `IpcRegistry`.\n * Register one with {@link McpRegistry.setErrorTranslator}.\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 * # There is NO `fromWire`, and that is the protocol, not an oversight\n *\n * The HTTP and IPC translators have two halves because webpieces sits on BOTH ends of those wires: it\n * writes the response AND, in another process, reads one. **webpieces is never the MCP client.** The\n * client is Claude (or another model host); there is no return path for webpieces to translate, so\n * the pair is one-directional by nature. Do not \"restore the symmetry\" by adding a half with nothing\n * to call it.\n *\n * # The pre-SDK boundary does NOT share the HTTP `ErrorTranslator`, despite the identical type\n *\n * `WpMcpErrorTranslator.toBearerBoundaryResponse` returns an `HttpResponseDto`, exactly like\n * `ErrorTranslator.toWire` — and it must STILL not be routed through it. Two reasons, both hard:\n *\n * - its body must stay JSON-RPC shaped (`McpHttpErrorBody`) or an MCP client cannot parse the reply\n *   at all, whereas an app's HTTP translator publishes the app's own REST envelope;\n * - it emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` that MCP clients use for OAuth\n *   discovery, so an app rewriting it breaks connector onboarding.\n *\n * Same TYPE, different OWNER. `tools/list` is framework-owned for the same reason.\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().toWire(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.\n */\nexport interface McpErrorTranslator {\n    /** An error in, the whole `tools/call` reply out. Named for its HTTP and IPC twins. */\n    toWire(error: Error): CallToolResult;\n}\n\n/**\n * webpieces' DEFAULT `tools/call` rendering, and what {@link McpRegistry} holds until an app installs\n * its own. Public so an app's own {@link McpErrorTranslator} can DECLINE an error by delegating to it\n * — the MCP twin of `WebpiecesDefaultErrorTranslator.toWire` 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 McpErrorTranslator {\n    private readonly boundary = new ApiErrorBoundary();\n\n    toWire(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"]}

package/src/WpMcpErrorTranslator.d.ts

@@ -1,98 +1,8 @@
 import { CallToolResult, ProtocolError } from '@modelcontextprotocol/server';
-import { ContextKey, HttpResponseDto } from '@webpieces/core-util';
-/** `_meta` key carrying the Webpieces requestId on every tools/call result, success or failure. */
-export declare const MCP_REQUEST_ID_META_KEY = "webpieces/requestId";
-/** JSON-RPC error `data` so a user can quote the requestId of any protocol-level failure. */
-export declare class McpErrorData {
-    readonly requestId: string;
-    constructor(requestId: string);
-}
-/**
- * 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.
- */
-export declare class McpCorrelation {
-    readonly jsonRpcId: string | number | null;
-    readonly toolName?: string | undefined;
-    static readonly KEY: ContextKey<McpCorrelation, "untrusted">;
-    constructor(jsonRpcId: string | number | null, toolName?: string | undefined);
-    /** Stamp what this request knows so far; `WpMcpServer` re-stamps once the tool name is known. */
-    static stamp(correlation: McpCorrelation): void;
-    /** A renderer reached before anything stamped (a failure with no parseable body) still renders. */
-    static current(): McpCorrelation;
-    /** The webpieces requestId of the request being served, as every MCP reply reports it. */
-    static requestId(): string;
-}
-/** The only error shape rendered into model-visible MCP tool content. */
-export declare class ModelVisibleToolError {
-    readonly kind: string;
-    readonly message: string;
-    readonly requestId: string;
-    readonly field?: string | undefined;
-    readonly callerMessage?: string | undefined;
-    readonly errorCode?: string | undefined;
-    readonly retryAfterSeconds?: number | undefined;
-    readonly statusCode?: number | undefined;
-    constructor(kind: string, message: string, requestId: string, field?: string | undefined, callerMessage?: string | undefined, errorCode?: string | undefined, retryAfterSeconds?: number | undefined, statusCode?: number | undefined);
-}
-/** JSON-RPC error body written by the HTTP boundary before the SDK is involved. */
-export declare class McpHttpErrorBody {
-    readonly error: McpHttpErrorDetail;
-    readonly id: string | number | null;
-    readonly jsonrpc = "2.0";
-    constructor(error: McpHttpErrorDetail, id: string | number | null);
-}
-export declare class McpHttpErrorDetail {
-    readonly code: number;
-    readonly message: string;
-    readonly data: McpErrorData;
-    constructor(code: number, message: string, data: McpErrorData);
-}
+import { HttpResponseDto } from '@webpieces/core-util';
+import { McpHttpErrorBody } from './McpToolCallRendering';
 /**
- * The application's own `tools/call` error translation — the MCP twin of the `ErrorTranslators` an
- * app registers on `ClientRegistry` for the HTTP path. Register one with
- * `WpMcpServerConfig.setErrorTranslator(...)`; it is NOT a global, because `WpMcpServer` is
- * constructed by app code and two servers may run in one process.
- *
- * An app owns its error taxonomy and owns how those errors should be explained to a model, so a
- * claimed error yields the ENTIRE `CallToolResult` — content, `structuredContent`, `isError`, the lot.
- *
- * Contract:
- * - `error` is the RAW thrown value: an app must be able to `instanceof` its own error classes.
- *   `ApiErrorBoundary` never substitutes an object for the thrown error, so there is exactly one
- *   error value on this path.
- * - There is no "not mine" return. A registered translator REPLACES the webpieces default and
- *   declines by DELEGATING to it: `new McpDefaultToolCallRenderer().toToolCallResult(error)`.
- * - webpieces default-fills `_meta['webpieces/requestId']` only when the returned result has NO
- *   `_meta`. An app that sets `_meta` owns it untouched.
- * - scope is `tools/call` ONLY. The pre-SDK HTTP boundary and `tools/list` stay framework-owned:
- *   that boundary emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` MCP clients
- *   depend on for OAuth discovery, and an app rewriting it breaks connector onboarding.
- */
-export interface McpErrorTranslators {
-    toToolCallResult(error: Error): CallToolResult;
-}
-/**
- * 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`.
- */
-export declare class McpDefaultToolCallRenderer implements McpErrorTranslators {
-    private readonly boundary;
-    toToolCallResult(error: Error): CallToolResult;
-    private modelVisible;
-}
-/**
- * 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:
  *
@@ -108,15 +18,13 @@ export declare class McpDefaultToolCallRenderer implements McpErrorTranslators {
  */
 export declare class WpMcpErrorTranslator {
     private readonly challenge;
-    private readonly appTranslators?;
     private readonly boundary;
     private readonly defaultToolCall;
     /**
      * @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: () => string, appTranslators?: McpErrorTranslators | undefined);
+    constructor(challenge: () => string);
     /**
      * Boundary #1: everything webpieces itself rejects before the SDK is involved — bearer
      * verification, `Origin`, a malformed body. This is 401/403/400/500 today and any status
@@ -143,9 +51,10 @@ export declare class WpMcpErrorTranslator {
      * 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: Error): CallToolResult;
     /** The `_meta` every tools/call result carries so a user can quote its requestId. */
@@ -154,6 +63,9 @@ export declare class WpMcpErrorTranslator {
      * 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.
      */
     private appOrDefault;
     /**

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 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 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     * 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"]}