@mcp-ts/sdk 1.3.1 → 1.3.3

package/src/client/react/index.ts

@@ -1,16 +1,16 @@
-/**
- * MCP SDK - React Client
- * Simple React hooks for MCP app rendering
- */
-
-// Core MCP Hook
-export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './use-mcp.js';
-
-// App Host (internal use)
-export { useAppHost } from './use-app-host.js';
-
-// Simplified MCP Apps Hook - the main API
-export { useMcpApps } from './use-mcp-apps.js';
-
-// Re-export shared types and client from main entry
-export * from '../index.js';
+/**
+ * MCP SDK - React Client
+ * Simple React hooks for MCP app rendering
+ */
+
+// Core MCP Hook
+export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './use-mcp.js';
+
+// App Host (internal use)
+export { useAppHost } from './use-app-host.js';
+
+// Simplified MCP Apps Hook - the main API
+export { useMcpApps } from './use-mcp-apps.js';
+
+// Re-export shared types and client from main entry
+export * from '../index.js';

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

@@ -1,214 +1,214 @@
-/**
- * MCP Apps Hook
- *
- * Provides utilities for rendering interactive UI components from MCP servers.
- */
-
-import React, { useState, useEffect, useCallback, useRef, memo } from 'react';
-import { useAppHost } from './use-app-host.js';
-import type { SSEClient } from '../core/sse-client.js';
-
-export interface McpClient {
-  connections: Array<{
-    sessionId: string;
-    tools: Array<{
-      name: string;
-      mcpApp?: {
-        resourceUri: string;
-      };
-      _meta?: {
-        ui?: {
-          resourceUri?: string;
-        };
-        'ui/resourceUri'?: string;
-      };
-    }>;
-  }>;
-  sseClient?: SSEClient | null;
-}
-
-export interface McpAppMetadata {
-  toolName: string;
-  resourceUri: string;
-  sessionId: string;
-}
-
-interface McpAppRendererProps {
-  metadata: McpAppMetadata;
-  input?: Record<string, unknown>;
-  result?: unknown;
-  status: 'executing' | 'inProgress' | 'complete' | 'idle';
-  sseClient?: SSEClient | null;
-  /** Custom CSS class for the container */
-  className?: string;
-}
-
-/**
- * Internal component that renders the MCP app in a sandboxed iframe
- */
-const McpAppRenderer = memo(function McpAppRenderer({
-  metadata,
-  input,
-  result,
-  status,
-  sseClient,
-  className,
-}: McpAppRendererProps) {
-  const iframeRef = useRef<HTMLIFrameElement>(null);
-  const { host, error: hostError } = useAppHost(sseClient as SSEClient, iframeRef);
-  const [isLaunched, setIsLaunched] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Track which data has been sent to prevent duplicates
-  const sentInputRef = useRef(false);
-  const sentResultRef = useRef(false);
-  const lastInputRef = useRef(input);
-  const lastResultRef = useRef(result);
-  const lastStatusRef = useRef(status);
-
-  // Launch the app when host is ready
-  useEffect(() => {
-    if (!host || !metadata.resourceUri || !metadata.sessionId) return;
-
-    host
-      .launch(metadata.resourceUri, metadata.sessionId)
-      .then(() => setIsLaunched(true))
-      .catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
-  }, [host, metadata.resourceUri, metadata.sessionId]);
-
-  // Send tool input when available or when it changes
-  useEffect(() => {
-    if (!host || !isLaunched || !input) return;
-    
-    // Send if never sent, or if input changed
-    if (!sentInputRef.current || JSON.stringify(input) !== JSON.stringify(lastInputRef.current)) {
-      sentInputRef.current = true;
-      lastInputRef.current = input;
-      host.sendToolInput(input);
-    }
-  }, [host, isLaunched, input]);
-
-  // Send tool result when complete or when it changes
-  useEffect(() => {
-    if (!host || !isLaunched || result === undefined) return;
-    if (status !== 'complete') return;
-
-    // Send if never sent, or if result changed
-    if (!sentResultRef.current || JSON.stringify(result) !== JSON.stringify(lastResultRef.current)) {
-      sentResultRef.current = true;
-      lastResultRef.current = result;
-      const formattedResult =
-        typeof result === 'string'
-          ? { content: [{ type: 'text', text: result }] }
-          : result;
-      host.sendToolResult(formattedResult);
-    }
-  }, [host, isLaunched, result, status]);
-
-  // Reset sent flags when tool status resets to executing (new tool call)
-  useEffect(() => {
-    if (status === 'executing' && lastStatusRef.current !== 'executing') {
-      sentInputRef.current = false;
-      sentResultRef.current = false;
-    }
-    lastStatusRef.current = status;
-  }, [status]);
-
-  // Display errors
-  const displayError = error || hostError;
-  if (displayError) {
-    return (
-      <div className={`p-4 bg-red-900/20 border border-red-700 rounded text-red-200 ${className || ''}`}>
-        Error: {displayError.message || String(displayError)}
-      </div>
-    );
-  }
-
-  return (
-    <div className={`w-full border border-gray-700 rounded overflow-hidden bg-white min-h-96 my-2 relative ${className || ''}`}>
-      <iframe
-        ref={iframeRef}
-        sandbox="allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-downloads"
-        className="w-full h-full min-h-96"
-        style={{ height: 'auto' }}
-        title="MCP App"
-      />
-      {!isLaunched && (
-        <div className="absolute inset-0 bg-gray-900/50 flex items-center justify-center pointer-events-none">
-          <div className="w-6 h-6 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
-        </div>
-      )}
-    </div>
-  );
-});
-
-/**
- * Simple hook to get MCP app metadata
- *
- * @param mcpClient - The MCP client from useMcp() or context
- * @returns Object with getAppMetadata function and McpAppRenderer component
- *
- * @example
- * ```tsx
- * function ToolRenderer(props) {
- *   const { getAppMetadata, McpAppRenderer } = useMcpApps(mcpClient);
- *   const metadata = getAppMetadata(props.name);
- *
- *   if (!metadata) return null;
- *   return (
- *     <McpAppRenderer
- *       metadata={metadata}
- *       input={props.args}
- *       result={props.result}
- *       status={props.status}
- *     />
- *   );
- * }
- * ```
- */
-export function useMcpApps(mcpClient: McpClient | null) {
-  /**
-   * Get MCP app metadata for a tool name
-   * This is fast and can be called on every render
-   */
-  const getAppMetadata = useCallback(
-    (toolName: string): McpAppMetadata | undefined => {
-      if (!mcpClient) return undefined;
-
-      const extractedName = extractToolName(toolName);
-
-      for (const conn of mcpClient.connections) {
-        for (const tool of conn.tools) {
-          const candidateName = extractToolName(tool.name);
-          // Check both locations: direct mcpApp or _meta.ui
-          const resourceUri =
-            tool.mcpApp?.resourceUri ??
-            tool._meta?.ui?.resourceUri ??
-            tool._meta?.['ui/resourceUri'];
-
-          if (resourceUri && candidateName === extractedName) {
-            return {
-              toolName: candidateName,
-              resourceUri,
-              sessionId: conn.sessionId,
-            };
-          }
-        }
-      }
-
-      return undefined;
-    },
-    [mcpClient]
-  );
-
-  return { getAppMetadata, McpAppRenderer };
-}
-
-/**
- * Extract the base tool name, removing any prefixes
- */
-function extractToolName(fullName: string): string {
-  // Handle patterns like "tool_abc123_get-time" -> "get-time"
-  const match = fullName.match(/(?:tool_[^_]+_)?(.+)$/);
-  return match?.[1] || fullName;
-}
+/**
+ * MCP Apps Hook
+ *
+ * Provides utilities for rendering interactive UI components from MCP servers.
+ */
+
+import React, { useState, useEffect, useCallback, useRef, memo } from 'react';
+import { useAppHost } from './use-app-host.js';
+import type { SSEClient } from '../core/sse-client.js';
+
+export interface McpClient {
+  connections: Array<{
+    sessionId: string;
+    tools: Array<{
+      name: string;
+      mcpApp?: {
+        resourceUri: string;
+      };
+      _meta?: {
+        ui?: {
+          resourceUri?: string;
+        };
+        'ui/resourceUri'?: string;
+      };
+    }>;
+  }>;
+  sseClient?: SSEClient | null;
+}
+
+export interface McpAppMetadata {
+  toolName: string;
+  resourceUri: string;
+  sessionId: string;
+}
+
+interface McpAppRendererProps {
+  metadata: McpAppMetadata;
+  input?: Record<string, unknown>;
+  result?: unknown;
+  status: 'executing' | 'inProgress' | 'complete' | 'idle';
+  sseClient?: SSEClient | null;
+  /** Custom CSS class for the container */
+  className?: string;
+}
+
+/**
+ * Internal component that renders the MCP app in a sandboxed iframe
+ */
+const McpAppRenderer = memo(function McpAppRenderer({
+  metadata,
+  input,
+  result,
+  status,
+  sseClient,
+  className,
+}: McpAppRendererProps) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const { host, error: hostError } = useAppHost(sseClient as SSEClient, iframeRef);
+  const [isLaunched, setIsLaunched] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Track which data has been sent to prevent duplicates
+  const sentInputRef = useRef(false);
+  const sentResultRef = useRef(false);
+  const lastInputRef = useRef(input);
+  const lastResultRef = useRef(result);
+  const lastStatusRef = useRef(status);
+
+  // Launch the app when host is ready
+  useEffect(() => {
+    if (!host || !metadata.resourceUri || !metadata.sessionId) return;
+
+    host
+      .launch(metadata.resourceUri, metadata.sessionId)
+      .then(() => setIsLaunched(true))
+      .catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
+  }, [host, metadata.resourceUri, metadata.sessionId]);
+
+  // Send tool input when available or when it changes
+  useEffect(() => {
+    if (!host || !isLaunched || !input) return;
+    
+    // Send if never sent, or if input changed
+    if (!sentInputRef.current || JSON.stringify(input) !== JSON.stringify(lastInputRef.current)) {
+      sentInputRef.current = true;
+      lastInputRef.current = input;
+      host.sendToolInput(input);
+    }
+  }, [host, isLaunched, input]);
+
+  // Send tool result when complete or when it changes
+  useEffect(() => {
+    if (!host || !isLaunched || result === undefined) return;
+    if (status !== 'complete') return;
+
+    // Send if never sent, or if result changed
+    if (!sentResultRef.current || JSON.stringify(result) !== JSON.stringify(lastResultRef.current)) {
+      sentResultRef.current = true;
+      lastResultRef.current = result;
+      const formattedResult =
+        typeof result === 'string'
+          ? { content: [{ type: 'text', text: result }] }
+          : result;
+      host.sendToolResult(formattedResult);
+    }
+  }, [host, isLaunched, result, status]);
+
+  // Reset sent flags when tool status resets to executing (new tool call)
+  useEffect(() => {
+    if (status === 'executing' && lastStatusRef.current !== 'executing') {
+      sentInputRef.current = false;
+      sentResultRef.current = false;
+    }
+    lastStatusRef.current = status;
+  }, [status]);
+
+  // Display errors
+  const displayError = error || hostError;
+  if (displayError) {
+    return (
+      <div className={`p-4 bg-red-900/20 border border-red-700 rounded text-red-200 ${className || ''}`}>
+        Error: {displayError.message || String(displayError)}
+      </div>
+    );
+  }
+
+  return (
+    <div className={`w-full border border-gray-700 rounded overflow-hidden bg-white min-h-96 my-2 relative ${className || ''}`}>
+      <iframe
+        ref={iframeRef}
+        sandbox="allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-downloads"
+        className="w-full h-full min-h-96"
+        style={{ height: 'auto' }}
+        title="MCP App"
+      />
+      {!isLaunched && (
+        <div className="absolute inset-0 bg-gray-900/50 flex items-center justify-center pointer-events-none">
+          <div className="w-6 h-6 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
+        </div>
+      )}
+    </div>
+  );
+});
+
+/**
+ * Simple hook to get MCP app metadata
+ *
+ * @param mcpClient - The MCP client from useMcp() or context
+ * @returns Object with getAppMetadata function and McpAppRenderer component
+ *
+ * @example
+ * ```tsx
+ * function ToolRenderer(props) {
+ *   const { getAppMetadata, McpAppRenderer } = useMcpApps(mcpClient);
+ *   const metadata = getAppMetadata(props.name);
+ *
+ *   if (!metadata) return null;
+ *   return (
+ *     <McpAppRenderer
+ *       metadata={metadata}
+ *       input={props.args}
+ *       result={props.result}
+ *       status={props.status}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useMcpApps(mcpClient: McpClient | null) {
+  /**
+   * Get MCP app metadata for a tool name
+   * This is fast and can be called on every render
+   */
+  const getAppMetadata = useCallback(
+    (toolName: string): McpAppMetadata | undefined => {
+      if (!mcpClient) return undefined;
+
+      const extractedName = extractToolName(toolName);
+
+      for (const conn of mcpClient.connections) {
+        for (const tool of conn.tools) {
+          const candidateName = extractToolName(tool.name);
+          // Check both locations: direct mcpApp or _meta.ui
+          const resourceUri =
+            tool.mcpApp?.resourceUri ??
+            tool._meta?.ui?.resourceUri ??
+            tool._meta?.['ui/resourceUri'];
+
+          if (resourceUri && candidateName === extractedName) {
+            return {
+              toolName: candidateName,
+              resourceUri,
+              sessionId: conn.sessionId,
+            };
+          }
+        }
+      }
+
+      return undefined;
+    },
+    [mcpClient]
+  );
+
+  return { getAppMetadata, McpAppRenderer };
+}
+
+/**
+ * Extract the base tool name, removing any prefixes
+ */
+function extractToolName(fullName: string): string {
+  // Handle patterns like "tool_abc123_get-time" -> "get-time"
+  const match = fullName.match(/(?:tool_[^_]+_)?(.+)$/);
+  return match?.[1] || fullName;
+}

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

@@ -64,6 +64,13 @@ export interface UseMcpOptions {
    * @default 60000
    */
   requestTimeout?: number;
+
+  /**
+   * Enable client debug logs.
+   * @default false
+   */
+  debug?: boolean;
+
 }
 
 export interface McpConnection {
@@ -74,8 +81,9 @@ export interface McpConnection {
   transport?: string;
   state: McpConnectionState;
   tools: ToolInfo[];
+  authUrl?: string;
   error?: string;
-  connectedAt?: Date;
+  createdAt?: Date;
 }
 
 export interface McpClient {
@@ -150,6 +158,11 @@ export interface McpClient {
    */
   finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
 
+  /**
+   * Explicitly resume OAuth flow for an existing session
+   */
+  resumeAuth: (sessionId: string) => Promise<void>;
+
   /**
    * Call a tool from a session
    */
@@ -207,6 +220,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
 
   const clientRef = useRef<SSEClient | null>(null);
   const isMountedRef = useRef(true);
+  const suppressAuthRedirectSessionsRef = useRef<Set<string>>(new Set());
 
   const [connections, setConnections] = useState<McpConnection[]>([]);
   const [status, setStatus] = useState<'connecting' | 'connected' | 'disconnected' | 'error'>(
@@ -239,7 +253,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           setStatus(newStatus);
         }
       },
-      requestTimeout: options.requestTimeout,
+      debug: options.debug,
     };
 
     const client = new SSEClient(clientOptions);
@@ -262,25 +276,52 @@ export function useMcp(options: UseMcpOptions): McpClient {
   /**
    * Update connections based on event
    */
-  const updateConnectionsFromEvent = useCallback((event: McpConnectionEvent) => {
-    if (!isMountedRef.current) return;
-
-    setConnections((prev: McpConnection[]) => {
-      switch (event.type) {
-        case 'state_changed': {
-          const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
-          if (existing) {
-            return prev.map((c: McpConnection) =>
-              c.sessionId === event.sessionId ? { ...c, state: event.state } : c
+  const updateConnectionsFromEvent = useCallback((event: McpConnectionEvent) => {
+    if (!isMountedRef.current) return;
+
+    const isTransientReconnectState = (state: McpConnectionState): boolean =>
+      state === 'INITIALIZING' ||
+      state === 'VALIDATING' ||
+      state === 'RECONNECTING' ||
+      state === 'CONNECTING' ||
+      state === 'CONNECTED' ||
+      state === 'DISCOVERING';
+
+    setConnections((prev: McpConnection[]) => {
+      switch (event.type) {
+        case 'state_changed': {
+          const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
+          if (existing) {
+            // 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
+                : event.state;
+
+            return prev.map((c: McpConnection) =>
+              c.sessionId === event.sessionId ? {
+                ...c,
+                state: nextState,
+                // update createdAt if present in event, otherwise keep existing
+                createdAt: event.createdAt ? new Date(event.createdAt) : c.createdAt
+              } : c
             );
           } else {
+            // Fix: Don't add back disconnected sessions that were just removed
+            if (event.state === 'DISCONNECTED') {
+              return prev;
+            }
+
             return [
               ...prev,
               {
                 sessionId: event.sessionId,
                 serverId: event.serverId,
                 serverName: event.serverName,
+                serverUrl: event.serverUrl,
                 state: event.state,
+                createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                 tools: [],
               },
             ];
@@ -303,14 +344,17 @@ export function useMcp(options: UseMcpOptions): McpClient {
           if (event.authUrl) {
             onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: event.authUrl });
 
-            if (onRedirect) {
-              onRedirect(event.authUrl);
-            } else if (typeof window !== 'undefined') {
-              window.location.href = event.authUrl;
+            // Suppress redirects/popups for auto-restore on page load.
+            if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
+              if (onRedirect) {
+                onRedirect(event.authUrl);
+              } else if (typeof window !== 'undefined') {
+                window.location.href = event.authUrl;
+              }
             }
           }
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING' } : c
+            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: event.authUrl } : c
           );
         }
 
@@ -328,7 +372,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           return prev;
       }
     });
-  }, [onLog]);
+  }, [onLog, onRedirect]);
 
   /**
    * Load sessions from server
@@ -351,7 +395,8 @@ export function useMcp(options: UseMcpOptions): McpClient {
             serverName: s.serverName ?? 'Unknown Server',
             serverUrl: s.serverUrl,
             transport: s.transport,
-            state: 'VALIDATING' as McpConnectionState,
+            state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+            createdAt: new Date(s.createdAt),
             tools: [],
           }))
         );
@@ -362,9 +407,16 @@ export function useMcp(options: UseMcpOptions): McpClient {
         sessions.map(async (session: SessionInfo) => {
           if (clientRef.current) {
             try {
+              // Pending auth sessions should not auto-trigger popup/redirect on reload.
+              if (session.active === false) {
+                return;
+              }
+              suppressAuthRedirectSessionsRef.current.add(session.sessionId);
               await clientRef.current.restoreSession(session.sessionId);
             } catch (error) {
               console.error(`[useMcp] Failed to validate session ${session.sessionId}:`, error);
+            } finally {
+              suppressAuthRedirectSessionsRef.current.delete(session.sessionId);
             }
           }
         })
@@ -448,6 +500,18 @@ export function useMcp(options: UseMcpOptions): McpClient {
     return await clientRef.current.finishAuth(sessionId, code);
   }, []);
 
+  /**
+   * Explicit user action to resume OAuth for an existing pending session.
+   */
+  const resumeAuth = useCallback(async (sessionId: string): Promise<void> => {
+    if (!clientRef.current) {
+      throw new Error('SSE client not initialized');
+    }
+    // Ensure this attempt is not suppressed as background restore.
+    suppressAuthRedirectSessionsRef.current.delete(sessionId);
+    await clientRef.current.restoreSession(sessionId);
+  }, []);
+
   /**
    * Call a tool
    */
@@ -565,6 +629,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
     connectSSE,
     disconnectSSE,
     finishAuth,
+    resumeAuth,
     callTool,
     listTools,
     listPrompts,