@mcp-ts/sdk 1.4.0 → 1.5.1

package/src/client/react/use-mcp-apps.tsx

@@ -15,7 +15,9 @@ import React, {
   useImperativeHandle,
   type MutableRefObject,
 } from 'react';
-import { useAppHost, type UseAppHostOptions } from './use-app-host.js';
+import type { UseAppHostOptions } from './use-app-host.js';
+import { useAppHost } from './use-app-host.js';
+import { resolveMetaToolProxy } from '../../shared/meta-tools.js';
 import type { SSEClient } from '../core/sse-client.js';
 import { APP_HOST_DEFAULTS } from '../core/constants.js';
 import type { SandboxConfig } from '../core/app-host.js';
@@ -56,9 +58,10 @@ export interface McpAppRendererHandle {
 /** Props for {@link useMcpApps}'s `McpAppRenderer` (client is supplied via the hook). */
 export interface McpAppRendererProps extends Pick<UseAppHostOptions, 'sandbox' | 'hostContext' | 'onCallTool' | 'onReadResource' | 'onFallbackRequest' | 'onMessage' | 'onOpenLink' | 'onLoggingMessage' | 'onSizeChanged' | 'onError'> {
   name: string;
+  client?: McpClient | null;
   toolResourceUri?: string;
   html?: string;
-  input?: Record<string, unknown>;
+  input?: Record<string, unknown> | null;
   result?: unknown;
   status?: 'executing' | 'inProgress' | 'complete' | 'idle';
   toolInputPartial?: any;
@@ -102,8 +105,10 @@ const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(functi
   },
   ref,
 ) {
+  
   const mcpClient = clientRef.current;
-  const metadata = getMcpAppMetadata(mcpClient, name);
+  const { toolName: resolvedToolName, args: resolvedInput } = resolveMetaToolProxy(name, input);
+  const metadata = getMcpAppMetadata(mcpClient, resolvedToolName, resolvedInput);
   const sseClient = mcpClient?.sseClient ?? null;
   const resourceUri = toolResourceUri || metadata?.resourceUri;
   const appSessionId = metadata?.sessionId;
@@ -194,7 +199,7 @@ const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(functi
 
   const sentInputRef = useRef(false);
   const sentResultRef = useRef(false);
-  const lastInputRef = useRef(input);
+  const lastInputRef = useRef(resolvedInput);
   const lastResultRef = useRef(result);
   const lastStatusRef = useRef(status);
 
@@ -236,15 +241,16 @@ const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(functi
       .catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
   }, [host, resourceUri, html, appSessionId]);
 
+  // Send tool inputs
   useEffect(() => {
-    if (!host || !isLaunched || !resourceUri || !appSessionId || !input) return;
+    if (!host || !isLaunched || !resourceUri || !appSessionId || !resolvedInput) return;
 
-    if (!sentInputRef.current || JSON.stringify(input) !== JSON.stringify(lastInputRef.current)) {
+    if (!sentInputRef.current || JSON.stringify(resolvedInput) !== JSON.stringify(lastInputRef.current)) {
       sentInputRef.current = true;
-      lastInputRef.current = input;
-      host.sendToolInput(input);
+      lastInputRef.current = resolvedInput;
+      host.sendToolInput(resolvedInput);
     }
-  }, [host, isLaunched, input, resourceUri, appSessionId, name]);
+  }, [host, isLaunched, resolvedInput, resourceUri, appSessionId, resolvedToolName]);
 
   useEffect(() => {
     if (!host || !isLaunched || !resourceUri || !appSessionId || result === undefined) return;
@@ -259,7 +265,7 @@ const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(functi
           : result;
       host.sendToolResult(formattedResult);
     }
-  }, [host, isLaunched, result, status, resourceUri, appSessionId, name]);
+  }, [host, isLaunched, result, status, resourceUri, appSessionId, resolvedToolName]);
 
   useEffect(() => {
     if (status === 'executing' && lastStatusRef.current !== 'executing') {
@@ -354,34 +360,44 @@ const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(functi
 const McpAppView = memo(McpAppViewInner);
 McpAppView.displayName = 'McpAppView';
 
+/**
+ * Renders an interactive MCP application inside a sandboxed iframe.
+ */
+export const McpAppRenderer = memo(
+  forwardRef<McpAppRendererHandle, McpAppRendererProps>(function McpAppRenderer(
+    { client, ...props },
+    ref
+  ) {
+    const clientRef = useRef(client || null);
+    clientRef.current = client || null;
+
+    return <McpAppView ref={ref} clientRef={clientRef} {...props} />;
+  })
+);
+
 /**
  * Helpers scoped to one `mcpClient`. Pass the client here once; `McpAppRenderer` only needs per-tool props (`name`, `input`, `result`, `status`).
  *
  * @param mcpClient - From `useMcp()` or context (for example `useMcpContext()`).
+ * @deprecated Use the standalone `<McpAppRenderer>` component and `getMcpAppMetadata` utility directly.
  */
 export function useMcpApps(mcpClient: McpClient | null) {
-  // Stable `McpAppRenderer` type: parent re-renders and `connections` updates must not remount the iframe.
-  const clientRef = useRef(mcpClient);
-  clientRef.current = mcpClient;
-
   const getAppMetadata = useCallback(
-    (toolName: string) => getMcpAppMetadata(clientRef.current, toolName),
-    []
+    (toolName: string) => getMcpAppMetadata(mcpClient, toolName),
+    [mcpClient]
   );
 
-  const McpAppRenderer = useMemo(() => {
-    const Inner = forwardRef<McpAppRendererHandle, McpAppRendererProps>(function McpAppRenderer(
-      props,
-      ref,
-    ) {
-      return <McpAppView ref={ref} clientRef={clientRef} {...props} />;
-    });
-    const Renderer = memo(Inner);
-    Renderer.displayName = 'McpAppRenderer';
-    return Renderer;
-  }, []);
-
-  return { getAppMetadata, McpAppRenderer };
+  const BoundMcpAppRenderer = useMemo(() => {
+    const Renderer = forwardRef<McpAppRendererHandle, Omit<McpAppRendererProps, 'client'>>(
+      function BoundMcpAppRenderer(props, ref) {
+        return <McpAppRenderer ref={ref} client={mcpClient} {...props} />;
+      }
+    );
+    Renderer.displayName = 'BoundMcpAppRenderer';
+    return memo(Renderer);
+  }, [mcpClient]);
+
+  return { getAppMetadata, McpAppRenderer: BoundMcpAppRenderer };
 }
 
 function extractToolName(fullName: string): string {
@@ -389,13 +405,15 @@ function extractToolName(fullName: string): string {
   return match?.[1] || fullName;
 }
 
-function getMcpAppMetadata(
+export function getMcpAppMetadata(
   mcpClient: McpClient | null,
-  toolName: string
+  toolName: string,
+  input?: Record<string, unknown> | null
 ): McpAppMetadata | undefined {
   if (!mcpClient) return undefined;
 
-  const extractedName = extractToolName(toolName);
+  const { toolName: proxyToolName } = resolveMetaToolProxy(toolName, input);
+  const extractedName = extractToolName(proxyToolName);
 
   for (const conn of mcpClient.connections) {
     for (const tool of conn.tools) {

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

@@ -290,17 +290,48 @@ export function useMcp(options: UseMcpOptions): McpClient {
       state === 'CONNECTED' ||
       state === 'DISCOVERING';
 
+    const getVisibleState = (
+      incomingState: McpConnectionState,
+      existingState?: McpConnectionState,
+      previousState?: McpConnectionState
+    ): McpConnectionState => {
+      // `INITIALIZING` has two meanings in practice:
+      // 1. genuine cold start / reconnect work
+      // 2. an internal setup step that happens mid-OAuth completion
+      //
+      // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+      // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+      // We keep the raw event stream intact for observability, but collapse the
+      // visible state back into the current auth phase in the UI.
+      if (
+        incomingState === 'INITIALIZING' &&
+        (existingState === 'AUTHENTICATING' ||
+          existingState === 'AUTHENTICATED' ||
+          previousState === 'AUTHENTICATING' ||
+          previousState === 'AUTHENTICATED')
+      ) {
+        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+          ? 'AUTHENTICATED'
+          : 'AUTHENTICATING';
+      }
+
+      return incomingState;
+    };
+
     setConnections((prev: McpConnection[]) => {
       switch (event.type) {
         case 'state_changed': {
           const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
           if (existing) {
+            // Normalize the incoming backend state into the smoother user-facing
+            // state we want to render for this existing connection.
+            const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
             // In stateless per-request transport, tool calls can emit transient reconnect states.
             // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
             const nextState =
-              existing.state === 'READY' && isTransientReconnectState(event.state)
+              existing.state === 'READY' && isTransientReconnectState(normalizedState)
                 ? existing.state
-                : event.state;
+                : normalizedState;
 
             return prev.map((c: McpConnection) =>
               c.sessionId === event.sessionId ? {
@@ -323,7 +354,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 serverId: event.serverId,
                 serverName: event.serverName,
                 serverUrl: event.serverUrl,
-                state: event.state,
+                // New connections do not have prior local state, so we normalize
+                // only against the server-reported previous state.
+                state: getVisibleState(event.state, undefined, event.previousState),
                 createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                 tools: [],
               },

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

@@ -240,16 +240,49 @@ export function useMcp(options: UseMcpOptions): McpClient {
             state === 'CONNECTED' ||
             state === 'DISCOVERING';
 
+        const getVisibleState = (
+            incomingState: McpConnectionState,
+            existingState?: McpConnectionState,
+            previousState?: McpConnectionState
+        ): McpConnectionState => {
+            // `INITIALIZING` has two meanings in practice:
+            // 1. genuine cold start / reconnect work
+            // 2. an internal setup step that happens mid-OAuth completion
+            //
+            // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+            // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+            // We keep the raw event stream intact for observability, but collapse the
+            // visible state back into the current auth phase in the UI.
+            if (
+                incomingState === 'INITIALIZING' &&
+                (
+                    existingState === 'AUTHENTICATING' ||
+                    existingState === 'AUTHENTICATED' ||
+                    previousState === 'AUTHENTICATING' ||
+                    previousState === 'AUTHENTICATED'
+                )
+            ) {
+                return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+                    ? 'AUTHENTICATED'
+                    : 'AUTHENTICATING';
+            }
+
+            return incomingState;
+        };
+
         switch (event.type) {
             case 'state_changed': {
                 const existing = connections.value.find((c) => c.sessionId === event.sessionId);
                 if (existing) {
+                    // Normalize the incoming backend state into the smoother user-facing
+                    // state we want to render for this existing connection.
+                    const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
                     // In stateless per-request transport, tool calls can emit transient reconnect states.
                     // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
                     const nextState =
-                        existing.state === 'READY' && isTransientReconnectState(event.state)
+                        existing.state === 'READY' && isTransientReconnectState(normalizedState)
                             ? existing.state
-                            : event.state;
+                            : normalizedState;
 
                     const index = connections.value.indexOf(existing);
                     connections.value[index] = {
@@ -268,7 +301,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         sessionId: event.sessionId,
                         serverId: event.serverId,
                         serverName: event.serverName,
-                        state: event.state,
+                        // New connections do not have prior local state, so we normalize
+                        // only against the server-reported previous state.
+                        state: getVisibleState(event.state, undefined, event.previousState),
                         createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                         tools: [],
                     }];

package/src/server/handlers/sse-handler.ts

@@ -363,9 +363,24 @@ export class SSEConnectionManager {
       return existing;
     }
 
+    const session = await storage.getSession(this.identity, sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
     const client = new MCPClient({
       identity: this.identity,
       sessionId,
+      // These fields are optional in MCPClient, but when rehydrating a known
+      // stored session on the server we pass them explicitly to preserve the
+      // original transport/connection metadata instead of relying on lazy
+      // reloading during initialize().
+      serverId: session.serverId,
+      serverName: session.serverName,
+      serverUrl: session.serverUrl,
+      callbackUrl: session.callbackUrl,
+      transportType: session.transportType,
+      headers: session.headers,
     });
 
     // Subscribe to events before connecting
@@ -437,6 +452,16 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original transport/connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        transportType: session.transportType,
+        headers: session.headers,
         ...clientMetadata,
       });
 
@@ -478,6 +503,20 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        // NOTE: transportType is intentionally omitted here.
+        // The session's stored transportType is a placeholder ('streamable_http')
+        // set before transport negotiation. Omitting it lets MCPClient auto-negotiate
+        // (try streamable_http → SSE fallback), which is critical for servers like
+        // Neon that only support SSE transport.
+        headers: session.headers,
       });
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));

package/src/server/index.ts

@@ -32,6 +32,8 @@ export type {
 } from '../shared/events';
 
 export type {
+  ToolClient,
+  ToolClientProvider,
   ToolInfo,
   McpRpcRequest,
   McpRpcResponse,

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

@@ -500,16 +500,10 @@ export class MCPClient {
       this.emitStateChange('CONNECTED');
       this.emitProgress('Connected successfully');
 
-      // Promote short-lived OAuth-pending session TTL to long-lived active TTL once.
-      // Also persist when transport negotiation changed the effective transport.
-      const existingSession = await storage.getSession(this.identity, this.sessionId);
-      const needsTransportUpdate = !existingSession || existingSession.transportType !== this.transportType;
-      const needsTtlPromotion = !existingSession || existingSession.active !== true;
-
-      if (needsTransportUpdate || needsTtlPromotion) {
-        console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
-        await this.saveSession(SESSION_TTL_SECONDS, true);
-      }
+      // Refresh session metadata on every successful connect so active sessions
+      // record ongoing usage and don't look dormant to storage cleanup jobs.
+      console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
+      await this.saveSession(SESSION_TTL_SECONDS, true);
     } catch (error) {
       /** Handle Authentication Errors */
       if (
@@ -537,11 +531,17 @@ export class MCPClient {
               : `OAuth authorization URL not available: ${detail}`;
           this.emitError(message, 'auth');
           this.emitStateChange('FAILED');
+          
+          // Proactive Cleanup: This session has reached a terminal failure state. 
+          // We remove it now to ensure the database remains lean, bypassing the 
+          // automated lifecycle sweep.
           try {
             await storage.removeSession(this.identity, this.sessionId);
           } catch {
-            // best-effort cleanup
+            // Non-blocking: Proactive cleanup failures are suppressed to prioritize 
+            // the original error context.
           }
+          
           throw new Error(message);
         }
 
@@ -571,6 +571,19 @@ export class MCPClient {
       const errorMessage = error instanceof Error ? error.message : 'Connection failed';
       this.emitError(errorMessage, 'connection');
       this.emitStateChange('FAILED');
+
+      // Terminal Handshake Failure: only purge transient sessions. Active
+      // sessions may still hold valid credentials for a later reconnect.
+      try {
+        const existingSession = await storage.getSession(this.identity, this.sessionId);
+        if (!existingSession || existingSession.active !== true) {
+          await storage.removeSession(this.identity, this.sessionId);
+        }
+      } catch {
+        // Non-blocking: Cleanup is performed on a best-effort basis and should
+        // not interfere with the primary error propagation.
+      }
+
       throw error;
     }
   }
@@ -606,6 +619,7 @@ export class MCPClient {
 
     let lastError: unknown;
     let tokensExchanged = false;
+    let authenticatedStateEmitted = false;
 
     for (const currentType of transportsToTry) {
       const isLastAttempt = currentType === transportsToTry[transportsToTry.length - 1];
@@ -623,10 +637,11 @@ export class MCPClient {
           this.emitProgress(`Tokens already exchanged, skipping auth step for ${currentType}...`);
         }
 
-        /** Success! Update transport type */
-        this.transportType = currentType;
+        if (!authenticatedStateEmitted) {
+          this.emitStateChange('AUTHENTICATED');
+          authenticatedStateEmitted = true;
+        }
 
-        this.emitStateChange('AUTHENTICATED');
         this.emitProgress('Creating authenticated client...');
 
         this.client = new Client(
@@ -650,6 +665,9 @@ export class MCPClient {
         /** We explicitly try to connect with the transport we just auth'd with first */
         await this.client.connect(this.transport);
 
+        /** Connection succeeded — lock in the transport type */
+        this.transportType = currentType;
+
         this.emitStateChange('CONNECTED');
         // Update session with 12hr TTL after successful OAuth
         console.log(`[MCPClient] Updating session ${this.sessionId} to 12hr TTL (OAuth complete)`);
@@ -1108,7 +1126,9 @@ export class MCPClient {
    * @returns Server name or undefined
    */
   getServerName(): string | undefined {
-    return this.serverName;
+    const info = (this.client as any)?.getServerVersion();
+    console.log('server info ->', info);
+    return info?.title ?? info?.name ?? this.serverName;
   }
 
   /**

package/src/shared/index.ts

@@ -22,6 +22,8 @@ export * from './errors';
 
 // Types
 export type {
+  ToolClient,
+  ToolClientProvider,
   ToolInfo,
   McpRpcRequest,
   McpRpcResponse,
@@ -73,3 +75,37 @@ export {
   type ToolUiConfig,
 } from './tool-utils.js';
 
+// Tool Router — Context window optimization
+export {
+  ToolRouter,
+  type ToolRouterOptions,
+  type ToolRouterStrategy,
+  type ToolRouterClientInput,
+  type ToolGroupInfo,
+} from './tool-router.js';
+
+export {
+  ToolIndex,
+  type ToolSummary,
+  type IndexedTool,
+  type ToolIndexOptions,
+  type EmbedFn,
+} from './tool-index.js';
+
+export {
+  SchemaCompressor,
+  type CompactTool,
+  type CompressionStats,
+} from './schema-compressor.js';
+
+export {
+  createSearchToolDefinition,
+  createRegexSearchToolDefinition,
+  createGetSchemaToolDefinition,
+  createExecuteToolDefinition,
+  executeMetaTool,
+  isMetaTool,
+  resolveMetaToolProxy,
+  type CallToolFn,
+} from './meta-tools.js';
+