@leanmcp/core 0.3.18 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
 /**
  * Simple configurable logger for LeanMCP SDK
@@ -58,6 +59,43 @@ declare class Logger {
 }
 declare const defaultLogger: Logger;
 
+/**
+ * Session data stored in persistent storage (e.g., DynamoDB)
+ */
+interface SessionData {
+    sessionId: string;
+    createdAt: Date;
+    updatedAt: Date;
+    ttl?: number;
+    data?: Record<string, any>;
+}
+/**
+ * Interface for session storage backends
+ * Implementations can use DynamoDB, Redis, or other persistent stores
+ */
+interface ISessionStore {
+    /**
+     * Check if a session exists in the store
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Create a new session in the store
+     */
+    createSession(sessionId: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Get session data from the store
+     */
+    getSession(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Update session data in the store
+     */
+    updateSession(sessionId: string, data: Partial<SessionData>): Promise<void>;
+    /**
+     * Delete a session from the store
+     */
+    deleteSession(sessionId: string): Promise<void>;
+}
+
 interface HTTPServerOptions {
     port?: number;
     cors?: boolean | {
@@ -71,6 +109,8 @@ interface HTTPServerOptions {
     dashboard?: boolean;
     /** OAuth/Auth configuration (MCP authorization spec) */
     auth?: HTTPServerAuthOptions;
+    /** Session store for stateful mode (enables session persistence across Lambda container recycling) */
+    sessionStore?: ISessionStore;
 }
 /**
  * OAuth/Auth configuration for MCP server
@@ -530,6 +570,127 @@ declare function createProtectedResourceMetadata(options: {
     documentationUrl?: string;
 }): ProtectedResourceMetadata;
 
+interface LeanMCPSessionProviderOptions {
+    tableName?: string;
+    region?: string;
+    ttlSeconds?: number;
+    logging?: boolean;
+    sessionStore?: ISessionStore;
+}
+/**
+ * Drop-in replacement for Map<string, StreamableHTTPServerTransport>
+ * Provides automatic session persistence for Lambda deployments
+ *
+ * @example
+ * // Before: const transports = new Map<string, StreamableHTTPServerTransport>();
+ * // After:  const sessions = new LeanMCPSessionProvider();
+ *
+ * // Then use sessions.get(), sessions.set(), sessions.getOrRecreate()
+ */
+declare class LeanMCPSessionProvider {
+    private transports;
+    private sessionStore;
+    constructor(options?: LeanMCPSessionProviderOptions);
+    /**
+     * Get transport from memory
+     */
+    get(sessionId: string): StreamableHTTPServerTransport | undefined;
+    /**
+     * Check if session exists (memory or DynamoDB)
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * Store transport and create session in DynamoDB
+     */
+    set(sessionId: string, transport: StreamableHTTPServerTransport): Promise<void>;
+    /**
+     * Delete transport and session
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Get or recreate transport for a session
+     * This is the key method for Lambda support - handles container recycling
+     *
+     * @param sessionId - Session ID to get or recreate
+     * @param serverFactory - Factory function to create fresh MCP server instances
+     * @param transportOptions - Optional callbacks for transport lifecycle events
+     * @returns Transport instance or null if session doesn't exist
+     */
+    getOrRecreate(sessionId: string, serverFactory: () => Server | Promise<Server>, transportOptions?: {
+        onsessioninitialized?: (sid: string) => void;
+        onclose?: () => void;
+    }): Promise<StreamableHTTPServerTransport | null>;
+    /**
+     * Get session data from DynamoDB
+     */
+    getSessionData(sessionId: string): Promise<Record<string, any> | null>;
+    /**
+     * Update session data in DynamoDB
+     */
+    updateSessionData(sessionId: string, data: Record<string, any>): Promise<void>;
+    /**
+     * Get number of in-memory transports
+     */
+    get size(): number;
+    /**
+     * Get all session IDs in memory
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Get all transports in memory
+     */
+    values(): IterableIterator<StreamableHTTPServerTransport>;
+    /**
+     * Iterate over all sessions in memory
+     */
+    entries(): IterableIterator<[string, StreamableHTTPServerTransport]>;
+    /**
+     * Clear all in-memory transports (does not affect DynamoDB)
+     */
+    clear(): void;
+}
+
+declare const DEFAULT_TABLE_NAME = "leanmcp-sessions";
+declare const DEFAULT_TTL_SECONDS = 86400;
+interface DynamoDBSessionStoreOptions {
+    tableName?: string;
+    region?: string;
+    ttlSeconds?: number;
+    logging?: boolean;
+}
+/**
+ * DynamoDB-backed session store for stateful Lambda MCP servers
+ * Automatically handles session persistence across Lambda container recycling
+ */
+declare class DynamoDBSessionStore implements ISessionStore {
+    private client;
+    private tableName;
+    private ttlSeconds;
+    private logger;
+    constructor(options?: DynamoDBSessionStoreOptions);
+    /**
+     * Check if a session exists in DynamoDB
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Create a new session in DynamoDB
+     */
+    createSession(sessionId: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Get session data from DynamoDB
+     */
+    getSession(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Update session data in DynamoDB
+     * Automatically refreshes TTL on each update
+     */
+    updateSession(sessionId: string, updates: Partial<SessionData>): Promise<void>;
+    /**
+     * Delete a session from DynamoDB
+     */
+    deleteSession(sessionId: string): Promise<void>;
+}
+
 interface MCPServerOptions {
     servicesDir: string;
     port?: number;
@@ -673,16 +834,10 @@ declare class MCPServer {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -693,8 +848,8 @@ declare class MCPServer {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -703,8 +858,8 @@ declare class MCPServer {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -734,16 +889,10 @@ declare class MCPServerRuntime {
         method: string;
         params?: {
             [x: string]: unknown;
-            task?: {
-                [x: string]: unknown;
-                ttl?: number | null | undefined;
-                pollInterval?: number | undefined;
-            } | undefined;
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -754,8 +903,8 @@ declare class MCPServerRuntime {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
                 "io.modelcontextprotocol/related-task"?: {
-                    [x: string]: unknown;
                     taskId: string;
                 } | undefined;
             } | undefined;
@@ -764,8 +913,8 @@ declare class MCPServerRuntime {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
             "io.modelcontextprotocol/related-task"?: {
-                [x: string]: unknown;
                 taskId: string;
             } | undefined;
         } | undefined;
@@ -779,4 +928,4 @@ declare class MCPServerRuntime {
  */
 declare function startMCPServer(options: MCPServerOptions): Promise<MCPServerRuntime>;
 
-export { Auth, type AuthErrorOptions, type AuthErrorResult, type AuthOptions, Deprecated, type HTTPServerAuthOptions, type HTTPServerInput, type HTTPServerOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, type ProtectedResourceMetadata, Render, Resource, type ResourceOptions, SchemaConstraint, type SecurityScheme, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createAuthError, createHTTPServer, createProtectedResourceMetadata, defaultLogger, extractBearerToken, getDecoratedMethods, getMethodMetadata, isAuthError, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };
+export { Auth, type AuthErrorOptions, type AuthErrorResult, type AuthOptions, DEFAULT_TABLE_NAME, DEFAULT_TTL_SECONDS, Deprecated, DynamoDBSessionStore, type HTTPServerAuthOptions, type HTTPServerInput, type HTTPServerOptions, type ISessionStore, LeanMCPSessionProvider, type LeanMCPSessionProviderOptions, LogLevel, type LogPayload, Logger, type LoggerHandler, type LoggerOptions, MCPServer, type MCPServerConstructorOptions, type MCPServerFactory, type MCPServerOptions, MCPServerRuntime, Optional, Prompt, type PromptOptions, type ProtectedResourceMetadata, Render, Resource, type ResourceOptions, SchemaConstraint, type SecurityScheme, type SessionData, Tool, type ToolOptions, UI, UserEnvs, classToJsonSchema, classToJsonSchemaWithConstraints, createAuthError, createHTTPServer, createProtectedResourceMetadata, defaultLogger, extractBearerToken, getDecoratedMethods, getMethodMetadata, isAuthError, startMCPServer, validateNonEmpty, validatePath, validatePort, validateServiceName, validateUrl };