Add statelessMode to streamableHttp.ts

Author: rinormaloku

src/server/streamableHttp.test.ts

@@ -14,12 +14,13 @@ interface TestServerConfig {
   enableJsonResponse?: boolean;
   customRequestHandler?: (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;
   eventStore?: EventStore;
+  statelessMode?: boolean;
 }
 
 /**
  * Helper to create and start test HTTP server with MCP setup
  */
-async function createTestServer(config: TestServerConfig = { sessionIdGenerator: (() => randomUUID()) }): Promise<{
+async function createTestServer(config: TestServerConfig = { sessionIdGenerator: (() => randomUUID()), statelessMode: false }): Promise<{
   server: Server;
   transport: StreamableHTTPServerTransport;
   mcpServer: McpServer;
@@ -41,6 +42,7 @@ async function createTestServer(config: TestServerConfig = { sessionIdGenerator:
 
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: config.sessionIdGenerator,
+    statelessMode: config.statelessMode,
     enableJsonResponse: config.enableJsonResponse ?? false,
     eventStore: config.eventStore
   });
@@ -313,7 +315,7 @@ describe("StreamableHTTPServerTransport", () => {
     // First initialize to get a session ID
     sessionId = await initializeServer();
 
-    // Open a standalone SSE stream  
+    // Open a standalone SSE stream
     const sseResponse = await fetch(baseUrl, {
       method: "GET",
       headers: {
@@ -810,7 +812,7 @@ describe("StreamableHTTPServerTransport with pre-parsed body", () => {
       id: "preparsed-1",
     };
 
-    // Send an empty body since we'll use pre-parsed body  
+    // Send an empty body since we'll use pre-parsed body
     const response = await fetch(baseUrl, {
       method: "POST",
       headers: {
@@ -1028,7 +1030,7 @@ describe("StreamableHTTPServerTransport with resumability", () => {
     expect(idMatch).toBeTruthy();
     const firstEventId = idMatch![1];
 
-    // Send a second notification 
+    // Send a second notification
     await mcpServer.server.sendLoggingMessage({ level: "info", data: "Second notification from MCP server" });
 
     // Close the first SSE stream to simulate a disconnect
@@ -1064,7 +1066,7 @@ describe("StreamableHTTPServerTransport in stateless mode", () => {
   let baseUrl: URL;
 
   beforeEach(async () => {
-    const result = await createTestServer({ sessionIdGenerator: undefined });
+    const result = await createTestServer({ sessionIdGenerator: undefined, statelessMode: true });
     server = result.server;
     transport = result.transport;
     baseUrl = result.baseUrl;
@@ -1075,13 +1077,6 @@ describe("StreamableHTTPServerTransport in stateless mode", () => {
   });
 
   it("should operate without session ID validation", async () => {
-    // Initialize the server first
-    const initResponse = await sendPostRequest(baseUrl, TEST_MESSAGES.initialize);
-
-    expect(initResponse.status).toBe(200);
-    // Should NOT have session ID header in stateless mode
-    expect(initResponse.headers.get("mcp-session-id")).toBeNull();
-
     // Try request without session ID - should work in stateless mode
     const toolsResponse = await sendPostRequest(baseUrl, TEST_MESSAGES.toolsList);
 
@@ -1117,7 +1112,7 @@ describe("StreamableHTTPServerTransport in stateless mode", () => {
   });
 
   it("should reject second SSE stream even in stateless mode", async () => {
-    // Despite no session ID requirement, the transport still only allows 
+    // Despite no session ID requirement, the transport still only allows
     // one standalone SSE stream at a time
 
     // Initialize the server first

src/server/streamableHttp.ts

@@ -34,11 +34,18 @@ export interface StreamableHTTPServerTransportOptions {
   /**
    * Function that generates a session ID for the transport.
    * The session ID SHOULD be globally unique and cryptographically secure (e.g., a securely generated UUID, a JWT, or a cryptographic hash)
-   * 
-   * Return undefined to disable session management.
+   *
+   * Not used in stateless mode.
    */
   sessionIdGenerator: (() => string) | undefined;
 
+  /**
+   * Whether to run in stateless mode (no session management).
+   * In stateless mode, no initialization is required and there's no session tracking.
+   * Default is false (stateful mode).
+   */
+  statelessMode?: boolean;
+
   /**
    * A callback for session initialization events
    * This is called when the server initializes a new session.
@@ -64,37 +71,39 @@ export interface StreamableHTTPServerTransportOptions {
 
 /**
  * Server transport for Streamable HTTP: this implements the MCP Streamable HTTP transport specification.
- * It supports both SSE streaming and direct HTTP responses.
- * 
+ * It supports both SSE streaming and direct HTTP responses.r
+ *
  * Usage example:
- * 
+ *
  * ```typescript
  * // Stateful mode - server sets the session ID
  * const statefulTransport = new StreamableHTTPServerTransport({
- *  sessionId: randomUUID(),
+ *   sessionIdGenerator: () => randomUUID(),
  * });
- * 
- * // Stateless mode - explicitly set session ID to undefined
+ *
+ * // Stateless mode - explicitly enable stateless mode
  * const statelessTransport = new StreamableHTTPServerTransport({
- *    sessionId: undefined,
+ *   statelessMode: true,
+ *   enableJsonResponse: true, // Optional
  * });
- * 
+ *
  * // Using with pre-parsed request body
  * app.post('/mcp', (req, res) => {
  *   transport.handleRequest(req, res, req.body);
  * });
  * ```
- * 
+ *
  * In stateful mode:
  * - Session ID is generated and included in response headers
  * - Session ID is always included in initialization responses
  * - Requests with invalid session IDs are rejected with 404 Not Found
  * - Non-initialization requests without a session ID are rejected with 400 Bad Request
  * - State is maintained in-memory (connections, message history)
- * 
+ *
  * In stateless mode:
- * - Session ID is only included in initialization responses
+ * - No initialization is required before handling requests
  * - No session validation is performed
+ * - No state is maintained between requests
  */
 export class StreamableHTTPServerTransport implements Transport {
   // when sessionId is not set (undefined), it means the transport is in stateless mode
@@ -108,6 +117,7 @@ export class StreamableHTTPServerTransport implements Transport {
   private _standaloneSseStreamId: string = '_GET_stream';
   private _eventStore?: EventStore;
   private _onsessioninitialized?: (sessionId: string) => void;
+  private _statelessMode: boolean = false;
 
   sessionId?: string | undefined;
   onclose?: () => void;
@@ -119,6 +129,12 @@ export class StreamableHTTPServerTransport implements Transport {
     this._enableJsonResponse = options.enableJsonResponse ?? false;
     this._eventStore = options.eventStore;
     this._onsessioninitialized = options.onsessioninitialized;
+    this._statelessMode = options.statelessMode ?? false;
+
+    // In stateless mode, no initialization is required
+    if (this._statelessMode) {
+      this._initialized = true;
+    }
   }
 
   /**
@@ -166,7 +182,7 @@ export class StreamableHTTPServerTransport implements Transport {
     }
 
     // If an Mcp-Session-Id is returned by the server during initialization,
-    // clients using the Streamable HTTP transport MUST include it 
+    // clients using the Streamable HTTP transport MUST include it
     // in the Mcp-Session-Id header on all of their subsequent HTTP requests.
     if (!this.validateSession(req, res)) {
       return;
@@ -180,7 +196,7 @@ export class StreamableHTTPServerTransport implements Transport {
       }
     }
 
-    // The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, 
+    // The server MUST either return Content-Type: text/event-stream in response to this HTTP GET,
     // or else return HTTP 405 Method Not Allowed
     const headers: Record<string, string> = {
       "Content-Type": "text/event-stream",
@@ -376,7 +392,7 @@ export class StreamableHTTPServerTransport implements Transport {
 
       }
       // If an Mcp-Session-Id is returned by the server during initialization,
-      // clients using the Streamable HTTP transport MUST include it 
+      // clients using the Streamable HTTP transport MUST include it
       // in the Mcp-Session-Id header on all of their subsequent HTTP requests.
       if (!isInitializationRequest && !this.validateSession(req, res)) {
         return;
@@ -475,11 +491,12 @@ export class StreamableHTTPServerTransport implements Transport {
       }));
       return false;
     }
-    if (this.sessionId === undefined) {
-      // If the session ID is not set, the session management is disabled
-      // and we don't need to validate the session ID
+
+    // If in stateless mode or the session ID is undefined, no session validation is needed
+    if (this._statelessMode || this.sessionId === undefined) {
       return true;
     }
+
     const sessionId = req.headers["mcp-session-id"];
 
     if (!sessionId) {