@mcp-ts/sdk 1.3.9 → 1.4.0

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

@@ -4,9 +4,21 @@
  * 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 React, {
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  memo,
+  useMemo,
+  forwardRef,
+  useImperativeHandle,
+  type MutableRefObject,
+} from 'react';
+import { useAppHost, type UseAppHostOptions } from './use-app-host.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';
 
 export interface McpClient {
   connections: Array<{
@@ -33,100 +45,211 @@ export interface McpAppMetadata {
   sessionId: string;
 }
 
-interface McpAppRendererProps {
-  mcpClient: McpClient | null;
+/**
+ * Imperative handle for {@link useMcpApps}'s `McpAppRenderer` (via `ref`),
+ * aligned with `@mcp-ui/client`'s `AppRendererHandle.teardownResource`.
+ */
+export interface McpAppRendererHandle {
+  teardownResource: (params?: Record<string, unknown>) => void;
+}
+
+/** 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;
+  toolResourceUri?: string;
+  html?: string;
   input?: Record<string, unknown>;
   result?: unknown;
-  status: 'executing' | 'inProgress' | 'complete' | 'idle';
-  /** Custom CSS class for the container */
+  status?: 'executing' | 'inProgress' | 'complete' | 'idle';
+  toolInputPartial?: any;
+  toolCancelled?: boolean;
   className?: string;
+  loader?: React.ReactNode;
 }
 
-/**
- * Simplified MCP App renderer - users just pass tool name and data
- * Internal hook handles metadata lookup and SSE client retrieval
- */
-const McpAppRenderer = memo(function McpAppRenderer({
-  mcpClient,
-  name,
-  input,
-  result,
-  status,
-  className,
-}: McpAppRendererProps) {
-  const getAppMetadata = useCallback((): McpAppMetadata | undefined => {
-    if (!mcpClient) return undefined;
-
-    const extractedName = extractToolName(name);
-
-    for (const conn of mcpClient.connections) {
-      for (const tool of conn.tools) {
-        const candidateName = extractToolName(tool.name);
-        const resourceUri =
-          tool.mcpApp?.resourceUri ??
-          tool._meta?.ui?.resourceUri ??
-          tool._meta?.['ui/resourceUri'];
-
-        if (resourceUri && candidateName === extractedName) {
-          return {
-            toolName: candidateName,
-            resourceUri,
-            sessionId: conn.sessionId,
-          };
+type McpAppViewProps = McpAppRendererProps & {
+  /**
+   * Ref avoids tying `McpAppRenderer` identity to `mcpClient`: when `connections` updates, `useMcp()` still
+   * returns a new object (correct for `useEffect` deps), but the iframe must not remount.
+   */
+  clientRef: MutableRefObject<McpClient | null>;
+};
+
+/** Renders one MCP App in a sandboxed iframe; reads the latest client from `clientRef` each render. */
+const McpAppViewInner = forwardRef<McpAppRendererHandle, McpAppViewProps>(function McpAppView(
+  {
+    clientRef,
+    name,
+    toolResourceUri,
+    html,
+    input,
+    result,
+    status = 'idle',
+    toolInputPartial,
+    toolCancelled,
+    sandbox,
+    hostContext,
+    onCallTool,
+    onReadResource,
+    onFallbackRequest,
+    onMessage,
+    onOpenLink,
+    onLoggingMessage,
+    onSizeChanged,
+    onError: onHostError,
+    className,
+    loader,
+  },
+  ref,
+) {
+  const mcpClient = clientRef.current;
+  const metadata = getMcpAppMetadata(mcpClient, name);
+  const sseClient = mcpClient?.sseClient ?? null;
+  const resourceUri = toolResourceUri || metadata?.resourceUri;
+  const appSessionId = metadata?.sessionId;
+
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Tracks the last height (px) reported by the guest before/after fullscreen so we
+  // can restore it when the native fullscreen API exits and the guest fires a stale
+  // resize event that would otherwise collapse the iframe to 0.
+  const preFullscreenHeightRef = useRef<number | null>(null);
+  const displayModeRef = useRef<'inline' | 'fullscreen'>('inline');
+  const [displayMode, setDisplayMode] = useState<'inline' | 'fullscreen'>('inline');
+
+  const setDisplayModeWithRef = (mode: 'inline' | 'fullscreen') => {
+    displayModeRef.current = mode;
+    setDisplayMode(mode);
+  };
+
+  const { host, error: hostError } = useAppHost(sseClient as any, iframeRef, {
+    sandbox,
+    hostContext,
+    onCallTool,
+    onReadResource,
+    onFallbackRequest,
+    onMessage,
+    onOpenLink,
+    onLoggingMessage,
+    // Intercept onSizeChanged: when exiting fullscreen, ignore guest resize events
+    // that arrive with the shrunken viewport dimensions, and restore the pre-fullscreen height.
+    onSizeChanged: (params) => {
+      if (displayModeRef.current === 'inline' && preFullscreenHeightRef.current !== null) {
+        // Guest fired a resize right after fullscreen exit – restore the saved height
+        const savedHeight = preFullscreenHeightRef.current;
+        preFullscreenHeightRef.current = null;
+        if (iframeRef.current) {
+          iframeRef.current.style.height = `${savedHeight}px`;
+        }
+        return;
+      }
+      onSizeChanged?.(params);
+    },
+    onError: onHostError,
+    onRequestDisplayMode: async (params) => {
+      if (params.mode === 'fullscreen') {
+        // Snapshot current iframe height so we can restore on exit
+        if (iframeRef.current) {
+          const h = iframeRef.current.getBoundingClientRect().height;
+          if (h > 0) preFullscreenHeightRef.current = h;
+        }
+        try {
+          if (containerRef.current?.requestFullscreen) {
+            await containerRef.current.requestFullscreen();
+          } else if ((containerRef.current as any)?.webkitRequestFullscreen) {
+            await (containerRef.current as any).webkitRequestFullscreen();
+          }
+          setDisplayModeWithRef('fullscreen');
+        } catch (err) {
+          console.warn('[McpAppHost] requestFullscreen failed:', err);
+          preFullscreenHeightRef.current = null;
+          return { mode: 'inline' };
         }
+      } else if (params.mode === 'inline') {
+        // Eagerly restore height — don't wait for a guest onsizechange that may never arrive
+        restoreHeightAfterFullscreen();
+        try {
+          if (document.fullscreenElement) {
+            await document.exitFullscreen();
+          }
+        } catch (err) {}
+        setDisplayModeWithRef('inline');
       }
+      return { mode: params.mode };
     }
+  });
 
-    return undefined;
-  }, [mcpClient, name]);
-
-  const metadata = getAppMetadata();
-  const sseClient = mcpClient?.sseClient ?? null;
+  useImperativeHandle(
+    ref,
+    () => ({
+      teardownResource: (params?: Record<string, unknown>) => {
+        host?.teardownResource(params ?? {});
+      },
+    }),
+    [host],
+  );
 
-  if (!metadata || !sseClient) {
-    return null;
-  }
-  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;
+    setIsLaunched(false);
+    setError(null);
+  }, [resourceUri, appSessionId]);
+
+  // Eagerly restore the iframe's pre-fullscreen height at every exit point.
+  // The guest app may NOT fire onSizeChanged after exiting fullscreen, so we cannot
+  // rely on the onSizeChanged interceptor to restore the height.
+  const restoreHeightAfterFullscreen = () => {
+    const savedHeight = preFullscreenHeightRef.current;
+    if (savedHeight && iframeRef.current) {
+      iframeRef.current.style.height = `${savedHeight}px`;
+    }
+    preFullscreenHeightRef.current = null;
+  };
+
+  useEffect(() => {
+    const onFullscreenChange = () => {
+      const isFullscreen = !!document.fullscreenElement;
+      // Use ref to avoid stale closure (ESC key exit path)
+      if (!isFullscreen && displayModeRef.current === 'fullscreen') {
+        restoreHeightAfterFullscreen();
+        setDisplayModeWithRef('inline');
+      }
+    };
+    document.addEventListener('fullscreenchange', onFullscreenChange);
+    return () => document.removeEventListener('fullscreenchange', onFullscreenChange);
+  }, []); // stable – reads from refs only, no stale closure over state
+
+  useEffect(() => {
+    if (!host || (!resourceUri && !html)) return;
 
     host
-      .launch(metadata.resourceUri, metadata.sessionId)
+      .launch({ uri: resourceUri, html }, appSessionId)
       .then(() => setIsLaunched(true))
       .catch((err) => setError(err instanceof Error ? err : new Error(String(err))));
-  }, [host, metadata.resourceUri, metadata.sessionId]);
+  }, [host, resourceUri, html, appSessionId]);
 
-  // Send tool input when available or when it changes
   useEffect(() => {
-    if (!host || !isLaunched || !input) return;
-    
-    // Send if never sent, or if input changed
+    if (!host || !isLaunched || !resourceUri || !appSessionId || !input) return;
+
     if (!sentInputRef.current || JSON.stringify(input) !== JSON.stringify(lastInputRef.current)) {
       sentInputRef.current = true;
       lastInputRef.current = input;
       host.sendToolInput(input);
     }
-  }, [host, isLaunched, input]);
+  }, [host, isLaunched, input, resourceUri, appSessionId, name]);
 
-  // Send tool result when complete or when it changes
   useEffect(() => {
-    if (!host || !isLaunched || result === undefined) return;
+    if (!host || !isLaunched || !resourceUri || !appSessionId || 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;
@@ -136,9 +259,8 @@ const McpAppRenderer = memo(function McpAppRenderer({
           : result;
       host.sendToolResult(formattedResult);
     }
-  }, [host, isLaunched, result, status]);
+  }, [host, isLaunched, result, status, resourceUri, appSessionId, name]);
 
-  // Reset sent flags when tool status resets to executing (new tool call)
   useEffect(() => {
     if (status === 'executing' && lastStatusRef.current !== 'executing') {
       sentInputRef.current = false;
@@ -147,7 +269,33 @@ const McpAppRenderer = memo(function McpAppRenderer({
     lastStatusRef.current = status;
   }, [status]);
 
-  // Display errors
+  useEffect(() => {
+    if (!host) return;
+    // Merge user-provided hostContext with our internal displayMode, then notify the guest.
+    // This causes Excalidraw (and other MCP apps) to switch between inline/fullscreen UI mode.
+    const mergedCtx = {
+      theme: APP_HOST_DEFAULTS.THEME,
+      platform: APP_HOST_DEFAULTS.PLATFORM,
+      containerDimensions: { maxHeight: APP_HOST_DEFAULTS.MAX_HEIGHT },
+      availableDisplayModes: ['inline', 'fullscreen'],
+      ...(hostContext || {}),
+      displayMode, // always override with our authoritative state
+    };
+    host.setHostContext(mergedCtx);
+  }, [host, hostContext, displayMode]);
+
+  useEffect(() => {
+    if (host && toolInputPartial) host.sendToolInputPartial(toolInputPartial);
+  }, [host, toolInputPartial]);
+
+  useEffect(() => {
+    if (host && toolCancelled) host.sendToolCancelled("User cancelled");
+  }, [host, toolCancelled]);
+
+  if (!metadata && !html && !toolResourceUri) {
+    return null;
+  }
+
   const displayError = error || hostError;
   if (displayError) {
     return (
@@ -157,91 +305,115 @@ const McpAppRenderer = memo(function McpAppRenderer({
     );
   }
 
+  const opacityClass = isLaunched ? 'opacity-100' : 'opacity-0';
+  let containerClass = `w-full border border-gray-700 rounded bg-transparent my-2 relative ${className || ''}`;
+  let iframeClass = `w-full transition-opacity duration-300 ${opacityClass}`;
+
+  // When native fullscreen is active, the container naturally expands via the browser API.
+  // We only need to satisfy flex layout so the iframe fills 100% of the fullscreen viewport.
+  if (displayMode === 'fullscreen') {
+    containerClass = `w-full h-full bg-black m-0 p-0 flex flex-col relative`;
+    iframeClass = `w-full flex-1 transition-opacity duration-300 ${opacityClass}`;
+  }
+
   return (
-    <div className={`w-full border border-gray-700 rounded overflow-hidden bg-white min-h-96 my-2 relative ${className || ''}`}>
+    <div ref={containerRef} className={containerClass}>
+      {displayMode === 'fullscreen' && (
+        <div className="absolute top-0 right-0 p-2 z-[100000] w-full bg-gradient-to-b from-black/80 to-transparent flex justify-end">
+          <button 
+            title="Exit Fullscreen"
+            onClick={() => {
+              // Eagerly restore height before the browser animation completes
+              restoreHeightAfterFullscreen();
+              if (document.fullscreenElement) document.exitFullscreen();
+              setDisplayModeWithRef('inline');
+            }} 
+            className="px-4 py-2 bg-gray-800 hover:bg-gray-700 text-white rounded-md shadow flex items-center gap-2 border border-gray-600 transition-colors"
+          >
+            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M8 3v3a2 2 0 0 1-2 2H3m18 0h-3a2 2 0 0 1-2-2V3m0 18v-3a2 2 0 0 1 2-2h3M3 16h3a2 2 0 0 1 2 2v3"/></svg>
+            <span className="text-sm font-medium">Exit</span>
+          </button>
+        </div>
+      )}
       <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' }}
+        allow="fullscreen"
+        className={iframeClass}
         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" />
+      {!isLaunched && loader && (
+        <div className="absolute inset-0 bg-transparent flex items-center justify-center pointer-events-none z-10">
+          {loader}
         </div>
       )}
     </div>
   );
 });
 
+const McpAppView = memo(McpAppViewInner);
+McpAppView.displayName = 'McpAppView';
+
 /**
- * Simple hook to get MCP app metadata
- *
- * @param mcpClient - The MCP client from useMcp() or context
- * @returns Object with getAppMetadata function and McpAppRenderer component
+ * Helpers scoped to one `mcpClient`. Pass the client here once; `McpAppRenderer` only needs per-tool props (`name`, `input`, `result`, `status`).
  *
- * @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}
- *     />
- *   );
- * }
- * ```
+ * @param mcpClient - From `useMcp()` or context (for example `useMcpContext()`).
  */
 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,
-            };
-          }
-        }
-      }
+  // Stable `McpAppRenderer` type: parent re-renders and `connections` updates must not remount the iframe.
+  const clientRef = useRef(mcpClient);
+  clientRef.current = mcpClient;
 
-      return undefined;
-    },
-    [mcpClient]
+  const getAppMetadata = useCallback(
+    (toolName: string) => getMcpAppMetadata(clientRef.current, toolName),
+    []
   );
 
+  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 };
 }
 
-/**
- * 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;
 }
+
+function getMcpAppMetadata(
+  mcpClient: McpClient | null,
+  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);
+      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;
+}

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

@@ -4,7 +4,7 @@
  * Based on Cloudflare's agents pattern
  */
 
-import { useEffect, useRef, useState, useCallback } from 'react';
+import { useEffect, useRef, useState, useCallback, useMemo } from 'react';
 import { SSEClient, type SSEClientOptions } from '../core/sse-client';
 import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
 import type {
@@ -227,6 +227,8 @@ export function useMcp(options: UseMcpOptions): McpClient {
     'disconnected'
   );
   const [isInitializing, setIsInitializing] = useState(false);
+  /** Mirrored from `clientRef` so the public `McpClient` object can be memoized when the instance is ready. */
+  const [sseClient, setSseClient] = useState<SSEClient | null>(null);
 
   /**
    * Initialize SSE client
@@ -258,6 +260,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
 
     const client = new SSEClient(clientOptions);
     clientRef.current = client;
+    setSseClient(client);
 
     if (autoConnect) {
       client.connect();
@@ -340,21 +343,32 @@ export function useMcp(options: UseMcpOptions): McpClient {
         }
 
         case 'auth_required': {
-          // Handle OAuth redirect
-          if (event.authUrl) {
-            onLog?.('info', `OAuth required - redirecting to ${event.authUrl}`, { authUrl: 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;
-              }
+          const url = (event.authUrl || '').trim();
+          if (!url) {
+            onLog?.('error', 'OAuth required but authorization URL is missing', { sessionId: event.sessionId });
+            return prev.map((c: McpConnection) =>
+              c.sessionId === event.sessionId
+                ? {
+                    ...c,
+                    state: 'FAILED',
+                    error: 'OAuth authorization URL not available',
+                    authUrl: undefined,
+                  }
+                : c
+            );
+          }
+          onLog?.('info', `OAuth required - redirecting to ${url}`, { authUrl: url });
+
+          // Suppress redirects/popups for auto-restore on page load.
+          if (!suppressAuthRedirectSessionsRef.current.has(event.sessionId)) {
+            if (onRedirect) {
+              onRedirect(url);
+            } else if (typeof window !== 'undefined') {
+              window.location.href = url;
             }
           }
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: event.authUrl } : c
+            c.sessionId === event.sessionId ? { ...c, state: 'AUTHENTICATING', authUrl: url } : c
           );
         }
 
@@ -615,27 +629,52 @@ export function useMcp(options: UseMcpOptions): McpClient {
     [getConnection]
   );
 
-  return {
-    connections,
-    status,
-    isInitializing,
-    connect,
-    disconnect,
-    getConnection,
-    getConnectionByServerId,
-    isServerConnected,
-    getTools,
-    refresh,
-    connectSSE,
-    disconnectSSE,
-    finishAuth,
-    resumeAuth,
-    callTool,
-    listTools,
-    listPrompts,
-    getPrompt,
-    listResources,
-    readResource,
-    sseClient: clientRef.current,
-  };
+  return useMemo(
+    () => ({
+      connections,
+      status,
+      isInitializing,
+      connect,
+      disconnect,
+      getConnection,
+      getConnectionByServerId,
+      isServerConnected,
+      getTools,
+      refresh,
+      connectSSE,
+      disconnectSSE,
+      finishAuth,
+      resumeAuth,
+      callTool,
+      listTools,
+      listPrompts,
+      getPrompt,
+      listResources,
+      readResource,
+      sseClient,
+    }),
+    [
+      connections,
+      status,
+      isInitializing,
+      connect,
+      disconnect,
+      getConnection,
+      getConnectionByServerId,
+      isServerConnected,
+      getTools,
+      refresh,
+      connectSSE,
+      disconnectSSE,
+      finishAuth,
+      resumeAuth,
+      callTool,
+      listTools,
+      listPrompts,
+      getPrompt,
+      listResources,
+      readResource,
+      sseClient,
+    ]
+  );
 }