@webpieces/mcp-server 0.4.773 → 0.4.775

package/src/McpDeployment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpDeployment.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpDeployment.ts"],"names":[],"mappings":";;;AAAA,yDAAsF;AAItF,uFAAuF;AACvF,MAAa,aAAa;IAEF;IACA;IACA;IAHpB,YACoB,IAAuB,EACvB,GAAmB,EACnB,KAAa;QAFb,SAAI,GAAJ,IAAI,CAAmB;QACvB,QAAG,GAAH,GAAG,CAAgB;QACnB,UAAK,GAAL,KAAK,CAAQ;QAE7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAClE,CAAC;IAED,6EAA6E;IAC7E,MAAM,CAAC,aAAa,CAAC,KAAK,GAAG,MAAM;QAC/B,OAAO,IAAI,aAAa,CAAC,gBAAgB,EAAE,IAAI,+BAAsB,EAAE,EAAE,KAAK,CAAC,CAAC;IACpF,CAAC;IAED,6EAA6E;IAC7E,MAAM,CAAC,WAAW,CAAC,GAAmB,EAAE,KAAK,GAAG,MAAM;QAClD,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAC1F,IAAI,GAAG,YAAY,+BAAsB,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACX,4FAA4F,CAC/F,CAAC;QACN,CAAC;QACD,OAAO,IAAI,aAAa,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;CACJ;AAzBD,sCAyBC","sourcesContent":["import { InMemoryServerEventBus, ServerEventBus } from '@modelcontextprotocol/server';\n\nexport type McpDeploymentMode = 'single-process' | 'distributed';\n\n/** Makes process topology and bounded list-cache behavior explicit at construction. */\nexport class McpDeployment {\n    private constructor(\n        public readonly mode: McpDeploymentMode,\n        public readonly bus: ServerEventBus,\n        public readonly ttlMs: number,\n    ) {\n        if (!Number.isFinite(ttlMs) || ttlMs <= 0)\n            throw new Error('MCP list cache ttlMs must be positive.');\n    }\n\n    // webpieces-disable no-function-outside-class -- explicit deployment factory\n    static singleProcess(ttlMs = 30_000): McpDeployment {\n        return new McpDeployment('single-process', new InMemoryServerEventBus(), ttlMs);\n    }\n\n    // webpieces-disable no-function-outside-class -- explicit deployment factory\n    static distributed(bus: ServerEventBus, ttlMs = 30_000): McpDeployment {\n        if (!bus) throw new Error('Distributed MCP deployment requires a shared ServerEventBus.');\n        if (bus instanceof InMemoryServerEventBus) {\n            throw new Error(\n                'Distributed MCP deployment cannot use InMemoryServerEventBus; supply a cross-instance bus.',\n            );\n        }\n        return new McpDeployment('distributed', bus, ttlMs);\n    }\n}\n"]}

package/src/McpInvocationContext.d.ts

@@ -0,0 +1,14 @@
+import { ContextKey } from '@webpieces/core-util';
+export type McpProgressReporter = (progress: number, total?: number, message?: string) => Promise<void>;
+/** Trusted, context-local MCP facts available to a bound application endpoint. */
+export declare class McpInvocationContext {
+    readonly jsonRpcId: string | number;
+    readonly toolName: string;
+    readonly subject: string;
+    readonly roles: readonly string[];
+    readonly signal: AbortSignal;
+    readonly reportProgress?: McpProgressReporter | undefined;
+    constructor(jsonRpcId: string | number, toolName: string, subject: string, roles: readonly string[], signal: AbortSignal, reportProgress?: McpProgressReporter | undefined);
+}
+/** Context-only: it has no HTTP header and cannot be asserted by a remote caller. */
+export declare const MCP_INVOCATION_CONTEXT: ContextKey<McpInvocationContext, "trusted">;

package/src/McpInvocationContext.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_INVOCATION_CONTEXT = exports.McpInvocationContext = void 0;
+const core_util_1 = require("@webpieces/core-util");
+/** Trusted, context-local MCP facts available to a bound application endpoint. */
+class McpInvocationContext {
+    jsonRpcId;
+    toolName;
+    subject;
+    roles;
+    signal;
+    reportProgress;
+    constructor(jsonRpcId, toolName, subject, roles, signal, reportProgress) {
+        this.jsonRpcId = jsonRpcId;
+        this.toolName = toolName;
+        this.subject = subject;
+        this.roles = roles;
+        this.signal = signal;
+        this.reportProgress = reportProgress;
+    }
+}
+exports.McpInvocationContext = McpInvocationContext;
+/** Context-only: it has no HTTP header and cannot be asserted by a remote caller. */
+exports.MCP_INVOCATION_CONTEXT = core_util_1.ContextKey.trusted('mcpInvocationContext', 'constructed from the official MCP SDK request and the verified MCP credential', undefined, false, false);
+//# sourceMappingURL=McpInvocationContext.js.map

package/src/McpInvocationContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpInvocationContext.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpInvocationContext.ts"],"names":[],"mappings":";;;AAAA,oDAAkD;AAQlD,kFAAkF;AAClF,MAAa,oBAAoB;IAET;IACA;IACA;IACA;IACA;IACA;IANpB,YACoB,SAA0B,EAC1B,QAAgB,EAChB,OAAe,EACf,KAAwB,EACxB,MAAmB,EACnB,cAAoC;QALpC,cAAS,GAAT,SAAS,CAAiB;QAC1B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,YAAO,GAAP,OAAO,CAAQ;QACf,UAAK,GAAL,KAAK,CAAmB;QACxB,WAAM,GAAN,MAAM,CAAa;QACnB,mBAAc,GAAd,cAAc,CAAsB;IACrD,CAAC;CACP;AATD,oDASC;AAED,qFAAqF;AACxE,QAAA,sBAAsB,GAAG,sBAAU,CAAC,OAAO,CACpD,sBAAsB,EACtB,+EAA+E,EAC/E,SAAS,EACT,KAAK,EACL,KAAK,CACR,CAAC","sourcesContent":["import { ContextKey } from '@webpieces/core-util';\n\nexport type McpProgressReporter = (\n    progress: number,\n    total?: number,\n    message?: string,\n) => Promise<void>;\n\n/** Trusted, context-local MCP facts available to a bound application endpoint. */\nexport class McpInvocationContext {\n    constructor(\n        public readonly jsonRpcId: string | number,\n        public readonly toolName: string,\n        public readonly subject: string,\n        public readonly roles: readonly string[],\n        public readonly signal: AbortSignal,\n        public readonly reportProgress?: McpProgressReporter,\n    ) {}\n}\n\n/** Context-only: it has no HTTP header and cannot be asserted by a remote caller. */\nexport const MCP_INVOCATION_CONTEXT = ContextKey.trusted<McpInvocationContext>(\n    'mcpInvocationContext',\n    'constructed from the official MCP SDK request and the verified MCP credential',\n    undefined,\n    false,\n    false,\n);\n"]}

package/src/McpToolRegistry.d.ts

@@ -1,5 +1,6 @@
-import { ApiJsonSchema, AuthMeta, DtoClass, DtoSchemaBuilder, WpMcpToolMetadata } from '@webpieces/core-util';
+import { ApiJsonSchema, AuthMeta, DtoClass, DtoSchemaBuilder, WpMcpJwtAuthMetadata, WpMcpToolMetadata } from '@webpieces/core-util';
 import { ClassType } from '@webpieces/http-routing';
+import { McpApiBinding } from './McpApiBinding';
 /** Fully resolved contract metadata for one MCP tool. */
 export declare class RegisteredMcpTool {
     readonly apiClass: ClassType;
@@ -8,19 +9,21 @@ export declare class RegisteredMcpTool {
     readonly description: string;
     readonly annotations: WpMcpToolMetadata['hints'];
     readonly authMeta: AuthMeta;
+    readonly mcpAuth: WpMcpJwtAuthMetadata;
+    readonly binding: McpApiBinding;
     readonly requestClass: DtoClass;
     readonly responseClass: DtoClass;
     readonly inputSchema: ApiJsonSchema;
     readonly outputSchema: ApiJsonSchema;
-    constructor(apiClass: ClassType, methodName: string, name: string, description: string, annotations: WpMcpToolMetadata['hints'], authMeta: AuthMeta, requestClass: DtoClass, responseClass: DtoClass, inputSchema: ApiJsonSchema, outputSchema: ApiJsonSchema);
-    /** Listing is advisory; the ordinary endpoint AuthFilter is the only authorization boundary. */
+    constructor(apiClass: ClassType, methodName: string, name: string, description: string, annotations: WpMcpToolMetadata['hints'], authMeta: AuthMeta, mcpAuth: WpMcpJwtAuthMetadata, binding: McpApiBinding, requestClass: DtoClass, responseClass: DtoClass, inputSchema: ApiJsonSchema, outputSchema: ApiJsonSchema);
+    /** Listing is advisory; MCP authorization is rechecked before the endpoint auth boundary. */
     isVisibleTo(listingRoles: readonly string[]): boolean;
 }
 /** Fail-fast registry built entirely from API/decorator metadata. */
 export declare class McpToolRegistry {
     readonly tools: readonly RegisteredMcpTool[];
     readonly schemaBuilder: DtoSchemaBuilder;
-    constructor(apiClasses: readonly ClassType[]);
+    constructor(bindings: readonly McpApiBinding[]);
     find(name: string): RegisteredMcpTool | undefined;
     private resolve;
 }

package/src/McpToolRegistry.js

@@ -10,28 +10,30 @@ class RegisteredMcpTool {
     description;
     annotations;
     authMeta;
+    mcpAuth;
+    binding;
     requestClass;
     responseClass;
     inputSchema;
     outputSchema;
-    constructor(apiClass, methodName, name, description, annotations, authMeta, requestClass, responseClass, inputSchema, outputSchema) {
+    constructor(apiClass, methodName, name, description, annotations, authMeta, mcpAuth, binding, requestClass, responseClass, inputSchema, outputSchema) {
         this.apiClass = apiClass;
         this.methodName = methodName;
         this.name = name;
         this.description = description;
         this.annotations = annotations;
         this.authMeta = authMeta;
+        this.mcpAuth = mcpAuth;
+        this.binding = binding;
         this.requestClass = requestClass;
         this.responseClass = responseClass;
         this.inputSchema = inputSchema;
         this.outputSchema = outputSchema;
     }
-    /** Listing is advisory; the ordinary endpoint AuthFilter is the only authorization boundary. */
+    /** Listing is advisory; MCP authorization is rechecked before the endpoint auth boundary. */
     isVisibleTo(listingRoles) {
-        if (this.authMeta.mode.kind !== 'jwt')
-            return true;
-        const required = (0, core_util_1.rolesRequired)(this.authMeta.mode.requirement);
-        return required.length === 0 || required.some((role) => listingRoles.includes(role));
+        const required = (0, core_util_1.rolesRequired)(this.mcpAuth.requirement);
+        return (required.length === 0 || required.some((role) => listingRoles.includes(role)));
     }
 }
 exports.RegisteredMcpTool = RegisteredMcpTool;
@@ -39,16 +41,17 @@ exports.RegisteredMcpTool = RegisteredMcpTool;
 class McpToolRegistry {
     tools;
     schemaBuilder = new core_util_1.DtoSchemaBuilder();
-    constructor(apiClasses) {
+    constructor(bindings) {
         const registered = [];
         const names = new Set();
-        for (const apiClass of apiClasses) {
+        for (const binding of bindings) {
+            const apiClass = binding.api;
             for (const metadata of (0, core_util_1.getWpMcpTools)(apiClass)) {
                 if (names.has(metadata.name)) {
                     throw new Error(`Duplicate @WpMcpTool name '${metadata.name}'. Tool names must be globally unique.`);
                 }
                 names.add(metadata.name);
-                registered.push(this.resolve(apiClass, metadata));
+                registered.push(this.resolve(apiClass, metadata, binding));
             }
         }
         this.tools = registered;
@@ -56,7 +59,7 @@ class McpToolRegistry {
     find(name) {
         return this.tools.find((tool) => tool.name === name);
     }
-    resolve(apiClass, metadata) {
+    resolve(apiClass, metadata, binding) {
         const endpoints = (0, core_util_1.getEndpoints)(apiClass) ?? {};
         if (!endpoints[metadata.methodName]) {
             throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must also be an @Endpoint.`);
@@ -65,15 +68,16 @@ class McpToolRegistry {
             throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must be an RPC endpoint.`);
         }
         const authMeta = (0, core_util_1.getAuthMeta)(apiClass, metadata.methodName);
-        if (!authMeta || (authMeta.mode.kind !== 'jwt' && authMeta.mode.kind !== 'public')) {
-            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must use @WpAuthJwt or @WpAuthPublic.`);
-        }
-        if (authMeta.mode.kind === 'public' && !metadata.hints.readOnlyHint) {
-            throw new Error(`Public MCP tool ${metadata.name} must be read-only.`);
+        if (!authMeta)
+            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} has no HTTP auth.`);
+        const mcpAuth = (0, core_util_1.getWpMcpAuthJwt)(apiClass, metadata.methodName);
+        if (!mcpAuth) {
+            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must declare @WpMcpAuthJwt(...).`);
         }
+        binding.validateMethod(metadata.methodName);
         const requestClass = this.schemaBuilder.requestClassOf(apiClass, metadata.methodName);
         const responseClass = this.schemaBuilder.responseClassOf(apiClass, metadata.methodName);
-        return new RegisteredMcpTool(apiClass, metadata.methodName, metadata.name, metadata.description, metadata.hints, authMeta, requestClass, responseClass, this.schemaBuilder.build(requestClass), this.schemaBuilder.build(responseClass));
+        return new RegisteredMcpTool(apiClass, metadata.methodName, metadata.name, metadata.description, metadata.hints, authMeta, mcpAuth, binding, requestClass, responseClass, this.schemaBuilder.build(requestClass), this.schemaBuilder.build(responseClass));
     }
 }
 exports.McpToolRegistry = McpToolRegistry;

package/src/McpToolRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpToolRegistry.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpToolRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiJsonSchema,\n    AuthMeta,\n    DtoClass,\n    DtoSchemaBuilder,\n    getAuthMeta,\n    getEndpointKind,\n    getEndpoints,\n    getWpMcpTools,\n    rolesRequired,\n    WpMcpToolMetadata,\n} from '@webpieces/core-util';\nimport { ClassType } from '@webpieces/http-routing';\n\n/** Fully resolved contract metadata for one MCP tool. */\nexport class RegisteredMcpTool {\n    constructor(\n        public readonly apiClass: ClassType,\n        public readonly methodName: string,\n        public readonly name: string,\n        public readonly description: string,\n        public readonly annotations: WpMcpToolMetadata['hints'],\n        public readonly authMeta: AuthMeta,\n        public readonly requestClass: DtoClass,\n        public readonly responseClass: DtoClass,\n        public readonly inputSchema: ApiJsonSchema,\n        public readonly outputSchema: ApiJsonSchema,\n    ) {}\n\n    /** Listing is advisory; the ordinary endpoint AuthFilter is the only authorization boundary. */\n    isVisibleTo(listingRoles: readonly string[]): boolean {\n        if (this.authMeta.mode.kind !== 'jwt') return true;\n        const required = rolesRequired(this.authMeta.mode.requirement);\n        return required.length === 0 || required.some((role: string) => listingRoles.includes(role));\n    }\n}\n\n/** Fail-fast registry built entirely from API/decorator metadata. */\nexport class McpToolRegistry {\n    readonly tools: readonly RegisteredMcpTool[];\n    readonly schemaBuilder = new DtoSchemaBuilder();\n\n    constructor(apiClasses: readonly ClassType[]) {\n        const registered: RegisteredMcpTool[] = [];\n        const names = new Set<string>();\n        for (const apiClass of apiClasses) {\n            for (const metadata of getWpMcpTools(apiClass)) {\n                if (names.has(metadata.name)) {\n                    throw new Error(`Duplicate @WpMcpTool name '${metadata.name}'. Tool names must be globally unique.`);\n                }\n                names.add(metadata.name);\n                registered.push(this.resolve(apiClass, metadata));\n            }\n        }\n        this.tools = registered;\n    }\n\n    find(name: string): RegisteredMcpTool | undefined {\n        return this.tools.find((tool: RegisteredMcpTool) => tool.name === name);\n    }\n\n    private resolve(apiClass: ClassType, metadata: WpMcpToolMetadata): RegisteredMcpTool {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        if (!endpoints[metadata.methodName]) {\n            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must also be an @Endpoint.`);\n        }\n        if (getEndpointKind(apiClass, metadata.methodName) !== 'rpc') {\n            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} must be an RPC endpoint.`);\n        }\n        const authMeta = getAuthMeta(apiClass, metadata.methodName);\n        if (!authMeta || (authMeta.mode.kind !== 'jwt' && authMeta.mode.kind !== 'public')) {\n            throw new Error(\n                `@WpMcpTool ${apiClass.name}.${metadata.methodName} must use @WpAuthJwt or @WpAuthPublic.`,\n            );\n        }\n        if (authMeta.mode.kind === 'public' && !metadata.hints.readOnlyHint) {\n            throw new Error(`Public MCP tool ${metadata.name} must be read-only.`);\n        }\n        const requestClass = this.schemaBuilder.requestClassOf(apiClass, metadata.methodName);\n        const responseClass = this.schemaBuilder.responseClassOf(apiClass, metadata.methodName);\n        return new RegisteredMcpTool(\n            apiClass,\n            metadata.methodName,\n            metadata.name,\n            metadata.description,\n            metadata.hints,\n            authMeta,\n            requestClass,\n            responseClass,\n            this.schemaBuilder.build(requestClass),\n            this.schemaBuilder.build(responseClass),\n        );\n    }\n}\n"]}
+{"version":3,"file":"McpToolRegistry.js","sourceRoot":"","sources":["../../../../../packages/http/mcp-server/src/McpToolRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiJsonSchema,\n    AuthMeta,\n    DtoClass,\n    DtoSchemaBuilder,\n    getAuthMeta,\n    getEndpointKind,\n    getEndpoints,\n    getWpMcpTools,\n    getWpMcpAuthJwt,\n    rolesRequired,\n    WpMcpJwtAuthMetadata,\n    WpMcpToolMetadata,\n} from '@webpieces/core-util';\nimport { ClassType } from '@webpieces/http-routing';\nimport { McpApiBinding } from './McpApiBinding';\n\n/** Fully resolved contract metadata for one MCP tool. */\nexport class RegisteredMcpTool {\n    constructor(\n        public readonly apiClass: ClassType,\n        public readonly methodName: string,\n        public readonly name: string,\n        public readonly description: string,\n        public readonly annotations: WpMcpToolMetadata['hints'],\n        public readonly authMeta: AuthMeta,\n        public readonly mcpAuth: WpMcpJwtAuthMetadata,\n        public readonly binding: McpApiBinding,\n        public readonly requestClass: DtoClass,\n        public readonly responseClass: DtoClass,\n        public readonly inputSchema: ApiJsonSchema,\n        public readonly outputSchema: ApiJsonSchema,\n    ) {}\n\n    /** Listing is advisory; MCP authorization is rechecked before the endpoint auth boundary. */\n    isVisibleTo(listingRoles: readonly string[]): boolean {\n        const required = rolesRequired(this.mcpAuth.requirement);\n        return (\n            required.length === 0 || required.some((role: string) => listingRoles.includes(role))\n        );\n    }\n}\n\n/** Fail-fast registry built entirely from API/decorator metadata. */\nexport class McpToolRegistry {\n    readonly tools: readonly RegisteredMcpTool[];\n    readonly schemaBuilder = new DtoSchemaBuilder();\n\n    constructor(bindings: readonly McpApiBinding[]) {\n        const registered: RegisteredMcpTool[] = [];\n        const names = new Set<string>();\n        for (const binding of bindings) {\n            const apiClass = binding.api;\n            for (const metadata of getWpMcpTools(apiClass)) {\n                if (names.has(metadata.name)) {\n                    throw new Error(\n                        `Duplicate @WpMcpTool name '${metadata.name}'. Tool names must be globally unique.`,\n                    );\n                }\n                names.add(metadata.name);\n                registered.push(this.resolve(apiClass, metadata, binding));\n            }\n        }\n        this.tools = registered;\n    }\n\n    find(name: string): RegisteredMcpTool | undefined {\n        return this.tools.find((tool: RegisteredMcpTool) => tool.name === name);\n    }\n\n    private resolve(\n        apiClass: ClassType,\n        metadata: WpMcpToolMetadata,\n        binding: McpApiBinding,\n    ): RegisteredMcpTool {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        if (!endpoints[metadata.methodName]) {\n            throw new Error(\n                `@WpMcpTool ${apiClass.name}.${metadata.methodName} must also be an @Endpoint.`,\n            );\n        }\n        if (getEndpointKind(apiClass, metadata.methodName) !== 'rpc') {\n            throw new Error(\n                `@WpMcpTool ${apiClass.name}.${metadata.methodName} must be an RPC endpoint.`,\n            );\n        }\n        const authMeta = getAuthMeta(apiClass, metadata.methodName);\n        if (!authMeta)\n            throw new Error(`@WpMcpTool ${apiClass.name}.${metadata.methodName} has no HTTP auth.`);\n        const mcpAuth = getWpMcpAuthJwt(apiClass, metadata.methodName);\n        if (!mcpAuth) {\n            throw new Error(\n                `@WpMcpTool ${apiClass.name}.${metadata.methodName} must declare @WpMcpAuthJwt(...).`,\n            );\n        }\n        binding.validateMethod(metadata.methodName);\n        const requestClass = this.schemaBuilder.requestClassOf(apiClass, metadata.methodName);\n        const responseClass = this.schemaBuilder.responseClassOf(apiClass, metadata.methodName);\n        return new RegisteredMcpTool(\n            apiClass,\n            metadata.methodName,\n            metadata.name,\n            metadata.description,\n            metadata.hints,\n            authMeta,\n            mcpAuth,\n            binding,\n            requestClass,\n            responseClass,\n            this.schemaBuilder.build(requestClass),\n            this.schemaBuilder.build(responseClass),\n        );\n    }\n}\n"]}

package/src/WpMcpErrorTranslator.d.ts

@@ -0,0 +1,69 @@
+import { CallToolResult, ProtocolError } from '@modelcontextprotocol/server';
+import { Response } from 'express';
+/** `_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);
+}
+/** Correlation facts for one failure; rendered into the single operator log line. */
+export declare class McpFailureScope {
+    readonly requestId: string;
+    readonly jsonRpcId: string | number | null;
+    readonly method: string;
+    readonly toolName?: string | undefined;
+    constructor(requestId: string, jsonRpcId: string | number | null, method: string, toolName?: string | undefined);
+    describe(): 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;
+    constructor(kind: string, message: string, requestId: string, field?: string | undefined, callerMessage?: string | undefined, errorCode?: string | undefined, retryAfterSeconds?: 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 ONE place every MCP failure is mapped to a reply, mirroring `ApiErrorHttpMapper` for HTTP.
+ * Each MCP entry point (the bind HTTP handler, tools/list, tools/call) has exactly one catch that
+ * only delegates here. Normalization and per-kind log levels are the shared `ApiErrorBoundary`
+ * rules, and published text comes only from `ApiErrorCodec.encode`: this class never puts an
+ * error's own message on the wire unless it is an `ApiEndUserError`.
+ */
+export declare class WpMcpErrorTranslator {
+    private readonly boundary;
+    /**
+     * Pre-SDK failures: 401 + WWW-Authenticate, 403, 400 (-32700), anything else 500 (-32603).
+     * A failure after response headers were sent can only end the stream.
+     */
+    toHttp(thrown: Error, res: Response, scope: McpFailureScope, wwwAuthenticate: string): void;
+    /** Express body-parser failures (malformed JSON, body too large) are caller input errors. */
+    toHttpBodyFailure(cause: Error, res: Response, scope: McpFailureScope, wwwAuth: string): void;
+    /** tools/list and other result-less methods: bad-request → -32602, anything else → -32603. */
+    toProtocolError(thrown: Error, scope: McpFailureScope): ProtocolError;
+    /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */
+    unknownTool(toolName: string, scope: McpFailureScope): ProtocolError;
+    /** Every tools/call failure after the tool is found: an `isError: true` result the model sees. */
+    toToolResult(thrown: Error, scope: McpFailureScope): CallToolResult;
+    /** The `_meta` every tools/call result carries so a user can quote its requestId. */
+    resultMeta(requestId: string): Record<string, string>;
+    private modelVisible;
+    private writeHttp;
+}

package/src/WpMcpErrorTranslator.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpMcpErrorTranslator = exports.McpHttpErrorDetail = exports.McpHttpErrorBody = exports.ModelVisibleToolError = exports.McpFailureScope = exports.McpErrorData = exports.MCP_REQUEST_ID_META_KEY = void 0;
+const server_1 = require("@modelcontextprotocol/server");
+const core_util_1 = require("@webpieces/core-util");
+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;
+/** Correlation facts for one failure; rendered into the single operator log line. */
+class McpFailureScope {
+    requestId;
+    jsonRpcId;
+    method;
+    toolName;
+    constructor(requestId, jsonRpcId, method, toolName) {
+        this.requestId = requestId;
+        this.jsonRpcId = jsonRpcId;
+        this.method = method;
+        this.toolName = toolName;
+    }
+    describe() {
+        const tool = this.toolName ? ` tool=${this.toolName}` : '';
+        return `requestId=${this.requestId} jsonRpcId=${String(this.jsonRpcId)} method=${this.method}${tool}`;
+    }
+}
+exports.McpFailureScope = McpFailureScope;
+/** The only error shape rendered into model-visible MCP tool content. */
+class ModelVisibleToolError {
+    kind;
+    message;
+    requestId;
+    field;
+    callerMessage;
+    errorCode;
+    retryAfterSeconds;
+    constructor(kind, message, requestId, field, callerMessage, errorCode, retryAfterSeconds) {
+        this.kind = kind;
+        this.message = message;
+        this.requestId = requestId;
+        this.field = field;
+        this.callerMessage = callerMessage;
+        this.errorCode = errorCode;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+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;
+/**
+ * The ONE place every MCP failure is mapped to a reply, mirroring `ApiErrorHttpMapper` for HTTP.
+ * Each MCP entry point (the bind HTTP handler, tools/list, tools/call) has exactly one catch that
+ * only delegates here. Normalization and per-kind log levels are the shared `ApiErrorBoundary`
+ * rules, and published text comes only from `ApiErrorCodec.encode`: this class never puts an
+ * error's own message on the wire unless it is an `ApiEndUserError`.
+ */
+class WpMcpErrorTranslator {
+    boundary = new core_util_1.ApiErrorBoundary(log);
+    /**
+     * Pre-SDK failures: 401 + WWW-Authenticate, 403, 400 (-32700), anything else 500 (-32603).
+     * A failure after response headers were sent can only end the stream.
+     */
+    toHttp(thrown, res, scope, wwwAuthenticate) {
+        const error = this.boundary.normalize(thrown);
+        this.boundary.logOperatorDetail(error, scope.describe());
+        if (res.headersSent) {
+            res.end();
+            return;
+        }
+        const generic = core_util_1.ApiErrorCodec.encode(error).message;
+        switch (error.kind) {
+            case 'unauthorized':
+                res.setHeader('WWW-Authenticate', wwwAuthenticate);
+                this.writeHttp(res, 401, -32_000, generic, scope);
+                return;
+            case 'forbidden':
+                this.writeHttp(res, 403, -32_000, generic, scope);
+                return;
+            case 'bad-request':
+                this.writeHttp(res, 400, server_1.ProtocolErrorCode.ParseError, generic, scope);
+                return;
+            default:
+                this.writeHttp(res, 500, server_1.ProtocolErrorCode.InternalError, 'Internal Error', scope);
+        }
+    }
+    /** Express body-parser failures (malformed JSON, body too large) are caller input errors. */
+    toHttpBodyFailure(cause, res, scope, wwwAuth) {
+        this.toHttp(new core_util_1.ApiBadRequestError(`MCP request body rejected: ${cause.message}`, undefined, undefined, cause), res, scope, wwwAuth);
+    }
+    /** tools/list and other result-less methods: bad-request → -32602, anything else → -32603. */
+    toProtocolError(thrown, scope) {
+        const error = this.boundary.normalize(thrown);
+        this.boundary.logOperatorDetail(error, scope.describe());
+        const payload = core_util_1.ApiErrorCodec.encode(error);
+        if (error.kind === 'bad-request') {
+            return new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, payload.callerMessage ?? payload.message, new McpErrorData(scope.requestId));
+        }
+        const message = error.kind === 'end-user' ? payload.message : 'Internal Error';
+        return new server_1.ProtocolError(server_1.ProtocolErrorCode.InternalError, message, new McpErrorData(scope.requestId));
+    }
+    /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */
+    unknownTool(toolName, scope) {
+        log.info(`Unknown MCP tool: ${scope.describe()}`);
+        return new server_1.ProtocolError(server_1.ProtocolErrorCode.InvalidParams, `Unknown tool: ${toolName}`, new McpErrorData(scope.requestId));
+    }
+    /** Every tools/call failure after the tool is found: an `isError: true` result the model sees. */
+    toToolResult(thrown, scope) {
+        const error = this.boundary.normalize(thrown);
+        this.boundary.logOperatorDetail(error, scope.describe());
+        const visible = this.modelVisible(core_util_1.ApiErrorCodec.encode(error), scope);
+        const text = JSON.stringify(visible);
+        return {
+            content: [{ type: 'text', text }],
+            isError: true,
+            _meta: this.resultMeta(scope.requestId),
+        };
+    }
+    /** The `_meta` every tools/call result carries so a user can quote its requestId. */
+    resultMeta(requestId) {
+        return { [exports.MCP_REQUEST_ID_META_KEY]: requestId };
+    }
+    modelVisible(payload, scope) {
+        switch (payload.kind) {
+            case 'end-user':
+                return new ModelVisibleToolError(payload.kind, payload.message, scope.requestId, undefined, undefined, payload.errorCode);
+            case 'bad-request':
+                return new ModelVisibleToolError(payload.kind, payload.callerMessage ?? payload.message, scope.requestId, payload.field, payload.callerMessage);
+            case 'implementation':
+                return new ModelVisibleToolError(payload.kind, `Internal error in tool ${scope.toolName ?? 'unknown'} (requestId ${scope.requestId}). ` +
+                    'This is a bug in the tool, not in your arguments; retrying with different ' +
+                    'arguments will not help.', scope.requestId);
+            default:
+                return new ModelVisibleToolError(payload.kind, payload.message, scope.requestId, undefined, undefined, undefined, payload.retryAfterSeconds);
+        }
+    }
+    writeHttp(res, status, code, message, scope) {
+        res.status(status).json(new McpHttpErrorBody(new McpHttpErrorDetail(code, message, new McpErrorData(scope.requestId)), scope.jsonRpcId));
+    }
+}
+exports.WpMcpErrorTranslator = WpMcpErrorTranslator;
+//# sourceMappingURL=WpMcpErrorTranslator.js.map

package/src/WpMcpErrorTranslator.js.map

@@ -0,0 +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 { Response } from 'express';\nimport {\n    ApiBadRequestError,\n    ApiErrorBoundary,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    DtoValue,\n    LogManager,\n} from '@webpieces/core-util';\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/** Correlation facts for one failure; rendered into the single operator log line. */\nexport class McpFailureScope {\n    constructor(\n        public readonly requestId: string,\n        public readonly jsonRpcId: string | number | null,\n        public readonly method: string,\n        public readonly toolName?: string,\n    ) {}\n\n    describe(): string {\n        const tool = this.toolName ? ` tool=${this.toolName}` : '';\n        return `requestId=${this.requestId} jsonRpcId=${String(this.jsonRpcId)} method=${this.method}${tool}`;\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    ) {}\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 ONE place every MCP failure is mapped to a reply, mirroring `ApiErrorHttpMapper` for HTTP.\n * Each MCP entry point (the bind HTTP handler, tools/list, tools/call) has exactly one catch that\n * only delegates here. Normalization and per-kind log levels are the shared `ApiErrorBoundary`\n * rules, and published text comes only from `ApiErrorCodec.encode`: this class never puts an\n * error's own message on the wire unless it is an `ApiEndUserError`.\n */\nexport class WpMcpErrorTranslator {\n    private readonly boundary = new ApiErrorBoundary(log);\n\n    /**\n     * Pre-SDK failures: 401 + WWW-Authenticate, 403, 400 (-32700), anything else 500 (-32603).\n     * A failure after response headers were sent can only end the stream.\n     */\n    toHttp(thrown: Error, res: Response, scope: McpFailureScope, wwwAuthenticate: string): void {\n        const error = this.boundary.normalize(thrown);\n        this.boundary.logOperatorDetail(error, scope.describe());\n        if (res.headersSent) {\n            res.end();\n            return;\n        }\n        const generic = ApiErrorCodec.encode(error).message;\n        switch (error.kind) {\n            case 'unauthorized':\n                res.setHeader('WWW-Authenticate', wwwAuthenticate);\n                this.writeHttp(res, 401, -32_000, generic, scope);\n                return;\n            case 'forbidden':\n                this.writeHttp(res, 403, -32_000, generic, scope);\n                return;\n            case 'bad-request':\n                this.writeHttp(res, 400, ProtocolErrorCode.ParseError, generic, scope);\n                return;\n            default:\n                this.writeHttp(res, 500, ProtocolErrorCode.InternalError, 'Internal Error', scope);\n        }\n    }\n\n    /** Express body-parser failures (malformed JSON, body too large) are caller input errors. */\n    toHttpBodyFailure(cause: Error, res: Response, scope: McpFailureScope, wwwAuth: string): void {\n        this.toHttp(\n            new ApiBadRequestError(\n                `MCP request body rejected: ${cause.message}`,\n                undefined,\n                undefined,\n                cause,\n            ),\n            res,\n            scope,\n            wwwAuth,\n        );\n    }\n\n    /** tools/list and other result-less methods: bad-request → -32602, anything else → -32603. */\n    toProtocolError(thrown: Error, scope: McpFailureScope): ProtocolError {\n        const error = this.boundary.normalize(thrown);\n        this.boundary.logOperatorDetail(error, scope.describe());\n        const payload = ApiErrorCodec.encode(error);\n        if (error.kind === 'bad-request') {\n            return new ProtocolError(\n                ProtocolErrorCode.InvalidParams,\n                payload.callerMessage ?? payload.message,\n                new McpErrorData(scope.requestId),\n            );\n        }\n        const message = error.kind === 'end-user' ? payload.message : 'Internal Error';\n        return new ProtocolError(\n            ProtocolErrorCode.InternalError,\n            message,\n            new McpErrorData(scope.requestId),\n        );\n    }\n\n    /** tools/call with a name no binding registered: a JSON-RPC protocol error per MCP 2026-07-28. */\n    unknownTool(toolName: string, scope: McpFailureScope): ProtocolError {\n        log.info(`Unknown MCP tool: ${scope.describe()}`);\n        return new ProtocolError(\n            ProtocolErrorCode.InvalidParams,\n            `Unknown tool: ${toolName}`,\n            new McpErrorData(scope.requestId),\n        );\n    }\n\n    /** Every tools/call failure after the tool is found: an `isError: true` result the model sees. */\n    toToolResult(thrown: Error, scope: McpFailureScope): CallToolResult {\n        const error = this.boundary.normalize(thrown);\n        this.boundary.logOperatorDetail(error, scope.describe());\n        const visible = this.modelVisible(ApiErrorCodec.encode(error), scope);\n        const text = JSON.stringify(visible as DtoValue);\n        return {\n            content: [{ type: 'text', text }],\n            isError: true,\n            _meta: this.resultMeta(scope.requestId),\n        };\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    private modelVisible(payload: ApiErrorPayload, scope: McpFailureScope): ModelVisibleToolError {\n        switch (payload.kind) {\n            case 'end-user':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.message,\n                    scope.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                    scope.requestId,\n                    payload.field,\n                    payload.callerMessage,\n                );\n            case 'implementation':\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    `Internal error in tool ${scope.toolName ?? 'unknown'} (requestId ${scope.requestId}). ` +\n                        'This is a bug in the tool, not in your arguments; retrying with different ' +\n                        'arguments will not help.',\n                    scope.requestId,\n                );\n            default:\n                return new ModelVisibleToolError(\n                    payload.kind,\n                    payload.message,\n                    scope.requestId,\n                    undefined,\n                    undefined,\n                    undefined,\n                    payload.retryAfterSeconds,\n                );\n        }\n    }\n\n    private writeHttp(\n        res: Response,\n        status: number,\n        code: number,\n        message: string,\n        scope: McpFailureScope,\n    ): void {\n        res.status(status).json(\n            new McpHttpErrorBody(\n                new McpHttpErrorDetail(code, message, new McpErrorData(scope.requestId)),\n                scope.jsonRpcId,\n            ),\n        );\n    }\n}\n"]}

package/src/WpMcpServer.d.ts

@@ -1,34 +1,65 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ApiFactory, ClassType } from '@webpieces/http-routing';
+import { Express } from 'express';
 import { McpProtectedResourceMetadata, WpMcpServerConfig } from './McpAuth';
-/** The only error shape rendered into model-visible MCP content. */
-export declare class ModelVisibleToolError {
-    readonly kind: string;
-    readonly message: string;
-    readonly requestId?: string | undefined;
-    readonly field?: string | undefined;
-    readonly callerMessage?: string | undefined;
-    readonly errorCode?: string | undefined;
-    readonly retryAfterSeconds?: number | undefined;
-    constructor(kind: string, message: string, requestId?: string | undefined, field?: string | undefined, callerMessage?: string | undefined, errorCode?: string | undefined, retryAfterSeconds?: number | undefined);
-}
+import { McpBindOptions } from './McpBindOptions';
 /**
- * Node-only MCP adapter. Build one Server per authenticated transport/session; every tool call still
- * re-enters the endpoint's ordinary AuthFilter, so tools/list visibility never grants access.
+ * Modern-only MCP 2026-07-28 adapter around the official SDK's request-scoped HTTP handler.
+ *
+ * Error boundary: every failure is mapped by the one `WpMcpErrorTranslator`, and each entry point
+ * has exactly one catch that only delegates to it: the bind HTTP handler (`toHttp`), tools/list
+ * (`toProtocolError`) and tools/call (`toToolResult`). `subscriptions/listen` is served entirely by
+ * the SDK's listen router, so Webpieces has no handler (and no catch) there. The external bearer is
+ * verified exactly once per POST, at the HTTP boundary, before the SDK is involved.
  */
 export declare class WpMcpServer<TGrant, TMintRequest> {
     private readonly config;
-    private readonly registry;
     private readonly dispatcher;
-    constructor(config: WpMcpServerConfig<TGrant, TMintRequest>, apiFactory: ApiFactory, apiClasses: readonly ClassType[]);
-    build(accessToken: string): Promise<Server>;
+    private readonly translator;
+    private registry?;
+    private handler?;
+    private streamingHandler?;
+    private nodeHandler?;
+    private streamingNodeHandler?;
+    private revision?;
+    constructor(config: WpMcpServerConfig<TGrant, TMintRequest>);
+    bind(app: Express, options: McpBindOptions): void;
     protectedResourceMetadata(): McpProtectedResourceMetadata;
-    private buildForAccessToken;
-    private verifyCredential;
+    /** Gracefully closes active listen/request streams; clients must reconnect and refresh lists. */
+    close(): Promise<void>;
+    /** Level-triggered invalidation; the authoritative list is always fetched again by clients. */
+    toolsChanged(): void;
+    get registryRevision(): string | undefined;
+    private createHandler;
+    /** Entry point #1: the one catch for everything before and around the SDK exchange. */
+    private handleHttp;
+    private serveExpress;
+    /** Verifies the external bearer once for this POST. Handlers never re-verify it. */
+    private authenticate;
+    private disconnectSignal;
+    private buildSdkServer;
+    /** Entry point #2: tools/list has no tool-result channel, so failures are JSON-RPC errors. */
+    private handleListTools;
+    private listTools;
+    private toolDefinition;
+    /**
+     * Entry point #3: an unknown tool is a JSON-RPC -32602; every failure after the tool is found
+     * is an `isError: true` result, identically for local and remote bindings.
+     */
+    private handleCallTool;
+    /** Everything a tool call does. No catch in here: failures propagate to handleCallTool. */
+    private callTool;
+    private mintEndpointJwt;
     private validateCredential;
-    private call;
-    private validateEndpointJwt;
-    private apiError;
-    private errorResult;
+    private authInfo;
+    private progressReporter;
+    private progressParams;
+    private requestId;
+    private sdkScope;
+    private httpScope;
+    private challenge;
+    private bodyObject;
+    private hasProgressToken;
+    private toHttpRequest;
+    private calculateRegistryRevision;
+    private requireRegistry;
     private record;
 }