@mcp-ts/sdk 2.4.3 → 2.4.5

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.3",
+  "version": "2.4.5",
   "publishConfig": {
     "access": "public"
   },

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/handlers/sse-handler.ts

@@ -38,7 +38,7 @@ import { UnauthorizedError } from '../../shared/errors.js';
 import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
 import { parseOAuthState } from '../../shared/utils.js';
 import { MCPClient } from '../mcp/oauth-client.js';
-import { sessions } from '../storage/index.js';
+import { sessions, generateServerId } from '../storage/index.js';
 
 // ============================================
 // Types & Interfaces
@@ -256,7 +256,7 @@ export class SSEConnectionManager {
     // Tool name format: tool_<serverId>_<toolName> - with 12 char serverId leaves 46 chars for tool name
     const serverId = params.serverId && params.serverId.length <= 12
       ? params.serverId
-      : await sessions.generateSessionId();
+      : generateServerId();
 
     // Check for existing connections
     const existingSessions = await sessions.list(this.userId);

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,
+      }
+    );
   }
 
   /**
@@ -275,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;
     }
 
@@ -336,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
@@ -363,7 +360,15 @@ export class MCPClient {
     if (!existingSession && this.serverId && this.serverUrl && this.callbackUrl) {
       this.createdAt = Date.now();
       const updatedAt = this.createdAt;
-      console.log(`[MCPClient] Creating pending session ${this.sessionId} for connection setup`);
+      this._onObservabilityEvent.fire({
+        type: 'mcp:client:session_created',
+        level: 'info',
+        message: `Creating pending session ${this.sessionId} for connection setup`,
+        sessionId: this.sessionId,
+        serverId: this.serverId,
+        timestamp: Date.now(),
+        id: nanoid(),
+      });
       await sessions.create({
         sessionId: this.sessionId,
         userId: this.userId,
@@ -380,6 +385,8 @@ export class MCPClient {
     }
   }
 
+
+
   /**
    * Saves current session state to the session store
    * Creates new session if it doesn't exist, updates if it does
@@ -509,31 +516,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);
@@ -553,7 +550,15 @@ export class MCPClient {
 
       // Refresh session metadata on every successful connect so active sessions
       // record ongoing usage and don't look dormant to session cleanup jobs.
-      console.log(`[MCPClient] Saving active session ${this.sessionId} (connect success)`);
+      this._onObservabilityEvent.fire({
+        type: 'mcp:client:session_saved',
+        level: 'info',
+        message: `Saving active session ${this.sessionId} (connect success)`,
+        sessionId: this.sessionId,
+        serverId: this.serverId,
+        timestamp: Date.now(),
+        id: nanoid(),
+      });
       await this.saveSession('active');
     } catch (error) {
       /** Handle Authentication Errors */
@@ -591,7 +596,15 @@ export class MCPClient {
         }
 
         this.emitStateChange('AUTHENTICATING');
-        console.log(`[MCPClient] Saving pending OAuth session ${this.sessionId}`);
+        this._onObservabilityEvent.fire({
+          type: 'mcp:client:session_saved',
+          level: 'info',
+          message: `Saving pending OAuth session ${this.sessionId}`,
+          sessionId: this.sessionId,
+          serverId: this.serverId,
+          timestamp: Date.now(),
+          id: nanoid(),
+        });
         await this.saveSession('pending');
 
         if (this.serverId) {
@@ -643,7 +656,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';
@@ -697,34 +710,30 @@ export class MCPClient {
           authenticatedStateEmitted = true;
         }
 
-        this.emitProgress('Creating authenticated client...');
-
-        this.client = new Client(
-          {
-            name: MCP_CLIENT_NAME,
-            version: MCP_CLIENT_VERSION,
-          },
-          {
-            capabilities: {
-              extensions: {
-                'io.modelcontextprotocol/ui': {
-                  mimeTypes: ['text/html+mcp'],
-                },
-              },
-            } as McpAppClientCapabilities
-          }
-        );
-
         this.emitStateChange('CONNECTING');
 
-        /** We explicitly try to connect with the transport we just auth'd with first */
+        // The SDK Client may still have a transport attached from a prior
+        // connect() that failed with UnauthorizedError; close it first so
+        // we can negotiate a fresh session with the newly-exchanged tokens.
+        if (this.client.transport) {
+          try { await this.client.close(); } catch {}
+        }
+
         await this.client.connect(this.transport);
 
         /** Connection succeeded — lock in the transport type */
         this.transportType = currentType;
 
         this.emitStateChange('CONNECTED');
-        console.log(`[MCPClient] Saving active session ${this.sessionId} (OAuth complete)`);
+        this._onObservabilityEvent.fire({
+          type: 'mcp:client:session_saved',
+          level: 'info',
+          message: `Saving active session ${this.sessionId} (OAuth complete)`,
+          sessionId: this.sessionId,
+          serverId: this.serverId,
+          timestamp: Date.now(),
+          id: nanoid(),
+        });
         await this.saveSession('active');
 
         return; // Success, exit function
@@ -778,10 +787,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async listTools(): Promise<ListToolsResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
-
     this.emitStateChange('DISCOVERING');
 
     try {
@@ -825,9 +830,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async callTool(toolName: string, toolArgs: Record<string, unknown>): Promise<CallToolResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
 
     const request: CallToolRequest = {
       method: 'tools/call',
@@ -888,10 +890,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async listPrompts(): Promise<ListPromptsResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
-
     this.emitStateChange('DISCOVERING');
 
     try {
@@ -924,9 +922,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
 
     const request: GetPromptRequest = {
       method: 'prompts/get',
@@ -947,10 +942,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async listResources(): Promise<ListResourcesResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
-
     this.emitStateChange('DISCOVERING');
 
     try {
@@ -982,9 +973,6 @@ export class MCPClient {
    * @throws {Error} When client is not connected
    */
   async readResource(uri: string): Promise<ReadResourceResult> {
-    if (!this.client) {
-      throw new Error('Not connected to server');
-    }
 
     const request: ReadResourceRequest = {
       method: 'resources/read',
@@ -1013,10 +1001,9 @@ export class MCPClient {
       return await fn();
     } catch (error) {
       if (!(error instanceof Error && error.message.includes('MCP_SESSION_EXPIRED'))) throw error;
-      if (this.client) {
+      if (this.client.transport) {
         try { await this.client.close(); } catch {}
         this.transport = null;
-        this.client = null;
       }
       await this.reconnect();
       return await fn();
@@ -1030,31 +1017,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');
-    }
-
-    // Close the client initialize() may have created — we need a fresh
-    // client that will negotiate a new transport session.
-    if (this.client) {
-      try { await this.client.close(); } catch {}
-    }
-
-    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();
   }
 
   /**
@@ -1063,9 +1028,18 @@ export class MCPClient {
    */
   async clearSession(): Promise<void> {
     try {
-      await this.initialize();
+      await this.ensureSession();
     } catch (error) {
-      console.warn('[MCPClient] Initialization failed during clearSession:', error);
+      this._onObservabilityEvent.fire({
+        type: 'mcp:client:error',
+        level: 'warn',
+        message: 'Initialization failed during clearSession',
+        sessionId: this.sessionId,
+        serverId: this.serverId,
+        payload: { error: String(error) },
+        timestamp: Date.now(),
+        id: nanoid(),
+      });
     }
 
     if (this.oauthProvider) {
@@ -1081,7 +1055,7 @@ export class MCPClient {
    * @returns True if connected, false otherwise
    */
   isConnected(): boolean {
-    return this.client !== null;
+    return this.client.transport !== undefined;
   }
 
   /**
@@ -1108,10 +1082,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

@@ -9,7 +9,7 @@ import type { SessionStore, Session, SessionMutationEvent, SessionMutationListen
 
 // Re-export types
 export * from './types.js';
-export { generateSessionId } from '../../shared/utils.js';
+export { generateSessionId, generateServerId } from '../../shared/utils.js';
 export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage, SupabaseStorageBackend, NeonStorageBackend };
 
 export function createSupabaseStorageBackend(client: any): SupabaseStorageBackend {

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();

package/src/shared/utils.ts

@@ -1,17 +1,10 @@
-import { customAlphabet } from 'nanoid';
+import { customAlphabet, nanoid } from 'nanoid';
 
 const OAUTH_STATE_SEPARATOR = '.';
 
-/** first char: letters only (required by OpenAI) */
-const firstChar = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-    1
-);
-
-/** remaining chars: alphanumeric */
-const rest = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
-    11
+const serverIdAlphabet = customAlphabet(
+    'abcdefghijklmnopqrstuvwxyz0123456789',
+    12
 );
 
 /**
@@ -32,11 +25,20 @@ export function sanitizeServerLabel(name: string): string {
 }
 
 /**
- * Generates a standard 12-character session ID compliant with external tool restrictions.
- * First character is always a letter.
+ * Generates a session ID with a human-readable prefix for easy identification.
+ * Format: sess_<21-char nanoid> (26 chars total).
+ * Not used in tool names, so length is not constrained.
  */
 export function generateSessionId(): string {
-    return firstChar() + rest();
+    return 'sess_' + nanoid(21);
+}
+
+/**
+ * Generates a short server ID suitable for use in tool names.
+ * 12-char alphanumeric string that keeps tool_<serverId>_<toolName> under 64 chars.
+ */
+export function generateServerId(): string {
+    return serverIdAlphabet();
 }
 
 export interface ParsedOAuthState {