@mongodb-js/mcp-http-runners 3.0.0-prerelease.1 → 3.0.0-prerelease.3

package/dist/mcpHttpServer.d.ts

@@ -1,6 +1,7 @@
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import type { ICompositeLogger, IMetrics, DefaultMetricDefinitions, TransportRequestContext, ISessionStore, HttpServerOptions, SessionManagementOptions, SessionServer } from "@mongodb-js/mcp-types";
+import { type McpHttpHandler } from "@modelcontextprotocol/server";
+import type { ICompositeLogger, IMetrics, DefaultMetricDefinitions, TransportRequestContext, HttpServerOptions, BaseServer } from "@mongodb-js/mcp-types";
 import { ExpressBasedHttpServer } from "./expressBasedHttpServer.js";
+import { type LegacyMcpHandler, type LegacySessionOptions } from "./legacyMcpHttpHandler.js";
 /**
  * Options for creating an MCPHttpServer instance.
  */
@@ -8,19 +9,32 @@ export type MCPHttpServerOptions<TMetrics extends DefaultMetricDefinitions = Def
     options: {
         /** HTTP server options */
         http: HttpServerOptions;
-        /** Session management options */
-        session: SessionManagementOptions;
     };
     /** Logger for the server */
     logger: ICompositeLogger;
     /** Metrics instance */
     metrics: IMetrics<TMetrics>;
-    /** Session store for managing transports */
-    sessionStore: ISessionStore<StreamableHTTPServerTransport>;
+    /**
+     * Tunables for the 2025-era (legacy) session lifecycle: the `maxSessions`
+     * cap, the idle/notification timeouts, and the LRU eviction idle grace. See
+     * {@link LegacySessionOptions}.
+     */
+    sessionOptions?: LegacySessionOptions;
 };
 /**
- * HTTP server that handles MCP requests over HTTP using the Streamable HTTP transport.
+ * HTTP server that serves MCP requests over HTTP.
+ *
+ * The 2026-07-28 protocol is served **statelessly** through the SDK's
+ * `createMcpHandler` (`legacy: 'reject'`): each request builds a fresh
+ * request-scoped server and carries client identity per request in the `_meta`
+ * envelope. No per-client sessions, no `mcp-session-id` routing on that path.
  *
+ * 2025-era (legacy) requests are delegated to a sessionful
+ * {@link LegacyMcpHttpHandler} (see its docs for why): the 2025 protocol needs
+ * a live, correlated transport for its `initialize`-declared capabilities and
+ * server→client elicitation, which the SDK's `legacy: 'stateless'` mode cannot
+ * provide. The modern/legacy split is isolated from this class so each path
+ * stays clean.
  *
  * @example
  * ```typescript
@@ -31,56 +45,41 @@ export type MCPHttpServerOptions<TMetrics extends DefaultMetricDefinitions = Def
  * }
  * ```
  */
-export declare abstract class MCPHttpServer<TServer extends SessionServer = SessionServer, TMetrics extends DefaultMetricDefinitions = DefaultMetricDefinitions> extends ExpressBasedHttpServer {
-    private readonly sessionStore;
-    readonly sessionOptions: SessionManagementOptions;
+export declare abstract class MCPHttpServer<TServer extends BaseServer = BaseServer, TMetrics extends DefaultMetricDefinitions = DefaultMetricDefinitions> extends ExpressBasedHttpServer {
+    /** The 2026-07-28 serving entry; modern requests are routed here. */
+    private readonly modernHandler;
+    /** Sessionful 2025-era serving (initialize/SSE/requests carried per session). */
+    private readonly legacyHandler;
     protected readonly metrics: IMetrics<TMetrics>;
-    private readonly pendingInitializations;
-    constructor({ options, logger, metrics, sessionStore }: MCPHttpServerOptions<TMetrics>);
+    constructor({ options, logger, metrics, sessionOptions }: MCPHttpServerOptions<TMetrics>);
     stop(): Promise<void>;
+    /**
+     * Builds the handler that serves 2025-era (legacy) traffic. Subclasses may
+     * override this to plug in an alternative legacy transport/session
+     * implementation; the default returns a {@link LegacyMcpHttpHandler} built
+     * from {@link MCPHttpServer.createServerForRequest}.
+     */
+    protected createLegacyHandler({ logger, http, sessionOptions, }: {
+        logger: ICompositeLogger;
+        http: HttpServerOptions;
+        sessionOptions?: LegacySessionOptions;
+    }): LegacyMcpHandler;
     /**
      * Creates a server instance for a specific request. Override this method
      * in subclasses to customize per-request server creation.
      */
     protected abstract createServerForRequest(request: TransportRequestContext): Promise<TServer>;
-    private reportSessionError;
-    private startKeepAliveLoop;
-    /**
-     * Ensures the session for the given sessionId is initialized, serializing
-     * concurrent initialization attempts so only one runs at a time.
-     *
-     * If a session already exists in the store, this is a no-op.
-     * If another request is already initializing this session, this call waits
-     * for that initialization to complete.
-     * Otherwise, this call performs the initialization.
-     *
-     * After this method resolves, the caller should look up the transport from
-     * the session store via `sessionStore.getSession()`.
-     *
-     * When `isImplicitInitialization` is true, the transport is pre-configured as
-     * initialized (bypassing the MCP initialize handshake) so that it can handle
-     * non-initialize requests immediately. When false, the transport is left in
-     * its default state so it can process the initialize request normally.
-     */
-    private ensureSessionInitialized;
-    /**
-     * Restores the client state negotiated during the session's original
-     * initialization onto an implicitly re-initialized server. The server on
-     * this pod never saw the client's `initialize` request, so without this
-     * it would treat the client as capability-less — e.g. skipping
-     * confirmation elicitation for destructive tools. No-op when the session
-     * store does not persist negotiated client state.
-     */
-    private restoreNegotiatedClientState;
+    /** Request middleware hook for `/mcp`, called after body parse + header validation, before routing. */
+    protected registerMiddlewares(): void;
     /**
-     * Arranges for the client state negotiated by a real `initialize`
-     * exchange to be persisted through the session store, so implicit
-     * re-initializations of this session can restore it. Wraps the
-     * `oninitialized` callback installed by `server.connect`, hence must run
-     * after it.
+     * Builds the 2026-07-28 serving entry. One factory backs every modern
+     * request: it constructs a fresh request-scoped server, registers it, and
+     * hands the underlying {@link McpServer} to `createMcpHandler`.
+     * `legacy: 'reject'` means this entry serves ONLY the 2026-07-28 era;
+     * 2025-era traffic is routed to the sessionful legacy handler (see
+     * {@link LegacyMcpHttpHandler}).
      */
-    private captureNegotiatedClientStateOnInitialize;
-    protected setupMiddlewares(): void;
+    protected createModernHandler(): McpHttpHandler;
     protected setupRoutes(): Promise<void>;
     private withErrorHandling;
 }

package/dist/mcpHttpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpHttpServer.d.ts","sourceRoot":"","sources":["../src/mcpHttpServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAGnG,OAAO,KAAK,EACR,gBAAgB,EAEhB,QAAQ,EACR,wBAAwB,EACxB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,aAAa,EAEhB,MAAM,uBAAuB,CAAC;AAgB/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,SAAS,wBAAwB,GAAG,wBAAwB,IAAI;IACrG,OAAO,EAAE;QACL,0BAA0B;QAC1B,IAAI,EAAE,iBAAiB,CAAC;QACxB,iCAAiC;QACjC,OAAO,EAAE,wBAAwB,CAAC;KACrC,CAAC;IACF,4BAA4B;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,uBAAuB;IACvB,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B,4CAA4C;IAC5C,YAAY,EAAE,aAAa,CAAC,6BAA6B,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,8BAAsB,aAAa,CAC/B,OAAO,SAAS,aAAa,GAAG,aAAa,EAC7C,QAAQ,SAAS,wBAAwB,GAAG,wBAAwB,CACtE,SAAQ,sBAAsB;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+C;IAC5E,SAAgB,cAAc,EAAE,wBAAwB,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAoC;gBAE/D,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,oBAAoB,CAAC,QAAQ,CAAC;IAazE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAE7F,OAAO,CAAC,kBAAkB;YAsCZ,kBAAkB;IAmDhC;;;;;;;;;;;;;;;;OAgBG;YACW,wBAAwB;IA+ItC;;;;;;;OAOG;YACW,4BAA4B;IAqC1C;;;;;;OAMG;IACH,OAAO,CAAC,wCAAwC;IAyBhD,SAAS,CAAC,gBAAgB,IAAI,IAAI;cAmBT,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA+FrD,OAAO,CAAC,iBAAiB;CAqC5B"}
+{"version":3,"file":"mcpHttpServer.d.ts","sourceRoot":"","sources":["../src/mcpHttpServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,cAAc,EAEtB,MAAM,8BAA8B,CAAC;AAItC,OAAO,KAAK,EACR,gBAAgB,EAChB,QAAQ,EACR,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACb,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAwB,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEnH;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,SAAS,wBAAwB,GAAG,wBAAwB,IAAI;IACrG,OAAO,EAAE;QACL,0BAA0B;QAC1B,IAAI,EAAE,iBAAiB,CAAC;KAC3B,CAAC;IACF,4BAA4B;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,uBAAuB;IACvB,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACzC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,aAAa,CAC/B,OAAO,SAAS,UAAU,GAAG,UAAU,EACvC,QAAQ,SAAS,wBAAwB,GAAG,wBAAwB,CACtE,SAAQ,sBAAsB;IAC5B,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAEnC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,oBAAoB,CAAC,QAAQ,CAAC;IAa3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAAC,EAC1B,MAAM,EACN,IAAI,EACJ,cAAc,GACjB,EAAE;QACC,MAAM,EAAE,gBAAgB,CAAC;QACzB,IAAI,EAAE,iBAAiB,CAAC;QACxB,cAAc,CAAC,EAAE,oBAAoB,CAAC;KACzC,GAAG,gBAAgB;IAkBpB;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAE7F,uGAAuG;IACvG,SAAS,CAAC,mBAAmB,IAAI,IAAI;IAErC;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,IAAI,cAAc;cAgDtB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAiDrD,OAAO,CAAC,iBAAiB;CA0B5B"}