@frontmcp/sdk 0.4.1 → 0.5.1

package/src/transport/mcp-handlers/unsubscribe-request.handler.d.ts

@@ -0,0 +1,57 @@
+import { UnsubscribeRequest, EmptyResult } from '@modelcontextprotocol/sdk/types.js';
+import { McpHandlerOptions } from './mcp-handlers.types';
+/**
+ * Handler for the resources/unsubscribe MCP request.
+ * Per MCP 2025-11-25 spec, this allows clients to unsubscribe from
+ * receiving notifications about a specific resource.
+ */
+export default function UnsubscribeRequestHandler({ scope }: McpHandlerOptions): {
+    requestSchema: import("zod").ZodObject<{
+        method: import("zod").ZodLiteral<"resources/unsubscribe">;
+        params: import("zod").ZodObject<{
+            task: import("zod").ZodOptional<import("zod").ZodObject<{
+                ttl: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodNull]>>;
+                pollInterval: import("zod").ZodOptional<import("zod").ZodNumber>;
+            }, import("zod/v4/core").$loose>>;
+            _meta: import("zod").ZodOptional<import("zod").ZodObject<{
+                progressToken: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodNumber]>>;
+                "io.modelcontextprotocol/related-task": import("zod").ZodOptional<import("zod").ZodObject<{
+                    taskId: import("zod").ZodString;
+                }, import("zod/v4/core").$loose>>;
+            }, import("zod/v4/core").$loose>>;
+            uri: import("zod").ZodString;
+        }, import("zod/v4/core").$loose>;
+    }, import("zod/v4/core").$strip>;
+    handler: (request: UnsubscribeRequest, ctx: import("./mcp-handlers.types").McpRequestHandler<{
+        method: "resources/unsubscribe";
+        params: {
+            [x: string]: unknown;
+            uri: string;
+            task?: {
+                [x: string]: unknown;
+                ttl?: number | null | undefined;
+                pollInterval?: number | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    [x: string]: unknown;
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        };
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                "io.modelcontextprotocol/related-task"?: {
+                    [x: string]: unknown;
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }>) => Promise<EmptyResult>;
+};

package/src/transport/mcp-handlers/unsubscribe-request.handler.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = UnsubscribeRequestHandler;
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+/**
+ * Handler for the resources/unsubscribe MCP request.
+ * Per MCP 2025-11-25 spec, this allows clients to unsubscribe from
+ * receiving notifications about a specific resource.
+ */
+function UnsubscribeRequestHandler({ scope }) {
+    return {
+        requestSchema: types_js_1.UnsubscribeRequestSchema,
+        handler: async (request, ctx) => {
+            const { uri } = request.params;
+            // Get session ID from auth context
+            const sessionId = ctx.authInfo?.sessionId;
+            if (!sessionId) {
+                scope.logger.warn('resources/unsubscribe: No session ID found in request context');
+                return {};
+            }
+            // Unsubscribe the session from the resource
+            const wasSubscribed = scope.notifications.unsubscribeResource(sessionId, uri);
+            if (wasSubscribed) {
+                scope.logger.verbose(`resources/unsubscribe: Session ${sessionId.slice(0, 20)}... unsubscribed from ${uri}`);
+            }
+            else {
+                scope.logger.verbose(`resources/unsubscribe: Session ${sessionId.slice(0, 20)}... was not subscribed to ${uri}`);
+            }
+            // Per MCP spec, return empty result
+            return {};
+        },
+    };
+}
+//# sourceMappingURL=unsubscribe-request.handler.js.map

package/src/transport/mcp-handlers/unsubscribe-request.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe-request.handler.js","sourceRoot":"","sources":["../../../../src/transport/mcp-handlers/unsubscribe-request.handler.ts"],"names":[],"mappings":";;AAQA,4CA4BC;AApCD,iEAA+G;AAG/G;;;;GAIG;AACH,SAAwB,yBAAyB,CAAC,EAAE,KAAK,EAAqB;IAC5E,OAAO;QACL,aAAa,EAAE,mCAAwB;QACvC,OAAO,EAAE,KAAK,EAAE,OAA2B,EAAE,GAAG,EAAwB,EAAE;YACxE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YAE/B,mCAAmC;YACnC,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC;YAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;gBACnF,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,4CAA4C;YAC5C,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YAE9E,IAAI,aAAa,EAAE,CAAC;gBAClB,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,kCAAkC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,yBAAyB,GAAG,EAAE,CAAC,CAAC;YAC/G,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,MAAM,CAAC,OAAO,CAClB,kCAAkC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,6BAA6B,GAAG,EAAE,CAC3F,CAAC;YACJ,CAAC;YAED,oCAAoC;YACpC,OAAO,EAAE,CAAC;QACZ,CAAC;KACoD,CAAC;AAC1D,CAAC","sourcesContent":["import { UnsubscribeRequestSchema, UnsubscribeRequest, EmptyResult } from '@modelcontextprotocol/sdk/types.js';\nimport { McpHandler, McpHandlerOptions } from './mcp-handlers.types';\n\n/**\n * Handler for the resources/unsubscribe MCP request.\n * Per MCP 2025-11-25 spec, this allows clients to unsubscribe from\n * receiving notifications about a specific resource.\n */\nexport default function UnsubscribeRequestHandler({ scope }: McpHandlerOptions) {\n  return {\n    requestSchema: UnsubscribeRequestSchema,\n    handler: async (request: UnsubscribeRequest, ctx): Promise<EmptyResult> => {\n      const { uri } = request.params;\n\n      // Get session ID from auth context\n      const sessionId = ctx.authInfo?.sessionId;\n      if (!sessionId) {\n        scope.logger.warn('resources/unsubscribe: No session ID found in request context');\n        return {};\n      }\n\n      // Unsubscribe the session from the resource\n      const wasSubscribed = scope.notifications.unsubscribeResource(sessionId, uri);\n\n      if (wasSubscribed) {\n        scope.logger.verbose(`resources/unsubscribe: Session ${sessionId.slice(0, 20)}... unsubscribed from ${uri}`);\n      } else {\n        scope.logger.verbose(\n          `resources/unsubscribe: Session ${sessionId.slice(0, 20)}... was not subscribed to ${uri}`,\n        );\n      }\n\n      // Per MCP spec, return empty result\n      return {};\n    },\n  } satisfies McpHandler<UnsubscribeRequest, EmptyResult>;\n}\n"]}

package/src/transport/transport.local.js

@@ -22,6 +22,9 @@ class LocalTransporter {
                 this.adapter = new transport_sse_adapter_1.TransportSSEAdapter(scope, key, onDispose ?? defaultOnDispose, res);
                 break;
             case 'streamable-http':
+            case 'stateless-http':
+                // Both streamable-http and stateless-http use the same underlying adapter
+                // The difference is in how the transport is managed (singleton vs per-session)
                 this.adapter = new transport_streamable_http_adapter_1.TransportStreamableHttpAdapter(scope, key, onDispose ?? defaultOnDispose, res);
                 break;
             default:
@@ -36,7 +39,8 @@ class LocalTransporter {
             await this.adapter.handleRequest(req, res);
         }
         catch (err) {
-            console.error('MCP POST error:', err);
+            // Use safe logging to avoid Node.js 24 util.inspect bug with Zod errors
+            console.error('MCP POST error:', err instanceof Error ? err.message : 'Unknown error');
             res.status(500).json((0, transport_error_1.rpcError)('Internal error'));
         }
     }
@@ -49,7 +53,8 @@ class LocalTransporter {
             return this.adapter.initialize(req, res);
         }
         catch (err) {
-            console.error('MCP POST error:', err);
+            // Use safe logging to avoid Node.js 24 util.inspect bug with Zod errors
+            console.error('MCP POST error:', err instanceof Error ? err.message : 'Unknown error');
             res.status(500).json((0, transport_error_1.rpcError)('Internal error'));
         }
     }

package/src/transport/transport.local.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.local.js","sourceRoot":"","sources":["../../../src/transport/transport.local.ts"],"names":[],"mappings":";;;AAEA,4EAAuE;AACvE,oGAA8F;AAC9F,uDAA6C;AAO7C,MAAa,gBAAgB;IAOwD;IAN1E,IAAI,CAAgB;IACpB,SAAS,CAAS;IAClB,SAAS,CAAS;IAEnB,OAAO,CAA4E;IAE3F,YAAY,KAAY,EAAE,GAAiB,EAAE,GAAmB,EAAmB,SAAsB;QAAtB,cAAS,GAAT,SAAS,CAAa;QACvG,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAE/B,MAAM,gBAAgB,GAAG,GAAG,EAAE;YAC5B,WAAW;QACb,CAAC,CAAC;QAEF,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,KAAK;gBACR,IAAI,CAAC,OAAO,GAAG,IAAI,2CAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,IAAI,gBAAgB,EAAE,GAAG,CAAC,CAAC;gBACvF,MAAM;YACR,KAAK,iBAAiB;gBACpB,IAAI,CAAC,OAAO,GAAG,IAAI,kEAA8B,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,IAAI,gBAAgB,EAAE,GAAG,CAAC,CAAC;gBAClG,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,IAAI,CAAC,SAAkB;QACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAA+B,EAAE,GAAmB;QACtE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;YACtC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,0BAAQ,EAAC,gBAAgB,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAA+B,EAAE,GAAmB;QACnE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;YACzB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;YACtC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,0BAAQ,EAAC,gBAAgB,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AA7DD,4CA6DC","sourcesContent":["import { Transporter, TransportKey, TransportType } from './transport.types';\nimport { AuthenticatedServerRequest } from '../server/server.types';\nimport { TransportSSEAdapter } from './adapters/transport.sse.adapter';\nimport { TransportStreamableHttpAdapter } from './adapters/transport.streamable-http.adapter';\nimport { rpcError } from './transport.error';\nimport { LocalTransportAdapter } from './adapters/transport.local.adapter';\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';\nimport { SSEServerTransport } from './legacy/legacy.sse.tranporter';\nimport { ServerResponse } from '../common';\nimport { Scope } from '../scope';\n\nexport class LocalTransporter implements Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  private adapter: LocalTransportAdapter<StreamableHTTPServerTransport | SSEServerTransport>;\n\n  constructor(scope: Scope, key: TransportKey, res: ServerResponse, private readonly onDispose?: () => void) {\n    this.type = key.type;\n    this.tokenHash = key.tokenHash;\n\n    const defaultOnDispose = () => {\n      /* empty */\n    };\n\n    switch (this.type) {\n      case 'sse':\n        this.adapter = new TransportSSEAdapter(scope, key, onDispose ?? defaultOnDispose, res);\n        break;\n      case 'streamable-http':\n        this.adapter = new TransportStreamableHttpAdapter(scope, key, onDispose ?? defaultOnDispose, res);\n        break;\n      default:\n        throw new Error(`Unsupported transport type: ${this.type}`);\n    }\n  }\n\n  ping(timeoutMs?: number): Promise<boolean> {\n    throw new Error('Method not implemented.');\n  }\n\n  async handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void> {\n    try {\n      await this.adapter.handleRequest(req, res);\n    } catch (err) {\n      console.error('MCP POST error:', err);\n      res.status(500).json(rpcError('Internal error'));\n    }\n  }\n\n  async ready(): Promise<void> {\n    return this.adapter.ready;\n  }\n\n  async initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void> {\n    try {\n      await this.adapter.ready;\n      return this.adapter.initialize(req, res);\n    } catch (err) {\n      console.error('MCP POST error:', err);\n      res.status(500).json(rpcError('Internal error'));\n    }\n  }\n\n  async destroy(reason: string): Promise<void> {\n    try {\n      await this.adapter.destroy(reason);\n    } finally {\n      this.onDispose?.();\n    }\n  }\n}\n"]}
+{"version":3,"file":"transport.local.js","sourceRoot":"","sources":["../../../src/transport/transport.local.ts"],"names":[],"mappings":";;;AAEA,4EAAuE;AACvE,oGAA8F;AAC9F,uDAA6C;AAO7C,MAAa,gBAAgB;IAOwD;IAN1E,IAAI,CAAgB;IACpB,SAAS,CAAS;IAClB,SAAS,CAAS;IAEnB,OAAO,CAA4E;IAE3F,YAAY,KAAY,EAAE,GAAiB,EAAE,GAAmB,EAAmB,SAAsB;QAAtB,cAAS,GAAT,SAAS,CAAa;QACvG,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAE/B,MAAM,gBAAgB,GAAG,GAAG,EAAE;YAC5B,WAAW;QACb,CAAC,CAAC;QAEF,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,KAAK;gBACR,IAAI,CAAC,OAAO,GAAG,IAAI,2CAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,IAAI,gBAAgB,EAAE,GAAG,CAAC,CAAC;gBACvF,MAAM;YACR,KAAK,iBAAiB,CAAC;YACvB,KAAK,gBAAgB;gBACnB,0EAA0E;gBAC1E,+EAA+E;gBAC/E,IAAI,CAAC,OAAO,GAAG,IAAI,kEAA8B,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,IAAI,gBAAgB,EAAE,GAAG,CAAC,CAAC;gBAClG,MAAM;YACR;gBACE,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,IAAI,CAAC,SAAkB;QACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,GAA+B,EAAE,GAAmB;QACtE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;YACvF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,0BAAQ,EAAC,gBAAgB,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAA+B,EAAE,GAAmB;QACnE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;YACzB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;YACvF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAA,0BAAQ,EAAC,gBAAgB,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AAlED,4CAkEC","sourcesContent":["import { Transporter, TransportKey, TransportType } from './transport.types';\nimport { AuthenticatedServerRequest } from '../server/server.types';\nimport { TransportSSEAdapter } from './adapters/transport.sse.adapter';\nimport { TransportStreamableHttpAdapter } from './adapters/transport.streamable-http.adapter';\nimport { rpcError } from './transport.error';\nimport { LocalTransportAdapter } from './adapters/transport.local.adapter';\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';\nimport { SSEServerTransport } from './legacy/legacy.sse.tranporter';\nimport { ServerResponse } from '../common';\nimport { Scope } from '../scope';\n\nexport class LocalTransporter implements Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  private adapter: LocalTransportAdapter<StreamableHTTPServerTransport | SSEServerTransport>;\n\n  constructor(scope: Scope, key: TransportKey, res: ServerResponse, private readonly onDispose?: () => void) {\n    this.type = key.type;\n    this.tokenHash = key.tokenHash;\n\n    const defaultOnDispose = () => {\n      /* empty */\n    };\n\n    switch (this.type) {\n      case 'sse':\n        this.adapter = new TransportSSEAdapter(scope, key, onDispose ?? defaultOnDispose, res);\n        break;\n      case 'streamable-http':\n      case 'stateless-http':\n        // Both streamable-http and stateless-http use the same underlying adapter\n        // The difference is in how the transport is managed (singleton vs per-session)\n        this.adapter = new TransportStreamableHttpAdapter(scope, key, onDispose ?? defaultOnDispose, res);\n        break;\n      default:\n        throw new Error(`Unsupported transport type: ${this.type}`);\n    }\n  }\n\n  ping(timeoutMs?: number): Promise<boolean> {\n    throw new Error('Method not implemented.');\n  }\n\n  async handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void> {\n    try {\n      await this.adapter.handleRequest(req, res);\n    } catch (err) {\n      // Use safe logging to avoid Node.js 24 util.inspect bug with Zod errors\n      console.error('MCP POST error:', err instanceof Error ? err.message : 'Unknown error');\n      res.status(500).json(rpcError('Internal error'));\n    }\n  }\n\n  async ready(): Promise<void> {\n    return this.adapter.ready;\n  }\n\n  async initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void> {\n    try {\n      await this.adapter.ready;\n      return this.adapter.initialize(req, res);\n    } catch (err) {\n      // Use safe logging to avoid Node.js 24 util.inspect bug with Zod errors\n      console.error('MCP POST error:', err instanceof Error ? err.message : 'Unknown error');\n      res.status(500).json(rpcError('Internal error'));\n    }\n  }\n\n  async destroy(reason: string): Promise<void> {\n    try {\n      await this.adapter.destroy(reason);\n    } finally {\n      this.onDispose?.();\n    }\n  }\n}\n"]}

package/src/transport/transport.registry.d.ts

@@ -7,12 +7,42 @@ export declare class TransportService {
     private readonly distributed;
     private readonly bus?;
     private readonly scope;
+    /**
+     * Session history cache for tracking if sessions were ever created.
+     * Used to differentiate between "session never initialized" (HTTP 400) and
+     * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
+     *
+     * Key: "type:tokenHash:sessionId", Value: creation timestamp
+     */
+    private readonly sessionHistory;
+    private readonly MAX_SESSION_HISTORY;
     constructor(scope: Scope);
     private initialize;
     destroy(): Promise<void>;
     getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined>;
     createTransporter(type: TransportType, token: string, sessionId: string, res: ServerResponse): Promise<Transporter>;
     destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void>;
+    /**
+     * Get or create a shared singleton transport for anonymous stateless requests.
+     * All anonymous requests share the same transport instance.
+     */
+    getOrCreateAnonymousStatelessTransport(type: TransportType, res: ServerResponse): Promise<Transporter>;
+    /**
+     * Get or create a singleton transport for authenticated stateless requests.
+     * Each unique token gets its own singleton transport.
+     */
+    getOrCreateAuthenticatedStatelessTransport(type: TransportType, token: string, res: ServerResponse): Promise<Transporter>;
+    /**
+     * Check if a session was ever created (even if it's been terminated/evicted).
+     * Used to differentiate between "session never initialized" (HTTP 400) and
+     * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
+     *
+     * @param type - Transport type (e.g., 'streamable-http', 'sse')
+     * @param token - The authorization token
+     * @param sessionId - The session ID to check
+     * @returns true if session was ever created, false otherwise
+     */
+    wasSessionCreated(type: TransportType, token: string, sessionId: string): boolean;
     private sha256;
     private keyOf;
     private ensureTypeBucket;

package/src/transport/transport.registry.js

@@ -8,12 +8,22 @@ const transport_remote_1 = require("./transport.remote");
 const transport_local_1 = require("./transport.local");
 const handle_streamable_http_flow_1 = tslib_1.__importDefault(require("./flows/handle.streamable-http.flow"));
 const handle_sse_flow_1 = tslib_1.__importDefault(require("./flows/handle.sse.flow"));
+const handle_stateless_http_flow_1 = tslib_1.__importDefault(require("./flows/handle.stateless-http.flow"));
 class TransportService {
     ready;
     byType = new Map();
     distributed;
     bus;
     scope;
+    /**
+     * Session history cache for tracking if sessions were ever created.
+     * Used to differentiate between "session never initialized" (HTTP 400) and
+     * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
+     *
+     * Key: "type:tokenHash:sessionId", Value: creation timestamp
+     */
+    sessionHistory = new Map();
+    MAX_SESSION_HISTORY = 10000;
     constructor(scope) {
         this.scope = scope;
         this.distributed = false; // get from scope metadata
@@ -24,7 +34,7 @@ class TransportService {
         this.ready = this.initialize();
     }
     async initialize() {
-        await this.scope.registryFlows(handle_streamable_http_flow_1.default, handle_sse_flow_1.default);
+        await this.scope.registryFlows(handle_streamable_http_flow_1.default, handle_sse_flow_1.default, handle_stateless_http_flow_1.default);
     }
     async destroy() {
         /* empty */
@@ -77,6 +87,67 @@ class TransportService {
         }
         throw new Error('Invalid session: cannot destroy non-existent transporter.');
     }
+    /**
+     * Get or create a shared singleton transport for anonymous stateless requests.
+     * All anonymous requests share the same transport instance.
+     */
+    async getOrCreateAnonymousStatelessTransport(type, res) {
+        const key = this.keyOf(type, '__anonymous__', '__stateless__');
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        // Create shared transport for all anonymous requests
+        const transporter = new transport_local_1.LocalTransporter(this.scope, key, res, () => {
+            this.evictLocal(key);
+            if (this.distributed && this.bus) {
+                this.bus.revoke(key).catch(() => void 0);
+            }
+        });
+        await transporter.ready();
+        this.insertLocal(key, transporter);
+        if (this.distributed && this.bus) {
+            await this.bus.advertise(key);
+        }
+        return transporter;
+    }
+    /**
+     * Get or create a singleton transport for authenticated stateless requests.
+     * Each unique token gets its own singleton transport.
+     */
+    async getOrCreateAuthenticatedStatelessTransport(type, token, res) {
+        const key = this.keyOf(type, token, '__stateless__');
+        const existing = this.lookupLocal(key);
+        if (existing)
+            return existing;
+        // Create singleton transport for this token
+        const transporter = new transport_local_1.LocalTransporter(this.scope, key, res, () => {
+            this.evictLocal(key);
+            if (this.distributed && this.bus) {
+                this.bus.revoke(key).catch(() => void 0);
+            }
+        });
+        await transporter.ready();
+        this.insertLocal(key, transporter);
+        if (this.distributed && this.bus) {
+            await this.bus.advertise(key);
+        }
+        return transporter;
+    }
+    /**
+     * Check if a session was ever created (even if it's been terminated/evicted).
+     * Used to differentiate between "session never initialized" (HTTP 400) and
+     * "session expired/terminated" (HTTP 404) per MCP Spec 2025-11-25.
+     *
+     * @param type - Transport type (e.g., 'streamable-http', 'sse')
+     * @param token - The authorization token
+     * @param sessionId - The session ID to check
+     * @returns true if session was ever created, false otherwise
+     */
+    wasSessionCreated(type, token, sessionId) {
+        const tokenHash = this.sha256(token);
+        const historyKey = `${type}:${tokenHash}:${sessionId}`;
+        return this.sessionHistory.has(historyKey);
+    }
     /* --------------------------------- internals -------------------------------- */
     sha256(value) {
         return (0, crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
@@ -119,6 +190,18 @@ class TransportService {
         const typeBucket = this.ensureTypeBucket(key.type);
         const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);
         tokenBucket.set(key.sessionId, t);
+        // Record session creation in history for HTTP 404 detection
+        const historyKey = `${key.type}:${key.tokenHash}:${key.sessionId}`;
+        this.sessionHistory.set(historyKey, Date.now());
+        // Evict oldest entries if cache exceeds max size (LRU-like eviction)
+        if (this.sessionHistory.size > this.MAX_SESSION_HISTORY) {
+            const entries = [...this.sessionHistory.entries()].sort((a, b) => a[1] - b[1]);
+            // Remove oldest 10% of entries
+            const toEvict = Math.ceil(this.MAX_SESSION_HISTORY * 0.1);
+            for (let i = 0; i < toEvict && i < entries.length; i++) {
+                this.sessionHistory.delete(entries[i][0]);
+            }
+        }
     }
     evictLocal(key) {
         const typeBucket = this.byType.get(key.type);

package/src/transport/transport.registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.registry.js","sourceRoot":"","sources":["../../../src/transport/transport.registry.ts"],"names":[],"mappings":";;;;AAAA,yCAAyC;AACzC,mCAAkC;AAUlC,yDAAqD;AACrD,uDAAmD;AAGnD,8GAA2E;AAC3E,sFAAoD;AAEpD,MAAa,gBAAgB;IAClB,KAAK,CAAgB;IACb,MAAM,GAA4B,IAAI,GAAG,EAAE,CAAC;IAC5C,WAAW,CAAU;IACrB,GAAG,CAAgB;IACnB,KAAK,CAAQ;IAE9B,YAAY,KAAY;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,CAAC,0BAA0B;QACpD,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC,0BAA0B;QAChD,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;QACjG,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IAEjC,CAAC;IAGO,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAC5B,qCAAwB,EACxB,yBAAa,CACd,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO;QACX,WAAW;IACb,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,IAAmB,EAAE,KAAa,EAAE,SAAiB;QACxE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAE/C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QAExB,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,IAAI,oCAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,iBAAiB,CACrB,IAAmB,EACnB,KAAa,EACb,SAAiB,EACjB,GAAmB;QAEnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,WAAW,GAAG,IAAI,kCAAgB,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE;YAClE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;YAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,WAAW,CAAC,KAAK,EAAE,CAAC;QAE1B,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAEnC,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACjC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,IAAmB,EAAE,KAAa,EAAE,SAAiB,EAAE,MAAe;QAC7F,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QAE/C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAC1C,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC/E,CAAC;IAED,kFAAkF;IAE1E,MAAM,CAAC,KAAa;QAC1B,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC;IAEO,KAAK,CAAC,IAAmB,EAAE,KAAa,EAAE,SAAiB,EAAE,YAAqB;QACxF,OAAO;YACL,IAAI;YACJ,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YAC7B,SAAS;YACT,YAAY;SACb,CAAC;IACJ,CAAC;IAEO,gBAAgB,CAAC,IAAmB;QAC1C,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,iBAAiB,CAAC,UAA+B,EAAE,SAAiB;QAC1E,IAAI,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;YACxC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAGO,WAAW,CAAC,GAAiB;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU;YAAE,OAAO,SAAS,CAAC;QAClC,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW;YAAE,OAAO,SAAS,CAAC;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAEO,WAAW,CAAC,GAAiB,EAAE,CAAc;QACnD,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QACtE,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAEO,UAAU,CAAC,GAAiB;QAClC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW;YAAE,OAAO;QACzB,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC;YAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7D,IAAI,UAAU,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;CACF;AA1JD,4CA0JC","sourcesContent":["// server/transport/transport.registry.ts\nimport {createHash} from 'crypto';\nimport {\n  TransportBus,\n  Transporter,\n  TransportKey,\n  TransportRegistryBucket,\n  TransportTokenBucket,\n  TransportType,\n  TransportTypeBucket,\n} from './transport.types';\nimport {RemoteTransporter} from './transport.remote';\nimport {LocalTransporter} from './transport.local';\nimport {ServerResponse} from '../common';\nimport {Scope} from '../scope';\nimport HandleStreamableHttpFlow from './flows/handle.streamable-http.flow';\nimport HandleSseFlow from './flows/handle.sse.flow';\n\nexport class TransportService {\n  readonly ready: Promise<void>;\n  private readonly byType: TransportRegistryBucket = new Map();\n  private readonly distributed: boolean;\n  private readonly bus?: TransportBus;\n  private readonly scope: Scope;\n\n  constructor(scope: Scope) {\n    this.scope = scope;\n    this.distributed = false; // get from scope metadata\n    this.bus = undefined; // get from scope metadata\n    if (this.distributed && !this.bus) {\n      throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');\n    }\n\n    this.ready = this.initialize();\n\n  }\n\n\n  private async initialize() {\n    await this.scope.registryFlows(\n      HandleStreamableHttpFlow,\n      HandleSseFlow,\n    );\n  }\n\n  async destroy() {\n    /* empty */\n  }\n\n  async getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) return local;\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        return new RemoteTransporter(key, this.bus);\n      }\n    }\n\n    return undefined;\n  }\n\n  async createTransporter(\n    type: TransportType,\n    token: string,\n    sessionId: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, sessionId);\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      key.sessionId = sessionId;\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  async destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) {\n      await local.destroy(reason);\n      return;\n    }\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        await this.bus.destroyRemote(key, reason);\n        return;\n      }\n    }\n\n    throw new Error('Invalid session: cannot destroy non-existent transporter.');\n  }\n\n  /* --------------------------------- internals -------------------------------- */\n\n  private sha256(value: string): string {\n    return createHash('sha256').update(value, 'utf8').digest('hex');\n  }\n\n  private keyOf(type: TransportType, token: string, sessionId: string, sessionIdSse?: string): TransportKey {\n    return {\n      type,\n      token,\n      tokenHash: this.sha256(token),\n      sessionId,\n      sessionIdSse,\n    };\n  }\n\n  private ensureTypeBucket(type: TransportType): TransportTypeBucket {\n    let bucket = this.byType.get(type);\n    if (!bucket) {\n      bucket = new Map<string, TransportTokenBucket>();\n      this.byType.set(type, bucket);\n    }\n    return bucket;\n  }\n\n  private ensureTokenBucket(typeBucket: TransportTypeBucket, tokenHash: string): TransportTokenBucket {\n    let bucket = typeBucket.get(tokenHash);\n    if (!bucket) {\n      bucket = new Map<string, Transporter>();\n      typeBucket.set(tokenHash, bucket);\n    }\n    return bucket;\n  }\n\n\n  private lookupLocal(key: TransportKey): Transporter | undefined {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return undefined;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return undefined;\n    return tokenBucket.get(key.sessionId);\n  }\n\n  private insertLocal(key: TransportKey, t: Transporter): void {\n    const typeBucket = this.ensureTypeBucket(key.type);\n    const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);\n    tokenBucket.set(key.sessionId, t);\n  }\n\n  private evictLocal(key: TransportKey): void {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return;\n    tokenBucket.delete(key.sessionId);\n    if (tokenBucket.size === 0) typeBucket.delete(key.tokenHash);\n    if (typeBucket.size === 0) this.byType.delete(key.type);\n  }\n}\n"]}
+{"version":3,"file":"transport.registry.js","sourceRoot":"","sources":["../../../src/transport/transport.registry.ts"],"names":[],"mappings":"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","sourcesContent":["// server/transport/transport.registry.ts\nimport { createHash } from 'crypto';\nimport {\n  TransportBus,\n  Transporter,\n  TransportKey,\n  TransportRegistryBucket,\n  TransportTokenBucket,\n  TransportType,\n  TransportTypeBucket,\n} from './transport.types';\nimport { RemoteTransporter } from './transport.remote';\nimport { LocalTransporter } from './transport.local';\nimport { ServerResponse } from '../common';\nimport { Scope } from '../scope';\nimport HandleStreamableHttpFlow from './flows/handle.streamable-http.flow';\nimport HandleSseFlow from './flows/handle.sse.flow';\nimport HandleStatelessHttpFlow from './flows/handle.stateless-http.flow';\n\nexport class TransportService {\n  readonly ready: Promise<void>;\n  private readonly byType: TransportRegistryBucket = new Map();\n  private readonly distributed: boolean;\n  private readonly bus?: TransportBus;\n  private readonly scope: Scope;\n\n  /**\n   * Session history cache for tracking if sessions were ever created.\n   * Used to differentiate between \"session never initialized\" (HTTP 400) and\n   * \"session expired/terminated\" (HTTP 404) per MCP Spec 2025-11-25.\n   *\n   * Key: \"type:tokenHash:sessionId\", Value: creation timestamp\n   */\n  private readonly sessionHistory: Map<string, number> = new Map();\n  private readonly MAX_SESSION_HISTORY = 10000;\n\n  constructor(scope: Scope) {\n    this.scope = scope;\n    this.distributed = false; // get from scope metadata\n    this.bus = undefined; // get from scope metadata\n    if (this.distributed && !this.bus) {\n      throw new Error('TransportRegistry: distributed=true requires a TransportBus implementation.');\n    }\n\n    this.ready = this.initialize();\n  }\n\n  private async initialize() {\n    await this.scope.registryFlows(HandleStreamableHttpFlow, HandleSseFlow, HandleStatelessHttpFlow);\n  }\n\n  async destroy() {\n    /* empty */\n  }\n\n  async getTransporter(type: TransportType, token: string, sessionId: string): Promise<Transporter | undefined> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) return local;\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        return new RemoteTransporter(key, this.bus);\n      }\n    }\n\n    return undefined;\n  }\n\n  async createTransporter(\n    type: TransportType,\n    token: string,\n    sessionId: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, sessionId);\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      key.sessionId = sessionId;\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  async destroyTransporter(type: TransportType, token: string, sessionId: string, reason?: string): Promise<void> {\n    const key = this.keyOf(type, token, sessionId);\n\n    const local = this.lookupLocal(key);\n    if (local) {\n      await local.destroy(reason);\n      return;\n    }\n\n    if (this.distributed && this.bus) {\n      const location = await this.bus.lookup(key);\n      if (location) {\n        await this.bus.destroyRemote(key, reason);\n        return;\n      }\n    }\n\n    throw new Error('Invalid session: cannot destroy non-existent transporter.');\n  }\n\n  /**\n   * Get or create a shared singleton transport for anonymous stateless requests.\n   * All anonymous requests share the same transport instance.\n   */\n  async getOrCreateAnonymousStatelessTransport(type: TransportType, res: ServerResponse): Promise<Transporter> {\n    const key = this.keyOf(type, '__anonymous__', '__stateless__');\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    // Create shared transport for all anonymous requests\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  /**\n   * Get or create a singleton transport for authenticated stateless requests.\n   * Each unique token gets its own singleton transport.\n   */\n  async getOrCreateAuthenticatedStatelessTransport(\n    type: TransportType,\n    token: string,\n    res: ServerResponse,\n  ): Promise<Transporter> {\n    const key = this.keyOf(type, token, '__stateless__');\n    const existing = this.lookupLocal(key);\n    if (existing) return existing;\n\n    // Create singleton transport for this token\n    const transporter = new LocalTransporter(this.scope, key, res, () => {\n      this.evictLocal(key);\n      if (this.distributed && this.bus) {\n        this.bus.revoke(key).catch(() => void 0);\n      }\n    });\n\n    await transporter.ready();\n    this.insertLocal(key, transporter);\n\n    if (this.distributed && this.bus) {\n      await this.bus.advertise(key);\n    }\n\n    return transporter;\n  }\n\n  /**\n   * Check if a session was ever created (even if it's been terminated/evicted).\n   * Used to differentiate between \"session never initialized\" (HTTP 400) and\n   * \"session expired/terminated\" (HTTP 404) per MCP Spec 2025-11-25.\n   *\n   * @param type - Transport type (e.g., 'streamable-http', 'sse')\n   * @param token - The authorization token\n   * @param sessionId - The session ID to check\n   * @returns true if session was ever created, false otherwise\n   */\n  wasSessionCreated(type: TransportType, token: string, sessionId: string): boolean {\n    const tokenHash = this.sha256(token);\n    const historyKey = `${type}:${tokenHash}:${sessionId}`;\n    return this.sessionHistory.has(historyKey);\n  }\n\n  /* --------------------------------- internals -------------------------------- */\n\n  private sha256(value: string): string {\n    return createHash('sha256').update(value, 'utf8').digest('hex');\n  }\n\n  private keyOf(type: TransportType, token: string, sessionId: string, sessionIdSse?: string): TransportKey {\n    return {\n      type,\n      token,\n      tokenHash: this.sha256(token),\n      sessionId,\n      sessionIdSse,\n    };\n  }\n\n  private ensureTypeBucket(type: TransportType): TransportTypeBucket {\n    let bucket = this.byType.get(type);\n    if (!bucket) {\n      bucket = new Map<string, TransportTokenBucket>();\n      this.byType.set(type, bucket);\n    }\n    return bucket;\n  }\n\n  private ensureTokenBucket(typeBucket: TransportTypeBucket, tokenHash: string): TransportTokenBucket {\n    let bucket = typeBucket.get(tokenHash);\n    if (!bucket) {\n      bucket = new Map<string, Transporter>();\n      typeBucket.set(tokenHash, bucket);\n    }\n    return bucket;\n  }\n\n  private lookupLocal(key: TransportKey): Transporter | undefined {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return undefined;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return undefined;\n    return tokenBucket.get(key.sessionId);\n  }\n\n  private insertLocal(key: TransportKey, t: Transporter): void {\n    const typeBucket = this.ensureTypeBucket(key.type);\n    const tokenBucket = this.ensureTokenBucket(typeBucket, key.tokenHash);\n    tokenBucket.set(key.sessionId, t);\n\n    // Record session creation in history for HTTP 404 detection\n    const historyKey = `${key.type}:${key.tokenHash}:${key.sessionId}`;\n    this.sessionHistory.set(historyKey, Date.now());\n\n    // Evict oldest entries if cache exceeds max size (LRU-like eviction)\n    if (this.sessionHistory.size > this.MAX_SESSION_HISTORY) {\n      const entries = [...this.sessionHistory.entries()].sort((a, b) => a[1] - b[1]);\n      // Remove oldest 10% of entries\n      const toEvict = Math.ceil(this.MAX_SESSION_HISTORY * 0.1);\n      for (let i = 0; i < toEvict && i < entries.length; i++) {\n        this.sessionHistory.delete(entries[i][0]);\n      }\n    }\n  }\n\n  private evictLocal(key: TransportKey): void {\n    const typeBucket = this.byType.get(key.type);\n    if (!typeBucket) return;\n    const tokenBucket = typeBucket.get(key.tokenHash);\n    if (!tokenBucket) return;\n    tokenBucket.delete(key.sessionId);\n    if (tokenBucket.size === 0) typeBucket.delete(key.tokenHash);\n    if (typeBucket.size === 0) this.byType.delete(key.type);\n  }\n}\n"]}

package/src/transport/transport.types.d.ts

@@ -1,9 +1,9 @@
 import { AuthenticatedServerRequest } from '../server/server.types';
 import { ElicitResult } from '@modelcontextprotocol/sdk/types.js';
-import { ZodObject } from 'zod';
+import { ZodType } from 'zod';
 import { Infer } from '../utils/types.utils';
 import { ServerResponse } from '../common';
-export type TransportType = 'sse' | 'streamable-http' | 'http';
+export type TransportType = 'sse' | 'streamable-http' | 'http' | 'stateless-http';
 export interface TransportKey {
     type: TransportType;
     token: string;
@@ -48,7 +48,7 @@ export interface TransportRegistryOptions {
 export type TransportTokenBucket = Map<string, Transporter>;
 export type TransportTypeBucket = Map<string, TransportTokenBucket>;
 export type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>;
-export type TypedElicitResult<T extends ZodObject<any>> = {
+export type TypedElicitResult<T extends ZodType> = {
     action: ElicitResult['action'];
     content: Infer<T>;
 };

package/src/transport/transport.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.types.js","sourceRoot":"","sources":["../../../src/transport/transport.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthenticatedServerRequest } from '../server/server.types';\nimport { ElicitResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ZodObject } from 'zod';\nimport { Infer } from '../utils/types.utils';\nimport { ServerResponse } from '../common';\n\nexport type TransportType = 'sse' | 'streamable-http' | 'http';\n\nexport interface TransportKey {\n  type: TransportType;\n  token: string;\n  tokenHash: string;\n  sessionId: string;\n  sessionIdSse?: string;\n}\n\nexport interface RemoteLocation {\n  nodeId: string;\n  channel: string;\n}\n\nexport interface TransportBus {\n  nodeId(): string;\n\n  advertise(key: TransportKey): Promise<void>;\n\n  revoke(key: TransportKey): Promise<void>;\n\n  lookup(key: TransportKey): Promise<RemoteLocation | null>;\n\n  proxyRequest(\n    key: TransportKey,\n    payload: {\n      method?: string;\n      url?: string;\n      headers?: Record<string, string | string[] | undefined>;\n    },\n    io: {\n      onResponseStart(statusCode: number, headers: Record<string, string>): void;\n      onResponseChunk(chunk: Uint8Array | string): void;\n      onResponseEnd(finalChunk?: Uint8Array | string): void;\n      onError?(err: Error | string): void;\n    },\n  ): Promise<void>;\n\n  destroyRemote(key: TransportKey, reason?: string): Promise<void>;\n}\n\n/* --------------------------------- API ---------------------------------- */\n\nexport interface Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  destroy(reason?: string): Promise<void>;\n\n  ping(timeoutMs?: number): Promise<boolean>;\n}\n\nexport interface TransportRegistryOptions {\n  distributed?: boolean;\n  bus?: TransportBus;\n}\n\nexport type TransportTokenBucket = Map<string, Transporter>; // sessionHash -> Transporter\nexport type TransportTypeBucket = Map<string, TransportTokenBucket>; // tokenHash   -> TokenBucket\nexport type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>; // tokenHash   -> TokenBucket\n\nexport type TypedElicitResult<T extends ZodObject<any>> = { action: ElicitResult['action']; content: Infer<T> };\n"]}
+{"version":3,"file":"transport.types.js","sourceRoot":"","sources":["../../../src/transport/transport.types.ts"],"names":[],"mappings":"","sourcesContent":["import { AuthenticatedServerRequest } from '../server/server.types';\nimport { ElicitResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ZodType } from 'zod';\nimport { Infer } from '../utils/types.utils';\nimport { ServerResponse } from '../common';\n\nexport type TransportType = 'sse' | 'streamable-http' | 'http' | 'stateless-http';\n\nexport interface TransportKey {\n  type: TransportType;\n  token: string;\n  tokenHash: string;\n  sessionId: string;\n  sessionIdSse?: string;\n}\n\nexport interface RemoteLocation {\n  nodeId: string;\n  channel: string;\n}\n\nexport interface TransportBus {\n  nodeId(): string;\n\n  advertise(key: TransportKey): Promise<void>;\n\n  revoke(key: TransportKey): Promise<void>;\n\n  lookup(key: TransportKey): Promise<RemoteLocation | null>;\n\n  proxyRequest(\n    key: TransportKey,\n    payload: {\n      method?: string;\n      url?: string;\n      headers?: Record<string, string | string[] | undefined>;\n    },\n    io: {\n      onResponseStart(statusCode: number, headers: Record<string, string>): void;\n      onResponseChunk(chunk: Uint8Array | string): void;\n      onResponseEnd(finalChunk?: Uint8Array | string): void;\n      onError?(err: Error | string): void;\n    },\n  ): Promise<void>;\n\n  destroyRemote(key: TransportKey, reason?: string): Promise<void>;\n}\n\n/* --------------------------------- API ---------------------------------- */\n\nexport interface Transporter {\n  readonly type: TransportType;\n  readonly tokenHash: string;\n  readonly sessionId: string;\n\n  initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;\n\n  destroy(reason?: string): Promise<void>;\n\n  ping(timeoutMs?: number): Promise<boolean>;\n}\n\nexport interface TransportRegistryOptions {\n  distributed?: boolean;\n  bus?: TransportBus;\n}\n\nexport type TransportTokenBucket = Map<string, Transporter>; // sessionHash -> Transporter\nexport type TransportTypeBucket = Map<string, TransportTokenBucket>; // tokenHash   -> TokenBucket\nexport type TransportRegistryBucket = Map<TransportType, TransportTypeBucket>; // tokenHash   -> TokenBucket\n\nexport type TypedElicitResult<T extends ZodType> = { action: ElicitResult['action']; content: Infer<T> };\n"]}

package/src/utils/content.utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Sanitize arbitrary JS values into JSON-safe objects suitable for:
+ *   - MCP `structuredContent`
+ *   - JSON.stringify without circular reference errors
+ *
+ * Rules:
+ *   - Drop functions and symbols.
+ *   - BigInt → string.
+ *   - Date → ISO string.
+ *   - Error → { name, message, stack }.
+ *   - Map → plain object.
+ *   - Set → array.
+ *   - Protect against circular references via WeakSet.
+ */
+export declare function sanitizeToJson(value: unknown): unknown;
+/**
+ * Convert a value to MCP structuredContent format.
+ * Returns Record<string, unknown> or undefined (matching MCP's structuredContent type).
+ * Primitives and arrays are wrapped in { value: ... }.
+ */
+export declare function toStructuredContent(value: unknown): Record<string, unknown> | undefined;
+/** MCP-compatible text resource content */
+export type TextContent = {
+    uri: string;
+    mimeType?: string;
+    text: string;
+};
+/** MCP-compatible blob resource content */
+export type BlobContent = {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+};
+/** MCP-compatible resource content (text or blob) */
+export type ResourceContent = TextContent | BlobContent;
+/**
+ * Build a resource content item for MCP ReadResourceResult format.
+ * Handles both text and binary (blob) content.
+ *
+ * @param uri - The resource URI
+ * @param content - The content to serialize (string, Buffer, object, etc.)
+ * @param mimeType - Optional MIME type override
+ */
+export declare function buildResourceContent(uri: string, content: unknown, mimeType?: string): ResourceContent;
+/**
+ * Infer MIME type from file extension or content.
+ */
+export declare function inferMimeType(uri: string, content?: unknown): string;