@webpieces/mcp-server 0.4.765

package/README.md

@@ -0,0 +1,51 @@
+# @webpieces/mcp-server
+
+Publishes explicitly annotated Webpieces RPC endpoints as MCP tools. The bridge generates input and
+output JSON Schema from DTO metadata, invokes the normal Webpieces filter/controller path, and turns
+exceptions into safe model-visible MCP results.
+
+`@WpMcpTool` is an opt-in. Existing endpoint authentication remains authoritative on every call.
+The MCP adapter never accepts trusted context values from tool arguments or headers.
+
+```ts
+@WpDto()
+class FindOrderRequest {
+    @WpDtoField(new WpDtoFieldOptions('Order identifier', true))
+    orderId!: string;
+}
+
+@WpDto()
+class FindOrderResponse {
+    @WpDtoField(new WpDtoFieldOptions('Current order state', true))
+    state!: string;
+}
+
+@ApiPath('/orders')
+abstract class OrdersApi {
+    @WpAuthJwt({ allRolesAllowed: true })
+    @Endpoint('/find', 'rpc')
+    @WpResponseDto(() => FindOrderResponse)
+    @WpMcpTool({
+        name: 'orders_find',
+        description: 'Find one order owned by the signed-in user.',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    })
+    find(request: FindOrderRequest): Promise<FindOrderResponse> {
+        throw new Error('contract only');
+    }
+}
+```
+
+The `@WpMcpTool.description` becomes the tool description returned by `tools/list`. The request and
+response classes generate `inputSchema` and `outputSchema`; `@WpDtoField` supplies property
+descriptions and the facts TypeScript erases, such as optionality and array element types.
+
+Applications construct `WpMcpServer` with their built `ApiFactory`, the API classes they want scanned,
+and an `McpAccessTokenVerifier`. The verifier checks issuer, signature, expiry, scopes, and the exact
+resource URI, then returns an endpoint bearer credential. The bridge uses that credential only for an
+in-process call through the ordinary `AuthFilter`; it never forwards the MCP token to downstream APIs.
+
+`protectedResourceMetadata()` returns the resource metadata an HTTP adapter can publish at the
+well-known OAuth protected-resource endpoint. OAuth token issuance remains pluggable.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@webpieces/mcp-server",
+  "version": "0.4.765",
+  "description": "Secure MCP tool generation from annotated Webpieces API contracts",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/http/mcp-server"
+  },
+  "keywords": [
+    "webpieces",
+    "mcp",
+    "server",
+    "ai"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@webpieces/core-context": "0.4.765",
+    "@webpieces/core-util": "0.4.765",
+    "@webpieces/http-routing": "0.4.765",
+    "reflect-metadata": "0.2.2",
+    "tslib": "2.8.1"
+  }
+}

package/src/McpApiDispatcher.d.ts

@@ -0,0 +1,23 @@
+import { ApiErrorPayload, DtoValue } from '@webpieces/core-util';
+import { ApiFactory } from '@webpieces/http-routing';
+import { RegisteredMcpTool } from './McpToolRegistry';
+export declare class McpDispatchSuccess {
+    readonly value: DtoValue;
+    readonly requestId: string;
+    readonly success = true;
+    constructor(value: DtoValue, requestId: string);
+}
+export declare class McpDispatchFailure {
+    readonly error: ApiErrorPayload;
+    readonly requestId: string;
+    readonly success = false;
+    constructor(error: ApiErrorPayload, requestId: string);
+}
+export type McpDispatchResult = McpDispatchSuccess | McpDispatchFailure;
+/** Executes one tool through the same ApiFactory proxy/filter/controller path as HTTP. */
+export declare class McpApiDispatcher {
+    private readonly apiFactory;
+    private readonly schemaBuilder;
+    constructor(apiFactory: ApiFactory);
+    call(tool: RegisteredMcpTool, requestDto: DtoValue, endpointBearerToken: string): Promise<McpDispatchResult>;
+}

package/src/McpApiDispatcher.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpApiDispatcher = exports.McpDispatchFailure = exports.McpDispatchSuccess = void 0;
+const core_util_1 = require("@webpieces/core-util");
+const core_context_1 = require("@webpieces/core-context");
+class McpDispatchSuccess {
+    value;
+    requestId;
+    success = true;
+    constructor(value, requestId) {
+        this.value = value;
+        this.requestId = requestId;
+    }
+}
+exports.McpDispatchSuccess = McpDispatchSuccess;
+class McpDispatchFailure {
+    error;
+    requestId;
+    success = false;
+    constructor(error, requestId) {
+        this.error = error;
+        this.requestId = requestId;
+    }
+}
+exports.McpDispatchFailure = McpDispatchFailure;
+/** Executes one tool through the same ApiFactory proxy/filter/controller path as HTTP. */
+class McpApiDispatcher {
+    apiFactory;
+    schemaBuilder = new core_util_1.DtoSchemaBuilder();
+    constructor(apiFactory) {
+        this.apiFactory = apiFactory;
+    }
+    async call(tool, requestDto, endpointBearerToken) {
+        const headers = new Map();
+        headers.set('authorization', [`Bearer ${endpointBearerToken}`]);
+        const request = new core_context_1.HttpRequest('POST', `/__webpieces/mcp/${tool.name}`, headers);
+        return core_context_1.RequestContext.run(async () => {
+            new core_context_1.RequestContextHeaders().fillFromRequest(request);
+            const requestId = core_context_1.RequestContext.getUntrusted(core_util_1.WebpiecesCoreHeaders.REQUEST_ID) ?? 'missing-request-id';
+            const inputFailure = this.schemaBuilder.validate(tool.requestClass, requestDto);
+            if (inputFailure) {
+                return new McpDispatchFailure(core_util_1.ApiErrorCodec.encode(new core_util_1.ApiBadRequestError('MCP request DTO did not match its declared schema.', undefined, inputFailure.message)), requestId);
+            }
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- transport boundary sanitizes endpoint throws
+            try {
+                const client = this.apiFactory.createApiClient(tool.apiClass);
+                const value = (await client[tool.methodName](requestDto));
+                return new McpDispatchSuccess(value, requestId);
+            }
+            catch (err) {
+                const error = (0, core_util_1.toError)(err);
+                return new McpDispatchFailure(core_util_1.ApiErrorCodec.encode(error), requestId);
+            }
+        });
+    }
+}
+exports.McpApiDispatcher = McpApiDispatcher;
+//# sourceMappingURL=McpApiDispatcher.js.map

package/src/McpApiDispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpApiDispatcher.js","sourceRoot":"","sources":["../../../../../../packages/http/mcp-server/src/McpApiDispatcher.ts"],"names":[],"mappings":";;;AAAA,oDAQ8B;AAC9B,0DAA6F;AAI7F,MAAa,kBAAkB;IAEC;IAAiC;IADpD,OAAO,GAAG,IAAI,CAAC;IACxB,YAA4B,KAAe,EAAkB,SAAiB;QAAlD,UAAK,GAAL,KAAK,CAAU;QAAkB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;CACrF;AAHD,gDAGC;AAED,MAAa,kBAAkB;IAEC;IAAwC;IAD3D,OAAO,GAAG,KAAK,CAAC;IACzB,YAA4B,KAAsB,EAAkB,SAAiB;QAAzD,UAAK,GAAL,KAAK,CAAiB;QAAkB,cAAS,GAAT,SAAS,CAAQ;IAAG,CAAC;CAC5F;AAHD,gDAGC;AAID,0FAA0F;AAC1F,MAAa,gBAAgB;IAGI;IAFZ,aAAa,GAAG,IAAI,4BAAgB,EAAE,CAAC;IAExD,YAA6B,UAAsB;QAAtB,eAAU,GAAV,UAAU,CAAY;IAAG,CAAC;IAEvD,KAAK,CAAC,IAAI,CACN,IAAuB,EACvB,UAAoB,EACpB,mBAA2B;QAE3B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,UAAU,mBAAmB,EAAE,CAAC,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,0BAAW,CAAC,MAAM,EAAE,oBAAoB,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QAClF,OAAO,6BAAc,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;YACjC,IAAI,oCAAqB,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YACrD,MAAM,SAAS,GACX,6BAAc,CAAC,YAAY,CAAC,gCAAoB,CAAC,UAAU,CAAC,IAAI,oBAAoB,CAAC;YACzF,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;YAChF,IAAI,YAAY,EAAE,CAAC;gBACf,OAAO,IAAI,kBAAkB,CACzB,yBAAa,CAAC,MAAM,CAChB,IAAI,8BAAkB,CAClB,oDAAoD,EACpD,SAAS,EACT,YAAY,CAAC,OAAO,CACvB,CACJ,EACD,SAAS,CACZ,CAAC;YACN,CAAC;YACD,8GAA8G;YAC9G,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,eAAe,CAAiB,IAAI,CAAC,QAAiB,CAAC,CAAC;gBACvF,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,CAAa,CAAC;gBACtE,OAAO,IAAI,kBAAkB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,IAAA,mBAAO,EAAC,GAAG,CAAC,CAAC;gBAC3B,OAAO,IAAI,kBAAkB,CAAC,yBAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;YAC1E,CAAC;QACL,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAzCD,4CAyCC","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiErrorCodec,\n    ApiErrorPayload,\n    DtoSchemaBuilder,\n    DtoValue,\n    toError,\n    WebpiecesCoreHeaders,\n} from '@webpieces/core-util';\nimport { HttpRequest, RequestContext, RequestContextHeaders } from '@webpieces/core-context';\nimport { ApiFactory, ApiClientProxy } from '@webpieces/http-routing';\nimport { RegisteredMcpTool } from './McpToolRegistry';\n\nexport class McpDispatchSuccess {\n    readonly success = true;\n    constructor(public readonly value: DtoValue, public readonly requestId: string) {}\n}\n\nexport class McpDispatchFailure {\n    readonly success = false;\n    constructor(public readonly error: ApiErrorPayload, public readonly requestId: string) {}\n}\n\nexport type McpDispatchResult = McpDispatchSuccess | McpDispatchFailure;\n\n/** Executes one tool through the same ApiFactory proxy/filter/controller path as HTTP. */\nexport class McpApiDispatcher {\n    private readonly schemaBuilder = new DtoSchemaBuilder();\n\n    constructor(private readonly apiFactory: ApiFactory) {}\n\n    async call(\n        tool: RegisteredMcpTool,\n        requestDto: DtoValue,\n        endpointBearerToken: string,\n    ): Promise<McpDispatchResult> {\n        const headers = new Map<string, string[]>();\n        headers.set('authorization', [`Bearer ${endpointBearerToken}`]);\n        const request = new HttpRequest('POST', `/__webpieces/mcp/${tool.name}`, headers);\n        return RequestContext.run(async () => {\n            new RequestContextHeaders().fillFromRequest(request);\n            const requestId =\n                RequestContext.getUntrusted(WebpiecesCoreHeaders.REQUEST_ID) ?? 'missing-request-id';\n            const inputFailure = this.schemaBuilder.validate(tool.requestClass, requestDto);\n            if (inputFailure) {\n                return new McpDispatchFailure(\n                    ApiErrorCodec.encode(\n                        new ApiBadRequestError(\n                            'MCP request DTO did not match its declared schema.',\n                            undefined,\n                            inputFailure.message,\n                        ),\n                    ),\n                    requestId,\n                );\n            }\n            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- transport boundary sanitizes endpoint throws\n            try {\n                const client = this.apiFactory.createApiClient<ApiClientProxy>(tool.apiClass as never);\n                const value = (await client[tool.methodName](requestDto)) as DtoValue;\n                return new McpDispatchSuccess(value, requestId);\n            } catch (err: unknown) {\n                const error = toError(err);\n                return new McpDispatchFailure(ApiErrorCodec.encode(error), requestId);\n            }\n        });\n    }\n}\n"]}

package/src/McpAuth.d.ts

@@ -0,0 +1,42 @@
+/** Credential accepted at the MCP resource boundary and the local endpoint credential it resolves to. */
+export declare class VerifiedMcpCredential {
+    /** Used only on the in-process endpoint invocation; never forwarded to another service. */
+    readonly endpointBearerToken: string;
+    readonly issuer: string;
+    /** The RFC 8707 resource/audience the verifier proved from the access token. */
+    readonly resource: string;
+    readonly expiresAtEpochSeconds: number;
+    readonly scopes: readonly string[];
+    /** Advisory tools/list filtering only. Endpoint authorization always runs again. */
+    readonly listingRoles: readonly string[];
+    constructor(
+    /** Used only on the in-process endpoint invocation; never forwarded to another service. */
+    endpointBearerToken: string, issuer: string, 
+    /** The RFC 8707 resource/audience the verifier proved from the access token. */
+    resource: string, expiresAtEpochSeconds: number, scopes: readonly string[], 
+    /** Advisory tools/list filtering only. Endpoint authorization always runs again. */
+    listingRoles?: readonly string[]);
+}
+/** Application-owned verification/token-exchange seam for a resource-bound MCP access token. */
+export declare abstract class McpAccessTokenVerifier {
+    abstract verify(accessToken: string, expectedResource: string): Promise<VerifiedMcpCredential>;
+}
+/** RFC 9728-style metadata exposed by the MCP protected resource. */
+export declare class McpProtectedResourceMetadata {
+    readonly resource: string;
+    readonly authorization_servers: readonly string[];
+    readonly bearer_methods_supported: string[];
+    readonly scopes_supported?: readonly string[];
+    constructor(resource: string, authorizationServers: readonly string[], scopesSupported?: readonly string[]);
+}
+/** Node MCP server configuration. OAuth token issuance stays with the application/identity provider. */
+export declare class WpMcpServerConfig {
+    readonly name: string;
+    readonly version: string;
+    readonly resource: string;
+    readonly tokenVerifier: McpAccessTokenVerifier;
+    readonly authorizationServers: readonly string[];
+    readonly requiredScopes: readonly string[];
+    constructor(name: string, version: string, resource: string, tokenVerifier: McpAccessTokenVerifier, authorizationServers: readonly string[], requiredScopes: readonly string[]);
+    protectedResourceMetadata(): McpProtectedResourceMetadata;
+}

package/src/McpAuth.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpMcpServerConfig = exports.McpProtectedResourceMetadata = exports.McpAccessTokenVerifier = exports.VerifiedMcpCredential = void 0;
+/** Credential accepted at the MCP resource boundary and the local endpoint credential it resolves to. */
+class VerifiedMcpCredential {
+    endpointBearerToken;
+    issuer;
+    resource;
+    expiresAtEpochSeconds;
+    scopes;
+    listingRoles;
+    constructor(
+    /** Used only on the in-process endpoint invocation; never forwarded to another service. */
+    endpointBearerToken, issuer, 
+    /** The RFC 8707 resource/audience the verifier proved from the access token. */
+    resource, expiresAtEpochSeconds, scopes, 
+    /** Advisory tools/list filtering only. Endpoint authorization always runs again. */
+    listingRoles = []) {
+        this.endpointBearerToken = endpointBearerToken;
+        this.issuer = issuer;
+        this.resource = resource;
+        this.expiresAtEpochSeconds = expiresAtEpochSeconds;
+        this.scopes = scopes;
+        this.listingRoles = listingRoles;
+    }
+}
+exports.VerifiedMcpCredential = VerifiedMcpCredential;
+/** Application-owned verification/token-exchange seam for a resource-bound MCP access token. */
+class McpAccessTokenVerifier {
+}
+exports.McpAccessTokenVerifier = McpAccessTokenVerifier;
+/** RFC 9728-style metadata exposed by the MCP protected resource. */
+class McpProtectedResourceMetadata {
+    resource;
+    authorization_servers;
+    bearer_methods_supported = ['header'];
+    scopes_supported;
+    constructor(resource, authorizationServers, scopesSupported) {
+        this.resource = resource;
+        this.authorization_servers = authorizationServers;
+        this.scopes_supported = scopesSupported;
+    }
+}
+exports.McpProtectedResourceMetadata = McpProtectedResourceMetadata;
+/** Node MCP server configuration. OAuth token issuance stays with the application/identity provider. */
+class WpMcpServerConfig {
+    name;
+    version;
+    resource;
+    tokenVerifier;
+    authorizationServers;
+    requiredScopes;
+    constructor(name, version, resource, tokenVerifier, authorizationServers, requiredScopes) {
+        this.name = name;
+        this.version = version;
+        this.resource = resource;
+        this.tokenVerifier = tokenVerifier;
+        this.authorizationServers = authorizationServers;
+        this.requiredScopes = requiredScopes;
+        if (name.trim() === '' || version.trim() === '' || resource.trim() === '') {
+            throw new Error('MCP name, version, and resource must be non-empty.');
+        }
+    }
+    protectedResourceMetadata() {
+        return new McpProtectedResourceMetadata(this.resource, this.authorizationServers, this.requiredScopes);
+    }
+}
+exports.WpMcpServerConfig = WpMcpServerConfig;
+//# sourceMappingURL=McpAuth.js.map

package/src/McpAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpAuth.js","sourceRoot":"","sources":["../../../../../../packages/http/mcp-server/src/McpAuth.ts"],"names":[],"mappings":";;;AAAA,yGAAyG;AACzG,MAAa,qBAAqB;IAGV;IACA;IAEA;IACA;IACA;IAEA;IATpB;IACI,2FAA2F;IAC3E,mBAA2B,EAC3B,MAAc;IAC9B,gFAAgF;IAChE,QAAgB,EAChB,qBAA6B,EAC7B,MAAyB;IACzC,oFAAoF;IACpE,eAAkC,EAAE;QAPpC,wBAAmB,GAAnB,mBAAmB,CAAQ;QAC3B,WAAM,GAAN,MAAM,CAAQ;QAEd,aAAQ,GAAR,QAAQ,CAAQ;QAChB,0BAAqB,GAArB,qBAAqB,CAAQ;QAC7B,WAAM,GAAN,MAAM,CAAmB;QAEzB,iBAAY,GAAZ,YAAY,CAAwB;IACrD,CAAC;CACP;AAZD,sDAYC;AAED,gGAAgG;AAChG,MAAsB,sBAAsB;CAK3C;AALD,wDAKC;AAED,qEAAqE;AACrE,MAAa,4BAA4B;IAC5B,QAAQ,CAAS;IACjB,qBAAqB,CAAoB;IACzC,wBAAwB,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtC,gBAAgB,CAAqB;IAE9C,YACI,QAAgB,EAChB,oBAAuC,EACvC,eAAmC;QAEnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,qBAAqB,GAAG,oBAAoB,CAAC;QAClD,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;IAC5C,CAAC;CACJ;AAfD,oEAeC;AAED,wGAAwG;AACxG,MAAa,iBAAiB;IAEN;IACA;IACA;IACA;IACA;IACA;IANpB,YACoB,IAAY,EACZ,OAAe,EACf,QAAgB,EAChB,aAAqC,EACrC,oBAAuC,EACvC,cAAiC;QALjC,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,aAAQ,GAAR,QAAQ,CAAQ;QAChB,kBAAa,GAAb,aAAa,CAAwB;QACrC,yBAAoB,GAApB,oBAAoB,CAAmB;QACvC,mBAAc,GAAd,cAAc,CAAmB;QAEjD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACxE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC1E,CAAC;IACL,CAAC;IAED,yBAAyB;QACrB,OAAO,IAAI,4BAA4B,CACnC,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,oBAAoB,EACzB,IAAI,CAAC,cAAc,CACtB,CAAC;IACN,CAAC;CACJ;AArBD,8CAqBC","sourcesContent":["/** Credential accepted at the MCP resource boundary and the local endpoint credential it resolves to. */\nexport class VerifiedMcpCredential {\n    constructor(\n        /** Used only on the in-process endpoint invocation; never forwarded to another service. */\n        public readonly endpointBearerToken: string,\n        public readonly issuer: string,\n        /** The RFC 8707 resource/audience the verifier proved from the access token. */\n        public readonly resource: string,\n        public readonly expiresAtEpochSeconds: number,\n        public readonly scopes: readonly string[],\n        /** Advisory tools/list filtering only. Endpoint authorization always runs again. */\n        public readonly listingRoles: readonly string[] = [],\n    ) {}\n}\n\n/** Application-owned verification/token-exchange seam for a resource-bound MCP access token. */\nexport abstract class McpAccessTokenVerifier {\n    abstract verify(\n        accessToken: string,\n        expectedResource: string,\n    ): Promise<VerifiedMcpCredential>;\n}\n\n/** RFC 9728-style metadata exposed by the MCP protected resource. */\nexport class McpProtectedResourceMetadata {\n    readonly resource: string;\n    readonly authorization_servers: readonly string[];\n    readonly bearer_methods_supported = ['header'];\n    readonly scopes_supported?: readonly string[];\n\n    constructor(\n        resource: string,\n        authorizationServers: readonly string[],\n        scopesSupported?: readonly string[],\n    ) {\n        this.resource = resource;\n        this.authorization_servers = authorizationServers;\n        this.scopes_supported = scopesSupported;\n    }\n}\n\n/** Node MCP server configuration. OAuth token issuance stays with the application/identity provider. */\nexport class WpMcpServerConfig {\n    constructor(\n        public readonly name: string,\n        public readonly version: string,\n        public readonly resource: string,\n        public readonly tokenVerifier: McpAccessTokenVerifier,\n        public readonly authorizationServers: readonly string[],\n        public readonly requiredScopes: readonly string[],\n    ) {\n        if (name.trim() === '' || version.trim() === '' || resource.trim() === '') {\n            throw new Error('MCP name, version, and resource must be non-empty.');\n        }\n    }\n\n    protectedResourceMetadata(): McpProtectedResourceMetadata {\n        return new McpProtectedResourceMetadata(\n            this.resource,\n            this.authorizationServers,\n            this.requiredScopes,\n        );\n    }\n}\n"]}

package/src/McpToolRegistry.d.ts

@@ -0,0 +1,26 @@
+import { ApiJsonSchema, AuthMeta, DtoClass, DtoSchemaBuilder, WpMcpToolMetadata } from '@webpieces/core-util';
+import { ClassType } from '@webpieces/http-routing';
+/** Fully resolved contract metadata for one MCP tool. */
+export declare class RegisteredMcpTool {
+    readonly apiClass: ClassType;
+    readonly methodName: string;
+    readonly name: string;
+    readonly description: string;
+    readonly annotations: WpMcpToolMetadata['hints'];
+    readonly authMeta: AuthMeta;
+    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. */
+    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[]);
+    find(name: string): RegisteredMcpTool | undefined;
+    private resolve;
+}

package/src/McpToolRegistry.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpToolRegistry = exports.RegisteredMcpTool = void 0;
+const core_util_1 = require("@webpieces/core-util");
+/** Fully resolved contract metadata for one MCP tool. */
+class RegisteredMcpTool {
+    apiClass;
+    methodName;
+    name;
+    description;
+    annotations;
+    authMeta;
+    requestClass;
+    responseClass;
+    inputSchema;
+    outputSchema;
+    constructor(apiClass, methodName, name, description, annotations, authMeta, requestClass, responseClass, inputSchema, outputSchema) {
+        this.apiClass = apiClass;
+        this.methodName = methodName;
+        this.name = name;
+        this.description = description;
+        this.annotations = annotations;
+        this.authMeta = authMeta;
+        this.requestClass = requestClass;
+        this.responseClass = responseClass;
+        this.inputSchema = inputSchema;
+        this.outputSchema = outputSchema;
+    }
+    /** Listing is advisory; the ordinary endpoint AuthFilter is the only authorization 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));
+    }
+}
+exports.RegisteredMcpTool = RegisteredMcpTool;
+/** Fail-fast registry built entirely from API/decorator metadata. */
+class McpToolRegistry {
+    tools;
+    schemaBuilder = new core_util_1.DtoSchemaBuilder();
+    constructor(apiClasses) {
+        const registered = [];
+        const names = new Set();
+        for (const apiClass of apiClasses) {
+            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));
+            }
+        }
+        this.tools = registered;
+    }
+    find(name) {
+        return this.tools.find((tool) => tool.name === name);
+    }
+    resolve(apiClass, metadata) {
+        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.`);
+        }
+        if ((0, core_util_1.getEndpointKind)(apiClass, metadata.methodName) !== 'rpc') {
+            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.`);
+        }
+        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));
+    }
+}
+exports.McpToolRegistry = McpToolRegistry;
+//# sourceMappingURL=McpToolRegistry.js.map

package/src/McpToolRegistry.js.map

@@ -0,0 +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"]}

package/src/WpMcpServer.d.ts

@@ -0,0 +1,32 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ApiFactory, ClassType } from '@webpieces/http-routing';
+import { 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);
+}
+/**
+ * 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.
+ */
+export declare class WpMcpServer {
+    private readonly config;
+    private readonly registry;
+    private readonly dispatcher;
+    constructor(config: WpMcpServerConfig, apiFactory: ApiFactory, apiClasses: readonly ClassType[]);
+    build(accessToken: string): Promise<Server>;
+    protectedResourceMetadata(): ReturnType<WpMcpServerConfig['protectedResourceMetadata']>;
+    private buildForCredential;
+    private validateCredential;
+    private call;
+    private apiError;
+    private errorResult;
+    private record;
+}

package/src/WpMcpServer.js

@@ -0,0 +1,144 @@
+"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");
+const core_util_1 = require("@webpieces/core-util");
+const McpApiDispatcher_1 = require("./McpApiDispatcher");
+const McpToolRegistry_1 = require("./McpToolRegistry");
+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;
+    }
+}
+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.
+ */
+class WpMcpServer {
+    config;
+    registry;
+    dispatcher;
+    constructor(config, apiFactory, apiClasses) {
+        this.config = config;
+        this.registry = new McpToolRegistry_1.McpToolRegistry(apiClasses);
+        this.dispatcher = new McpApiDispatcher_1.McpApiDispatcher(apiFactory);
+    }
+    async build(accessToken) {
+        const credential = await this.config.tokenVerifier.verify(accessToken, this.config.resource);
+        this.validateCredential(credential);
+        return this.buildForCredential(credential);
+    }
+    protectedResourceMetadata() {
+        return this.config.protectedResourceMetadata();
+    }
+    buildForCredential(credential) {
+        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, () => ({
+            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,
+            })),
+        }));
+        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}`);
+            }
+            return this.call(tool, request.params.arguments ?? {}, credential);
+        });
+        return server;
+    }
+    validateCredential(credential) {
+        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.expiresAtEpochSeconds <= Date.now() / 1000) {
+            throw new Error('MCP access token has expired.');
+        }
+        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.endpointBearerToken.trim() === '') {
+            throw new Error('MCP verifier returned an empty endpoint bearer credential.');
+        }
+    }
+    async call(tool, args, credential) {
+        const result = await this.dispatcher.call(tool, args ?? {}, credential.endpointBearerToken);
+        if (!result.success)
+            return this.apiError(result.error, result.requestId);
+        const outputFailure = this.registry.schemaBuilder.validate(tool.responseClass, result.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));
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured) }],
+            structuredContent: structured,
+        };
+    }
+    apiError(payload, requestId) {
+        return this.errorResult(new ModelVisibleToolError(payload.kind, payload.message, requestId, payload.field, payload.callerMessage, payload.errorCode, payload.retryAfterSeconds));
+    }
+    errorResult(error) {
+        const structured = this.record(error);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured) }],
+            structuredContent: structured,
+            isError: true,
+        };
+    }
+    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);
+        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;
+    }
+}
+exports.WpMcpServer = WpMcpServer;
+//# sourceMappingURL=WpMcpServer.js.map

package/src/WpMcpServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WpMcpServer.js","sourceRoot":"","sources":["../../../../../../packages/http/mcp-server/src/WpMcpServer.ts"],"names":[],"mappings":"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","sourcesContent":["import { Server } from '@modelcontextprotocol/sdk/server/index.js';\nimport {\n    CallToolRequest,\n    CallToolRequestSchema,\n    CallToolResult,\n    ErrorCode,\n    ListToolsRequestSchema,\n    McpError,\n} from '@modelcontextprotocol/sdk/types.js';\nimport {\n    ApiErrorPayload,\n    DtoValue,\n    LogManager,\n    toError,\n} from '@webpieces/core-util';\nimport { ApiFactory, ClassType } from '@webpieces/http-routing';\nimport { VerifiedMcpCredential, WpMcpServerConfig } from './McpAuth';\nimport { McpApiDispatcher } from './McpApiDispatcher';\nimport { McpToolRegistry, RegisteredMcpTool } from './McpToolRegistry';\n\nconst log = LogManager.getLogger('WpMcpServer');\n\n/** The only error shape rendered into model-visible MCP 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/**\n * Node-only MCP adapter. Build one Server per authenticated transport/session; every tool call still\n * re-enters the endpoint's ordinary AuthFilter, so tools/list visibility never grants access.\n */\nexport class WpMcpServer {\n    private readonly registry: McpToolRegistry;\n    private readonly dispatcher: McpApiDispatcher;\n\n    constructor(\n        private readonly config: WpMcpServerConfig,\n        apiFactory: ApiFactory,\n        apiClasses: readonly ClassType[],\n    ) {\n        this.registry = new McpToolRegistry(apiClasses);\n        this.dispatcher = new McpApiDispatcher(apiFactory);\n    }\n\n    async build(accessToken: string): Promise<Server> {\n        const credential = await this.config.tokenVerifier.verify(\n            accessToken,\n            this.config.resource,\n        );\n        this.validateCredential(credential);\n        return this.buildForCredential(credential);\n    }\n\n    protectedResourceMetadata(): ReturnType<WpMcpServerConfig['protectedResourceMetadata']> {\n        return this.config.protectedResourceMetadata();\n    }\n\n    private buildForCredential(credential: VerifiedMcpCredential): Server {\n        const server = new Server(\n            // webpieces-disable no-anonymous-object-literals -- external MCP SDK request structure\n            { name: this.config.name, version: this.config.version },\n            // webpieces-disable no-anonymous-object-literals -- external MCP SDK capability structure\n            { capabilities: { tools: {} } },\n        );\n        server.setRequestHandler(ListToolsRequestSchema, () => ({\n            tools: this.registry.tools\n                .filter((tool: RegisteredMcpTool) => tool.isVisibleTo(credential.listingRoles))\n                .map((tool: RegisteredMcpTool) => ({\n                    name: tool.name,\n                    description: tool.description,\n                    inputSchema: tool.inputSchema,\n                    outputSchema: tool.outputSchema,\n                    annotations: tool.annotations,\n                })),\n        }));\n        server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {\n            const tool = this.registry.find(request.params.name);\n            if (!tool) {\n                throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);\n            }\n            return this.call(tool, request.params.arguments ?? {}, credential);\n        });\n        return server;\n    }\n\n    private validateCredential(credential: VerifiedMcpCredential): void {\n        if (credential.resource !== this.config.resource) {\n            throw new Error('MCP access token was not issued for this protected resource.');\n        }\n        if (!this.config.authorizationServers.includes(credential.issuer)) {\n            throw new Error('MCP access token issuer is not trusted by this protected resource.');\n        }\n        if (credential.expiresAtEpochSeconds <= Date.now() / 1000) {\n            throw new Error('MCP access token has expired.');\n        }\n        for (const scope of this.config.requiredScopes) {\n            if (!credential.scopes.includes(scope)) {\n                throw new Error(`MCP access token is missing required scope '${scope}'.`);\n            }\n        }\n        if (credential.endpointBearerToken.trim() === '') {\n            throw new Error('MCP verifier returned an empty endpoint bearer credential.');\n        }\n    }\n\n    private async call(\n        tool: RegisteredMcpTool,\n        args: DtoValue,\n        credential: VerifiedMcpCredential,\n    ): Promise<CallToolResult> {\n        const result = await this.dispatcher.call(tool, args ?? {}, credential.endpointBearerToken);\n        if (!result.success) return this.apiError(result.error, result.requestId);\n\n        const outputFailure = this.registry.schemaBuilder.validate(tool.responseClass, result.value);\n        if (outputFailure) {\n            log.error(\n                `MCP output schema violation for ${tool.apiClass.name}.${tool.methodName}: ${outputFailure.message}`,\n            );\n            return this.errorResult(\n                new ModelVisibleToolError('implementation', 'Internal Error', result.requestId),\n            );\n        }\n        let structured: Record<string, DtoValue>;\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- transport boundary sanitizes serialization failures\n        try {\n            structured = this.record(result.value);\n        } catch (err: unknown) {\n            const error = toError(err);\n            log.error(\n                `MCP response serialization failed for ${tool.apiClass.name}.${tool.methodName}`,\n                error,\n            );\n            return this.errorResult(\n                new ModelVisibleToolError('implementation', 'Internal Error', result.requestId),\n            );\n        }\n        return {\n            content: [{ type: 'text', text: JSON.stringify(structured) }],\n            structuredContent: structured,\n        };\n    }\n\n    private apiError(payload: ApiErrorPayload, requestId: string): CallToolResult {\n        return this.errorResult(\n            new ModelVisibleToolError(\n                payload.kind,\n                payload.message,\n                requestId,\n                payload.field,\n                payload.callerMessage,\n                payload.errorCode,\n                payload.retryAfterSeconds,\n            ),\n        );\n    }\n\n    private errorResult(error: ModelVisibleToolError): CallToolResult {\n        const structured = this.record(error);\n        return {\n            content: [{ type: 'text', text: JSON.stringify(structured) }],\n            structuredContent: structured,\n            isError: true,\n        };\n    }\n\n    private record(value: DtoValue): Record<string, DtoValue> {\n        const json = JSON.stringify(value);\n        if (json === undefined) throw new Error('MCP structured content is not JSON serializable.');\n        const parsed = JSON.parse(json) as DtoValue;\n        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n            // webpieces-disable no-anonymous-object-literals -- external MCP structured-content wrapper\n            return { value: parsed };\n        }\n        return parsed as Record<string, DtoValue>;\n    }\n}\n"]}

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export { McpAccessTokenVerifier, McpProtectedResourceMetadata, VerifiedMcpCredential, WpMcpServerConfig, } from './McpAuth';
+export { McpToolRegistry, RegisteredMcpTool } from './McpToolRegistry';
+export { McpApiDispatcher, McpDispatchFailure, McpDispatchSuccess, } from './McpApiDispatcher';
+export type { McpDispatchResult } from './McpApiDispatcher';
+export { ModelVisibleToolError, WpMcpServer } from './WpMcpServer';

package/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WpMcpServer = exports.ModelVisibleToolError = exports.McpDispatchSuccess = exports.McpDispatchFailure = exports.McpApiDispatcher = exports.RegisteredMcpTool = exports.McpToolRegistry = exports.WpMcpServerConfig = exports.VerifiedMcpCredential = exports.McpProtectedResourceMetadata = exports.McpAccessTokenVerifier = void 0;
+var McpAuth_1 = require("./McpAuth");
+Object.defineProperty(exports, "McpAccessTokenVerifier", { enumerable: true, get: function () { return McpAuth_1.McpAccessTokenVerifier; } });
+Object.defineProperty(exports, "McpProtectedResourceMetadata", { enumerable: true, get: function () { return McpAuth_1.McpProtectedResourceMetadata; } });
+Object.defineProperty(exports, "VerifiedMcpCredential", { enumerable: true, get: function () { return McpAuth_1.VerifiedMcpCredential; } });
+Object.defineProperty(exports, "WpMcpServerConfig", { enumerable: true, get: function () { return McpAuth_1.WpMcpServerConfig; } });
+var McpToolRegistry_1 = require("./McpToolRegistry");
+Object.defineProperty(exports, "McpToolRegistry", { enumerable: true, get: function () { return McpToolRegistry_1.McpToolRegistry; } });
+Object.defineProperty(exports, "RegisteredMcpTool", { enumerable: true, get: function () { return McpToolRegistry_1.RegisteredMcpTool; } });
+var McpApiDispatcher_1 = require("./McpApiDispatcher");
+Object.defineProperty(exports, "McpApiDispatcher", { enumerable: true, get: function () { return McpApiDispatcher_1.McpApiDispatcher; } });
+Object.defineProperty(exports, "McpDispatchFailure", { enumerable: true, get: function () { return McpApiDispatcher_1.McpDispatchFailure; } });
+Object.defineProperty(exports, "McpDispatchSuccess", { enumerable: true, get: function () { return McpApiDispatcher_1.McpDispatchSuccess; } });
+var WpMcpServer_1 = require("./WpMcpServer");
+Object.defineProperty(exports, "ModelVisibleToolError", { enumerable: true, get: function () { return WpMcpServer_1.ModelVisibleToolError; } });
+Object.defineProperty(exports, "WpMcpServer", { enumerable: true, get: function () { return WpMcpServer_1.WpMcpServer; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/http/mcp-server/src/index.ts"],"names":[],"mappings":";;;AAAA,qCAKmB;AAJf,iHAAA,sBAAsB,OAAA;AACtB,uHAAA,4BAA4B,OAAA;AAC5B,gHAAA,qBAAqB,OAAA;AACrB,4GAAA,iBAAiB,OAAA;AAErB,qDAAuE;AAA9D,kHAAA,eAAe,OAAA;AAAE,oHAAA,iBAAiB,OAAA;AAC3C,uDAI4B;AAHxB,oHAAA,gBAAgB,OAAA;AAChB,sHAAA,kBAAkB,OAAA;AAClB,sHAAA,kBAAkB,OAAA;AAGtB,6CAAmE;AAA1D,oHAAA,qBAAqB,OAAA;AAAE,0GAAA,WAAW,OAAA","sourcesContent":["export {\n    McpAccessTokenVerifier,\n    McpProtectedResourceMetadata,\n    VerifiedMcpCredential,\n    WpMcpServerConfig,\n} from './McpAuth';\nexport { McpToolRegistry, RegisteredMcpTool } from './McpToolRegistry';\nexport {\n    McpApiDispatcher,\n    McpDispatchFailure,\n    McpDispatchSuccess,\n} from './McpApiDispatcher';\nexport type { McpDispatchResult } from './McpApiDispatcher';\nexport { ModelVisibleToolError, WpMcpServer } from './WpMcpServer';\n"]}