@webpieces/mcp-server 0.4.772 → 0.4.774

package/src/WpMcpServer.js

@@ -1,212 +1,389 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WpMcpServer = exports.ModelVisibleToolError = void 0;
-const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
-const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+exports.WpMcpServer = void 0;
+const node_crypto_1 = require("node:crypto");
+const server_1 = require("@modelcontextprotocol/server");
+const node_1 = require("@modelcontextprotocol/node");
+const express_1 = require("express");
 const core_util_1 = require("@webpieces/core-util");
+const core_context_1 = require("@webpieces/core-context");
 const McpAuth_1 = require("./McpAuth");
 const McpApiDispatcher_1 = require("./McpApiDispatcher");
+const McpInvocationContext_1 = require("./McpInvocationContext");
 const McpToolRegistry_1 = require("./McpToolRegistry");
+const WpMcpErrorTranslator_1 = require("./WpMcpErrorTranslator");
 const log = core_util_1.LogManager.getLogger('WpMcpServer');
-/** The only error shape rendered into model-visible MCP 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;
+/** Facts established once per POST at the bind boundary and handed to the SDK handlers. */
+class McpPostAuthentication {
+    accessToken;
+    credential;
+    disconnectSignal;
+    constructor(accessToken, credential, disconnectSignal) {
+        this.accessToken = accessToken;
+        this.credential = credential;
+        this.disconnectSignal = disconnectSignal;
     }
 }
-exports.ModelVisibleToolError = ModelVisibleToolError;
 /**
- * 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.
+ * The official SDK server with Webpieces-owned tools/list and tools/call handlers. It answers
+ * `toolInputSchemaJson` from the Webpieces registry so the SDK's pre-dispatch SEP-2243
+ * `Mcp-Param-*` header validation still runs without registering SDK-side tool callbacks.
+ */
+class WpSdkMcpServer extends server_1.McpServer {
+    registry;
+    constructor(info, options, registry) {
+        super(info, options);
+        this.registry = registry;
+    }
+    // webpieces-disable no-any-unknown -- signature is fixed by the SDK's JSON Schema record type
+    toolInputSchemaJson(name) {
+        return this.registry.find(name)?.inputSchema;
+    }
+}
+/**
+ * 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.
  */
 class WpMcpServer {
     config;
+    dispatcher = new McpApiDispatcher_1.McpApiDispatcher();
+    translator = new WpMcpErrorTranslator_1.WpMcpErrorTranslator();
     registry;
-    dispatcher;
-    constructor(config, apiFactory, apiClasses) {
+    handler;
+    streamingHandler;
+    nodeHandler;
+    streamingNodeHandler;
+    revision;
+    constructor(config) {
         this.config = config;
-        this.registry = new McpToolRegistry_1.McpToolRegistry(apiClasses);
-        this.dispatcher = new McpApiDispatcher_1.McpApiDispatcher(apiFactory);
     }
-    async build(accessToken) {
-        await this.verifyCredential(accessToken);
-        return this.buildForAccessToken(accessToken);
+    bind(app, options) {
+        if (this.handler)
+            throw new Error('WpMcpServer.bind(...) may be called only once.');
+        this.registry = new McpToolRegistry_1.McpToolRegistry(options.bindings);
+        this.revision = this.calculateRegistryRevision(this.registry);
+        this.handler = this.createHandler(options, 'auto');
+        this.streamingHandler = this.createHandler(options, 'sse');
+        this.nodeHandler = (0, node_1.toNodeHandler)(this.handler, {
+            onerror: (error) => log.error('MCP Node transport failed', error),
+        });
+        this.streamingNodeHandler = (0, node_1.toNodeHandler)(this.streamingHandler, {
+            onerror: (error) => log.error('MCP streaming Node transport failed', error),
+        });
+        app.post(options.endpointPath, (0, express_1.json)(), async (req, res) => this.handleHttp(req, res, options), 
+        // Express routes body-parser failures (bad JSON, body too large) to an error handler.
+        (err, req, res, _next) => core_context_1.RequestContext.run(() => {
+            new core_context_1.RequestContextHeaders().fillFromRequest(this.toHttpRequest(req));
+            this.translator.toHttpBodyFailure(err, res, this.httpScope(req), this.challenge());
+        }));
     }
     protectedResourceMetadata() {
         return this.config.protectedResourceMetadata();
     }
-    buildForAccessToken(accessToken) {
-        const server = new index_js_1.Server(
-        // webpieces-disable no-anonymous-object-literals -- external MCP SDK request structure
-        { name: this.config.name, version: this.config.version }, 
-        // webpieces-disable no-anonymous-object-literals -- external MCP SDK capability structure
-        { capabilities: { tools: {} } });
-        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
-            const credential = await this.verifyCredential(accessToken);
-            return {
-                tools: this.registry.tools
-                    .filter((tool) => tool.isVisibleTo(credential.listingRoles))
-                    .map((tool) => ({
-                    name: tool.name,
-                    description: tool.description,
-                    inputSchema: tool.inputSchema,
-                    outputSchema: tool.outputSchema,
-                    annotations: tool.annotations,
-                })),
-            };
+    /** Gracefully closes active listen/request streams; clients must reconnect and refresh lists. */
+    async close() {
+        await Promise.all([this.handler?.close(), this.streamingHandler?.close()]);
+    }
+    /** Level-triggered invalidation; the authoritative list is always fetched again by clients. */
+    toolsChanged() {
+        this.handler?.notify.toolsChanged();
+    }
+    get registryRevision() {
+        return this.revision;
+    }
+    createHandler(options, responseMode) {
+        return (0, server_1.createMcpHandler)((context) => this.buildSdkServer(context, options), {
+            legacy: 'reject',
+            responseMode,
+            bus: options.deployment.bus,
+            maxSubscriptions: options.maxSubscriptions,
+            keepAliveMs: options.keepAliveMs,
+            onerror: (error) => log.warn('MCP protocol request rejected', error),
         });
-        server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
-            const tool = this.registry.find(request.params.name);
-            if (!tool) {
-                throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+    }
+    /** Entry point #1: the one catch for everything before and around the SDK exchange. */
+    async handleHttp(req, res, options) {
+        res.setHeader('X-Accel-Buffering', 'no');
+        await core_context_1.RequestContext.run(async () => {
+            new core_context_1.RequestContextHeaders().fillFromRequest(this.toHttpRequest(req));
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP HTTP entry point; delegates only to WpMcpErrorTranslator
+            try {
+                await this.serveExpress(req, res, options);
+            }
+            catch (err) {
+                const error = (0, core_util_1.toError)(err);
+                this.translator.toHttp(error, res, this.httpScope(req), this.challenge());
             }
-            return this.call(tool, request.params.arguments ?? {}, accessToken);
         });
+    }
+    async serveExpress(req, res, options) {
+        const origin = req.header('origin');
+        if (origin && !options.allowedOrigins.includes(origin)) {
+            throw new core_util_1.ApiForbiddenError(`MCP request Origin '${origin}' is not allowed.`);
+        }
+        const authentication = await this.authenticate(req);
+        const request = req;
+        request.auth = this.authInfo(authentication);
+        const serve = this.hasProgressToken(req.body)
+            ? this.streamingNodeHandler
+            : this.nodeHandler;
+        if (!serve)
+            throw new core_util_1.ApiImplementationError('MCP Node handlers are not initialized.');
+        await serve(request, res, req.body);
+    }
+    /** Verifies the external bearer once for this POST. Handlers never re-verify it. */
+    async authenticate(req) {
+        const match = req.header('authorization')?.match(/^Bearer ([^\s]+)$/i);
+        const token = match?.[1];
+        if (!token)
+            throw new core_util_1.ApiUnauthorizedError('MCP request has no bearer access token.');
+        const credential = await this.config.accessTokenAuthority.verifyAccessToken(token, this.config.resource);
+        this.validateCredential(credential);
+        return new McpPostAuthentication(token, credential, this.disconnectSignal(req));
+    }
+    disconnectSignal(req) {
+        const disconnected = new AbortController();
+        const res = req.res;
+        const cancel = () => disconnected.abort();
+        req.once('aborted', cancel);
+        req.socket.once('close', cancel);
+        res?.once('close', cancel);
+        res?.once('finish', () => {
+            req.off('aborted', cancel);
+            req.socket.off('close', cancel);
+            res.off('close', cancel);
+        });
+        return disconnected.signal;
+    }
+    buildSdkServer(context, options) {
+        const authentication = context.authInfo?.extra?.['webpiecesAuthentication'];
+        if (context.era !== 'modern' || !(authentication instanceof McpPostAuthentication)) {
+            throw new core_util_1.ApiImplementationError('WpMcpServer serves only MCP 2026-07-28 requests authenticated by its bind boundary.');
+        }
+        const registry = this.requireRegistry();
+        const server = new WpSdkMcpServer({ name: this.config.name, version: `${this.config.version}+${this.revision}` }, {
+            capabilities: { tools: { listChanged: true } },
+            cacheHints: {
+                'tools/list': { ttlMs: options.deployment.ttlMs, cacheScope: 'private' },
+                'server/discover': { ttlMs: options.deployment.ttlMs, cacheScope: 'private' },
+            },
+        }, registry);
+        server.server.removeRequestHandler('tools/list');
+        server.server.removeRequestHandler('tools/call');
+        server.server.setRequestHandler('tools/list', async (_request, sdkContext) => this.handleListTools(authentication, sdkContext));
+        server.server.setRequestHandler('tools/call', async (request, sdkContext) => this.handleCallTool(server, request, authentication, sdkContext));
         return server;
     }
-    async verifyCredential(accessToken) {
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- security boundary logs owner detail and exposes only a generic authentication failure
+    /** Entry point #2: tools/list has no tool-result channel, so failures are JSON-RPC errors. */
+    async handleListTools(authentication, sdkContext) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP tools/list entry point; delegates only to WpMcpErrorTranslator
         try {
-            const credential = await this.config.accessTokenAuthority.verifyAccessToken(accessToken, this.config.resource);
-            this.validateCredential(credential);
-            return credential;
+            return this.listTools(authentication.credential);
         }
         catch (err) {
             const error = (0, core_util_1.toError)(err);
-            log.warn('MCP access-token verification rejected a request', error);
-            throw new core_util_1.ApiUnauthorizedError('MCP access token rejected.', undefined, error);
+            throw this.translator.toProtocolError(error, this.sdkScope(sdkContext, 'tools/list'));
         }
     }
-    validateCredential(credential) {
-        const now = Math.floor(Date.now() / 1000);
-        if (credential.subject.trim() === '') {
-            throw new Error('MCP access token has no subject.');
-        }
-        if (!Number.isFinite(credential.issuedAtEpochSeconds) ||
-            !Number.isFinite(credential.expiresAtEpochSeconds) ||
-            !Number.isFinite(credential.accountValidatedAtEpochSeconds)) {
-            throw new Error('MCP access token security timestamps must be finite.');
-        }
-        if (credential.resource !== this.config.resource) {
-            throw new Error('MCP access token was not issued for this protected resource.');
-        }
-        if (!this.config.authorizationServers.includes(credential.issuer)) {
-            throw new Error('MCP access token issuer is not trusted by this protected resource.');
-        }
-        if (credential.issuedAtEpochSeconds > now) {
-            throw new Error('MCP access token was issued in the future.');
-        }
-        if (credential.expiresAtEpochSeconds <= now) {
-            throw new Error('MCP access token has expired.');
-        }
-        if (credential.expiresAtEpochSeconds - credential.issuedAtEpochSeconds >
-            McpAuth_1.MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS) {
-            throw new Error('MCP access token lifetime exceeds 30 days.');
-        }
-        for (const scope of this.config.requiredScopes) {
-            if (!credential.scopes.includes(scope)) {
-                throw new Error(`MCP access token is missing required scope '${scope}'.`);
-            }
-        }
-        if (credential.accountValidatedAtEpochSeconds > now ||
-            now - credential.accountValidatedAtEpochSeconds > this.config.maxAccountValidationAgeSeconds) {
-            throw new Error('MCP account authorization state is not fresh enough for dispatch.');
+    listTools(credential) {
+        const tools = [];
+        for (const tool of this.requireRegistry().tools) {
+            if (tool.isVisibleTo(credential.listingRoles))
+                tools.push(this.toolDefinition(tool));
         }
+        return { tools };
     }
-    async call(tool, args, accessToken) {
-        let credential;
-        // webpieces-disable no-unmanaged-exceptions -- MCP transport boundary normalizes authentication failures before they reach the model
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP transport boundary
-        try {
-            credential = await this.verifyCredential(accessToken);
-        }
-        catch (err) {
-            //const error = toError(err);
-            throw new types_js_1.McpError(types_js_1.ErrorCode.InvalidRequest, 'Unauthorized');
-        }
-        let endpointJwt;
-        // webpieces-disable no-unmanaged-exceptions -- MCP transport boundary logs mint failures and exposes only a generic protocol error
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP transport boundary
+    toolDefinition(tool) {
+        return {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: tool.annotations,
+            _meta: { webpiecesRegistryRevision: this.revision },
+        };
+    }
+    /**
+     * 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.
+     */
+    async handleCallTool(server, request, authentication, sdkContext) {
+        const name = request.params.name;
+        const scope = this.sdkScope(sdkContext, 'tools/call', name);
+        const tool = this.requireRegistry().find(name);
+        if (!tool)
+            throw this.translator.unknownTool(name, scope);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- MCP tools/call entry point; delegates only to WpMcpErrorTranslator
         try {
-            const descriptor = new McpAuth_1.McpEndpointDescriptor(tool.name, tool.apiClass.name, tool.methodName);
-            const mintRequest = this.config.endpointMintRequest(credential, descriptor);
-            endpointJwt = await this.config.endpointJwtAuthority.mint(mintRequest);
-            this.validateEndpointJwt(endpointJwt, accessToken);
+            const result = await this.callTool(tool, request, authentication, sdkContext);
+            result._meta = this.translator.resultMeta(scope.requestId);
+            return server.server.projectCallToolResult(result, tool.outputSchema);
         }
         catch (err) {
             const error = (0, core_util_1.toError)(err);
-            log.error(`MCP endpoint credential mint failed for ${tool.apiClass.name}.${tool.methodName}`, error);
-            throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, 'Internal Error');
+            return this.translator.toToolResult(error, scope);
         }
-        const result = await this.dispatcher.call(tool, args ?? {}, endpointJwt.token);
-        if (!result.success)
-            return this.apiError(result.error, result.requestId);
-        const outputFailure = this.registry.schemaBuilder.validate(tool.responseClass, result.value);
+    }
+    /** Everything a tool call does. No catch in here: failures propagate to handleCallTool. */
+    async callTool(tool, request, authentication, sdkContext) {
+        const credential = authentication.credential;
+        const endpointJwt = tool.binding.topology === 'local'
+            ? await this.mintEndpointJwt(tool, authentication)
+            : undefined;
+        const invocation = new McpInvocationContext_1.McpInvocationContext(sdkContext.mcpReq.id, tool.name, credential.subject, credential.listingRoles, AbortSignal.any([sdkContext.mcpReq.signal, authentication.disconnectSignal]), this.progressReporter(sdkContext));
+        const args = (request.params.arguments ?? {});
+        const value = await this.dispatcher.call(tool, args, credential, invocation, endpointJwt?.token);
+        const outputFailure = this.requireRegistry().schemaBuilder.validate(tool.responseClass, value);
         if (outputFailure) {
-            log.error(`MCP output schema violation for ${tool.apiClass.name}.${tool.methodName}: ${outputFailure.message}`);
-            return this.errorResult(new ModelVisibleToolError('implementation', 'Internal Error', result.requestId));
-        }
-        let structured;
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- transport boundary sanitizes serialization failures
-        try {
-            structured = this.record(result.value);
-        }
-        catch (err) {
-            const error = (0, core_util_1.toError)(err);
-            log.error(`MCP response serialization failed for ${tool.apiClass.name}.${tool.methodName}`, error);
-            return this.errorResult(new ModelVisibleToolError('implementation', 'Internal Error', result.requestId));
+            throw new core_util_1.ApiImplementationError(`MCP output schema violation for ${tool.apiClass.name}.${tool.methodName}: ${outputFailure.message}`);
         }
+        const structured = this.record(value);
         return {
             content: [{ type: 'text', text: JSON.stringify(structured) }],
             structuredContent: structured,
         };
     }
-    validateEndpointJwt(endpointJwt, accessToken) {
+    async mintEndpointJwt(tool, authentication) {
+        const descriptor = new McpAuth_1.McpEndpointDescriptor(tool.name, tool.apiClass.name, tool.methodName);
+        const minted = await this.config.endpointJwtAuthority.mint(this.config.endpointMintRequest(authentication.credential, descriptor));
         const now = Math.floor(Date.now() / 1000);
-        if (endpointJwt.token === accessToken) {
-            throw new Error('MCP access-token passthrough to endpoint dispatch is forbidden.');
-        }
-        if (endpointJwt.expiresAtEpochSeconds <= now) {
-            throw new Error('MCP endpoint JWT has already expired.');
+        if (minted.token === authentication.accessToken) {
+            throw new core_util_1.ApiImplementationError(`MCP access-token passthrough is forbidden (endpoint JWT for ${tool.name}).`);
         }
-        if (endpointJwt.expiresAtEpochSeconds - now >
-            this.config.maxEndpointJwtLifetimeSeconds) {
-            throw new Error('MCP endpoint JWT lifetime exceeds the configured one-hour ceiling.');
+        if (minted.expiresAtEpochSeconds <= now ||
+            minted.expiresAtEpochSeconds - now > this.config.maxEndpointJwtLifetimeSeconds) {
+            throw new core_util_1.ApiImplementationError(`MCP endpoint JWT lifetime is invalid for ${tool.name}.`);
         }
+        return minted;
     }
-    apiError(payload, requestId) {
-        return this.errorResult(new ModelVisibleToolError(payload.kind, payload.message, requestId, payload.field, payload.callerMessage, payload.errorCode, payload.retryAfterSeconds));
+    validateCredential(credential) {
+        const now = Math.floor(Date.now() / 1000);
+        const reject = (reason) => {
+            throw new core_util_1.ApiUnauthorizedError(`MCP access token rejected: ${reason}`);
+        };
+        if (credential.subject.trim() === '')
+            reject('no subject');
+        const stamps = [
+            credential.issuedAtEpochSeconds,
+            credential.expiresAtEpochSeconds,
+            credential.accountValidatedAtEpochSeconds,
+        ];
+        if (!stamps.every(Number.isFinite))
+            reject('security timestamps must be finite');
+        if (credential.resource !== this.config.resource)
+            reject('resource mismatch');
+        if (!this.config.authorizationServers.includes(credential.issuer)) {
+            reject('issuer is not trusted');
+        }
+        if (credential.issuedAtEpochSeconds > now || credential.expiresAtEpochSeconds <= now) {
+            reject('outside its valid time window');
+        }
+        const lifetime = credential.expiresAtEpochSeconds - credential.issuedAtEpochSeconds;
+        if (lifetime > McpAuth_1.MAX_MCP_ACCESS_TOKEN_LIFETIME_SECONDS)
+            reject('lifetime exceeds 30 days');
+        for (const scope of this.config.requiredScopes) {
+            if (!credential.scopes.includes(scope))
+                reject(`missing required scope '${scope}'`);
+        }
+        const validatedAge = now - credential.accountValidatedAtEpochSeconds;
+        if (credential.accountValidatedAtEpochSeconds > now ||
+            validatedAge > this.config.maxAccountValidationAgeSeconds) {
+            reject('account authorization state is not fresh enough for dispatch');
+        }
     }
-    errorResult(error) {
-        const structured = this.record(error);
+    authInfo(authentication) {
+        const credential = authentication.credential;
         return {
-            content: [{ type: 'text', text: JSON.stringify(structured) }],
-            // `outputSchema` describes the endpoint's success DTO. MCP clients validate
-            // structuredContent against it even when isError is true, so error details must stay
-            // in text content until the protocol supports a separate error schema.
-            isError: true,
+            token: authentication.accessToken,
+            clientId: credential.subject,
+            scopes: [...credential.scopes],
+            expiresAt: credential.expiresAtEpochSeconds,
+            resource: new URL(credential.resource),
+            extra: { webpiecesAuthentication: authentication },
         };
     }
+    progressReporter(context) {
+        const token = context.mcpReq._meta?.progressToken;
+        if (token === undefined)
+            return undefined;
+        return async (progress, total, message) => {
+            await context.mcpReq.notify({
+                method: 'notifications/progress',
+                params: this.progressParams(token, progress, total, message),
+            });
+        };
+    }
+    progressParams(progressToken, progress, total, message) {
+        const params = { progressToken, progress };
+        if (total !== undefined)
+            params['total'] = total;
+        if (message !== undefined)
+            params['message'] = message;
+        return params;
+    }
+    requestId() {
+        return core_context_1.RequestContext.getUntrusted(core_util_1.WebpiecesCoreHeaders.REQUEST_ID) ?? 'missing-request-id';
+    }
+    sdkScope(context, method, toolName) {
+        return new WpMcpErrorTranslator_1.McpFailureScope(this.requestId(), context.mcpReq.id, method, toolName);
+    }
+    httpScope(req) {
+        const body = this.bodyObject(req.body);
+        const id = body?.['id'];
+        const method = body?.['method'];
+        const params = this.bodyObject(body?.['params']);
+        const name = params?.['name'];
+        return new WpMcpErrorTranslator_1.McpFailureScope(this.requestId(), typeof id === 'string' || typeof id === 'number' ? id : null, typeof method === 'string' ? method : 'unknown', typeof name === 'string' ? name : undefined);
+    }
+    challenge() {
+        return `Bearer resource_metadata="${this.config.resource}"`;
+    }
+    bodyObject(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return undefined;
+        return value;
+    }
+    hasProgressToken(body) {
+        const params = this.bodyObject(this.bodyObject(body)?.['params']);
+        return this.bodyObject(params?.['_meta'])?.['progressToken'] !== undefined;
+    }
+    toHttpRequest(req) {
+        const headers = new Map();
+        for (const [name, value] of Object.entries(req.headers)) {
+            if (typeof value === 'string')
+                headers.set(name, [value]);
+            else if (Array.isArray(value))
+                headers.set(name, value);
+        }
+        return new core_context_1.HttpRequest(req.method, req.originalUrl || req.path, headers);
+    }
+    calculateRegistryRevision(registry) {
+        const surface = registry.tools.map((tool) => [
+            tool.name,
+            tool.description,
+            tool.inputSchema,
+            tool.outputSchema,
+            tool.annotations,
+        ]);
+        return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(surface)).digest('hex').slice(0, 12);
+    }
+    requireRegistry() {
+        if (!this.registry)
+            throw new Error('Call WpMcpServer.bind(...) before serving requests.');
+        return this.registry;
+    }
     record(value) {
-        const json = JSON.stringify(value);
-        if (json === undefined)
-            throw new Error('MCP structured content is not JSON serializable.');
-        const parsed = JSON.parse(json);
+        const jsonValue = JSON.stringify(value);
+        if (jsonValue === undefined) {
+            throw new core_util_1.ApiImplementationError('MCP structured content is not JSON serializable.');
+        }
+        const parsed = JSON.parse(jsonValue);
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            // webpieces-disable no-anonymous-object-literals -- external MCP structured-content wrapper
             return { value: parsed };
         }
         return parsed;