@nitrostack/core 1.0.11 → 1.0.12

package/dist/core/transports/streamable-http.d.ts

@@ -14,8 +14,16 @@
  * - Protocol version header support
  */
 import { Express, Request, Response } from 'express';
-import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import { JSONRPCMessage, Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Factory that builds a fully-configured MCP server instance.
+ * Each Streamable HTTP session gets its own server, since an SDK server can
+ * only be connected to a single transport at a time.
+ */
+export type McpServerFactory = () => McpServer;
+/** Handles legacy HTTP+SSE clients that open GET without a Streamable HTTP session id (e.g. Cursor). */
+export type LegacySseHandler = (req: Request, res: Response) => Promise<void>;
 export interface StreamableHttpTransportOptions {
     /**
      * Port to listen on (default: 3000)
@@ -35,8 +43,15 @@ export interface StreamableHttpTransportOptions {
     enableSessions?: boolean;
     /**
      * Session timeout in ms (default: 30 minutes)
+     * Idle sessions are torn down after this period of inactivity.
      */
     sessionTimeout?: number;
+    /**
+     * Maximum number of concurrent MCP sessions (default: 1000).
+     * Once reached, new `initialize` requests are rejected with HTTP 429 to
+     * bound memory usage against unauthenticated session-creation floods.
+     */
+    maxSessions?: number;
     /**
      * Custom Express app (optional)
      */
@@ -47,23 +62,41 @@ export interface StreamableHttpTransportOptions {
     enableCors?: boolean;
 }
 /**
- * Streamable HTTP Transport
- * Implements MCP Streamable HTTP specification
+ * Streamable HTTP host.
+ *
+ * This class owns the Express application (CORS, origin checks, OAuth discovery
+ * routes, health, documentation page, legacy-SSE lifecycle) but delegates the
+ * actual MCP protocol handling on `/mcp` to the official
+ * `@modelcontextprotocol/sdk` `StreamableHTTPServerTransport`. That transport
+ * returns the JSON-RPC result on the POST response (or an SSE stream on the same
+ * request), which is what modern MCP clients such as Cursor expect.
  */
-export declare class StreamableHttpTransport implements Transport {
+export declare class StreamableHttpTransport {
     private app;
     private server;
-    private sessions;
-    private activeStreams;
-    private messageHandler?;
-    private closeHandler?;
-    private errorHandler?;
     private options;
-    private sessionCleanupInterval?;
     private getToolsCallback?;
     private serverConfig?;
     private logoBase64?;
+    private _routesRegistered;
+    private mcpServerFactory?;
+    private legacySseHandler?;
+    private mcpSessions;
+    private pendingSessions;
+    private sessionCleanupInterval?;
+    /** Grace period for a created session to finish `initialize` before it is reaped. */
+    private static readonly PENDING_SESSION_TIMEOUT_MS;
     constructor(options?: StreamableHttpTransportOptions);
+    /**
+     * Provide the factory used to build a configured MCP server per session.
+     * Must be called before `start()`.
+     */
+    setMcpServerFactory(factory: McpServerFactory): void;
+    /**
+     * Fallback for clients that speak legacy HTTP+SSE on GET /mcp (no mcp-session-id).
+     * Streamable HTTP clients always begin with POST initialize instead.
+     */
+    setLegacySseHandler(handler: LegacySseHandler): void;
     /**
      * Load logo image as base64 for embedding in documentation page
      */
@@ -77,41 +110,30 @@ export declare class StreamableHttpTransport implements Transport {
      */
     private setupRoutes;
     /**
-     * Handle POST requests (client sending messages to server)
-     */
-    private handlePost;
-    /**
-     * Handle GET requests (client opening SSE stream)
-     */
-    private handleGet;
-    /**
-     * Handle DELETE requests (session termination)
+     * Delegate an `/mcp` request (POST/GET/DELETE) to the official SDK
+     * Streamable HTTP transport. A new session (and its own MCP server instance)
+     * is created on an `initialize` POST; subsequent requests are routed by the
+     * `mcp-session-id` header.
      */
-    private handleDelete;
+    private handleMcpRequest;
     /**
-     * Start SSE stream for a request
+     * Create a new MCP session: a fresh configured MCP server connected to a new
+     * official Streamable HTTP transport. The transport registers itself in the
+     * session map once it has negotiated a session id, and removes itself on close.
      */
-    private startSSEStream;
+    private createSession;
     /**
-     * Send message to client(s)
+     * Tear down a session, removing it from both the live and pending collections
+     * and closing its transport and server. Safe to call from the sweeper, request
+     * error paths, and shutdown.
      */
-    send(message: JSONRPCMessage): Promise<void>;
+    private destroySession;
     /**
-     * Send message to a specific stream
+     * Periodically tear down sessions that have been idle longer than
+     * `sessionTimeout`. Prevents unbounded memory growth from clients that
+     * initialize but never disconnect or send DELETE.
      */
-    private sendToStream;
-    /**
-     * Send response to the stream that made the request
-     */
-    private sendToRequestStream;
-    /**
-     * Send message to a sessionless stream
-     */
-    private sendToStreamSessionless;
-    /**
-     * Replay messages for resumability
-     */
-    private replayMessages;
+    private startSessionCleanup;
     /**
      * Start the HTTP server
      */
@@ -120,33 +142,14 @@ export declare class StreamableHttpTransport implements Transport {
      * Register additional HTTP routes
      * Allows modules (like OAuthModule) to add custom endpoints
      */
-    on(path: string, handler: (req: Request, res: Response) => void): void;
+    on(path: string, handler: (req: any, res: any) => void): void;
     /**
-     * Close the transport
+     * Close the transport: tear down all live MCP sessions and the HTTP server.
      */
     close(): Promise<void>;
     /**
-     * Set message handler
-     */
-    set onmessage(handler: (message: JSONRPCMessage) => Promise<void>);
-    /**
-     * Set close handler
-     */
-    set onclose(handler: () => void);
-    /**
-     * Set error handler
-     */
-    set onerror(handler: (error: Error) => void);
-    /**
-     * Start session cleanup interval
-     */
-    private startSessionCleanup;
-    /**
-     * Helper methods
+     * Whether a parsed JSON-RPC body is an `initialize` request.
      */
-    private generateSessionId;
-    private getMessageType;
-    private isResponse;
     private isInitializeRequest;
     private isLocalhost;
     /**

package/dist/core/transports/streamable-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamable-http.d.ts","sourceRoot":"","sources":["../../../src/core/transports/streamable-http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"streamable-http.d.ts","sourceRoot":"","sources":["../../../src/core/transports/streamable-http.ts"],"names":[],"mappings":"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"}