@mcp-ts/sdk 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -4,8 +4,10 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { UnauthorizedError as UnauthorizedError$1, discoverOAuthProtectedResourceMetadata, discoverAuthorizationServerMetadata, refreshAuthorization } from '@modelcontextprotocol/sdk/client/auth.js';
 import { ListToolsResultSchema, CallToolResultSchema, ListPromptsResultSchema, GetPromptResultSchema, ListResourcesResultSchema, ReadResourceResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import * as fs2 from 'fs';
 import { promises } from 'fs';
 import * as path from 'path';
+import { AppBridge, PostMessageTransport } from '@modelcontextprotocol/ext-apps/app-bridge';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -507,6 +509,148 @@ var FileStorageBackend = class {
   async disconnect() {
   }
 };
+var SqliteStorage = class {
+  constructor(options = {}) {
+    __publicField(this, "db", null);
+    __publicField(this, "table");
+    __publicField(this, "initialized", false);
+    __publicField(this, "dbPath");
+    this.dbPath = options.path || "./sessions.db";
+    this.table = options.table || "mcp_sessions";
+  }
+  async init() {
+    if (this.initialized) return;
+    try {
+      const DatabaseConstructor = (await import('better-sqlite3')).default;
+      const dir = path.dirname(this.dbPath);
+      if (!fs2.existsSync(dir)) {
+        fs2.mkdirSync(dir, { recursive: true });
+      }
+      this.db = new DatabaseConstructor(this.dbPath);
+      this.db.exec(`
+                CREATE TABLE IF NOT EXISTS ${this.table} (
+                    sessionId TEXT PRIMARY KEY,
+                    identity TEXT NOT NULL,
+                    data TEXT NOT NULL,
+                    expiresAt INTEGER
+                );
+                CREATE INDEX IF NOT EXISTS idx_${this.table}_identity ON ${this.table}(identity);
+            `);
+      this.initialized = true;
+    } catch (error) {
+      if (error.code === "MODULE_NOT_FOUND" || error.message?.includes("better-sqlite3")) {
+        throw new Error(
+          "better-sqlite3 is not installed. Please install it with: npm install better-sqlite3"
+        );
+      }
+      throw error;
+    }
+  }
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new Error("SqliteStorage not initialized. Call init() first.");
+    }
+  }
+  generateSessionId() {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < 32; i++) {
+      result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+  }
+  async createSession(session, ttl) {
+    this.ensureInitialized();
+    const { sessionId, identity } = session;
+    if (!sessionId || !identity) {
+      throw new Error("identity and sessionId required");
+    }
+    const expiresAt = ttl ? Date.now() + ttl * 1e3 : null;
+    try {
+      const stmt = this.db.prepare(
+        `INSERT INTO ${this.table} (sessionId, identity, data, expiresAt) VALUES (?, ?, ?, ?)`
+      );
+      stmt.run(sessionId, identity, JSON.stringify(session), expiresAt);
+    } catch (error) {
+      if (error.code === "SQLITE_CONSTRAINT_PRIMARYKEY") {
+        throw new Error(`Session ${sessionId} already exists`);
+      }
+      throw error;
+    }
+  }
+  async updateSession(identity, sessionId, data, ttl) {
+    this.ensureInitialized();
+    if (!sessionId || !identity) {
+      throw new Error("identity and sessionId required");
+    }
+    const currentSession = await this.getSession(identity, sessionId);
+    if (!currentSession) {
+      throw new Error(`Session ${sessionId} not found for identity ${identity}`);
+    }
+    const updatedSession = { ...currentSession, ...data };
+    const expiresAt = ttl ? Date.now() + ttl * 1e3 : null;
+    const stmt = this.db.prepare(
+      `UPDATE ${this.table} SET data = ?, expiresAt = ? WHERE sessionId = ? AND identity = ?`
+    );
+    stmt.run(JSON.stringify(updatedSession), expiresAt, sessionId, identity);
+  }
+  async getSession(identity, sessionId) {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(
+      `SELECT data FROM ${this.table} WHERE sessionId = ? AND identity = ?`
+    );
+    const row = stmt.get(sessionId, identity);
+    if (!row) return null;
+    return JSON.parse(row.data);
+  }
+  async getIdentitySessionsData(identity) {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(
+      `SELECT data FROM ${this.table} WHERE identity = ?`
+    );
+    const rows = stmt.all(identity);
+    return rows.map((row) => JSON.parse(row.data));
+  }
+  async getIdentityMcpSessions(identity) {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(
+      `SELECT sessionId FROM ${this.table} WHERE identity = ?`
+    );
+    const rows = stmt.all(identity);
+    return rows.map((row) => row.sessionId);
+  }
+  async removeSession(identity, sessionId) {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE sessionId = ? AND identity = ?`
+    );
+    stmt.run(sessionId, identity);
+  }
+  async getAllSessionIds() {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(`SELECT sessionId FROM ${this.table}`);
+    const rows = stmt.all();
+    return rows.map((row) => row.sessionId);
+  }
+  async clearAll() {
+    this.ensureInitialized();
+    const stmt = this.db.prepare(`DELETE FROM ${this.table}`);
+    stmt.run();
+  }
+  async cleanupExpiredSessions() {
+    this.ensureInitialized();
+    const now = Date.now();
+    const stmt = this.db.prepare(
+      `DELETE FROM ${this.table} WHERE expiresAt IS NOT NULL AND expiresAt < ?`
+    );
+    stmt.run(now);
+  }
+  async disconnect() {
+    if (this.db) {
+      this.db.close();
+    }
+  }
+};
 
 // src/server/storage/index.ts
 var storageInstance = null;
@@ -538,6 +682,13 @@ async function createStorage() {
     store.init().catch((err) => console.error("[Storage] Failed to initialize file storage:", err));
     return store;
   }
+  if (type === "sqlite") {
+    const dbPath = process.env.MCP_TS_STORAGE_SQLITE_PATH;
+    console.log(`[Storage] Using SQLite storage (${dbPath || "default"}) (Explicit)`);
+    const store = new SqliteStorage({ path: dbPath });
+    store.init().catch((err) => console.error("[Storage] Failed to initialize SQLite storage:", err));
+    return store;
+  }
   if (type === "memory") {
     console.log("[Storage] Using In-Memory storage (Explicit)");
     return new MemoryStorageBackend();
@@ -560,6 +711,12 @@ async function createStorage() {
     store.init().catch((err) => console.error("[Storage] Failed to initialize file storage:", err));
     return store;
   }
+  if (process.env.MCP_TS_STORAGE_SQLITE_PATH) {
+    console.log(`[Storage] Auto-detected MCP_TS_STORAGE_SQLITE_PATH. Using SQLite storage (${process.env.MCP_TS_STORAGE_SQLITE_PATH}).`);
+    const store = new SqliteStorage({ path: process.env.MCP_TS_STORAGE_SQLITE_PATH });
+    store.init().catch((err) => console.error("[Storage] Failed to initialize SQLite storage:", err));
+    return store;
+  }
   console.log("[Storage] No storage configured. Using In-Memory storage (Default).");
   return new MemoryStorageBackend();
 }
@@ -1135,7 +1292,15 @@ var MCPClient = class _MCPClient {
           name: "mcp-ts-oauth-client",
           version: "2.0"
         },
-        { capabilities: {} }
+        {
+          capabilities: {
+            extensions: {
+              "io.modelcontextprotocol/ui": {
+                mimeTypes: ["text/html+mcp"]
+              }
+            }
+          }
+        }
       );
     }
     const existingSession = await storage.getSession(this.identity, this.sessionId);
@@ -1317,7 +1482,15 @@ var MCPClient = class _MCPClient {
             name: "mcp-ts-oauth-client",
             version: "2.0"
           },
-          { capabilities: {} }
+          {
+            capabilities: {
+              extensions: {
+                "io.modelcontextprotocol/ui": {
+                  mimeTypes: ["text/html+mcp"]
+                }
+              }
+            }
+          }
         );
         this.emitStateChange("CONNECTING");
         await this.client.connect(this.transport);
@@ -1873,6 +2046,7 @@ var MultiSessionClient = class {
 };
 
 // src/server/handlers/sse-handler.ts
+var DEFAULT_HEARTBEAT_INTERVAL = 3e4;
 var SSEConnectionManager = class {
   constructor(options, sendEvent) {
     this.options = options;
@@ -1902,7 +2076,7 @@ var SSEConnectionManager = class {
    * Start heartbeat to keep connection alive
    */
   startHeartbeat() {
-    const interval = this.options.heartbeatInterval || 3e4;
+    const interval = this.options.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL;
     this.heartbeatTimer = setInterval(() => {
       if (this.isActive) {
         this.sendEvent({
@@ -1915,6 +2089,7 @@ var SSEConnectionManager = class {
   }
   /**
    * Handle incoming RPC requests
+   * Returns the RPC response directly for immediate HTTP response (bypassing SSE latency)
    */
   async handleRequest(request) {
     try {
@@ -1956,39 +2131,29 @@ var SSEConnectionManager = class {
         default:
           throw new Error(`Unknown method: ${request.method}`);
       }
-      this.sendEvent({
+      const response = {
         id: request.id,
         result
-      });
+      };
+      this.sendEvent(response);
+      return response;
     } catch (error) {
-      this.sendEvent({
+      const errorResponse = {
         id: request.id,
         error: {
           code: RpcErrorCodes.EXECUTION_ERROR,
           message: error instanceof Error ? error.message : "Unknown error"
         }
-      });
+      };
+      this.sendEvent(errorResponse);
+      return errorResponse;
     }
   }
   /**
-   * Get all user sessions
+   * Get all sessions for the current identity
    */
   async getSessions() {
     const sessions = await storage.getIdentitySessionsData(this.identity);
-    this.sendEvent({
-      level: "debug",
-      message: `Retrieved ${sessions.length} sessions for identity ${this.identity}`,
-      timestamp: Date.now(),
-      metadata: {
-        identity: this.identity,
-        sessionCount: sessions.length,
-        sessions: sessions.map((s) => ({
-          sessionId: s.sessionId,
-          serverId: s.serverId,
-          serverName: s.serverName
-        }))
-      }
-    });
     return {
       sessions: sessions.map((s) => ({
         sessionId: s.sessionId,
@@ -2003,7 +2168,8 @@ var SSEConnectionManager = class {
    * Connect to an MCP server
    */
   async connect(params) {
-    const { serverId, serverName, serverUrl, callbackUrl, transportType } = params;
+    const { serverName, serverUrl, callbackUrl, transportType } = params;
+    const serverId = params.serverId && params.serverId.length <= 12 ? params.serverId : await storage.generateSessionId();
     const existingSessions = await storage.getIdentitySessionsData(this.identity);
     const duplicate = existingSessions.find(
       (s) => s.serverId === serverId || s.serverUrl === serverUrl
@@ -2052,10 +2218,6 @@ var SSEConnectionManager = class {
       });
       await client.connect();
       const tools = await client.listTools();
-      const sessionAfterConnect = await storage.getSession(this.identity, sessionId);
-      console.log(`[SSE Handler] After connect() - Session ${sessionId}:`, {
-        serverId: sessionAfterConnect?.serverId
-      });
       this.emitConnectionEvent({
         type: "tools_discovered",
         sessionId,
@@ -2097,24 +2259,21 @@ var SSEConnectionManager = class {
     return { success: true };
   }
   /**
-   * Helper to get or restore a client
+   * Get an existing client or create and connect a new one for the session.
    */
   async getOrCreateClient(sessionId) {
-    let client = this.clients.get(sessionId);
-    if (!client) {
-      client = new MCPClient({
-        identity: this.identity,
-        sessionId
-      });
-      client.onConnectionEvent((event) => {
-        this.emitConnectionEvent(event);
-      });
-      client.onObservabilityEvent((event) => {
-        this.sendEvent(event);
-      });
-      await client.connect();
-      this.clients.set(sessionId, client);
+    const existing = this.clients.get(sessionId);
+    if (existing) {
+      return existing;
     }
+    const client = new MCPClient({
+      identity: this.identity,
+      sessionId
+    });
+    client.onConnectionEvent((event) => this.emitConnectionEvent(event));
+    client.onObservabilityEvent((event) => this.sendEvent(event));
+    await client.connect();
+    this.clients.set(sessionId, client);
     return client;
   }
   /**
@@ -2127,51 +2286,35 @@ var SSEConnectionManager = class {
     return { tools: result.tools };
   }
   /**
-   * Call a tool
+   * Call a tool on the MCP server
    */
   async callTool(params) {
     const { sessionId, toolName, toolArgs } = params;
     const client = await this.getOrCreateClient(sessionId);
-    return await client.callTool(toolName, toolArgs);
+    const result = await client.callTool(toolName, toolArgs);
+    const meta = result._meta || {};
+    return {
+      ...result,
+      _meta: {
+        ...meta,
+        sessionId
+      }
+    };
   }
   /**
-   * Refresh/validate a session
+   * Restore and validate an existing session
    */
   async restoreSession(params) {
     const { sessionId } = params;
-    this.sendEvent({
-      level: "debug",
-      message: `Starting session refresh for ${sessionId}`,
-      timestamp: Date.now(),
-      metadata: { sessionId, identity: this.identity }
-    });
     const session = await storage.getSession(this.identity, sessionId);
     if (!session) {
-      this.sendEvent({
-        level: "error",
-        message: `Session not found: ${sessionId}`,
-        timestamp: Date.now(),
-        metadata: { sessionId, identity: this.identity }
-      });
       throw new Error("Session not found");
     }
-    this.sendEvent({
-      level: "debug",
-      message: `Session found in Redis`,
-      timestamp: Date.now(),
-      metadata: {
-        sessionId,
-        serverId: session.serverId,
-        serverName: session.serverName,
-        serverUrl: session.serverUrl,
-        transportType: session.transportType
-      }
-    });
     this.emitConnectionEvent({
       type: "state_changed",
       sessionId,
-      serverId: session.serverId || "unknown",
-      serverName: session.serverName || "Unknown",
+      serverId: session.serverId ?? "unknown",
+      serverName: session.serverName ?? "Unknown",
       state: "VALIDATING",
       previousState: "DISCONNECTED",
       timestamp: Date.now()
@@ -2182,21 +2325,16 @@ var SSEConnectionManager = class {
         identity: this.identity,
         sessionId,
         ...clientMetadata
-        // Include metadata for consistency
-      });
-      client.onConnectionEvent((event) => {
-        this.emitConnectionEvent(event);
-      });
-      client.onObservabilityEvent((event) => {
-        this.sendEvent(event);
       });
+      client.onConnectionEvent((event) => this.emitConnectionEvent(event));
+      client.onObservabilityEvent((event) => this.sendEvent(event));
       await client.connect();
       this.clients.set(sessionId, client);
       const tools = await client.listTools();
       this.emitConnectionEvent({
         type: "tools_discovered",
         sessionId,
-        serverId: session.serverId || "unknown",
+        serverId: session.serverId ?? "unknown",
         toolCount: tools.tools.length,
         tools: tools.tools,
         timestamp: Date.now()
@@ -2206,7 +2344,7 @@ var SSEConnectionManager = class {
       this.emitConnectionEvent({
         type: "error",
         sessionId,
-        serverId: session.serverId || "unknown",
+        serverId: session.serverId ?? "unknown",
         error: error instanceof Error ? error.message : "Validation failed",
         errorType: "validation",
         timestamp: Date.now()
@@ -2215,16 +2353,10 @@ var SSEConnectionManager = class {
     }
   }
   /**
-   * Complete OAuth authorization
+   * Complete OAuth authorization flow
    */
   async finishAuth(params) {
     const { sessionId, code } = params;
-    this.sendEvent({
-      level: "debug",
-      message: `Completing OAuth for session ${sessionId}`,
-      timestamp: Date.now(),
-      metadata: { sessionId, identity: this.identity }
-    });
     const session = await storage.getSession(this.identity, sessionId);
     if (!session) {
       throw new Error("Session not found");
@@ -2232,8 +2364,8 @@ var SSEConnectionManager = class {
     this.emitConnectionEvent({
       type: "state_changed",
       sessionId,
-      serverId: session.serverId || "unknown",
-      serverName: session.serverName || "Unknown",
+      serverId: session.serverId ?? "unknown",
+      serverName: session.serverName ?? "Unknown",
       state: "AUTHENTICATING",
       previousState: "DISCONNECTED",
       timestamp: Date.now()
@@ -2243,16 +2375,14 @@ var SSEConnectionManager = class {
         identity: this.identity,
         sessionId
       });
-      client.onConnectionEvent((event) => {
-        this.emitConnectionEvent(event);
-      });
+      client.onConnectionEvent((event) => this.emitConnectionEvent(event));
       await client.finishAuth(code);
       this.clients.set(sessionId, client);
       const tools = await client.listTools();
       this.emitConnectionEvent({
         type: "tools_discovered",
         sessionId,
-        serverId: session.serverId || "unknown",
+        serverId: session.serverId ?? "unknown",
         toolCount: tools.tools.length,
         tools: tools.tools,
         timestamp: Date.now()
@@ -2262,7 +2392,7 @@ var SSEConnectionManager = class {
       this.emitConnectionEvent({
         type: "error",
         sessionId,
-        serverId: session.serverId || "unknown",
+        serverId: session.serverId ?? "unknown",
         error: error instanceof Error ? error.message : "OAuth completion failed",
         errorType: "auth",
         timestamp: Date.now()
@@ -2302,7 +2432,7 @@ var SSEConnectionManager = class {
   async readResource(params) {
     const { sessionId, uri } = params;
     const client = await this.getOrCreateClient(sessionId);
-    return await client.readResource(uri);
+    return client.readResource(uri);
   }
   /**
    * Emit connection event
@@ -2332,19 +2462,17 @@ function createSSEHandler(options) {
       "Connection": "keep-alive",
       "Access-Control-Allow-Origin": "*"
     });
-    sendSSE(res, "connected", { timestamp: Date.now() });
+    writeSSEEvent(res, "connected", { timestamp: Date.now() });
     const manager = new SSEConnectionManager(options, (event) => {
       if ("id" in event) {
-        sendSSE(res, "rpc-response", event);
+        writeSSEEvent(res, "rpc-response", event);
       } else if ("type" in event && "sessionId" in event) {
-        sendSSE(res, "connection", event);
+        writeSSEEvent(res, "connection", event);
       } else {
-        sendSSE(res, "observability", event);
+        writeSSEEvent(res, "observability", event);
       }
     });
-    req.on("close", () => {
-      manager.dispose();
-    });
+    req.on("close", () => manager.dispose());
     if (req.method === "POST") {
       let body = "";
       req.on("data", (chunk) => {
@@ -2354,14 +2482,13 @@ function createSSEHandler(options) {
         try {
           const request = JSON.parse(body);
           await manager.handleRequest(request);
-        } catch (error) {
-          console.error("[SSE] Error handling request:", error);
+        } catch {
         }
       });
     }
   };
 }
-function sendSSE(res, event, data) {
+function writeSSEEvent(res, event, data) {
   res.write(`event: ${event}
 `);
   res.write(`data: ${JSON.stringify(data)}
@@ -2396,7 +2523,7 @@ function createNextMcpHandler(options = {}) {
     const stream = new TransformStream();
     const writer = stream.writable.getWriter();
     const encoder = new TextEncoder();
-    const sendSSE2 = (event, data) => {
+    const sendSSE = (event, data) => {
       const message = `event: ${event}
 data: ${JSON.stringify(data)}
 
@@ -2404,7 +2531,6 @@ data: ${JSON.stringify(data)}
       writer.write(encoder.encode(message)).catch(() => {
       });
     };
-    sendSSE2("connected", { timestamp: Date.now() });
     const previousManager = managers.get(identity);
     if (previousManager) {
       previousManager.dispose();
@@ -2419,15 +2545,16 @@ data: ${JSON.stringify(data)}
       },
       (event) => {
         if ("id" in event) {
-          sendSSE2("rpc-response", event);
+          sendSSE("rpc-response", event);
         } else if ("type" in event && "sessionId" in event) {
-          sendSSE2("connection", event);
+          sendSSE("connection", event);
         } else {
-          sendSSE2("observability", event);
+          sendSSE("observability", event);
         }
       }
     );
     managers.set(identity, manager);
+    sendSSE("connected", { timestamp: Date.now() });
     const abortController = new AbortController();
     request.signal?.addEventListener("abort", () => {
       manager.dispose();
@@ -2470,8 +2597,8 @@ data: ${JSON.stringify(data)}
           { status: 400 }
         );
       }
-      await manager.handleRequest(body);
-      return Response.json({ acknowledged: true });
+      const response = await manager.handleRequest(body);
+      return Response.json(response);
     } catch (error) {
       return Response.json(
         {
@@ -2486,20 +2613,25 @@ data: ${JSON.stringify(data)}
   }
   return { GET, POST };
 }
+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) {
@@ -2510,52 +2642,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;
@@ -2565,139 +2657,577 @@ 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
+   * Check if connected to the SSE endpoint
+   */
+  isConnected() {
+    return this.eventSource?.readyState === EventSource.OPEN;
+  }
+  // ============================================
+  // RPC Methods
+  // ============================================
+  async getSessions() {
+    return this.sendRequest("getSessions");
+  }
+  async connectToServer(params) {
+    return this.sendRequest("connect", params);
+  }
+  async disconnectFromServer(sessionId) {
+    return this.sendRequest("disconnect", { sessionId });
+  }
+  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)
+  // ============================================
+  /**
+   * Preload UI resources for tools that have UI metadata.
+   * Call this when tools are discovered to enable instant MCP App UI loading.
+   */
+  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);
+    }
+  }
+  /**
+   * Get a preloaded resource from cache, or fetch if not cached.
+   */
+  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;
+  }
+  /**
+   * Check if a resource is already cached
+   */
+  hasPreloadedResource(uri) {
+    return this.resourceCache.has(uri);
+  }
+  /**
+   * Clear the resource cache
+   */
+  clearResourceCache() {
+    this.resourceCache.clear();
+  }
+  // ============================================
+  // Private: Request Handling
+  // ============================================
+  /**
+   * Send an RPC request and return the response directly from HTTP.
+   * This bypasses SSE latency by returning results in the HTTP response body.
    */
   async sendRequest(method, params) {
     if (this.connectionPromise) {
       await this.connectionPromise;
     }
-    const id = `rpc_${nanoid(10)}`;
     const request = {
-      id,
+      id: `rpc_${nanoid(10)}`,
       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);
+    const response = await fetch(this.buildUrl(), {
+      method: "POST",
+      headers: this.buildHeaders(),
+      body: JSON.stringify(request)
     });
-    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;
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
     }
-    return promise;
+    const data = await response.json();
+    return this.parseRpcResponse(data, request.id);
   }
   /**
-   * Handle RPC response
+   * Parse RPC response and handle different response formats
    */
-  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);
-      }
+  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");
   }
   /**
-   * Get all user sessions
+   * Wait for RPC response via SSE (legacy fallback)
    */
-  async getSessions() {
-    return this.sendRequest("getSessions");
+  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
+      });
+    });
   }
   /**
-   * Connect to an MCP server
+   * Handle RPC response received via SSE (legacy)
    */
-  async connectToServer(params) {
-    return this.sendRequest("connect", params);
+  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);
+    }
   }
-  /**
-   * Disconnect from an MCP server
-   */
-  async disconnectFromServer(sessionId) {
-    return this.sendRequest("disconnect", { sessionId });
+  // ============================================
+  // 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();
+    });
   }
-  /**
-   * List tools from a session
-   */
-  async listTools(sessionId) {
-    return this.sendRequest("listTools", { sessionId });
+  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();
   }
-  /**
-   * Call a tool
-   */
-  async callTool(sessionId, toolName, toolArgs) {
-    return this.sendRequest("callTool", { sessionId, toolName, toolArgs });
+  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);
+    }
   }
+};
+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
+  // ============================================
   /**
-   * Refresh/validate a session
+   * 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 restoreSession(sessionId) {
-    return this.sendRequest("restoreSession", { sessionId });
+  async start() {
+    this.log("Host started, ready to launch");
   }
   /**
-   * Complete OAuth authorization
+   * Preload UI resources to enable instant app loading.
+   * Call this when tools are discovered to cache their UI resources.
    */
-  async finishAuth(sessionId, code) {
-    return this.sendRequest("finishAuth", { sessionId, code });
+  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);
+    }
   }
   /**
-   * List available prompts
+   * Launch an MCP App from a URL or MCP resource URI.
+   * Loads the HTML first, then establishes bridge connection.
    */
-  async listPrompts(sessionId) {
-    return this.sendRequest("listPrompts", { sessionId });
+  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);
+      };
+    });
   }
   /**
-   * Get a specific prompt with arguments
+   * Wait for iframe to finish loading
    */
-  async getPrompt(sessionId, name, args) {
-    return this.sendRequest("getPrompt", { sessionId, name, args });
+  onIframeReady() {
+    return new Promise((resolve) => {
+      if (this.iframe.contentDocument?.readyState === "complete") {
+        resolve();
+        return;
+      }
+      this.iframe.addEventListener("load", () => resolve(), { once: true });
+    });
   }
   /**
-   * List available resources
+   * Send tool input arguments to the MCP App.
+   * Call this after launch() when tool input is available.
    */
-  async listResources(sessionId) {
-    return this.sendRequest("listResources", { sessionId });
+  sendToolInput(args) {
+    this.log("Sending tool input to app");
+    this.bridge.sendToolInput({ arguments: args });
   }
   /**
-   * Read a specific resource
+   * Send tool result to the MCP App.
+   * Call this when the tool call completes.
    */
-  async readResource(sessionId, uri) {
-    return this.sendRequest("readResource", { sessionId, uri });
+  sendToolResult(result) {
+    this.log("Sending tool result to app");
+    this.bridge.sendToolResult(result);
   }
   /**
-   * Check if connected
+   * Send tool cancellation to the MCP App.
+   * Call this when the tool call is cancelled or fails.
    */
-  isConnected() {
-    return this.eventSource !== null && this.eventSource.readyState === EventSource.OPEN;
+  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(
+      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 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);
+    }
   }
 };
 
@@ -2718,6 +3248,6 @@ function isCallToolSuccess(response) {
   return "content" in response;
 }
 
-export { AuthenticationError, ConfigurationError, ConnectionError, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, DisposableStore, Emitter, InvalidStateError, MCPClient, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, McpError, MultiSessionClient, NotConnectedError, REDIS_KEY_PREFIX, RpcErrorCodes, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, SSEClient, SSEConnectionManager, STATE_EXPIRATION_MS, SessionNotFoundError, SessionValidationError, StorageOAuthClientProvider, TOKEN_EXPIRY_BUFFER_MS, ToolExecutionError, UnauthorizedError, createNextMcpHandler, createSSEHandler, isCallToolSuccess, isConnectAuthRequired, isConnectError, isConnectSuccess, isListToolsSuccess, sanitizeServerLabel, storage };
+export { AppHost, AuthenticationError, ConfigurationError, ConnectionError, DEFAULT_CLIENT_NAME, DEFAULT_CLIENT_URI, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_LOGO_URI, DEFAULT_POLICY_URI, DisposableStore, Emitter, InvalidStateError, MCPClient, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, McpError, MultiSessionClient, NotConnectedError, REDIS_KEY_PREFIX, RpcErrorCodes, SESSION_TTL_SECONDS, SOFTWARE_ID, SOFTWARE_VERSION, SSEClient, SSEConnectionManager, STATE_EXPIRATION_MS, SessionNotFoundError, SessionValidationError, StorageOAuthClientProvider, TOKEN_EXPIRY_BUFFER_MS, ToolExecutionError, UnauthorizedError, createNextMcpHandler, createSSEHandler, isCallToolSuccess, isConnectAuthRequired, isConnectError, isConnectSuccess, isListToolsSuccess, sanitizeServerLabel, storage };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map