@mcp-ts/sdk 1.0.0 → 1.1.0

package/src/client/core/types.ts

@@ -0,0 +1,31 @@
+import { SessionListResult } from '../../shared/types';
+
+/**
+ * Abstraction layer for the AppHost's network communication.
+ * 
+ * This interface decouples the `AppHost` from the concrete networking implementation (like `SSEClient`).
+ * Implementation can be:
+ * 1. `SSEClient`: Direct connection to MCP Server (Browser -> Server).
+ * 2. `ProxyClient`: Connection via an intermediary API (Browser -> Next.js API -> Server).
+ */
+export interface AppHostClient {
+    /**
+     * Check if the client is connected
+     */
+    isConnected(): boolean;
+
+    /**
+     * Get list of active sessions
+     */
+    getSessions(): Promise<SessionListResult>;
+
+    /**
+     * Call a tool on a specific session
+     */
+    callTool(sessionId: string, toolName: string, toolArgs: Record<string, unknown>): Promise<unknown>;
+
+    /**
+     * Read a resource from a specific session
+     */
+    readResource(sessionId: string, uri: string): Promise<unknown>;
+}

package/src/client/index.ts

@@ -5,6 +5,7 @@
 
 /** SSE client for real-time connections */
 export { SSEClient, type SSEClientOptions } from './core/sse-client';
+export { AppHost } from './core/app-host';
 
 
 

package/src/client/react/index.ts

@@ -5,6 +5,7 @@
 
 // React Hook
 export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './useMcp';
+export { useMcpApp } from './use-mcp-app';
 
 // Re-export shared types and client from main entry
 export * from '../index';

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

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import type { SSEClient } from '../core/sse-client';
+import { AppHost } from '../core/app-host';
+
+/**
+ * Hook to host an MCP App in a React component
+ *
+ * Optimized for instant loading:
+ * - Creates AppHost synchronously
+ * - Starts bridge connection immediately
+ * - Returns host before connection completes (ready to call launch)
+ *
+ * @param client - Connected SSEClient instance
+ * @param iframeRef - Reference to the iframe element
+ * @param options - Optional configuration
+ * @returns Object containing the AppHost instance (or null) and error state
+ */
+export function useMcpApp(
+    client: SSEClient,
+    iframeRef: React.RefObject<HTMLIFrameElement>,
+    options?: {
+        /** Callback when the App sends a message (e.g. to chat) */
+        onMessage?: (params: { role: string; content: unknown }) => void;
+    }
+) {
+    const [host, setHost] = useState<AppHost | null>(null);
+    const [error, setError] = useState<Error | null>(null);
+    const initializingRef = useRef(false);
+
+    // Store latest callback in ref to avoid re-initializing AppHost on callback change
+    const onMessageRef = useRef(options?.onMessage);
+    useEffect(() => {
+        onMessageRef.current = options?.onMessage;
+    }, [options?.onMessage]);
+
+    useEffect(() => {
+        if (!client || !iframeRef.current || initializingRef.current) return;
+
+        // Prevent double initialization in strict mode
+        initializingRef.current = true;
+
+        const initHost = async () => {
+            try {
+                // Initialize AppHost with security enforcement
+                const appHost = new AppHost(client, iframeRef.current!);
+
+                // Register message handler
+                appHost.onAppMessage = (params) => {
+                    onMessageRef.current?.(params);
+                };
+
+                // Set host immediately so launch can be called
+                // (launch will wait for bridge if needed)
+                setHost(appHost);
+
+                // Start bridge connection (this is fast, just sets up PostMessage)
+                await appHost.start();
+            } catch (err) {
+                console.error('[useMcpApp] Failed to initialize AppHost:', err);
+                setError(err instanceof Error ? err : new Error(String(err)));
+            }
+        };
+
+        initHost();
+
+        return () => {
+            initializingRef.current = false;
+            setHost(null);
+        };
+    }, [client, iframeRef]);
+
+    return { host, error };
+}

package/src/client/react/useMcp.ts

@@ -58,6 +58,12 @@ export interface UseMcpOptions {
    * If provided, this will be called instead of window.location.href assignment
    */
   onRedirect?: (url: string) => void;
+
+  /**
+   * Request timeout in milliseconds
+   * @default 60000
+   */
+  requestTimeout?: number;
 }
 
 export interface McpConnection {
@@ -177,6 +183,11 @@ export interface McpClient {
    * Read a specific resource
    */
   readResource: (sessionId: string, uri: string) => Promise<unknown>;
+
+  /**
+   * Access the underlying SSEClient instance (for advanced usage like AppHost)
+   */
+  client: SSEClient | null;
 }
 
 /**
@@ -228,6 +239,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           setStatus(newStatus);
         }
       },
+      requestTimeout: options.requestTimeout,
     };
 
     const client = new SSEClient(clientOptions);
@@ -276,6 +288,11 @@ export function useMcp(options: UseMcpOptions): McpClient {
         }
 
         case 'tools_discovered': {
+          // Preload UI resources for instant loading when tools are discovered
+          if (clientRef.current && event.tools?.length) {
+            clientRef.current.preloadToolUiResources(event.sessionId, event.tools);
+          }
+
           return prev.map((c: McpConnection) =>
             c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY' } : c
           );
@@ -554,5 +571,6 @@ export function useMcp(options: UseMcpOptions): McpClient {
     getPrompt,
     listResources,
     readResource,
+    client: clientRef.current,
   };
 }

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

@@ -100,9 +100,6 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
       });
     };
 
-    // Send initial connection event
-    sendSSE('connected', { timestamp: Date.now() });
-
     // Clean up previous manager if exists (prevents memory leaks on reconnect)
     const previousManager = managers.get(identity);
     if (previousManager) {
@@ -138,6 +135,10 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
 
     managers.set(identity, manager);
 
+    // Send connected event AFTER manager is registered (prevents race condition
+    // where client sends POST before manager is available)
+    sendSSE('connected', { timestamp: Date.now() });
+
     // Handle client disconnect
     const abortController = new AbortController();
     request.signal?.addEventListener('abort', () => {
@@ -194,11 +195,11 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
         );
       }
 
-      // Handle the request - response will be sent via SSE
-      await manager.handleRequest(body);
+      // Handle the request and return response directly (bypasses SSE latency)
+      const response = await manager.handleRequest(body);
 
-      // Return acknowledgment (actual response goes through SSE)
-      return Response.json({ acknowledged: true });
+      // Return the actual RPC response for immediate use by client
+      return Response.json(response);
     } catch (error) {
       return Response.json(
         {