mcp-server-framework 1.0.0

package/build/server/transport/streamable-http/stateful-handler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stateful Streamable HTTP Handler
+ *
+ * Manages persistent sessions with one SDK transport per client.
+ * Session lifecycle is tracked via SessionManager.
+ *
+ * @module server/transport/streamable-http/stateful-handler
+ */
+import type { Request, Response } from "express";
+import type { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { SessionManager } from "../../session/index.js";
+import type { SessionFactory } from "../types.js";
+import type { TransportRequestHandler } from "./transport.js";
+/**
+ * Stateful request handler — one SDK transport per persistent session.
+ *
+ * Manages session creation, lookup, and cleanup via SessionManager.
+ */
+export declare class StatefulHandler implements TransportRequestHandler {
+    private readonly sessionFactory;
+    private readonly sessionManager;
+    private readonly enableJsonResponse;
+    private readonly eventStore?;
+    /**
+     * Tracks in-flight session creations that have passed the capacity check
+     * but haven't yet called sessionManager.create() in the onsessioninitialized callback.
+     * Prevents race conditions where concurrent InitializeRequests both pass
+     * hasCapacity() before either creates a session.
+     */
+    private pendingCreations;
+    constructor(sessionFactory: SessionFactory, sessionManager: SessionManager, enableJsonResponse: boolean, eventStore?: EventStore | undefined);
+    handlePost(req: Request, res: Response): Promise<void>;
+    handleGet(req: Request, res: Response): Promise<void>;
+    handleDelete(req: Request, res: Response): Promise<void>;
+    private createSession;
+    private getSessionId;
+    private resolveSessionId;
+    private getTransport;
+    private injectSessionIdHeader;
+}
+//# sourceMappingURL=stateful-handler.d.ts.map

package/build/server/transport/streamable-http/stateful-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-handler.d.ts","sourceRoot":"","sources":["../../../../src/server/transport/streamable-http/stateful-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAKrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAyB9D;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,uBAAuB;IAU3D,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAZ9B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB,CAAK;gBAGV,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,cAAc,EAC9B,kBAAkB,EAAE,OAAO,EAC3B,UAAU,CAAC,EAAE,UAAU,YAAA;IAGpC,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCtD,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CrD,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;YAiChD,aAAa;IAuH3B,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,qBAAqB;CAQ9B"}

package/build/server/transport/streamable-http/stateful-handler.js

@@ -0,0 +1,264 @@
+/**
+ * Stateful Streamable HTTP Handler
+ *
+ * Manages persistent sessions with one SDK transport per client.
+ * Session lifecycle is tracked via SessionManager.
+ *
+ * @module server/transport/streamable-http/stateful-handler
+ */
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { SESSION_CLOSE_REASONS } from "../../session/index.js";
+import { JsonRpcErrorCode, HttpStatus, TransportErrorMessage } from "../../../errors/index.js";
+import { logger as baseLogger } from "../../../logger/index.js";
+import { TRANSPORT_LOG_COMPONENTS, MCP_HEADERS, SESSION_ID_QUERY_PARAMS } from "../constants.js";
+import { sendError, shortId } from "./transport.js";
+const logger = baseLogger.child({
+    component: TRANSPORT_LOG_COMPONENTS.STREAMABLE_HTTP,
+});
+/** @internal Log messages for stateful handler */
+const LogMessages = {
+    POST_NO_SESSION: "POST /mcp rejected: missing session ID for non-initialize request",
+    POST_SESSION_NOT_FOUND: "POST /mcp rejected: session not found [%s]",
+    POST_MESSAGE: "POST /mcp [%s] method=%s",
+    SESSION_CREATING: "Creating new session from %s",
+    SESSION_INITIALIZED: "Session initialized: %s",
+    SESSION_CAPACITY_REACHED: "Session capacity reached, closing transport for %s",
+    SESSION_CLOSED: "Session closed: %s",
+    GET_SSE_OPENED: "GET /mcp SSE stream opened [%s]",
+    GET_SESSION_NOT_FOUND: "GET /mcp rejected: session not found [%s]",
+    GET_SESSION_ID_FROM_QUERY: "Session ID received via query parameter — prefer Mcp-Session-Id header to avoid URL leakage via Referer/logs",
+    SESSION_ID_INJECTED: "Injected session ID into rawHeaders for SSE request",
+    GET_ERROR: "Error handling GET for session %s: %s",
+    DELETE_ERROR: "Error handling DELETE for session %s: %s",
+};
+/**
+ * Stateful request handler — one SDK transport per persistent session.
+ *
+ * Manages session creation, lookup, and cleanup via SessionManager.
+ */
+export class StatefulHandler {
+    sessionFactory;
+    sessionManager;
+    enableJsonResponse;
+    eventStore;
+    /**
+     * Tracks in-flight session creations that have passed the capacity check
+     * but haven't yet called sessionManager.create() in the onsessioninitialized callback.
+     * Prevents race conditions where concurrent InitializeRequests both pass
+     * hasCapacity() before either creates a session.
+     */
+    pendingCreations = 0;
+    constructor(sessionFactory, sessionManager, enableJsonResponse, eventStore) {
+        this.sessionFactory = sessionFactory;
+        this.sessionManager = sessionManager;
+        this.enableJsonResponse = enableJsonResponse;
+        this.eventStore = eventStore;
+    }
+    async handlePost(req, res) {
+        const sessionId = this.getSessionId(req);
+        // No session + InitializeRequest → create new session
+        if (!sessionId && isInitializeRequest(req.body)) {
+            await this.createSession(req, res);
+            return;
+        }
+        // No session + non-init request → error
+        if (!sessionId) {
+            logger.warn(LogMessages.POST_NO_SESSION);
+            sendError(res, HttpStatus.BAD_REQUEST, JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.SESSION_ID_REQUIRED);
+            return;
+        }
+        // Existing session → delegate to SDK transport
+        const transport = this.getTransport(sessionId);
+        if (!transport) {
+            logger.warn(LogMessages.POST_SESSION_NOT_FOUND, shortId(sessionId));
+            sendError(res, HttpStatus.NOT_FOUND, JsonRpcErrorCode.SESSION_NOT_FOUND, TransportErrorMessage.SESSION_NOT_FOUND);
+            return;
+        }
+        this.sessionManager.touch(sessionId);
+        const method = req.body?.method || "unknown";
+        logger.trace(LogMessages.POST_MESSAGE, shortId(sessionId), method);
+        await transport.handleRequest(req, res, req.body);
+    }
+    async handleGet(req, res) {
+        const sessionId = this.resolveSessionId(req);
+        if (!sessionId) {
+            sendError(res, HttpStatus.BAD_REQUEST, JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.SESSION_ID_OR_PARAM_REQUIRED);
+            return;
+        }
+        const transport = this.getTransport(sessionId);
+        if (!transport) {
+            logger.warn(LogMessages.GET_SESSION_NOT_FOUND, shortId(sessionId));
+            sendError(res, HttpStatus.NOT_FOUND, JsonRpcErrorCode.SESSION_NOT_FOUND, TransportErrorMessage.SESSION_NOT_FOUND_REINIT);
+            return;
+        }
+        this.sessionManager.touch(sessionId);
+        logger.trace(LogMessages.GET_SSE_OPENED, shortId(sessionId));
+        /* v8 ignore start - SDK SSE stream handling */
+        try {
+            this.injectSessionIdHeader(req, sessionId);
+            await transport.handleRequest(req, res);
+        }
+        catch (error) {
+            logger.error(LogMessages.GET_ERROR, sessionId, error);
+            sendError(res, HttpStatus.INTERNAL_SERVER_ERROR, JsonRpcErrorCode.INTERNAL_ERROR, TransportErrorMessage.INTERNAL_ERROR);
+        }
+        /* v8 ignore stop */
+    }
+    async handleDelete(req, res) {
+        const sessionId = this.getSessionId(req);
+        if (!sessionId) {
+            sendError(res, HttpStatus.BAD_REQUEST, JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.SESSION_ID_REQUIRED);
+            return;
+        }
+        const transport = this.getTransport(sessionId);
+        if (!transport) {
+            sendError(res, HttpStatus.NOT_FOUND, JsonRpcErrorCode.SESSION_NOT_FOUND, TransportErrorMessage.SESSION_NOT_FOUND);
+            return;
+        }
+        /* v8 ignore start - SDK DELETE handling */
+        try {
+            await transport.handleRequest(req, res);
+        }
+        catch (error) {
+            logger.error(LogMessages.DELETE_ERROR, sessionId, error);
+            sendError(res, HttpStatus.INTERNAL_SERVER_ERROR, JsonRpcErrorCode.INTERNAL_ERROR, TransportErrorMessage.INTERNAL_ERROR);
+        }
+        /* v8 ignore stop */
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Session Creation
+    // ─────────────────────────────────────────────────────────────────────────
+    async createSession(req, res) {
+        // Atomic capacity check accounting for in-flight session creations.
+        // Without this, concurrent InitializeRequests can both pass hasCapacity()
+        // before either calls sessionManager.create(), leading to wasted SDK connections.
+        // Node.js is single-threaded: no await between stats read and increment → atomic.
+        const { activeCount, maxSessions } = this.sessionManager.stats;
+        if (activeCount + this.pendingCreations >= maxSessions) {
+            logger.warn(LogMessages.SESSION_CAPACITY_REACHED, "pre-check");
+            sendError(res, HttpStatus.SERVICE_UNAVAILABLE, JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.TOO_MANY_SESSIONS);
+            return;
+        }
+        // Check per-transport limits (e.g., maxStreamableHttpSessions) before SDK handshake.
+        // Without this, the SDK sends InitializeResponse but sessionManager.create() rejects
+        // in the onsessioninitialized callback, leaving the client with a stale session ID.
+        if (!this.sessionManager.hasCapacityForTransport("http")) {
+            logger.warn(LogMessages.SESSION_CAPACITY_REACHED, "pre-check (per-transport)");
+            sendError(res, HttpStatus.SERVICE_UNAVAILABLE, JsonRpcErrorCode.SERVER_ERROR, TransportErrorMessage.TOO_MANY_SESSIONS);
+            return;
+        }
+        this.pendingCreations++;
+        // Idempotent slot release — safe to call multiple times (onsessioninitialized, onclose, finally).
+        let slotReleased = false;
+        const releaseSlot = () => {
+            if (!slotReleased) {
+                slotReleased = true;
+                this.pendingCreations--;
+            }
+        };
+        logger.debug(LogMessages.SESSION_CREATING, req.ip || "unknown");
+        try {
+            const mcpSession = this.sessionFactory();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                enableJsonResponse: this.enableJsonResponse,
+                ...(this.eventStore !== undefined && { eventStore: this.eventStore }),
+                onsessioninitialized: (sessionId) => {
+                    releaseSlot();
+                    logger.debug(LogMessages.SESSION_INITIALIZED, shortId(sessionId));
+                    const session = this.sessionManager.create({
+                        id: sessionId,
+                        transportType: "http",
+                        transport: transport, // @sdk-constraint — StreamableHTTPServerTransport.onclose is optional, Transport.onclose is not
+                        mcpSession,
+                    });
+                    if (!session) {
+                        logger.warn(LogMessages.SESSION_CAPACITY_REACHED, shortId(sessionId));
+                        void transport.close().catch((err) => {
+                            logger.warn("Failed to close transport after capacity rejection: %s", err instanceof Error ? err.message : String(err));
+                        });
+                    }
+                },
+            });
+            /* v8 ignore start - SDK callback registration */
+            transport.onclose = () => {
+                releaseSlot();
+                const sid = transport.sessionId;
+                if (sid) {
+                    logger.info(LogMessages.SESSION_CLOSED, shortId(sid));
+                    void this.sessionManager.close(sid, SESSION_CLOSE_REASONS.CLIENT_DISCONNECT).catch((err) => {
+                        logger.warn("Error closing session on client disconnect: %s", err instanceof Error ? err.message : String(err));
+                    });
+                }
+            };
+            /* v8 ignore stop */
+            try {
+                await mcpSession.sdk.connect(transport); // @sdk-constraint — StreamableHTTPServerTransport.onclose is optional, Transport.onclose is not
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch (connectError) {
+                // Cleanup transport and session on connect/handleRequest failure
+                // to prevent resource leaks (transport stays open, session never closed).
+                try {
+                    await transport.close();
+                }
+                catch {
+                    // Best-effort — transport may already be closed
+                }
+                const sid = transport.sessionId;
+                if (sid) {
+                    try {
+                        await this.sessionManager.close(sid, SESSION_CLOSE_REASONS.ERROR);
+                    }
+                    catch {
+                        // Best-effort — session may not have been fully created
+                    }
+                }
+                throw connectError;
+            }
+        }
+        finally {
+            releaseSlot();
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Helpers
+    // ─────────────────────────────────────────────────────────────────────────
+    getSessionId(req) {
+        const value = req.headers[MCP_HEADERS.SESSION_ID];
+        return typeof value === "string" ? value : undefined;
+    }
+    resolveSessionId(req) {
+        const headerValue = this.getSessionId(req);
+        if (headerValue)
+            return headerValue;
+        if (req.query) {
+            for (const param of SESSION_ID_QUERY_PARAMS) {
+                const value = req.query[param];
+                if (typeof value === "string" && value) {
+                    logger.warn(LogMessages.GET_SESSION_ID_FROM_QUERY);
+                    return value;
+                }
+            }
+        }
+        return undefined;
+    }
+    getTransport(sessionId) {
+        const session = this.sessionManager.get(sessionId);
+        if (!session)
+            return undefined;
+        // @transport-downcast — Sessions in this handler are exclusively created with StreamableHTTP transport
+        return session.transport.instance;
+    }
+    injectSessionIdHeader(req, sessionId) {
+        if (!req.headers[MCP_HEADERS.SESSION_ID] && sessionId) {
+            req.rawHeaders.push(MCP_HEADERS.SESSION_ID, sessionId);
+            // @express-api — IncomingHttpHeaders lacks writable string index; safe mutation for framework-internal header injection
+            req.headers[MCP_HEADERS.SESSION_ID] = sessionId;
+            logger.trace(LogMessages.SESSION_ID_INJECTED);
+        }
+    }
+}
+//# sourceMappingURL=stateful-handler.js.map

package/build/server/transport/streamable-http/stateful-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateful-handler.js","sourceRoot":"","sources":["../../../../src/server/transport/streamable-http/stateful-handler.ts"],"names":[],"mappings":"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"}

package/build/server/transport/streamable-http/stateless-handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stateless Streamable HTTP Handler
+ *
+ * Creates a fresh McpSession + SDK transport per request.
+ * No session tracking, no persistent connections.
+ *
+ * @module server/transport/streamable-http/stateless-handler
+ */
+import type { Request, Response } from "express";
+import type { SessionFactory } from "../types.js";
+import type { TransportRequestHandler } from "./transport.js";
+/**
+ * Stateless request handler — fresh McpSession + transport per request.
+ *
+ * Per MCP specification, stateless transports:
+ * - Do not emit Mcp-Session-Id headers
+ * - Do not support GET SSE streams or DELETE
+ * - Cannot be reused across requests (SDK constraint)
+ */
+export declare class StatelessHandler implements TransportRequestHandler {
+    private readonly sessionFactory;
+    private readonly enableJsonResponse;
+    constructor(sessionFactory: SessionFactory, enableJsonResponse: boolean);
+    handlePost(req: Request, res: Response): Promise<void>;
+    handleGet(_req: Request, res: Response): Promise<void>;
+    handleDelete(_req: Request, res: Response): Promise<void>;
+}
+//# sourceMappingURL=stateless-handler.d.ts.map

package/build/server/transport/streamable-http/stateless-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateless-handler.d.ts","sourceRoot":"","sources":["../../../../src/server/transport/streamable-http/stateless-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAe9D;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,uBAAuB;IAE5D,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBADlB,cAAc,EAAE,cAAc,EAC9B,kBAAkB,EAAE,OAAO;IAGxC,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCtD,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAShE"}

package/build/server/transport/streamable-http/stateless-handler.js

@@ -0,0 +1,81 @@
+/**
+ * Stateless Streamable HTTP Handler
+ *
+ * Creates a fresh McpSession + SDK transport per request.
+ * No session tracking, no persistent connections.
+ *
+ * @module server/transport/streamable-http/stateless-handler
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { JsonRpcErrorCode, HttpStatus, TransportErrorMessage } from "../../../errors/index.js";
+import { logger as baseLogger } from "../../../logger/index.js";
+import { TRANSPORT_LOG_COMPONENTS } from "../constants.js";
+import { sendError } from "./transport.js";
+const logger = baseLogger.child({
+    component: TRANSPORT_LOG_COMPONENTS.STREAMABLE_HTTP,
+});
+/** @internal Log messages for stateless handler */
+const LogMessages = {
+    STATELESS_POST: "Stateless POST /mcp method=%s",
+    STATELESS_ERROR: "Stateless request error: %s",
+    STATELESS_CLEANUP_ERROR: "Stateless cleanup error: %s",
+    STATELESS_NOT_ALLOWED: "%s not supported in stateless mode",
+};
+/**
+ * Stateless request handler — fresh McpSession + transport per request.
+ *
+ * Per MCP specification, stateless transports:
+ * - Do not emit Mcp-Session-Id headers
+ * - Do not support GET SSE streams or DELETE
+ * - Cannot be reused across requests (SDK constraint)
+ */
+export class StatelessHandler {
+    sessionFactory;
+    enableJsonResponse;
+    constructor(sessionFactory, enableJsonResponse) {
+        this.sessionFactory = sessionFactory;
+        this.enableJsonResponse = enableJsonResponse;
+    }
+    async handlePost(req, res) {
+        const method = req.body?.method || "unknown";
+        logger.trace(LogMessages.STATELESS_POST, method);
+        try {
+            const mcpSession = this.sessionFactory();
+            // @ts-expect-error @sdk-constraint — SDK sessionIdGenerator? doesn't accept undefined with exactOptionalPropertyTypes; undefined is the documented mechanism for stateless mode
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: this.enableJsonResponse,
+            });
+            try {
+                // @sdk-constraint — StreamableHTTPServerTransport structurally differs from Transport with exactOptionalPropertyTypes
+                await mcpSession.sdk.connect(transport);
+                await transport.handleRequest(req, res, req.body);
+            }
+            finally {
+                // Cleanup transport + session after the request completes (or fails).
+                // Runs even if connect() throws — prevents resource leaks on initialization failure.
+                // Use Promise.allSettled to ensure both cleanup steps run even if one fails.
+                const results = await Promise.allSettled([transport.close(), mcpSession.dispose()]);
+                for (const result of results) {
+                    if (result.status === "rejected") {
+                        const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                        logger.warn(LogMessages.STATELESS_CLEANUP_ERROR, reason);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger.error(LogMessages.STATELESS_ERROR, error);
+            sendError(res, HttpStatus.INTERNAL_SERVER_ERROR, JsonRpcErrorCode.INTERNAL_ERROR, TransportErrorMessage.INTERNAL_ERROR);
+        }
+    }
+    async handleGet(_req, res) {
+        logger.warn(LogMessages.STATELESS_NOT_ALLOWED, "GET");
+        sendError(res, HttpStatus.METHOD_NOT_ALLOWED, JsonRpcErrorCode.METHOD_NOT_FOUND, "GET not supported in stateless mode");
+    }
+    async handleDelete(_req, res) {
+        logger.warn(LogMessages.STATELESS_NOT_ALLOWED, "DELETE");
+        sendError(res, HttpStatus.METHOD_NOT_ALLOWED, JsonRpcErrorCode.METHOD_NOT_FOUND, "DELETE not supported in stateless mode");
+    }
+}
+//# sourceMappingURL=stateless-handler.js.map

package/build/server/transport/streamable-http/stateless-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateless-handler.js","sourceRoot":"","sources":["../../../../src/server/transport/streamable-http/stateless-handler.ts"],"names":[],"mappings":"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"}

package/build/server/transport/streamable-http/transport.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Streamable HTTP Transport
+ *
+ * Facade that delegates HTTP requests to the appropriate strategy handler
+ * based on the configured mode (stateful or stateless).
+ *
+ * Architecture:
+ *   Express Route → StreamableHttpTransport → Strategy Handler → SDK Transport → McpServer
+ *
+ * The SDK transport handles all MCP protocol concerns:
+ * - JSON-RPC 2.0 parsing and validation
+ * - Content-Type and Accept header validation
+ * - Session ID management (header setting/checking)
+ * - SSE stream setup for server-to-client notifications
+ * - Session termination
+ *
+ * This transport manages:
+ * - Strategy selection (stateful vs stateless)
+ * - HTTP method routing (POST, GET, DELETE)
+ * - Error responses for unsupported methods
+ *
+ * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+ * @module server/transport/streamable-http/transport
+ */
+import type { Request, Response } from "express";
+import type { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { SessionManager } from "../../session/index.js";
+import type { SessionFactory } from "../types.js";
+/**
+ * Strategy interface for handling Streamable HTTP transport requests.
+ *
+ * Implemented by:
+ * - {@link StatefulHandler} — one SDK transport per persistent session
+ * - {@link StatelessHandler} — fresh McpSession + transport per request
+ */
+export interface TransportRequestHandler {
+    handlePost(req: Request, res: Response): Promise<void>;
+    handleGet(req: Request, res: Response): Promise<void>;
+    handleDelete(req: Request, res: Response): Promise<void>;
+}
+/**
+ * Sends a JSON-RPC error response if headers haven't been sent.
+ */
+export declare function sendError(res: Response, status: number, code: number, message: string): void;
+/**
+ * Shortens a session ID for log display.
+ */
+export declare function shortId(sessionId: string): string;
+/**
+ * Configuration options for the Streamable HTTP transport.
+ */
+export interface StreamableHttpTransportOptions {
+    /** Operate in stateless mode (no session IDs). Default: false */
+    readonly stateless?: boolean | undefined;
+    /**
+     * Optional event store for stream resumability.
+     *
+     * When provided, the SDK transport stores SSE events and supports
+     * client reconnection via the `Last-Event-ID` header. Only meaningful
+     * in stateful mode — stateless requests have no persistent streams.
+     *
+     * The SDK provides {@link InMemoryEventStore} as a reference implementation.
+     * For production horizontal scaling, implement the {@link EventStore} interface
+     * with Redis, PostgreSQL, or another shared backend.
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+     */
+    readonly eventStore?: EventStore | undefined;
+    /**
+     * Prefer JSON responses over SSE for simple request-response.
+     *
+     * When true, the SDK returns `application/json` for non-streaming
+     * responses instead of `text/event-stream` SSE envelopes.
+     *
+     * MCP spec: "If the server is only sending one response with no
+     * notifications, it SHOULD prefer application/json."
+     *
+     * @default true
+     */
+    readonly enableJsonResponse?: boolean | undefined;
+}
+/**
+ * Routes HTTP requests to the appropriate strategy handler.
+ *
+ * In stateful mode (default): delegates to {@link StatefulHandler}
+ * In stateless mode: delegates to {@link StatelessHandler}
+ *
+ * All MCP protocol handling is delegated through the handler chain
+ * to the SDK's StreamableHTTPServerTransport.
+ */
+export declare class StreamableHttpTransport {
+    private readonly handler;
+    private readonly sessionManager;
+    constructor(sessionFactory: SessionFactory, sessionManager: SessionManager, options?: StreamableHttpTransportOptions);
+    /**
+     * Handle an incoming HTTP request by delegating to the appropriate
+     * strategy handler.
+     *
+     * This is the single entry point called by Express route handlers.
+     * Security middleware (DNS rebinding, rate limiting, protocol version)
+     * runs BEFORE this method is called.
+     */
+    handleRequest(req: Request, res: Response): Promise<void>;
+    /**
+     * Number of active stateful sessions.
+     * Returns 0 in stateless mode (no session tracking).
+     */
+    get activeSessionCount(): number;
+}
+//# sourceMappingURL=transport.d.ts.map

package/build/server/transport/streamable-http/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../src/server/transport/streamable-http/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oDAAoD,CAAC;AAErF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgBlD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAI5F;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjD;AAYD;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAEzC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnD;AAMD;;;;;;;;GAQG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;gBAG9C,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,cAAc,EAC9B,OAAO,GAAE,8BAAmC;IAc9C;;;;;;;OAOG;IACG,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/D;;;OAGG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;CACF"}