@mcp-ts/sdk 1.0.0 → 1.1.0

package/dist/client/react.js

@@ -2,24 +2,30 @@
 
 var react = require('react');
 var nanoid = require('nanoid');
+var appBridge = require('@modelcontextprotocol/ext-apps/app-bridge');
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var DEFAULT_REQUEST_TIMEOUT = 6e4;
+var MAX_RECONNECT_ATTEMPTS = 5;
+var BASE_RECONNECT_DELAY = 1e3;
 var SSEClient = class {
   constructor(options) {
     this.options = options;
     __publicField(this, "eventSource", null);
     __publicField(this, "pendingRequests", /* @__PURE__ */ new Map());
+    __publicField(this, "resourceCache", /* @__PURE__ */ new Map());
     __publicField(this, "reconnectAttempts", 0);
-    __publicField(this, "maxReconnectAttempts", 5);
-    __publicField(this, "reconnectDelay", 1e3);
     __publicField(this, "isManuallyDisconnected", false);
     __publicField(this, "connectionPromise", null);
     __publicField(this, "connectionResolver", null);
   }
+  // ============================================
+  // Connection Management
+  // ============================================
   /**
-   * Connect to SSE endpoint
+   * Connect to the SSE endpoint
    */
   connect() {
     if (this.eventSource) {
@@ -30,52 +36,12 @@ var SSEClient = class {
     this.connectionPromise = new Promise((resolve) => {
       this.connectionResolver = resolve;
     });
-    const url = new URL(this.options.url, typeof window !== "undefined" ? window.location.origin : void 0);
-    url.searchParams.set("identity", this.options.identity);
-    if (this.options.authToken) {
-      url.searchParams.set("token", this.options.authToken);
-    }
-    this.eventSource = new EventSource(url.toString());
-    this.eventSource.addEventListener("open", () => {
-      console.log("[SSEClient] Connected");
-      this.reconnectAttempts = 0;
-      this.options.onStatusChange?.("connected");
-    });
-    this.eventSource.addEventListener("connected", (e) => {
-      const data = JSON.parse(e.data);
-      console.log("[SSEClient] Server ready:", data);
-      if (this.connectionResolver) {
-        this.connectionResolver();
-        this.connectionResolver = null;
-      }
-    });
-    this.eventSource.addEventListener("connection", (e) => {
-      const event = JSON.parse(e.data);
-      this.options.onConnectionEvent?.(event);
-    });
-    this.eventSource.addEventListener("observability", (e) => {
-      const event = JSON.parse(e.data);
-      this.options.onObservabilityEvent?.(event);
-    });
-    this.eventSource.addEventListener("rpc-response", (e) => {
-      const response = JSON.parse(e.data);
-      this.handleRpcResponse(response);
-    });
-    this.eventSource.addEventListener("error", () => {
-      console.error("[SSEClient] Connection error");
-      this.options.onStatusChange?.("error");
-      if (!this.isManuallyDisconnected && this.reconnectAttempts < this.maxReconnectAttempts) {
-        this.reconnectAttempts++;
-        console.log(`[SSEClient] Reconnecting (attempt ${this.reconnectAttempts})...`);
-        setTimeout(() => {
-          this.disconnect();
-          this.connect();
-        }, this.reconnectDelay * this.reconnectAttempts);
-      }
-    });
+    const url = this.buildUrl();
+    this.eventSource = new EventSource(url);
+    this.setupEventListeners();
   }
   /**
-   * Disconnect from SSE endpoint
+   * Disconnect from the SSE endpoint
    */
   disconnect() {
     this.isManuallyDisconnected = true;
@@ -85,139 +51,281 @@ var SSEClient = class {
     }
     this.connectionPromise = null;
     this.connectionResolver = null;
-    for (const [id, { reject }] of this.pendingRequests.entries()) {
-      const error = new Error("Connection closed");
-      error.name = "ConnectionClosedError";
-      reject(error);
-    }
-    this.pendingRequests.clear();
+    this.rejectAllPendingRequests(new Error("Connection closed"));
     this.options.onStatusChange?.("disconnected");
   }
   /**
-   * Send RPC request via SSE
-   * Note: SSE is unidirectional (server->client), so we need to send requests via POST
-   */
-  async sendRequest(method, params) {
-    if (this.connectionPromise) {
-      await this.connectionPromise;
-    }
-    const id = `rpc_${nanoid.nanoid(10)}`;
-    const request = {
-      id,
-      method,
-      params
-    };
-    const promise = new Promise((resolve, reject) => {
-      this.pendingRequests.set(id, { resolve, reject });
-      setTimeout(() => {
-        if (this.pendingRequests.has(id)) {
-          this.pendingRequests.delete(id);
-          reject(new Error("Request timeout"));
-        }
-      }, 3e4);
-    });
-    try {
-      const url = new URL(this.options.url, typeof window !== "undefined" ? window.location.origin : void 0);
-      url.searchParams.set("identity", this.options.identity);
-      await fetch(url.toString(), {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...this.options.authToken && { Authorization: `Bearer ${this.options.authToken}` }
-        },
-        body: JSON.stringify(request)
-      });
-    } catch (error) {
-      this.pendingRequests.delete(id);
-      throw error;
-    }
-    return promise;
-  }
-  /**
-   * Handle RPC response
+   * Check if connected to the SSE endpoint
    */
-  handleRpcResponse(response) {
-    const pending = this.pendingRequests.get(response.id);
-    if (pending) {
-      this.pendingRequests.delete(response.id);
-      if (response.error) {
-        pending.reject(new Error(response.error.message));
-      } else {
-        pending.resolve(response.result);
-      }
-    }
+  isConnected() {
+    return this.eventSource?.readyState === EventSource.OPEN;
   }
-  /**
-   * Get all user sessions
-   */
+  // ============================================
+  // RPC Methods
+  // ============================================
   async getSessions() {
     return this.sendRequest("getSessions");
   }
-  /**
-   * Connect to an MCP server
-   */
   async connectToServer(params) {
     return this.sendRequest("connect", params);
   }
-  /**
-   * Disconnect from an MCP server
-   */
   async disconnectFromServer(sessionId) {
     return this.sendRequest("disconnect", { sessionId });
   }
-  /**
-   * List tools from a session
-   */
   async listTools(sessionId) {
     return this.sendRequest("listTools", { sessionId });
   }
+  async callTool(sessionId, toolName, toolArgs) {
+    const result = await this.sendRequest("callTool", { sessionId, toolName, toolArgs });
+    this.emitUiEventIfPresent(result, sessionId, toolName);
+    return result;
+  }
+  async restoreSession(sessionId) {
+    return this.sendRequest("restoreSession", { sessionId });
+  }
+  async finishAuth(sessionId, code) {
+    return this.sendRequest("finishAuth", { sessionId, code });
+  }
+  async listPrompts(sessionId) {
+    return this.sendRequest("listPrompts", { sessionId });
+  }
+  async getPrompt(sessionId, name, args) {
+    return this.sendRequest("getPrompt", { sessionId, name, args });
+  }
+  async listResources(sessionId) {
+    return this.sendRequest("listResources", { sessionId });
+  }
+  async readResource(sessionId, uri) {
+    return this.sendRequest("readResource", { sessionId, uri });
+  }
+  // ============================================
+  // Resource Preloading (for instant UI loading)
+  // ============================================
   /**
-   * Call a tool
+   * Preload UI resources for tools that have UI metadata.
+   * Call this when tools are discovered to enable instant MCP App UI loading.
    */
-  async callTool(sessionId, toolName, toolArgs) {
-    return this.sendRequest("callTool", { sessionId, toolName, toolArgs });
+  preloadToolUiResources(sessionId, tools) {
+    for (const tool of tools) {
+      const uri = this.extractUiResourceUri(tool);
+      if (!uri) continue;
+      if (this.resourceCache.has(uri)) {
+        this.log(`Resource already cached: ${uri}`);
+        continue;
+      }
+      this.log(`Preloading UI resource for tool "${tool.name}": ${uri}`);
+      const promise = this.sendRequest("readResource", { sessionId, uri }).catch((err) => {
+        this.log(`Failed to preload resource ${uri}: ${err.message}`, "warn");
+        this.resourceCache.delete(uri);
+        return null;
+      });
+      this.resourceCache.set(uri, promise);
+    }
   }
   /**
-   * Refresh/validate a session
+   * Get a preloaded resource from cache, or fetch if not cached.
    */
-  async restoreSession(sessionId) {
-    return this.sendRequest("restoreSession", { sessionId });
+  getOrFetchResource(sessionId, uri) {
+    const cached = this.resourceCache.get(uri);
+    if (cached) {
+      this.log(`Cache hit for resource: ${uri}`);
+      return cached;
+    }
+    this.log(`Cache miss, fetching resource: ${uri}`);
+    const promise = this.sendRequest("readResource", { sessionId, uri });
+    this.resourceCache.set(uri, promise);
+    return promise;
   }
   /**
-   * Complete OAuth authorization
+   * Check if a resource is already cached
    */
-  async finishAuth(sessionId, code) {
-    return this.sendRequest("finishAuth", { sessionId, code });
+  hasPreloadedResource(uri) {
+    return this.resourceCache.has(uri);
   }
   /**
-   * List available prompts
+   * Clear the resource cache
    */
-  async listPrompts(sessionId) {
-    return this.sendRequest("listPrompts", { sessionId });
+  clearResourceCache() {
+    this.resourceCache.clear();
   }
+  // ============================================
+  // Private: Request Handling
+  // ============================================
   /**
-   * Get a specific prompt with arguments
+   * Send an RPC request and return the response directly from HTTP.
+   * This bypasses SSE latency by returning results in the HTTP response body.
    */
-  async getPrompt(sessionId, name, args) {
-    return this.sendRequest("getPrompt", { sessionId, name, args });
+  async sendRequest(method, params) {
+    if (this.connectionPromise) {
+      await this.connectionPromise;
+    }
+    const request = {
+      id: `rpc_${nanoid.nanoid(10)}`,
+      method,
+      params
+    };
+    const response = await fetch(this.buildUrl(), {
+      method: "POST",
+      headers: this.buildHeaders(),
+      body: JSON.stringify(request)
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return this.parseRpcResponse(data, request.id);
   }
   /**
-   * List available resources
+   * Parse RPC response and handle different response formats
    */
-  async listResources(sessionId) {
-    return this.sendRequest("listResources", { sessionId });
+  parseRpcResponse(data, requestId) {
+    if ("result" in data) {
+      return data.result;
+    }
+    if ("error" in data && data.error) {
+      throw new Error(data.error.message || "Unknown RPC error");
+    }
+    if ("acknowledged" in data) {
+      return this.waitForSseResponse(requestId);
+    }
+    throw new Error("Invalid RPC response format");
   }
   /**
-   * Read a specific resource
+   * Wait for RPC response via SSE (legacy fallback)
    */
-  async readResource(sessionId, uri) {
-    return this.sendRequest("readResource", { sessionId, uri });
+  waitForSseResponse(requestId) {
+    const timeoutMs = this.options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error(`Request timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pendingRequests.set(requestId, {
+        resolve,
+        reject,
+        timeoutId
+      });
+    });
   }
   /**
-   * Check if connected
+   * Handle RPC response received via SSE (legacy)
    */
-  isConnected() {
-    return this.eventSource !== null && this.eventSource.readyState === EventSource.OPEN;
+  handleRpcResponse(response) {
+    const pending = this.pendingRequests.get(response.id);
+    if (!pending) return;
+    clearTimeout(pending.timeoutId);
+    this.pendingRequests.delete(response.id);
+    if (response.error) {
+      pending.reject(new Error(response.error.message));
+    } else {
+      pending.resolve(response.result);
+    }
+  }
+  // ============================================
+  // Private: Event Handling
+  // ============================================
+  setupEventListeners() {
+    if (!this.eventSource) return;
+    this.eventSource.addEventListener("open", () => {
+      this.log("Connected");
+      this.reconnectAttempts = 0;
+      this.options.onStatusChange?.("connected");
+    });
+    this.eventSource.addEventListener("connected", () => {
+      this.log("Server ready");
+      this.connectionResolver?.();
+      this.connectionResolver = null;
+    });
+    this.eventSource.addEventListener("connection", (e) => {
+      const event = JSON.parse(e.data);
+      this.options.onConnectionEvent?.(event);
+    });
+    this.eventSource.addEventListener("observability", (e) => {
+      const event = JSON.parse(e.data);
+      this.options.onObservabilityEvent?.(event);
+    });
+    this.eventSource.addEventListener("rpc-response", (e) => {
+      const response = JSON.parse(e.data);
+      this.handleRpcResponse(response);
+    });
+    this.eventSource.addEventListener("error", () => {
+      this.log("Connection error", "error");
+      this.options.onStatusChange?.("error");
+      this.attemptReconnect();
+    });
+  }
+  attemptReconnect() {
+    if (this.isManuallyDisconnected || this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      return;
+    }
+    this.reconnectAttempts++;
+    const delay = BASE_RECONNECT_DELAY * this.reconnectAttempts;
+    this.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})`);
+    setTimeout(() => {
+      this.disconnect();
+      this.connect();
+    }, delay);
+  }
+  // ============================================
+  // Private: Utilities
+  // ============================================
+  buildUrl() {
+    const url = new URL(this.options.url, globalThis.location?.origin);
+    url.searchParams.set("identity", this.options.identity);
+    if (this.options.authToken) {
+      url.searchParams.set("token", this.options.authToken);
+    }
+    return url.toString();
+  }
+  buildHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.options.authToken) {
+      headers["Authorization"] = `Bearer ${this.options.authToken}`;
+    }
+    return headers;
+  }
+  rejectAllPendingRequests(error) {
+    for (const [, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeoutId);
+      pending.reject(error);
+    }
+    this.pendingRequests.clear();
+  }
+  extractUiResourceUri(tool) {
+    const meta = tool._meta?.ui;
+    if (!meta || typeof meta !== "object") return void 0;
+    if (meta.visibility && !meta.visibility.includes("app")) return void 0;
+    return meta.resourceUri ?? meta.uri;
+  }
+  emitUiEventIfPresent(result, sessionId, toolName) {
+    const meta = result?._meta;
+    const resourceUri = meta?.ui?.resourceUri ?? meta?.["ui/resourceUri"];
+    if (resourceUri) {
+      this.options.onEvent?.({
+        type: "mcp-apps-ui",
+        sessionId,
+        resourceUri,
+        toolName,
+        result,
+        timestamp: Date.now()
+      });
+    }
+  }
+  log(message, level = "info") {
+    if (!this.options.debug && level === "info") return;
+    const prefix = "[SSEClient]";
+    switch (level) {
+      case "warn":
+        console.warn(prefix, message);
+        break;
+      case "error":
+        console.error(prefix, message);
+        break;
+      default:
+        console.log(prefix, message);
+    }
   }
 };
 
@@ -257,7 +365,8 @@ function useMcp(options) {
         if (isMountedRef.current) {
           setStatus(newStatus);
         }
-      }
+      },
+      requestTimeout: options.requestTimeout
     };
     const client = new SSEClient(clientOptions);
     clientRef.current = client;
@@ -296,6 +405,9 @@ function useMcp(options) {
           }
         }
         case "tools_discovered": {
+          if (clientRef.current && event.tools?.length) {
+            clientRef.current.preloadToolUiResources(event.sessionId, event.tools);
+          }
           return prev.map(
             (c) => c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: "READY" } : c
           );
@@ -482,11 +594,344 @@ function useMcp(options) {
     listPrompts,
     getPrompt,
     listResources,
-    readResource
+    readResource,
+    client: clientRef.current
   };
 }
+var HOST_INFO = { name: "mcp-ts-host", version: "1.0.0" };
+var SANDBOX_PERMISSIONS = [
+  "allow-scripts",
+  // Required for app JavaScript execution
+  "allow-forms",
+  // Required for form submissions
+  "allow-same-origin",
+  // Required for Blob URL correctness
+  "allow-modals",
+  // Required for dialogs/alerts
+  "allow-popups",
+  // Required for opening links
+  "allow-downloads"
+  // Required for file downloads
+].join(" ");
+var MCP_URI_SCHEMES = ["ui://", "mcp-app://"];
+var AppHost = class {
+  constructor(client, iframe, options) {
+    this.client = client;
+    this.iframe = iframe;
+    __publicField(this, "bridge");
+    __publicField(this, "sessionId");
+    __publicField(this, "resourceCache", /* @__PURE__ */ new Map());
+    __publicField(this, "debug");
+    /** Callback for app messages (e.g., chat messages from the app) */
+    __publicField(this, "onAppMessage");
+    this.debug = options?.debug ?? false;
+    this.configureSandbox();
+    this.bridge = this.initializeBridge();
+  }
+  // ============================================
+  // Public API
+  // ============================================
+  /**
+   * Start the host. This prepares the bridge handlers but doesn't connect yet.
+   * The actual connection happens in launch() after HTML is loaded.
+   * @returns Promise that resolves immediately (bridge connects during launch)
+   */
+  async start() {
+    this.log("Host started, ready to launch");
+  }
+  /**
+   * Preload UI resources to enable instant app loading.
+   * Call this when tools are discovered to cache their UI resources.
+   */
+  preload(tools) {
+    for (const tool of tools) {
+      const uri = this.extractUiResourceUri(tool);
+      if (!uri || this.resourceCache.has(uri)) continue;
+      const promise = this.preloadResource(uri);
+      this.resourceCache.set(uri, promise);
+    }
+  }
+  /**
+   * Launch an MCP App from a URL or MCP resource URI.
+   * Loads the HTML first, then establishes bridge connection.
+   */
+  async launch(url, sessionId) {
+    if (sessionId) this.sessionId = sessionId;
+    const initializedPromise = this.onAppReady();
+    if (this.isMcpUri(url)) {
+      await this.launchMcpApp(url);
+    } else {
+      this.iframe.src = url;
+    }
+    await this.onIframeReady();
+    await this.connectBridge();
+    this.log("Waiting for app initialization");
+    await Promise.race([
+      initializedPromise,
+      new Promise((resolve) => setTimeout(() => {
+        this.log("Initialization timeout - continuing anyway", "warn");
+        resolve();
+      }, 3e3))
+    ]);
+    this.log("App launched and ready");
+  }
+  /**
+   * Wait for app to signal initialization complete
+   */
+  onAppReady() {
+    return new Promise((resolve) => {
+      const originalHandler = this.bridge.oninitialized;
+      this.bridge.oninitialized = (...args) => {
+        this.log("App initialized");
+        resolve();
+        this.bridge.oninitialized = originalHandler;
+        originalHandler?.(...args);
+      };
+    });
+  }
+  /**
+   * Wait for iframe to finish loading
+   */
+  onIframeReady() {
+    return new Promise((resolve) => {
+      if (this.iframe.contentDocument?.readyState === "complete") {
+        resolve();
+        return;
+      }
+      this.iframe.addEventListener("load", () => resolve(), { once: true });
+    });
+  }
+  /**
+   * Send tool input arguments to the MCP App.
+   * Call this after launch() when tool input is available.
+   */
+  sendToolInput(args) {
+    this.log("Sending tool input to app");
+    this.bridge.sendToolInput({ arguments: args });
+  }
+  /**
+   * Send tool result to the MCP App.
+   * Call this when the tool call completes.
+   */
+  sendToolResult(result) {
+    this.log("Sending tool result to app");
+    this.bridge.sendToolResult(result);
+  }
+  /**
+   * Send tool cancellation to the MCP App.
+   * Call this when the tool call is cancelled or fails.
+   */
+  sendToolCancelled(reason) {
+    this.log("Sending tool cancellation to app");
+    this.bridge.sendToolCancelled({ reason });
+  }
+  // ============================================
+  // Private: Initialization
+  // ============================================
+  configureSandbox() {
+    if (this.iframe.sandbox.value !== SANDBOX_PERMISSIONS) {
+      this.iframe.sandbox.value = SANDBOX_PERMISSIONS;
+    }
+  }
+  initializeBridge() {
+    const bridge = new appBridge.AppBridge(
+      null,
+      HOST_INFO,
+      {
+        openLinks: {},
+        serverTools: {},
+        logging: {},
+        // Declare support for model context updates
+        updateModelContext: { text: {} }
+      },
+      {
+        // Initial host context
+        hostContext: {
+          theme: "dark",
+          platform: "web",
+          containerDimensions: { maxHeight: 6e3 },
+          displayMode: "inline",
+          availableDisplayModes: ["inline", "fullscreen"]
+        }
+      }
+    );
+    bridge.oncalltool = (params) => this.handleToolCall(params);
+    bridge.onopenlink = this.handleOpenLink.bind(this);
+    bridge.onmessage = this.handleMessage.bind(this);
+    bridge.onloggingmessage = (params) => this.log(`App log [${params.level}]: ${params.data}`);
+    bridge.onupdatemodelcontext = async () => ({});
+    bridge.onsizechange = async ({ width, height }) => {
+      if (height !== void 0) this.iframe.style.height = `${height}px`;
+      if (width !== void 0) this.iframe.style.minWidth = `min(${width}px, 100%)`;
+      return {};
+    };
+    bridge.onrequestdisplaymode = async (params) => ({
+      mode: params.mode === "fullscreen" ? "fullscreen" : "inline"
+    });
+    return bridge;
+  }
+  async connectBridge() {
+    this.log("Connecting bridge to iframe");
+    const transport = new appBridge.PostMessageTransport(
+      this.iframe.contentWindow,
+      this.iframe.contentWindow
+    );
+    try {
+      await this.bridge.connect(transport);
+      this.log("Bridge connected successfully");
+    } catch (error) {
+      this.log("Bridge connection failed", "error");
+      throw error;
+    }
+  }
+  // ============================================
+  // Private: Bridge Event Handlers
+  // ============================================
+  async handleToolCall(params) {
+    if (!this.client.isConnected()) {
+      throw new Error("Client disconnected");
+    }
+    const sessionId = await this.getSessionId();
+    if (!sessionId) {
+      throw new Error("No active session");
+    }
+    const result = await this.client.callTool(
+      sessionId,
+      params.name,
+      params.arguments ?? {}
+    );
+    return result;
+  }
+  async handleOpenLink(params) {
+    window.open(params.url, "_blank", "noopener,noreferrer");
+    return {};
+  }
+  async handleMessage(params) {
+    this.onAppMessage?.(params);
+    return {};
+  }
+  // ============================================
+  // Private: Resource Loading
+  // ============================================
+  async launchMcpApp(uri) {
+    if (!this.client.isConnected()) {
+      throw new Error("Client must be connected");
+    }
+    const sessionId = await this.getSessionId();
+    if (!sessionId) {
+      throw new Error("No active session");
+    }
+    const response = await this.fetchResourceWithCache(sessionId, uri);
+    if (!response?.contents?.length) {
+      throw new Error(`Empty resource: ${uri}`);
+    }
+    const content = response.contents[0];
+    const html = this.decodeContent(content);
+    if (!html) {
+      throw new Error(`Invalid content in resource: ${uri}`);
+    }
+    const blob = new Blob([html], { type: "text/html" });
+    this.iframe.src = URL.createObjectURL(blob);
+  }
+  async fetchResourceWithCache(sessionId, uri) {
+    if (this.hasClientCache()) {
+      return this.client.getOrFetchResource(sessionId, uri);
+    }
+    const cached = this.resourceCache.get(uri);
+    if (cached) {
+      const result = await cached;
+      if (result) return result;
+    }
+    return this.client.readResource(sessionId, uri);
+  }
+  async preloadResource(uri) {
+    try {
+      const sessionId = await this.getSessionId();
+      if (!sessionId) return null;
+      return await this.client.readResource(sessionId, uri);
+    } catch (error) {
+      this.log(`Preload failed for ${uri}`, "warn");
+      return null;
+    }
+  }
+  // ============================================
+  // Private: Utilities
+  // ============================================
+  async getSessionId() {
+    if (this.sessionId) return this.sessionId;
+    const result = await this.client.getSessions();
+    return result.sessions?.[0]?.sessionId;
+  }
+  isMcpUri(url) {
+    return MCP_URI_SCHEMES.some((scheme) => url.startsWith(scheme));
+  }
+  hasClientCache() {
+    return "getOrFetchResource" in this.client && typeof this.client.getOrFetchResource === "function";
+  }
+  extractUiResourceUri(tool) {
+    const meta = tool._meta;
+    if (!meta?.ui) return void 0;
+    return meta.ui.resourceUri ?? meta.ui.uri;
+  }
+  decodeContent(content) {
+    if (content.blob) {
+      return atob(content.blob);
+    }
+    return content.text;
+  }
+  log(message, level = "info") {
+    if (!this.debug && level === "info") return;
+    const prefix = "[AppHost]";
+    switch (level) {
+      case "warn":
+        console.warn(prefix, message);
+        break;
+      case "error":
+        console.error(prefix, message);
+        break;
+      default:
+        console.log(prefix, message);
+    }
+  }
+};
+
+// src/client/react/use-mcp-app.ts
+function useMcpApp(client, iframeRef, options) {
+  const [host, setHost] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const initializingRef = react.useRef(false);
+  const onMessageRef = react.useRef(options?.onMessage);
+  react.useEffect(() => {
+    onMessageRef.current = options?.onMessage;
+  }, [options?.onMessage]);
+  react.useEffect(() => {
+    if (!client || !iframeRef.current || initializingRef.current) return;
+    initializingRef.current = true;
+    const initHost = async () => {
+      try {
+        const appHost = new AppHost(client, iframeRef.current);
+        appHost.onAppMessage = (params) => {
+          onMessageRef.current?.(params);
+        };
+        setHost(appHost);
+        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 };
+}
 
+exports.AppHost = AppHost;
 exports.SSEClient = SSEClient;
 exports.useMcp = useMcp;
+exports.useMcpApp = useMcpApp;
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map