@mcp-ts/sdk 2.4.2 → 2.4.4

package/dist/{tool-router-CbG4Tum6.d.mts → tool-router-CGs3IDOJ.d.mts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { A as ToolClientProvider, T as ToolClient } from './types-CjczQwNX.mjs';
+import { A as ToolClientProvider, T as ToolClient } from './types-Bf-7GOLW.mjs';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{tool-router-ChIhPwgP.d.ts → tool-router-DQ-HrD7W.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { A as ToolClientProvider, T as ToolClient } from './types-CjczQwNX.js';
+import { A as ToolClientProvider, T as ToolClient } from './types-Bf-7GOLW.js';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{types-CjczQwNX.d.mts → types-Bf-7GOLW.d.mts}

@@ -2,7 +2,6 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 /**
  * Simple event emitter pattern for MCP connection events
- * Inspired by Cloudflare's agents pattern but adapted for serverless
  */
 type Disposable = {
     dispose(): void;
@@ -10,7 +9,6 @@ type Disposable = {
 type Event<T> = (listener: (event: T) => void) => Disposable;
 /**
  * Event emitter class for type-safe event handling
- * Similar to Cloudflare's Emitter but simplified for our use case
  */
 declare class Emitter<T> {
     private listeners;

package/dist/{types-CjczQwNX.d.ts → types-Bf-7GOLW.d.ts}

@@ -2,7 +2,6 @@ import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 /**
  * Simple event emitter pattern for MCP connection events
- * Inspired by Cloudflare's agents pattern but adapted for serverless
  */
 type Disposable = {
     dispose(): void;
@@ -10,7 +9,6 @@ type Disposable = {
 type Event<T> = (listener: (event: T) => void) => Disposable;
 /**
  * Event emitter class for type-safe event handling
- * Similar to Cloudflare's Emitter but simplified for our use case
  */
 declare class Emitter<T> {
     private listeners;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "publishConfig": {
     "access": "public"
   },

package/src/bin/mcp-ts.ts

@@ -82,13 +82,13 @@ async function initSupabase() {
             console.log('   npx supabase db push');
             console.log('\n3. Add your Supabase credentials to .env:');
             console.log('   SUPABASE_URL=https://<your-project-id>.supabase.co');
-            console.log('   SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>');
-            console.log('\n⚠️  Important: Use the service_role key (not the anon key) for server-side storage.');
-            console.log('   The service_role key bypasses RLS policies and is required for mcp-ts to work correctly.');
-            console.log('   Find it in: Supabase Dashboard -> Project Settings -> API -> service_role');
+            console.log('   SUPABASE_SECRET_KEY=<your-secret-key>');
+            console.log('\n⚠️  Important: Use the secret key (not the anon key) for server-side storage.');
+            console.log('   The secret key bypasses RLS policies and is required for mcp-ts to work correctly.');
+            console.log('   Find it in: Supabase Dashboard -> Project Settings -> API -> Secret key');
         } else if (files.length > 0) {
             console.log('\n👍 All migration files are already present in your project.');
-            console.log('   Ensure SUPABASE_SERVICE_ROLE_KEY (not SUPABASE_ANON_KEY) is set in your .env');
+            console.log('   Ensure SUPABASE_SECRET_KEY (not SUPABASE_ANON_KEY) is set in your .env');
         } else {
             console.log('⚠️  No migration files found to copy.');
         }

package/src/client/react/use-mcp.ts

@@ -1,7 +1,6 @@
 /**
  * useMcp React Hook
  * Manages MCP connections with SSE-based real-time updates
- * Based on Cloudflare's agents pattern
  */
 
 import { useEffect, useRef, useState, useCallback, useMemo } from 'react';

package/src/client/vue/use-mcp.ts

@@ -1,7 +1,6 @@
 /**
  * useMcp Vue Composable
  * Manages MCP connections with SSE-based real-time updates
- * Based on Cloudflare's agents pattern
  */
 
 import { ref, onMounted, onUnmounted, watch, computed, shallowRef } from 'vue';

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

@@ -152,6 +152,19 @@ export class MultiSessionClient implements ToolClientProvider {
         return this.clients;
     }
 
+    /**
+     * Removes and disconnects a single session by ID.
+     *
+     * @returns `true` if the session was found and removed, `false` if not found.
+     */
+    async removeSession(sessionId: string): Promise<boolean> {
+        const idx = this.clients.findIndex(c => c.getSessionId() === sessionId);
+        if (idx === -1) return false;
+        const [client] = this.clients.splice(idx, 1);
+        await client.disconnect();
+        return true;
+    }
+
     /**
      * Gracefully disconnects all active MCP clients and clears the internal list.
      *

package/src/server/mcp/oauth-client.ts

@@ -79,7 +79,7 @@ export interface MCPOAuthClientOptions {
  * Emits connection lifecycle events for observability
  */
 export class MCPClient {
-  private client: Client | null = null;
+  private client: Client;
   public oauthProvider: AgentsOAuthProvider | null = null;
   private transport: StreamableHTTPClientTransport | SSEClientTransport | null = null;
   private userId: string;
@@ -131,6 +131,22 @@ export class MCPClient {
     this.clientUri = options.clientUri;
     this.logoUri = options.logoUri;
     this.policyUri = options.policyUri;
+
+    this.client = new Client(
+      {
+        name: MCP_CLIENT_NAME,
+        version: MCP_CLIENT_VERSION,
+      },
+      {
+        capabilities: {
+          extensions: {
+            'io.modelcontextprotocol/ui': {
+              mimeTypes: ['text/html+mcp'],
+            },
+          },
+        } as McpAppClientCapabilities,
+      }
+    );
   }
 
   /**
@@ -257,7 +273,6 @@ export class MCPClient {
           const hasSessionHeader = init?.headers && new Headers(init.headers as HeadersInit).has('mcp-session-id');
 
           if (response.status === 404 && hasSessionHeader) {
-            this.client = null;
             throw new Error("MCP_SESSION_EXPIRED: Downstream session was not found on the server.");
           }
 
@@ -276,13 +291,12 @@ export class MCPClient {
   }
 
   /**
-   * Initializes client components (client, transport, OAuth provider)
-   * Loads missing configuration from Redis session store if needed
-   * This method is idempotent and safe to call multiple times
+   * Ensures session metadata and OAuth provider are loaded.
+   * Does NOT create the SDK Client — callers that need one create it themselves.
    * @private
    */
-  private async initialize(): Promise<void> {
-    if (this.client && this.oauthProvider) {
+  private async ensureSession(): Promise<void> {
+    if (this.oauthProvider) {
       return;
     }
 
@@ -337,24 +351,6 @@ export class MCPClient {
       });
     }
 
-    if (!this.client) {
-      this.client = new Client(
-        {
-          name: MCP_CLIENT_NAME,
-          version: MCP_CLIENT_VERSION,
-        },
-        {
-          capabilities: {
-            extensions: {
-              'io.modelcontextprotocol/ui': {
-                mimeTypes: ['text/html+mcp'],
-              },
-            },
-          } as McpAppClientCapabilities
-        }
-      );
-    }
-
     // Create session in the session store if it doesn't exist yet
     // This is needed BEFORE OAuth flow starts because the OAuth provider
     // will call saveCodeVerifier() which requires the session to exist
@@ -381,6 +377,8 @@ export class MCPClient {
     }
   }
 
+
+
   /**
    * Saves current session state to the session store
    * Creates new session if it doesn't exist, updates if it does
@@ -510,31 +508,21 @@ export class MCPClient {
    * @throws {Error} When connection fails for other reasons
    */
   async connect(): Promise<void> {
-    // Re-entry guard: if a previous SDK Client is still attached to a transport
-    // (e.g. a stale session from a prior connect() call on the same MCPClient
-    // instance), close and detach it before proceeding. The MCP SDK client will
-    // throw if asked to connect while a transport is already attached, and the
-    // stale transport would send an expired mcp-session-id to the remote server
-    // causing "Session not found. Reconnect without session header." errors.
-    //
-    // We also null out this.client so that initialize() creates a fresh Client
-    // instance with a clean transport slot, rather than reusing the old one.
-    // The oauthProvider is intentionally preserved — OAuth tokens remain valid
-    // across reconnects; only the transport session needs to be renegotiated.
-    if (this.client?.transport) {
+    // Close any existing transport so we can negotiate a fresh session.
+    // The SDK Client throws if asked to connect() while a transport is
+    // already attached; close() detaches it cleanly so the same Client
+    // instance can be reused.
+    if (this.client.transport) {
       this.transport = null;
-      try {
-        await this.client.close();
-      } catch {
+      try { await this.client.close(); } catch {
         // Closing a transport that may have already failed is best-effort.
       }
-      this.client = null;
     }
 
-    await this.initialize();
+    await this.ensureSession();
 
-    if (!this.client || !this.oauthProvider) {
-      const error = 'Client or OAuth provider not initialized';
+    if (!this.oauthProvider) {
+      const error = 'OAuth provider not initialized';
       this.emitError(error, 'connection');
       this.emitStateChange('FAILED');
       throw new Error(error);
@@ -644,7 +632,7 @@ export class MCPClient {
     this.emitStateChange('AUTHENTICATING');
     this.emitProgress('Exchanging authorization code for tokens...');
 
-    await this.initialize();
+    await this.ensureSession();
 
     if (!this.oauthProvider) {
       const error = 'OAuth provider not initialized';
@@ -791,7 +779,9 @@ export class MCPClient {
         params: {},
       };
 
-      const result = await this.client.request(request, ListToolsResultSchema);
+      const result = await this.withRetry(() =>
+        this.client!.request(request, ListToolsResultSchema)
+      );
 
       if (this.serverId) {
         this._onConnectionEvent.fire({
@@ -837,7 +827,9 @@ export class MCPClient {
     };
 
     try {
-      const result = await this.client.request(request, CallToolResultSchema);
+      const result = await this.withRetry(() =>
+        this.client!.request(request, CallToolResultSchema)
+      );
 
       this._onObservabilityEvent.fire({
         type: 'mcp:client:tool_call',
@@ -897,7 +889,9 @@ export class MCPClient {
         params: {},
       };
 
-      const result = await this.client.request(request, ListPromptsResultSchema);
+      const result = await this.withRetry(() =>
+        this.client!.request(request, ListPromptsResultSchema)
+      );
 
       this.emitStateChange('READY');
       this.emitProgress(`Discovered ${result.prompts.length} prompts`);
@@ -931,7 +925,9 @@ export class MCPClient {
       },
     };
 
-    return await this.client.request(request, GetPromptResultSchema);
+    return await this.withRetry(() =>
+      this.client!.request(request, GetPromptResultSchema)
+    );
   }
 
   /**
@@ -952,7 +948,9 @@ export class MCPClient {
         params: {},
       };
 
-      const result = await this.client.request(request, ListResourcesResultSchema);
+      const result = await this.withRetry(() =>
+        this.client!.request(request, ListResourcesResultSchema)
+      );
 
       this.emitStateChange('READY');
       this.emitProgress(`Discovered ${result.resources.length} resources`);
@@ -984,7 +982,33 @@ export class MCPClient {
       },
     };
 
-    return await this.client.request(request, ReadResourceResultSchema);
+    return await this.withRetry(() =>
+      this.client!.request(request, ReadResourceResultSchema)
+    );
+  }
+
+  /**
+   * Wraps an MCP request with automatic transport-session recovery.
+   *
+   * When the downstream MCP server rejects the request with a 404 indicating
+   * the transport session has expired, this method tears down the stale SDK
+   * client and transport, calls {@link reconnect} to negotiate a fresh session,
+   * and retries the request once.
+   *
+   * Non-transient errors (network failures, auth errors, etc.) propagate as-is.
+   */
+  private async withRetry<T>(fn: () => Promise<T>): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      if (!(error instanceof Error && error.message.includes('MCP_SESSION_EXPIRED'))) throw error;
+      if (this.client.transport) {
+        try { await this.client.close(); } catch {}
+        this.transport = null;
+      }
+      await this.reconnect();
+      return await fn();
+    }
   }
 
   /**
@@ -994,25 +1018,9 @@ export class MCPClient {
    * @throws {Error} When OAuth provider is not initialized
    */
   async reconnect(): Promise<void> {
-    await this.initialize();
-
-    if (!this.oauthProvider) {
-      throw new Error('OAuth provider not initialized');
-    }
-
-    this.client = new Client(
-      {
-        name: MCP_CLIENT_NAME,
-        version: MCP_CLIENT_VERSION,
-      },
-      { capabilities: {} }
-    );
-
-    // Use default logic to get transport, defaulting to what's stored or auto
-    const tt = this.transportType || 'streamable-http';
-    this.transport = this.getTransport(tt);
-
-    await this.client.connect(this.transport);
+    await this.ensureSession();
+    if (!this.oauthProvider) throw new Error('OAuth provider not initialized');
+    await this.connect();
   }
 
   /**
@@ -1021,7 +1029,7 @@ export class MCPClient {
    */
   async clearSession(): Promise<void> {
     try {
-      await this.initialize();
+      await this.ensureSession();
     } catch (error) {
       console.warn('[MCPClient] Initialization failed during clearSession:', error);
     }
@@ -1039,7 +1047,7 @@ export class MCPClient {
    * @returns True if connected, false otherwise
    */
   isConnected(): boolean {
-    return this.client !== null;
+    return this.client.transport !== undefined;
   }
 
   /**
@@ -1066,10 +1074,9 @@ export class MCPClient {
       }
     }
 
-    if (this.client) {
-      this.client.close();
+    if (this.client.transport) {
+      try { await this.client.close(); } catch {}
     }
-    this.client = null;
     this.oauthProvider = null;
     this.transport = null;
 

package/src/server/storage/index.ts

@@ -141,13 +141,13 @@ async function createStorage(): Promise<SessionStore> {
 
     if (type === 'supabase') {
         const url = process.env.SUPABASE_URL;
-        const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY;
+        const key = process.env.SUPABASE_SECRET_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.');
+            console.warn('[mcp-ts][Storage] Explicit selection "supabase" requires SUPABASE_URL and SUPABASE_SECRET_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.');
+            if (!process.env.SUPABASE_SECRET_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️  Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SECRET_KEY" is recommended.');
             }
             try {
                 const { createClient } = await import('@supabase/supabase-js');
@@ -210,14 +210,14 @@ async function createStorage(): Promise<SessionStore> {
         return await initializeStorage(new SqliteStorage({ path: process.env.MCP_TS_STORAGE_SQLITE_PATH }));
     }
 
-    if (process.env.SUPABASE_URL && (process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY)) {
+    if (process.env.SUPABASE_URL && (process.env.SUPABASE_SECRET_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!;
+            const key = process.env.SUPABASE_SECRET_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.');
+            if (!process.env.SUPABASE_SECRET_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️ Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SECRET_KEY" is recommended.');
             }
 
             const client = createClient(url, key);

package/src/shared/events.ts

@@ -1,6 +1,5 @@
 /**
  * Simple event emitter pattern for MCP connection events
- * Inspired by Cloudflare's agents pattern but adapted for serverless
  */
 
 export type Disposable = {
@@ -11,7 +10,6 @@ export type Event<T> = (listener: (event: T) => void) => Disposable;
 
 /**
  * Event emitter class for type-safe event handling
- * Similar to Cloudflare's Emitter but simplified for our use case
  */
 export class Emitter<T> {
   private listeners: Set<(event: T) => void> = new Set();