@mcp-ts/sdk 1.3.5 → 1.3.7

package/src/server/mcp/multi-session-client.ts

@@ -3,6 +3,11 @@
 import { MCPClient } from './oauth-client.js';
 import { storage, type SessionData } from '../storage/index.js';
 
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 1000;
+const CONNECTION_BATCH_SIZE = 5;
+
 /**
  * Manages multiple MCP connections for a single user identity.
  * Allows aggregating tools from all connected servers.
@@ -26,57 +31,155 @@ export interface MultiSessionOptions {
 }
 
 /**
- * Manages multiple MCP connections for a single user identity.
- * Allows aggregating tools from all connected servers.
+ * Manages multiple MCP client connections for a single user identity.
+ *
+ * On a traditional long-running server, you can cache this instance per user
+ * so the connections stay alive between requests. On serverless, a new instance
+ * will be created per invocation, but the underlying session data is always
+ * read from the storage backend so nothing is lost between calls.
  */
 export class MultiSessionClient {
     private clients: MCPClient[] = [];
     private identity: string;
     private options: MultiSessionOptions;
 
+    /**
+     * Creates a new MultiSessionClient for the given user identity.
+     *
+     * @param identity - A unique string identifying the user (e.g. user ID or email).
+     * @param options  - Optional tuning for connection timeout, retry count, and retry delay.
+     *                   Falls back to sensible defaults if not provided.
+     */
     constructor(identity: string, options: MultiSessionOptions = {}) {
         this.identity = identity;
         this.options = {
-            timeout: 15000,
-            maxRetries: 2,
-            retryDelay: 1000,
+            timeout: DEFAULT_TIMEOUT_MS,
+            maxRetries: DEFAULT_MAX_RETRIES,
+            retryDelay: DEFAULT_RETRY_DELAY_MS,
             ...options
         };
     }
 
+    /**
+     * Fetches all sessions for this identity from storage and returns only the
+     * ones that are ready to connect.
+     *
+     * A session is considered connectable when:
+     * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
+     * - Its `active` flag is not explicitly `false` — sessions with `active: false` are
+     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     *   and let the OAuth flow complete separately before we try to reconnect them.
+     *
+     * Note: Sessions where `active` is `undefined` (legacy records) are included
+     * for backwards compatibility.
+     */
     private async getActiveSessions(): Promise<SessionData[]> {
         const sessions = await storage.getIdentitySessionsData(this.identity);
-        console.log(`[MultiSessionClient] All sessions for ${this.identity}:`,
-            sessions.map(s => ({ sessionId: s.sessionId, serverId: s.serverId }))
+        const valid = sessions.filter(s =>
+            s.serverId &&
+            s.serverUrl &&
+            s.callbackUrl &&
+            s.active !== false  // exclude OAuth-pending / failed sessions
         );
-        const valid = sessions.filter(s => s.serverId && s.serverUrl && s.callbackUrl);
-        console.log(`[MultiSessionClient] Filtered valid sessions:`, valid.length);
         return valid;
     }
 
+    /**
+     * Connects to a list of sessions in controlled batches of `CONNECTION_BATCH_SIZE`.
+     *
+     * Batching prevents overwhelming the event loop or external servers when a user
+     * has many active MCP sessions (e.g. 20+ servers). Within each batch, sessions
+     * are connected concurrently using `Promise.all` for speed.
+     */
     private async connectInBatches(sessions: SessionData[]): Promise<void> {
-        const BATCH_SIZE = 5;
-        for (let i = 0; i < sessions.length; i += BATCH_SIZE) {
-            const batch = sessions.slice(i, i + BATCH_SIZE);
+        for (let i = 0; i < sessions.length; i += CONNECTION_BATCH_SIZE) {
+            const batch = sessions.slice(i, i + CONNECTION_BATCH_SIZE);
             await Promise.all(batch.map(session => this.connectSession(session)));
         }
     }
 
+    private connectionPromises = new Map<string, Promise<void>>();
+
+    /**
+     * Connects a single session, with built-in deduplication to prevent race conditions.
+     *
+     * - If a client for this session already exists and is connected, returns immediately.
+     * - If a connection attempt for this session is already in-flight (e.g. from a
+     *   concurrent call), it joins the existing promise instead of starting a new one.
+     *   This is the key concurrency lock — the `connectionPromises` map acts as a
+     *   per-session mutex so we never spin up two physical connections for the same session.
+     * - On completion (success or failure), the promise is cleaned up from the map.
+     */
     private async connectSession(session: SessionData): Promise<void> {
         const existingClient = this.clients.find(c => c.getSessionId() === session.sessionId);
         if (existingClient?.isConnected()) {
             return;
         }
 
-        const maxRetries = this.options.maxRetries ?? 2;
-        const retryDelay = this.options.retryDelay ?? 1000;
+        // Avoid concurrent connection attempts for the same session
+        if (this.connectionPromises.has(session.sessionId)) {
+            return this.connectionPromises.get(session.sessionId)!;
+        }
+
+        const connectPromise = this.establishConnectionWithRetries(session);
+
+        this.connectionPromises.set(session.sessionId, connectPromise);
+
+        try {
+            await connectPromise;
+        } finally {
+            this.connectionPromises.delete(session.sessionId);
+        }
+    }
+
+    /**
+     * The core connection loop for a single session.
+     *
+     * Attempts to establish a physical MCP connection, retrying up to `maxRetries` times
+     * if the connection fails. Each attempt:
+     * 1. Creates a fresh `MCPClient` instance from the session data.
+     * 2. Races the connect call against a timeout promise — if the server doesn't respond
+     *    within `timeoutMs`, the attempt is aborted and counted as a failure.
+     * 3. On success, replaces any stale client entry for this session in the `clients` array.
+     * 4. On failure, waits `retryDelay` ms before the next attempt.
+     *
+     * If all attempts are exhausted, logs an error and returns silently (does not throw),
+     * so a single bad server doesn't block the rest of the batch from connecting.
+     */
+    private async establishConnectionWithRetries(session: SessionData): Promise<void> {
+        const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
         let lastError: unknown;
 
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                const client = await this.createAndConnectClient(session);
+                const client = new MCPClient({
+                    identity: this.identity,
+                    sessionId: session.sessionId,
+                    serverId: session.serverId,
+                    serverUrl: session.serverUrl,
+                    callbackUrl: session.callbackUrl,
+                    serverName: session.serverName,
+                    transportType: session.transportType,
+                    headers: session.headers,
+                });
+
+                const timeoutMs = this.options.timeout ?? DEFAULT_TIMEOUT_MS;
+                let timeoutTimer: ReturnType<typeof setTimeout>;
+                const timeoutPromise = new Promise<never>((_, reject) => {
+                    timeoutTimer = setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
+                });
+
+                try {
+                    await Promise.race([client.connect(), timeoutPromise]);
+                } finally {
+                    clearTimeout(timeoutTimer!);
+                }
+
+                // Always replace the disconnected client entry
+                this.clients = this.clients.filter(c => c.getSessionId() !== session.sessionId);
                 this.clients.push(client);
-                return;
+                return; // successfully connected
             } catch (error) {
                 lastError = error;
                 if (attempt < maxRetries) {
@@ -88,41 +191,34 @@ export class MultiSessionClient {
         console.error(`[MultiSessionClient] Failed to connect to session ${session.sessionId} after ${maxRetries + 1} attempts:`, lastError);
     }
 
-    private async createAndConnectClient(session: SessionData): Promise<MCPClient> {
-        const client = new MCPClient({
-            identity: this.identity,
-            sessionId: session.sessionId,
-            serverId: session.serverId,
-            serverUrl: session.serverUrl,
-            callbackUrl: session.callbackUrl,
-            serverName: session.serverName,
-            transportType: session.transportType,
-            headers: session.headers,
-        });
-
-        const timeoutMs = this.options.timeout ?? 15000;
-        const timeoutPromise = new Promise<never>((_, reject) => {
-            setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs}ms`)), timeoutMs);
-        });
-
-        await Promise.race([client.connect(), timeoutPromise]);
-        return client;
-    }
-
+    /**
+     * The main entry point. Fetches all active sessions for this identity from
+     * storage and establishes connections to all of them in batches.
+     *
+     * Call this once after creating the client. On traditional servers, you can
+     * cache the `MultiSessionClient` instance after calling `connect()` to avoid
+     * re-fetching and re-connecting on every request.
+     */
     async connect(): Promise<void> {
         const sessions = await this.getActiveSessions();
         await this.connectInBatches(sessions);
     }
 
     /**
-     * Returns the array of currently connected clients.
+     * Returns all currently connected `MCPClient` instances.
+     *
+     * Use this to enumerate available tools across all connected servers,
+     * or to route a tool call to the right client by `serverId`.
      */
     getClients(): MCPClient[] {
         return this.clients;
     }
 
     /**
-     * Disconnects all clients.
+     * Gracefully disconnects all active MCP clients and clears the internal client list.
+     *
+     * Call this during server shutdown or when a user logs out to free up
+     * underlying transport resources (SSE streams, HTTP connections, etc.).
      */
     disconnect(): void {
         this.clients.forEach((client) => client.disconnect());

package/src/server/storage/file-backend.ts

@@ -1,20 +1,7 @@
-
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import { customAlphabet } from 'nanoid';
-import { StorageBackend, SessionData, SetClientOptions } from './types';
-
-// first char: letters only (required by OpenAI)
-const firstChar = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-    1
-);
-
-// remaining chars: alphanumeric
-const rest = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
-    11
-);
+import { StorageBackend, SessionData, SetClientOptions } from './types.js';
+import { generateSessionId } from '../../shared/utils.js';
 
 /**
  * File system implementation of StorageBackend
@@ -65,6 +52,7 @@ export class FileStorageBackend implements StorageBackend {
         }
 
         this.initialized = true;
+        console.log(`[mcp-ts][Storage] File: ✓ storage directory at ${path.dirname(this.filePath)} verified.`);
     }
 
     private async ensureInitialized() {
@@ -82,7 +70,7 @@ export class FileStorageBackend implements StorageBackend {
     }
 
     generateSessionId(): string {
-        return firstChar() + rest();
+        return generateSessionId();
     }
 
     async createSession(session: SessionData, ttl?: number): Promise<void> {

package/src/server/storage/index.ts

@@ -2,12 +2,18 @@
 import { RedisStorageBackend } from './redis-backend';
 import { MemoryStorageBackend } from './memory-backend';
 import { FileStorageBackend } from './file-backend';
-import { SqliteStorage } from './sqlite-backend';
-import type { StorageBackend } from './types';
+import { SqliteStorage } from './sqlite-backend.js';
+import { SupabaseStorageBackend } from './supabase-backend.js';
+import type { StorageBackend } from './types.js';
 
 // Re-export types
-export * from './types';
-export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage };
+export * from './types.js';
+export { generateSessionId } from '../../shared/utils.js';
+export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage, SupabaseStorageBackend };
+
+export function createSupabaseStorageBackend(client: any): SupabaseStorageBackend {
+    return new SupabaseStorageBackend(client);
+}
 
 let storageInstance: StorageBackend | null = null;
 let storagePromise: Promise<StorageBackend> | null = null;
@@ -30,33 +36,53 @@ async function createStorage(): Promise<StorageBackend> {
         try {
             const { getRedis } = await import('./redis.js');
             const redis = await getRedis();
-            console.log('[Storage] Using Redis storage (Explicit)');
-            return new RedisStorageBackend(redis);
+            console.log('[mcp-ts][Storage] Explicit selection: "redis"');
+            return await initializeStorage(new RedisStorageBackend(redis));
         } catch (error: any) {
-            console.error('[Storage] Failed to initialize Redis:', error.message);
-            console.log('[Storage] Falling back to In-Memory storage');
-            return new MemoryStorageBackend();
+            console.error('[mcp-ts][Storage] Failed to initialize Redis:', error.message);
+            console.log('[mcp-ts][Storage] Falling back to In-Memory storage');
+            return await initializeStorage(new MemoryStorageBackend());
         }
     }
 
     if (type === 'file') {
         const filePath = process.env.MCP_TS_STORAGE_FILE;
-        if (!filePath) {
-            console.warn('[Storage] MCP_TS_STORAGE_TYPE is "file" but MCP_TS_STORAGE_FILE is missing');
-        }
-        console.log(`[Storage] Using File storage (${filePath}) (Explicit)`);
+        console.log(`[mcp-ts][Storage] Explicit selection: "file" (${filePath || 'default'})`);
         return await initializeStorage(new FileStorageBackend({ path: filePath }));
     }
 
     if (type === 'sqlite') {
         const dbPath = process.env.MCP_TS_STORAGE_SQLITE_PATH;
-        console.log(`[Storage] Using SQLite storage (${dbPath || 'default'}) (Explicit)`);
+        console.log(`[mcp-ts][Storage] Explicit selection: "sqlite" (${dbPath || 'default'})`);
         return await initializeStorage(new SqliteStorage({ path: dbPath }));
     }
 
+    if (type === 'supabase') {
+        const url = process.env.SUPABASE_URL;
+        const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY;
+        
+        if (!url || !key) {
+            console.warn('[mcp-ts][Storage] Explicit selection "supabase" requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.');
+        } else {
+            if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️  Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+            }
+            try {
+                const { createClient } = await import('@supabase/supabase-js');
+                const client = createClient(url, key);
+                console.log('[mcp-ts][Storage] Explicit selection: "supabase"');
+                return await initializeStorage(new SupabaseStorageBackend(client as any));
+            } catch (error: any) {
+                console.error('[mcp-ts][Storage] Failed to initialize Supabase:', error.message);
+                console.log('[mcp-ts][Storage] Falling back to In-Memory storage');
+                return await initializeStorage(new MemoryStorageBackend());
+            }
+        }
+    }
+
     if (type === 'memory') {
-        console.log('[Storage] Using In-Memory storage (Explicit)');
-        return new MemoryStorageBackend();
+        console.log('[mcp-ts][Storage] Explicit selection: "memory"');
+        return await initializeStorage(new MemoryStorageBackend());
     }
 
     // Automatic inference (Fallback)
@@ -64,27 +90,44 @@ async function createStorage(): Promise<StorageBackend> {
         try {
             const { getRedis } = await import('./redis.js');
             const redis = await getRedis();
-            console.log('[Storage] Auto-detected REDIS_URL. Using Redis storage.');
-            return new RedisStorageBackend(redis);
+            console.log('[mcp-ts][Storage] Auto-detection: "redis" (via REDIS_URL)');
+            return await initializeStorage(new RedisStorageBackend(redis));
         } catch (error: any) {
-            console.error('[Storage] Redis auto-detection failed:', error.message);
-            console.log('[Storage] Falling back to In-Memory storage');
-            return new MemoryStorageBackend();
+            console.error('[mcp-ts][Storage] Redis auto-detection failed:', error.message);
+            console.log('[mcp-ts][Storage] Falling back to next available backend');
         }
     }
 
     if (process.env.MCP_TS_STORAGE_FILE) {
-        console.log(`[Storage] Auto-detected MCP_TS_STORAGE_FILE. Using File storage (${process.env.MCP_TS_STORAGE_FILE}).`);
+        console.log(`[mcp-ts][Storage] Auto-detection: "file" (${process.env.MCP_TS_STORAGE_FILE})`);
         return await initializeStorage(new FileStorageBackend({ path: process.env.MCP_TS_STORAGE_FILE }));
     }
 
     if (process.env.MCP_TS_STORAGE_SQLITE_PATH) {
-        console.log(`[Storage] Auto-detected MCP_TS_STORAGE_SQLITE_PATH. Using SQLite storage (${process.env.MCP_TS_STORAGE_SQLITE_PATH}).`);
+        console.log(`[mcp-ts][Storage] Auto-detection: "sqlite" (${process.env.MCP_TS_STORAGE_SQLITE_PATH})`);
         return await initializeStorage(new SqliteStorage({ path: process.env.MCP_TS_STORAGE_SQLITE_PATH }));
     }
 
-    console.log('[Storage] No storage configured. Using In-Memory storage (Default).');
-    return new MemoryStorageBackend();
+    if (process.env.SUPABASE_URL && (process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY)) {
+        try {
+            const { createClient } = await import('@supabase/supabase-js');
+            const url = process.env.SUPABASE_URL;
+            const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY!;
+            
+            if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️ Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+            }
+
+            const client = createClient(url, key);
+            console.log('[mcp-ts][Storage] Auto-detection: "supabase" (via SUPABASE_URL)');
+            return await initializeStorage(new SupabaseStorageBackend(client as any));
+        } catch (error: any) {
+            console.error('[mcp-ts][Storage] Supabase auto-detection failed:', error.message);
+        }
+    }
+
+    console.log('[mcp-ts][Storage] Defaulting to: "memory"');
+    return await initializeStorage(new MemoryStorageBackend());
 }
 
 async function getStorage(): Promise<StorageBackend> {

package/src/server/storage/memory-backend.ts

@@ -1,18 +1,5 @@
-
-import { customAlphabet } from 'nanoid';
-import { StorageBackend, SessionData, SetClientOptions } from './types';
-
-// first char: letters only (required by OpenAI)
-const firstChar = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-    1
-);
-
-// remaining chars: alphanumeric
-const rest = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
-    11
-);
+import { StorageBackend, SessionData, SetClientOptions } from './types.js';
+import { generateSessionId } from '../../shared/utils.js';
 
 /**
  * In-memory implementation of StorageBackend
@@ -27,12 +14,16 @@ export class MemoryStorageBackend implements StorageBackend {
 
     constructor() { }
 
+    async init(): Promise<void> {
+        console.log('[mcp-ts][Storage] Memory: ✓ internal memory store active.');
+    }
+
     private getSessionKey(identity: string, sessionId: string): string {
         return `${identity}:${sessionId}`;
     }
 
     generateSessionId(): string {
-        return firstChar() + rest();
+        return generateSessionId();
     }
 
     async createSession(session: SessionData, ttl?: number): Promise<void> {

package/src/server/storage/redis-backend.ts

@@ -1,20 +1,7 @@
-
 import type { Redis } from 'ioredis';
-import { customAlphabet } from 'nanoid';
-import { StorageBackend, SessionData } from './types';
+import { StorageBackend, SessionData } from './types.js';
 import { SESSION_TTL_SECONDS } from '../../shared/constants.js';
-
-/** first char: letters only (required by OpenAI) */
-const firstChar = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-    1
-);
-
-/** remaining chars: alphanumeric */
-const rest = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
-    11
-);
+import { generateSessionId } from '../../shared/utils.js';
 
 /**
  * Redis implementation of StorageBackend
@@ -26,6 +13,15 @@ export class RedisStorageBackend implements StorageBackend {
     private readonly IDENTITY_KEY_SUFFIX = ':sessions';
 
     constructor(private redis: Redis) { }
+    
+    async init(): Promise<void> {
+        try {
+            await this.redis.ping();
+            console.log('[mcp-ts][Storage] Redis: ✓ Connected to server.');
+        } catch (error: any) {
+            throw new Error(`[RedisStorage] Failed to connect to Redis: ${error.message}`);
+        }
+    }
 
     /**
      * Generates Redis key for a specific session
@@ -79,7 +75,7 @@ export class RedisStorageBackend implements StorageBackend {
     }
 
     generateSessionId(): string {
-        return firstChar() + rest();
+        return generateSessionId();
     }
 
     async createSession(session: SessionData, ttl?: number): Promise<void> {

package/src/server/storage/sqlite-backend.ts

@@ -2,6 +2,7 @@ import type { Database } from 'better-sqlite3';
 import { StorageBackend, SessionData } from './types.js'; // Ensure .js extension
 import * as fs from 'fs';
 import * as path from 'path';
+import { generateSessionId } from '../../shared/utils.js';
 
 export interface SqliteStorageOptions {
     path?: string;
@@ -44,6 +45,7 @@ export class SqliteStorage implements StorageBackend {
             `);
 
             this.initialized = true;
+            console.log(`[mcp-ts][Storage] SQLite: ✓ database at ${this.dbPath} verified.`);
         } catch (error: any) {
             if (error.code === 'MODULE_NOT_FOUND' || error.message?.includes('better-sqlite3')) {
                 throw new Error(
@@ -61,12 +63,7 @@ export class SqliteStorage implements StorageBackend {
     }
 
     generateSessionId(): string {
-        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-        let result = '';
-        for (let i = 0; i < 32; i++) {
-            result += chars.charAt(Math.floor(Math.random() * chars.length));
-        }
-        return result;
+        return generateSessionId();
     }
 
     async createSession(session: SessionData, ttl?: number): Promise<void> {