@webpieces/mcp-server 0.4.789 → 0.4.791

package/src/McpToolCallRendering.d.ts

@@ -0,0 +1,111 @@
+import { CallToolResult } from '@modelcontextprotocol/server';
+import { ContextKey } 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);
+}
+/**
+ * The application's own `tools/call` error translation — the MCP twin of the `ErrorTranslator` an app
+ * registers on `ClientRegistry` for HTTP and the `IpcErrorTranslator` it registers on `IpcRegistry`.
+ * Register one with {@link McpRegistry.setErrorTranslator}.
+ *
+ * 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.
+ *
+ * # There is NO `fromWire`, and that is the protocol, not an oversight
+ *
+ * The HTTP and IPC translators have two halves because webpieces sits on BOTH ends of those wires: it
+ * writes the response AND, in another process, reads one. **webpieces is never the MCP client.** The
+ * client is Claude (or another model host); there is no return path for webpieces to translate, so
+ * the pair is one-directional by nature. Do not "restore the symmetry" by adding a half with nothing
+ * to call it.
+ *
+ * # The pre-SDK boundary does NOT share the HTTP `ErrorTranslator`, despite the identical type
+ *
+ * `WpMcpErrorTranslator.toBearerBoundaryResponse` returns an `HttpResponseDto`, exactly like
+ * `ErrorTranslator.toWire` — and it must STILL not be routed through it. Two reasons, both hard:
+ *
+ * - its body must stay JSON-RPC shaped (`McpHttpErrorBody`) or an MCP client cannot parse the reply
+ *   at all, whereas an app's HTTP translator publishes the app's own REST envelope;
+ * - it emits the `401 + WWW-Authenticate: Bearer resource_metadata=...` that MCP clients use for OAuth
+ *   discovery, so an app rewriting it breaks connector onboarding.
+ *
+ * Same TYPE, different OWNER. `tools/list` is framework-owned for the same reason.
+ *
+ * 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().toWire(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.
+ */
+export interface McpErrorTranslator {
+    /** An error in, the whole `tools/call` reply out. Named for its HTTP and IPC twins. */
+    toWire(error: Error): CallToolResult;
+}
+/**
+ * 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`.
+ */
+export declare class McpDefaultToolCallRenderer implements McpErrorTranslator {
+    private readonly boundary;
+    toWire(error: Error): CallToolResult;
+    private modelVisible;
+}

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
@@ -137,15 +45,16 @@ export declare class WpMcpErrorTranslator {
      * error's operator text to the caller.
      */
     toListError(error: Error): never;
-    /** 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: string): ProtocolError;
     /**
      * 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;
     /**