@frontmcp/sdk 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "FrontMCP SDK",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -50,6 +50,16 @@
         "default": "./esm/mcp-apps/index.mjs"
       }
     },
+    "./transport": {
+      "require": {
+        "types": "./transport/index.d.ts",
+        "default": "./transport/index.js"
+      },
+      "import": {
+        "types": "./transport/index.d.ts",
+        "default": "./esm/transport/index.mjs"
+      }
+    },
     "./esm": null
   },
   "peerDependencies": {
@@ -66,7 +76,7 @@
     }
   },
   "dependencies": {
-    "@frontmcp/uipack": "0.6.2",
+    "@frontmcp/uipack": "0.6.3",
     "@modelcontextprotocol/sdk": "1.25.1",
     "ioredis": "^5.8.0",
     "jose": "^6.1.3",

package/transport/adapters/sse-transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Custom SSEServerTransport that supports session recreation.
+ *
+ * When recreating a session from Redis (e.g., in serverless environments
+ * or after client reconnection), we need to restore the transport's state
+ * including the event ID counter for proper SSE reconnection support.
+ *
+ * This class extends our custom SSEServerTransport to expose a public API
+ * for session recreation, maintaining the event ID sequence across reconnections.
+ */
+import { SSEServerTransport, SSEServerTransportOptions } from '../legacy/legacy.sse.tranporter';
+import type { ServerResponse } from 'http';
+export interface RecreateableSSEServerTransportOptions extends SSEServerTransportOptions {
+    /**
+     * Initial event ID counter value for session recreation.
+     * Use this when recreating a session to restore the event ID sequence.
+     */
+    initialEventId?: number;
+}
+/**
+ * SSEServerTransport with session recreation support.
+ *
+ * This is a drop-in replacement for SSEServerTransport that adds the ability
+ * to recreate a session with preserved state. This is essential for:
+ * - Serverless environments where the transport may be evicted from memory
+ * - Client reconnection scenarios where event ID continuity is required
+ * - Distributed systems where sessions are stored in Redis
+ *
+ * It extends SSEServerTransport to maintain full compatibility while
+ * adding public methods to set initialization state and restore event IDs.
+ */
+export declare class RecreateableSSEServerTransport extends SSEServerTransport {
+    private _isRecreatedSession;
+    constructor(endpoint: string, res: ServerResponse, options?: RecreateableSSEServerTransportOptions);
+    /**
+     * Validates that an event ID is a valid non-negative integer.
+     * Protects against negative values, NaN, Infinity, and non-integer values.
+     */
+    private isValidEventId;
+    /**
+     * Returns whether this is a recreated session.
+     */
+    get isRecreatedSession(): boolean;
+    /**
+     * Returns the current event ID counter value.
+     * Alias for lastEventId for consistency with the recreation API.
+     */
+    get eventIdCounter(): number;
+    /**
+     * Sets the event ID counter for session recreation.
+     * Use this when recreating a session from stored state to maintain
+     * event ID continuity for SSE reconnection support.
+     *
+     * @param eventId - The event ID to restore (must be a non-negative integer)
+     */
+    setEventIdCounter(eventId: number): void;
+    /**
+     * Sets the transport to a recreated session state.
+     * Use this when recreating a transport from a stored session.
+     *
+     * @param sessionId - The session ID (for verification, should match constructor)
+     * @param lastEventId - The last event ID that was sent to the client
+     */
+    setSessionState(sessionId: string, lastEventId?: number): void;
+}

package/transport/adapters/streamable-http-transport.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Custom StreamableHTTPServerTransport that supports session recreation.
+ *
+ * The MCP SDK's transport sets `_initialized` and `sessionId` only during
+ * the initialize request handshake. When recreating a transport from Redis
+ * (e.g., in serverless environments), we need to set these values directly.
+ *
+ * This class extends the MCP SDK's transport to expose a public API for
+ * session recreation, avoiding the need to access private properties.
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+export interface StreamableHTTPServerTransportOptions {
+    /**
+     * A function that generates a session ID for the transport.
+     * If provided, sessions are stateful and require the mcp-session-id header.
+     * If undefined, the transport operates in stateless mode.
+     */
+    sessionIdGenerator?: () => string;
+    /**
+     * If true, responses are sent as JSON instead of SSE.
+     * Default: false (SSE streaming mode)
+     */
+    enableJsonResponse?: boolean;
+    /**
+     * Event store for resumability support.
+     * Type uses `any` because the EventStore interface is not exported from the MCP SDK
+     * and varies between SDK versions. The actual type is defined internally by
+     * StreamableHTTPServerTransport.
+     */
+    eventStore?: any;
+    /**
+     * Callback when a session is initialized.
+     */
+    onsessioninitialized?: (sessionId: string) => void | Promise<void>;
+    /**
+     * Callback when a session is closed.
+     */
+    onsessionclosed?: (sessionId?: string) => void | Promise<void>;
+}
+/**
+ * StreamableHTTPServerTransport with session recreation support.
+ *
+ * This is a drop-in replacement for the MCP SDK's StreamableHTTPServerTransport
+ * that adds the ability to recreate a session without replaying the initialization
+ * handshake. This is essential for serverless environments where the transport
+ * may be evicted from memory and needs to be recreated from a stored session.
+ *
+ * It extends StreamableHTTPServerTransport to maintain full compatibility while
+ * adding public methods to set initialization state.
+ */
+export declare class RecreateableStreamableHTTPServerTransport extends StreamableHTTPServerTransport {
+    constructor(options?: StreamableHTTPServerTransportOptions);
+    /**
+     * Returns whether the transport has been initialized.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Sets the transport to an initialized state with the given session ID.
+     * Use this when recreating a transport from a stored session.
+     *
+     * This method allows you to "restore" a session without replaying the
+     * initialization handshake. After calling this method, the transport
+     * will accept requests with the given session ID.
+     *
+     * @param sessionId - The session ID that was previously assigned to this session
+     * @throws Error if sessionId is empty or invalid
+     */
+    setInitializationState(sessionId: string): void;
+}

package/transport/adapters/transport.local.adapter.d.ts

@@ -6,10 +6,19 @@ import { InMemoryEventStore } from '../transport.event-store';
 import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '../legacy/legacy.sse.tranporter';
+import { RecreateableStreamableHTTPServerTransport } from './streamable-http-transport';
+import { RecreateableSSEServerTransport } from './sse-transport';
 import { ZodType } from 'zod';
 import { FrontMcpLogger, ServerResponse } from '../../common';
 import { Scope } from '../../scope';
-export declare abstract class LocalTransportAdapter<T extends StreamableHTTPServerTransport | SSEServerTransport> {
+/**
+ * Base transport type that includes all supported transports.
+ * RecreateableStreamableHTTPServerTransport extends StreamableHTTPServerTransport
+ * and RecreateableSSEServerTransport extends SSEServerTransport,
+ * so they're also included in this union.
+ */
+export type SupportedTransport = StreamableHTTPServerTransport | SSEServerTransport | RecreateableStreamableHTTPServerTransport | RecreateableSSEServerTransport;
+export declare abstract class LocalTransportAdapter<T extends SupportedTransport> {
     #private;
     protected readonly scope: Scope;
     protected readonly key: TransportKey;
@@ -28,6 +37,11 @@ export declare abstract class LocalTransportAdapter<T extends StreamableHTTPServ
     abstract initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     abstract sendElicitRequest<T extends ZodType>(relatedRequestId: RequestId, message: string, requestedSchema: T): Promise<TypedElicitResult<T>>;
     abstract handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
+    /**
+     * Marks this transport as pre-initialized for session recreation.
+     * Override in subclasses that need to set the MCP SDK's _initialized flag.
+     */
+    markAsInitialized(): void;
     connectServer(): Promise<void>;
     get newRequestId(): RequestId;
     destroy(reason?: string): Promise<void>;

package/transport/adapters/transport.sse.adapter.d.ts

@@ -1,13 +1,26 @@
 import { AuthenticatedServerRequest } from '../../server/server.types';
 import { TypedElicitResult } from '../transport.types';
-import { SSEServerTransport } from '../legacy/legacy.sse.tranporter';
+import { RecreateableSSEServerTransport } from './sse-transport';
 import { LocalTransportAdapter } from './transport.local.adapter';
 import { RequestId } from '@modelcontextprotocol/sdk/types.js';
 import { ZodType } from 'zod';
 import { ServerResponse } from '../../common';
-export declare class TransportSSEAdapter extends LocalTransportAdapter<SSEServerTransport> {
+export declare class TransportSSEAdapter extends LocalTransportAdapter<RecreateableSSEServerTransport> {
     sessionId: string;
-    createTransport(sessionId: string, res: ServerResponse): SSEServerTransport;
+    /**
+     * Configures common error and close handlers for SSE transports.
+     */
+    private configureTransportHandlers;
+    createTransport(sessionId: string, res: ServerResponse): RecreateableSSEServerTransport;
+    /**
+     * Recreates a transport with preserved session state.
+     * Use this when restoring a session from Redis or other storage.
+     *
+     * @param sessionId - The session ID to restore
+     * @param res - The new response stream for SSE
+     * @param lastEventId - The last event ID that was sent (for reconnection support)
+     */
+    createTransportFromSession(sessionId: string, res: ServerResponse, lastEventId?: number): RecreateableSSEServerTransport;
     initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     sendElicitRequest<T extends ZodType>(relatedRequestId: RequestId, message: string, requestedSchema: T): Promise<TypedElicitResult<T>>;

package/transport/adapters/transport.streamable-http.adapter.d.ts

@@ -1,10 +1,10 @@
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { TransportType, TypedElicitResult } from '../transport.types';
 import { AuthenticatedServerRequest } from '../../server/server.types';
 import { LocalTransportAdapter } from './transport.local.adapter';
 import { RequestId } from '@modelcontextprotocol/sdk/types.js';
 import { ZodType } from 'zod';
 import { ServerResponse } from '../../common';
+import { RecreateableStreamableHTTPServerTransport } from './streamable-http-transport';
 /**
  * Stateless HTTP requests must be able to send multiple initialize calls without
  * tripping the MCP transport's "already initialized" guard. The upstream SDK
@@ -12,9 +12,18 @@ import { ServerResponse } from '../../common';
  * session generation entirely for stateless transports.
  */
 export declare const resolveSessionIdGenerator: (transportType: TransportType, sessionId: string) => (() => string) | undefined;
-export declare class TransportStreamableHttpAdapter extends LocalTransportAdapter<StreamableHTTPServerTransport> {
-    createTransport(sessionId: string, response: ServerResponse): StreamableHTTPServerTransport;
+export declare class TransportStreamableHttpAdapter extends LocalTransportAdapter<RecreateableStreamableHTTPServerTransport> {
+    createTransport(sessionId: string, response: ServerResponse): RecreateableStreamableHTTPServerTransport;
     initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     sendElicitRequest<T extends ZodType>(relatedRequestId: RequestId, message: string, requestedSchema: T): Promise<TypedElicitResult<T>>;
+    /**
+     * Marks this transport as pre-initialized for session recreation.
+     * This is needed when recreating a transport from Redis because the
+     * original initialize request was processed by a different transport instance.
+     *
+     * Uses the RecreateableStreamableHTTPServerTransport's public API to set
+     * initialization state, avoiding access to private properties.
+     */
+    markAsInitialized(): void;
 }

package/transport/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file index.ts
+ * @description Transport module barrel exports.
+ *
+ * Provides recreateable transport classes for session recreation support
+ * in serverless environments and distributed systems.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   RecreateableStreamableHTTPServerTransport,
+ *   RecreateableSSEServerTransport,
+ * } from '@frontmcp/sdk/transport';
+ * ```
+ *
+ * @module @frontmcp/sdk/transport
+ */
+export { RecreateableStreamableHTTPServerTransport, StreamableHTTPServerTransportOptions, } from './adapters/streamable-http-transport';
+export { RecreateableSSEServerTransport, RecreateableSSEServerTransportOptions } from './adapters/sse-transport';
+export { SSEServerTransport, SSEServerTransportOptions } from './legacy/legacy.sse.tranporter';
+export { SupportedTransport } from './adapters/transport.local.adapter';

package/transport/transport.local.d.ts

@@ -13,5 +13,11 @@ export declare class LocalTransporter implements Transporter {
     handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     ready(): Promise<void>;
     initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
+    /**
+     * Marks this transport as pre-initialized for session recreation.
+     * This is needed when recreating a transport from Redis because the
+     * original initialize request was processed by a different transport instance.
+     */
+    markAsInitialized(): void;
     destroy(reason: string): Promise<void>;
 }

package/transport/transport.registry.d.ts

@@ -47,9 +47,15 @@ export declare class TransportService {
      * @param type - Transport type
      * @param token - Authorization token
      * @param sessionId - Session ID
+     * @param options - Optional validation options
+     * @param options.clientFingerprint - Client fingerprint for additional validation
+     * @param options.warnOnFingerprintMismatch - If true, log warning on mismatch but still return session
      * @returns Stored session data if exists and token matches, undefined otherwise
      */
-    getStoredSession(type: TransportType, token: string, sessionId: string): Promise<StoredSession | undefined>;
+    getStoredSession(type: TransportType, token: string, sessionId: string, options?: {
+        clientFingerprint?: string;
+        warnOnFingerprintMismatch?: boolean;
+    }): Promise<StoredSession | undefined>;
     /**
      * Recreate a transport from stored session data.
      * Must be called with a valid response object to create the actual transport.

package/transport/transport.remote.d.ts

@@ -12,4 +12,5 @@ export declare class RemoteTransporter implements Transporter {
     initialize(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     handleRequest(_req: AuthenticatedServerRequest, _res: ServerResponse): Promise<void>;
     destroy(_reason?: string): Promise<void>;
+    markAsInitialized(): void;
 }

package/transport/transport.types.d.ts

@@ -40,6 +40,12 @@ export interface Transporter {
     handleRequest(req: AuthenticatedServerRequest, res: ServerResponse): Promise<void>;
     destroy(reason?: string): Promise<void>;
     ping(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Marks this transport as pre-initialized for session recreation.
+     * This is needed when recreating a transport from Redis because the
+     * original initialize request was processed by a different transport instance.
+     */
+    markAsInitialized(): void;
 }
 export interface TransportRegistryOptions {
     distributed?: boolean;