@mcp-ts/sdk 1.3.6 → 1.3.7

package/src/adapters/mastra-adapter.ts

@@ -1,126 +1,126 @@
-import { MCPClient } from '../server/mcp/oauth-client';
-import { MultiSessionClient } from '../server/mcp/multi-session-client';
-import type { z } from 'zod';
-
-export interface MastraAdapterOptions {
-    /** 
-     * Prefix for tool names to avoid collision with other tools.
-     * Defaults to the client's serverId.
-     */
-    prefix?: string;
-}
-
-/**
- * Interface definition for a Mastra tool since we might not have the SDK installed.
- * Based on Mastra documentation.
- */
-export interface MastraTool {
-    id: string;
-    description: string;
-    inputSchema: z.ZodType<any>;
-    execute: (args: any) => Promise<any>;
-}
-
-/**
- * Adapter to use MCP tools within Mastra agents.
- */
-export class MastraAdapter {
-    private z: typeof z | undefined;
-
-    constructor(
-        private client: MCPClient | MultiSessionClient,
-        private options: MastraAdapterOptions = {}
-    ) { }
-
-    /**
-     * Lazy-loads Zod dependency
-     */
-    private async ensureZod() {
-        if (!this.z) {
-            try {
-                const zod = await import('zod');
-                this.z = zod.z;
-            } catch (error) {
-                throw new Error(
-                    'zod is not installed. Install with:\n' +
-                    '  npm install zod'
-                );
-            }
-        }
-    }
-
-
-
-    private async transformTools(client: MCPClient): Promise<Record<string, MastraTool>> {
-        if (!client.isConnected()) {
-            return {};
-        }
-
-        await this.ensureZod();
-
-        const result = await client.listTools();
-        const prefix = this.options.prefix ?? client.getServerId() ?? 'mcp';
-        const tools: Record<string, MastraTool> = {};
-
-        for (const tool of result.tools) {
-            const toolName = `${prefix}_${tool.name}`;
-
-            // In a real implementation, you would use a library like 'json-schema-to-zod'
-            const schema = this.jsonSchemaToZod(tool.inputSchema);
-
-            tools[toolName] = {
-                id: toolName,
-                description: tool.description || `Tool ${tool.name}`,
-                inputSchema: schema,
-                execute: async (args: any) => {
-                    return await client.callTool(tool.name, args);
-                },
-            };
-        }
-
-        return tools;
-    }
-
-    private jsonSchemaToZod(schema: any): z.ZodType<any> {
-        try {
-            const { parseSchema } = require('json-schema-to-zod');
-            const zodSchemaString = parseSchema(schema);
-            // eslint-disable-next-line
-            return new Function('z', 'return ' + zodSchemaString)(this.z);
-        } catch (error) {
-            // Fallback: Accept any object if conversion fails
-            console.warn('[MastraAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
-            return this.z!.record(this.z!.any()).optional().describe("Dynamic Input");
-        }
-    }
-
-    /**
-     * Fetches tools from the MCP server and converts them to Mastra tools.
-     */
-    async getTools(): Promise<Record<string, MastraTool>> {
-        // Use duck typing instead of instanceof to handle module bundling issues
-        const isMultiSession = typeof (this.client as any).getClients === 'function';
-        const clients = isMultiSession
-            ? (this.client as MultiSessionClient).getClients()
-            : [this.client as MCPClient];
-
-        const results = await Promise.all(
-            clients.map(async (client) => {
-                try {
-                    return await this.transformTools(client);
-                } catch (error) {
-                    console.error(`[MastraAdapter] Failed to fetch tools from ${client.getServerId()}:`, error);
-                    return {};
-                }
-            })
-        );
-        return results.reduce((acc, tools) => ({ ...acc, ...tools }), {});
-    }
-
-    /**
-     * Convenience static method to fetch tools in a single line.
-     */
-    static async getTools(client: MCPClient | MultiSessionClient, options: MastraAdapterOptions = {}): Promise<Record<string, MastraTool>> {
-        return new MastraAdapter(client, options).getTools();
-    }
-}
+import { MCPClient } from '../server/mcp/oauth-client';
+import { MultiSessionClient } from '../server/mcp/multi-session-client';
+import type { z } from 'zod';
+
+export interface MastraAdapterOptions {
+    /** 
+     * Prefix for tool names to avoid collision with other tools.
+     * Defaults to the client's serverId.
+     */
+    prefix?: string;
+}
+
+/**
+ * Interface definition for a Mastra tool since we might not have the SDK installed.
+ * Based on Mastra documentation.
+ */
+export interface MastraTool {
+    id: string;
+    description: string;
+    inputSchema: z.ZodType<any>;
+    execute: (args: any) => Promise<any>;
+}
+
+/**
+ * Adapter to use MCP tools within Mastra agents.
+ */
+export class MastraAdapter {
+    private z: typeof z | undefined;
+
+    constructor(
+        private client: MCPClient | MultiSessionClient,
+        private options: MastraAdapterOptions = {}
+    ) { }
+
+    /**
+     * Lazy-loads Zod dependency
+     */
+    private async ensureZod() {
+        if (!this.z) {
+            try {
+                const zod = await import('zod');
+                this.z = zod.z;
+            } catch (error) {
+                throw new Error(
+                    'zod is not installed. Install with:\n' +
+                    '  npm install zod'
+                );
+            }
+        }
+    }
+
+
+
+    private async transformTools(client: MCPClient): Promise<Record<string, MastraTool>> {
+        if (!client.isConnected()) {
+            return {};
+        }
+
+        await this.ensureZod();
+
+        const result = await client.listTools();
+        const prefix = this.options.prefix ?? client.getServerId()?.replace(/-/g, '').substring(0, 8) ?? 'mcp';
+        const tools: Record<string, MastraTool> = {};
+
+        for (const tool of result.tools) {
+            const toolName = `${prefix}_${tool.name}`;
+
+            // In a real implementation, you would use a library like 'json-schema-to-zod'
+            const schema = this.jsonSchemaToZod(tool.inputSchema);
+
+            tools[toolName] = {
+                id: toolName,
+                description: tool.description || `Tool ${tool.name}`,
+                inputSchema: schema,
+                execute: async (args: any) => {
+                    return await client.callTool(tool.name, args);
+                },
+            };
+        }
+
+        return tools;
+    }
+
+    private jsonSchemaToZod(schema: any): z.ZodType<any> {
+        try {
+            const { parseSchema } = require('json-schema-to-zod');
+            const zodSchemaString = parseSchema(schema);
+            // eslint-disable-next-line
+            return new Function('z', 'return ' + zodSchemaString)(this.z);
+        } catch (error) {
+            // Fallback: Accept any object if conversion fails
+            console.warn('[MastraAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
+            return this.z!.record(this.z!.any()).optional().describe("Dynamic Input");
+        }
+    }
+
+    /**
+     * Fetches tools from the MCP server and converts them to Mastra tools.
+     */
+    async getTools(): Promise<Record<string, MastraTool>> {
+        // Use duck typing instead of instanceof to handle module bundling issues
+        const isMultiSession = typeof (this.client as any).getClients === 'function';
+        const clients = isMultiSession
+            ? (this.client as MultiSessionClient).getClients()
+            : [this.client as MCPClient];
+
+        const results = await Promise.all(
+            clients.map(async (client) => {
+                try {
+                    return await this.transformTools(client);
+                } catch (error) {
+                    console.error(`[MastraAdapter] Failed to fetch tools from ${client.getServerId()}:`, error);
+                    return {};
+                }
+            })
+        );
+        return results.reduce((acc, tools) => ({ ...acc, ...tools }), {});
+    }
+
+    /**
+     * Convenience static method to fetch tools in a single line.
+     */
+    static async getTools(client: MCPClient | MultiSessionClient, options: MastraAdapterOptions = {}): Promise<Record<string, MastraTool>> {
+        return new MastraAdapter(client, options).getTools();
+    }
+}

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
@@ -83,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

@@ -8,6 +8,7 @@ import type { StorageBackend } from './types.js';
 
 // Re-export types
 export * from './types.js';
+export { generateSessionId } from '../../shared/utils.js';
 export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage, SupabaseStorageBackend };
 
 export function createSupabaseStorageBackend(client: any): SupabaseStorageBackend {

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
@@ -36,7 +23,7 @@ export class MemoryStorageBackend implements StorageBackend {
     }
 
     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
@@ -88,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;
@@ -62,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> {

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

@@ -1,6 +1,7 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { StorageBackend, SessionData } from './types.js';
 import { SESSION_TTL_SECONDS } from '../../shared/constants.js';
+import { generateSessionId } from '../../shared/utils.js';
 
 export class SupabaseStorageBackend implements StorageBackend {
     private readonly DEFAULT_TTL = SESSION_TTL_SECONDS;
@@ -29,7 +30,7 @@ export class SupabaseStorageBackend implements StorageBackend {
     }
 
     generateSessionId(): string {
-        return crypto.randomUUID();
+        return generateSessionId();
     }
 
     private mapRowToSessionData(row: any): SessionData {

package/src/shared/utils.ts

@@ -1,3 +1,17 @@
+import { customAlphabet } from 'nanoid';
+
+/** first char: letters only (required by OpenAI) */
+const firstChar = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    1
+);
+
+/** remaining chars: alphanumeric */
+const rest = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
+    11
+);
+
 /**
  * Sanitize server name to create a valid server label
  * Must start with a letter and contain only letters, digits, '-' and '_'
@@ -14,3 +28,11 @@ export function sanitizeServerLabel(name: string): string {
 
   return sanitized;
 }
+
+/**
+ * Generates a standard 12-character session ID compliant with external tool restrictions.
+ * First character is always a letter.
+ */
+export function generateSessionId(): string {
+    return firstChar() + rest();
+}