mcp-use 1.10.5 → 1.11.0-canary.10

package/dist/src/server/sessions/stores/redis.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Redis Session Store
+ *
+ * Production-ready session storage using Redis for persistence across restarts
+ * and distributed deployments.
+ *
+ * **Note:** Redis is an optional dependency. Install it with:
+ * ```bash
+ * npm install redis
+ * # or
+ * pnpm add redis
+ * ```
+ *
+ * If Redis is not installed, importing this module will throw an error at runtime
+ * when attempting to use RedisSessionStore. Use dynamic imports with error handling
+ * if you want to gracefully fall back when Redis is not available.
+ *
+ * Supports:
+ * - Session persistence across server restarts
+ * - Distributed session sharing (load balancing)
+ * - Automatic TTL-based expiration
+ * - Connection pooling and error handling
+ */
+import type { SessionStore } from "./index.js";
+import type { SessionMetadata } from "../session-manager.js";
+/**
+ * Check if Redis is available as an optional dependency
+ * @returns true if Redis can be imported, false otherwise
+ */
+export declare function isRedisAvailable(): Promise<boolean>;
+/**
+ * Redis client interface - compatible with node-redis v5+ and ioredis
+ */
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: any): Promise<string | null>;
+    setEx?(key: string, seconds: number, value: string): Promise<string | null>;
+    setex?(key: string, seconds: number, value: string): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+    exists(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    expire?(key: string, seconds: number): Promise<boolean | number>;
+    sAdd?(key: string, ...members: string[]): Promise<number>;
+    sRem?(key: string, ...members: string[]): Promise<number>;
+    sMembers?(key: string): Promise<string[]>;
+    publish?(channel: string, message: string): Promise<number>;
+    subscribe?(channel: string, callback: (message: string) => void): Promise<number | void>;
+    unsubscribe?(channel: string): Promise<number | void>;
+    quit(): Promise<string | "OK">;
+}
+/**
+ * Configuration for Redis session store
+ */
+export interface RedisSessionStoreConfig {
+    /**
+     * Redis client instance (node-redis or ioredis)
+     * Must be already connected
+     */
+    client: RedisClient;
+    /**
+     * Key prefix for session storage (default: "mcp:session:")
+     */
+    prefix?: string;
+    /**
+     * Default TTL in seconds for sessions (default: 3600 = 1 hour)
+     */
+    defaultTTL?: number;
+    /**
+     * Whether to serialize/deserialize session data (default: true)
+     */
+    serialize?: boolean;
+}
+/**
+ * Redis-backed session metadata storage
+ *
+ * Stores ONLY serializable metadata (client capabilities, log level, timestamps).
+ * For managing active SSE streams, use RedisStreamManager.
+ *
+ * Suitable for:
+ * - Production deployments requiring session persistence
+ * - Distributed/clustered applications
+ * - Load-balanced environments
+ * - Horizontal scaling scenarios
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer, RedisSessionStore, RedisStreamManager } from 'mcp-use/server';
+ * import { createClient } from 'redis';
+ *
+ * // Create Redis clients (two needed for Pub/Sub)
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * const pubSubRedis = redis.duplicate();
+ *
+ * await redis.connect();
+ * await pubSubRedis.connect();
+ *
+ * // Create stores
+ * const sessionStore = new RedisSessionStore({ client: redis });
+ * const streamManager = new RedisStreamManager({
+ *   client: redis,
+ *   pubSubClient: pubSubRedis
+ * });
+ *
+ * // Use with MCP server
+ * const server = new MCPServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   sessionStore,
+ *   streamManager
+ * });
+ * ```
+ */
+export declare class RedisSessionStore implements SessionStore {
+    private client;
+    private prefix;
+    private defaultTTL;
+    constructor(config: RedisSessionStoreConfig);
+    /**
+     * Get full Redis key for a session ID
+     */
+    private getKey;
+    /**
+     * Retrieve session metadata by ID
+     */
+    get(sessionId: string): Promise<SessionMetadata | null>;
+    /**
+     * Store or update session metadata
+     */
+    set(sessionId: string, data: SessionMetadata): Promise<void>;
+    /**
+     * Delete a session
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Check if a session exists
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * List all session IDs
+     *
+     * WARNING: Uses KEYS command which blocks Redis. For production systems with
+     * many sessions, consider using SCAN instead or maintaining a separate SET of
+     * active session IDs.
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Store session metadata with custom TTL (time-to-live)
+     */
+    setWithTTL(sessionId: string, data: SessionMetadata, ttlMs: number): Promise<void>;
+    /**
+     * Close Redis connection
+     * Should be called when shutting down the server
+     */
+    close(): Promise<void>;
+    /**
+     * Clear all sessions (useful for testing)
+     * WARNING: This will delete all sessions with the configured prefix
+     *
+     * NOTE: Uses KEYS command which blocks Redis. This is acceptable for testing
+     * but should be avoided in production with large datasets.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/src/server/sessions/stores/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../../../src/server/sessions/stores/redis.ts"],"names":[],"mappings":"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"}

package/dist/src/server/sessions/streams/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Stream Manager Interface
+ *
+ * Handles active SSE/streaming connections separately from session metadata storage.
+ * This separation enables notifications, sampling, and resource subscriptions to work
+ * across distributed servers when using external storage (Redis, Postgres).
+ *
+ * Inspired by tmcp's split architecture between StreamSessionManager and InfoSessionManager.
+ */
+/**
+ * Abstract interface for managing active SSE stream connections
+ *
+ * Unlike SessionStore (which stores serializable metadata), StreamManager handles
+ * ACTIVE connections that cannot be serialized (ReadableStreamDefaultController, WebSockets).
+ *
+ * Key responsibilities:
+ * - Manage active SSE stream controllers
+ * - Enable server-to-client push (notifications, sampling responses)
+ * - Support distributed notifications via message bus (Redis Pub/Sub, Postgres NOTIFY)
+ *
+ * @example
+ * ```typescript
+ * // Redis-backed stream manager for distributed deployments
+ * const streamManager = new RedisStreamManager({
+ *   url: process.env.REDIS_URL,
+ *   password: process.env.REDIS_PASSWORD
+ * });
+ *
+ * // When SSE connection is established
+ * await streamManager.create(sessionId, controller);
+ *
+ * // From any server instance - send notification to client
+ * await streamManager.send([sessionId], 'event: message\ndata: {...}\n\n');
+ * ```
+ */
+export interface StreamManager {
+    /**
+     * Register an active SSE stream controller for a session
+     *
+     * @param sessionId - The unique session identifier
+     * @param controller - ReadableStreamDefaultController for the SSE connection
+     */
+    create(sessionId: string, controller: ReadableStreamDefaultController): Promise<void>;
+    /**
+     * Send data to one or more active SSE streams
+     *
+     * In distributed deployments:
+     * - Local implementation: directly enqueues to in-memory controller
+     * - Redis implementation: publishes to Pub/Sub channel, any server with this session receives it
+     * - Postgres implementation: uses NOTIFY/LISTEN for cross-server messaging
+     *
+     * @param sessionIds - Array of session IDs to send to, or undefined for broadcast to all
+     * @param data - SSE-formatted data (e.g., 'event: message\ndata: {...}\n\n')
+     */
+    send(sessionIds: string[] | undefined, data: string): Promise<void>;
+    /**
+     * Remove an active SSE stream
+     *
+     * @param sessionId - The unique session identifier
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Check if an active SSE stream exists for a session
+     *
+     * @param sessionId - The unique session identifier
+     * @returns True if stream exists, false otherwise
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * Close all connections and cleanup resources
+     * Should be called on server shutdown
+     */
+    close?(): Promise<void>;
+}
+export * from "./memory.js";
+export * from "./redis.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/server/sessions/streams/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/server/sessions/streams/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,+BAA+B,GAC1C,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;OAIG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/src/server/sessions/streams/memory.d.ts

@@ -0,0 +1,76 @@
+/**
+ * In-Memory Stream Manager
+ *
+ * Default implementation for managing active SSE connections in a single server instance.
+ * Streams are stored in memory and lost on server restart.
+ *
+ * For distributed deployments, use RedisStreamManager or PostgresStreamManager.
+ */
+import type { StreamManager } from "./index.js";
+/**
+ * In-memory stream management for SSE connections
+ *
+ * Stores active ReadableStreamDefaultController instances for pushing
+ * server-initiated messages (notifications, sampling responses) to clients.
+ *
+ * Suitable for:
+ * - Single-instance deployments
+ * - Development environments
+ * - Non-distributed architectures
+ *
+ * Not suitable for:
+ * - Load-balanced deployments (streams on different servers)
+ * - Horizontal scaling
+ * - Session persistence requirements
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer, InMemoryStreamManager } from 'mcp-use/server';
+ *
+ * const server = new MCPServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   streamManager: new InMemoryStreamManager()
+ * });
+ * ```
+ */
+export declare class InMemoryStreamManager implements StreamManager {
+    /**
+     * Map of active SSE stream controllers
+     * Key: sessionId, Value: ReadableStreamDefaultController
+     */
+    private streams;
+    /**
+     * Text encoder for converting strings to Uint8Array
+     */
+    private textEncoder;
+    /**
+     * Register an active SSE stream controller
+     */
+    create(sessionId: string, controller: ReadableStreamDefaultController): Promise<void>;
+    /**
+     * Send data to active SSE streams
+     *
+     * Directly enqueues data to in-memory controllers.
+     * For distributed deployments, use RedisStreamManager instead.
+     */
+    send(sessionIds: string[] | undefined, data: string): Promise<void>;
+    /**
+     * Remove an active SSE stream
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Check if an active stream exists
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * Close all active streams
+     */
+    close(): Promise<void>;
+    /**
+     * Get the number of active streams
+     * Useful for monitoring
+     */
+    get size(): number;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/src/server/sessions/streams/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../../src/server/sessions/streams/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAsD;IAErE;;OAEG;IACH,OAAO,CAAC,WAAW,CAAqB;IAExC;;OAEG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,+BAA+B,GAC1C,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;OAKG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCzE;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe9C;;OAEG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/src/server/sessions/streams/redis.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Redis Stream Manager
+ *
+ * Manages active SSE connections using Redis Pub/Sub for distributed notifications.
+ * Enables server-to-client push notifications across multiple server instances.
+ *
+ * **Note:** Redis is an optional dependency. Install it with:
+ * ```bash
+ * npm install redis
+ * # or
+ * pnpm add redis
+ * ```
+ *
+ * If Redis is not installed, importing this module will throw an error at runtime
+ * when attempting to use RedisStreamManager. Use dynamic imports with error handling
+ * if you want to gracefully fall back when Redis is not available.
+ */
+import type { StreamManager } from "./index.js";
+import type { RedisClient } from "../stores/redis.js";
+/**
+ * Check if Redis is available as an optional dependency
+ * @returns true if Redis can be imported, false otherwise
+ */
+export declare function isRedisAvailable(): Promise<boolean>;
+/**
+ * Configuration for Redis stream manager
+ */
+export interface RedisStreamManagerConfig {
+    /**
+     * Redis client for Pub/Sub subscriptions
+     * Should be a separate client from the main Redis client
+     */
+    pubSubClient: RedisClient;
+    /**
+     * Redis client for checking session availability
+     * Can be shared with SessionStore
+     */
+    client: RedisClient;
+    /**
+     * Channel prefix for Pub/Sub (default: "mcp:stream:")
+     */
+    prefix?: string;
+    /**
+     * Heartbeat interval in seconds to keep sessions alive (default: 10)
+     * Redis keys expire after this interval * 2
+     */
+    heartbeatInterval?: number;
+}
+/**
+ * Redis-backed stream management for distributed SSE connections
+ *
+ * Enables notifications, sampling, and resource subscriptions to work across
+ * multiple server instances using Redis Pub/Sub.
+ *
+ * Architecture:
+ * 1. Client connects to Server A → creates SSE stream
+ * 2. Server A subscribes to Redis channel `mcp:stream:{sessionId}`
+ * 3. Client makes request → Load balancer routes to Server B
+ * 4. Server B sends notification → publishes to Redis channel
+ * 5. Server A receives Redis message → pushes to SSE stream → Client gets notification
+ *
+ * @example
+ * ```typescript
+ * import { MCPServer, RedisStreamManager } from 'mcp-use/server';
+ * import { createClient } from 'redis';
+ *
+ * // Create two separate Redis clients (required for Pub/Sub)
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * const pubSubRedis = redis.duplicate();
+ *
+ * await redis.connect();
+ * await pubSubRedis.connect();
+ *
+ * const streamManager = new RedisStreamManager({
+ *   client: redis,
+ *   pubSubClient: pubSubRedis
+ * });
+ *
+ * const server = new MCPServer({
+ *   name: 'my-server',
+ *   version: '1.0.0',
+ *   streamManager
+ * });
+ * ```
+ */
+export declare class RedisStreamManager implements StreamManager {
+    private pubSubClient;
+    private client;
+    private prefix;
+    private heartbeatInterval;
+    private textEncoder;
+    /**
+     * Map of local controllers (only on this server instance)
+     * Key: sessionId, Value: controller
+     */
+    private localControllers;
+    /**
+     * Map of heartbeat intervals for keeping sessions alive
+     * Key: sessionId, Value: interval timer
+     */
+    private heartbeats;
+    constructor(config: RedisStreamManagerConfig);
+    /**
+     * Get the Redis channel name for a session
+     */
+    private getChannel;
+    /**
+     * Get the Redis key for tracking active sessions
+     */
+    private getAvailableKey;
+    /**
+     * Get the Redis key for the active sessions SET
+     */
+    private getActiveSessionsKey;
+    /**
+     * Register an active SSE stream and subscribe to Redis channel
+     */
+    create(sessionId: string, controller: ReadableStreamDefaultController): Promise<void>;
+    /**
+     * Send data to sessions via Redis Pub/Sub
+     *
+     * This works across distributed servers - any server with an active
+     * SSE connection for the target session will receive and forward the message.
+     *
+     * Note: Uses the regular client (not pubSubClient) for publishing.
+     * In node-redis v5+, clients in subscriber mode cannot publish.
+     */
+    send(sessionIds: string[] | undefined, data: string): Promise<void>;
+    /**
+     * Remove an active SSE stream
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Check if a session has an active stream (on ANY server)
+     */
+    has(sessionId: string): Promise<boolean>;
+    /**
+     * Close all connections and cleanup
+     */
+    close(): Promise<void>;
+    /**
+     * Get count of active local streams on this server instance
+     */
+    get localSize(): number;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/src/server/sessions/streams/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../../../../src/server/sessions/streams/redis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC,CAOzD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,YAAY,EAAE,WAAW,CAAC;IAE1B;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,WAAW,CAAqB;IAExC;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAsD;IAE9E;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAqC;gBAE3C,MAAM,EAAE,wBAAwB;IAO5C;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,+BAA+B,GAC1C,OAAO,CAAC,IAAI,CAAC;IAwFhB;;;;;;;;OAQG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDzE;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+D9C;;OAEG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc9C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC5B;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/src/server/types/common.d.ts

@@ -66,41 +66,121 @@ export interface ServerConfig {
     allowedOrigins?: string[];
     sessionIdleTimeoutMs?: number;
     /**
-     * Automatically create a new session when a request is received with an invalid/expired session ID.
+     * @deprecated This option is deprecated and will be removed in a future version.
      *
-     * **Default: true** (enables compatibility with non-compliant clients like ChatGPT)
+     * The MCP specification requires clients to send a new InitializeRequest when they receive
+     * a 404 response for a stale session. Modern MCP clients
+     * handle this correctly. The server now follows the spec strictly by returning 404 for invalid
+     * session IDs.
      *
-     * When set to `true` (default), the server will automatically create a new session when it receives
-     * a request with an invalid or expired session ID. This allows clients to seamlessly
-     * reconnect after server restarts without needing to send a new `initialize` request.
+     * If you need session persistence across server restarts, use the `sessionStore` option
+     * with a persistent storage backend (Redis, PostgreSQL, etc.) instead.
      *
-     * **Note**: According to the [MCP protocol specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management),
-     * clients **MUST** start a new session by sending a new `InitializeRequest` when they receive
-     * HTTP 404 in response to a request containing an `MCP-Session-Id`. However, some clients (like
-     * ChatGPT) don't properly handle this and fail to reconnect. Setting this to `true` enables
-     * compatibility with these non-compliant clients.
+     * @see {@link sessionStore} for persistent session storage
+     * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+     */
+    autoCreateSessionOnInvalidId?: boolean;
+    /**
+     * Enable stateless mode (no session tracking)
+     * - Default: true for Deno (edge runtimes), false for Node.js
+     * - Set to true to force stateless mode
+     * - Set to false to force stateful mode (with sessions)
+     * - Auto-detected per-request based on client Accept header
+     *
+     * **Auto-detection (Node.js default):**
+     * - Client sends `Accept: application/json, text/event-stream` → Stateful mode
+     * - Client sends `Accept: application/json` only → Stateless mode
+     * - Explicit `stateless: true` → Always stateless (ignores Accept header)
      *
-     * When set to `false`, the server follows the MCP protocol specification strictly:
-     * it returns HTTP 404 Not Found for requests with invalid session IDs, requiring
-     * clients to explicitly send a new `initialize` request.
+     * This enables compatibility with k6, curl, and other HTTP-only clients
+     * while maintaining full SSE support for capable clients.
+     *
+     * Stateless mode is required for edge functions where instances don't persist.
+     * Stateful mode supports sessions, resumability, and notifications.
      *
      * @example
      * ```typescript
-     * // Default behavior (compatible with ChatGPT and other non-compliant clients)
+     * // Auto-detected (Deno = stateless, Node.js = stateful with Accept header detection)
      * const server = new MCPServer({
      *   name: 'my-server',
      *   version: '1.0.0'
      * });
      *
-     * // Use strict MCP spec behavior (requires compliant clients)
+     * // Force stateless mode (ignores Accept header)
      * const server = new MCPServer({
      *   name: 'my-server',
      *   version: '1.0.0',
-     *   autoCreateSessionOnInvalidId: false
+     *   stateless: true
      * });
      * ```
      */
-    autoCreateSessionOnInvalidId?: boolean;
+    stateless?: boolean;
+    /**
+     * Custom session metadata storage backend (default: in-memory)
+     *
+     * Stores serializable session metadata (client capabilities, log level, timestamps).
+     * For active SSE stream management, use `streamManager`.
+     *
+     * Allows pluggable session persistence for scenarios requiring:
+     * - Session metadata survival across server restarts
+     * - Distributed/clustered deployments
+     * - Horizontal scaling with session sharing
+     *
+     * Default: InMemorySessionStore (metadata lost on restart)
+     *
+     * @example
+     * ```typescript
+     * import { MCPServer, RedisSessionStore } from 'mcp-use/server';
+     * import { createClient } from 'redis';
+     *
+     * const redis = createClient({ url: process.env.REDIS_URL });
+     * await redis.connect();
+     *
+     * const server = new MCPServer({
+     *   name: 'my-server',
+     *   version: '1.0.0',
+     *   sessionStore: new RedisSessionStore({ client: redis })
+     * });
+     * ```
+     */
+    sessionStore?: import("../sessions/stores/index.js").SessionStore;
+    /**
+     * Custom stream manager for active SSE connections (default: in-memory)
+     *
+     * Manages active SSE stream controllers for server-to-client push notifications.
+     * Separate from sessionStore to enable distributed notifications via Redis Pub/Sub.
+     *
+     * Default: InMemoryStreamManager (streams on this server only)
+     *
+     * For distributed deployments where notifications/sampling need to work across
+     * multiple server instances, use RedisStreamManager with Redis Pub/Sub.
+     *
+     * @example
+     * ```typescript
+     * import { MCPServer, RedisStreamManager, RedisSessionStore } from 'mcp-use/server';
+     * import { createClient } from 'redis';
+     *
+     * // Create two Redis clients (Pub/Sub requires dedicated client)
+     * const redis = createClient({ url: process.env.REDIS_URL });
+     * const pubSubRedis = redis.duplicate();
+     *
+     * await redis.connect();
+     * await pubSubRedis.connect();
+     *
+     * const server = new MCPServer({
+     *   name: 'my-server',
+     *   version: '1.0.0',
+     *   sessionStore: new RedisSessionStore({ client: redis }),
+     *   streamManager: new RedisStreamManager({
+     *     client: redis,
+     *     pubSubClient: pubSubRedis
+     *   })
+     * });
+     *
+     * // Now notifications and sampling work across all server instances!
+     * ```
+     */
+    streamManager?: import("../sessions/streams/index.js").StreamManager;
     /**
      * OAuth authentication configuration
      *
@@ -153,6 +233,29 @@ export interface ServerConfig {
      * ```
      */
     oauth?: OAuthProvider;
+    /**
+     * Path to favicon file relative to public directory
+     *
+     * The favicon will be automatically included in all widget pages.
+     * Place your favicon file in the public/ directory and specify the relative path.
+     *
+     * @example
+     * ```typescript
+     * const server = new MCPServer({
+     *   name: 'my-server',
+     *   version: '1.0.0',
+     *   favicon: 'favicon.ico' // References public/favicon.ico
+     * });
+     *
+     * // For files in subdirectories
+     * const server = new MCPServer({
+     *   name: 'my-server',
+     *   version: '1.0.0',
+     *   favicon: 'icons/app-icon.png' // References public/icons/app-icon.png
+     * });
+     * ```
+     */
+    favicon?: string;
 }
 export interface InputDefinition {
     name: string;

package/dist/src/server/types/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;KACzC,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,OAAO,CAC5D,CAAC,CAAC,CAAC,CAAC,EACJ,SAAS,CACV;CACF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC3D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,UAAU,GACjD,0BAA0B,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/server/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;KACzC,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,OAAO,CAC5D,CAAC,CAAC,CAAC,CAAC,EACJ,SAAS,CACV;CACF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC3D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,UAAU,GACjD,0BAA0B,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAExB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAY,CAAC,EAAE,OAAO,6BAA6B,EAAE,YAAY,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,aAAa,CAAC,EAAE,OAAO,8BAA8B,EAAE,aAAa,CAAC;IACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkDG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}