@mcp-ts/sdk 1.3.10 → 1.5.0

package/src/adapters/ai-adapter.ts

@@ -2,6 +2,8 @@ import { MCPClient } from '../server/mcp/oauth-client';
 import { MultiSessionClient } from '../server/mcp/multi-session-client';
 import type { JSONSchema7 } from 'json-schema';
 import type { ToolSet } from 'ai';
+import { ToolRouter } from '../shared/tool-router.js';
+import { executeMetaTool, isMetaTool } from '../shared/meta-tools.js';
 
 export interface AIAdapterOptions {
     /** 
@@ -9,6 +11,17 @@ export interface AIAdapterOptions {
      * Defaults to the client's serverId.
      */
     prefix?: string;
+
+    /**
+     * Optional ToolRouter for intelligent tool selection.
+     *
+     * When provided with `strategy: 'search'`, the adapter exposes only
+     * meta-tools (search_tools, get_tool_schema) instead of all tool schemas,
+     * reducing context window usage by 80–95%.
+     *
+     * When not provided, all tools are returned as before (backward-compatible).
+     */
+    toolRouter?: ToolRouter;
 }
 
 /**
@@ -80,6 +93,11 @@ export class AIAdapter {
     async getTools(): Promise<ToolSet> {
         await this.ensureJsonSchema();
 
+        // If a ToolRouter is provided, use its filtered output
+        if (this.options.toolRouter) {
+            return this.getToolsViaRouter(this.options.toolRouter);
+        }
+
         // Use duck typing instead of instanceof to handle module bundling issues
         // MultiSessionClient has getClients(), MCPClient does not
         const isMultiSession = typeof (this.client as any).getClients === 'function';
@@ -106,6 +124,63 @@ export class AIAdapter {
         return results.reduce((acc, tools) => ({ ...acc, ...tools }), {});
     }
 
+    /**
+     * Build a ToolSet from a ToolRouter's filtered output.
+     *
+     * In `search` strategy, only meta-tools are registered with the framework.
+     * Real tool execution is proxied through `mcp_execute_tool` which uses
+     * `router.callTool()` to route to the correct MCP client.
+     */
+    private async getToolsViaRouter(router: ToolRouter): Promise<ToolSet> {
+        const filteredTools = await router.getFilteredTools();
+
+        // @ts-ignore: ToolSet type inference can be tricky with dynamic imports
+        return Object.fromEntries(
+            filteredTools.map((tool) => {
+                const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
+                const namespace = routedTool.serverName ?? routedTool.sessionId;
+                const toolKey = isMetaTool(tool.name)
+                    ? tool.name
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName);
+
+                return [
+                    toolKey,
+                    {
+                        description: tool.description,
+                        inputSchema: this.jsonSchema!(tool.inputSchema as JSONSchema7),
+                        execute: async (args: any) => {
+                            // Handle meta-tool calls via the router
+                            if (isMetaTool(tool.name)) {
+                                const result = await executeMetaTool(
+                                    tool.name,
+                                    args,
+                                    router,
+                                    (name, toolArgs, targetNamespace) => router.callTool(name, toolArgs, targetNamespace)
+                                );
+                                if (result) {
+                                  return result;
+                                }
+                            }
+
+                            // For non-meta tools in 'all' or 'groups' strategy,
+                            // route directly to the correct MCP client
+                            return await router.callTool(tool.name, args, namespace);
+                        },
+                    },
+                ];
+            })
+        );
+    }
+
+    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
+        const namespace = sessionId ?? serverName ?? 'mcp';
+        const normalized = namespace
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '') || 'mcp';
+        return `tool_${normalized}_${toolName}`;
+    }
+
     /**
      * Convenience static method to fetch tools in a single line.
      */

package/src/adapters/langchain-adapter.ts

@@ -2,6 +2,8 @@ import { MCPClient } from '../server/mcp/oauth-client';
 import { MultiSessionClient } from '../server/mcp/multi-session-client';
 import type { DynamicStructuredTool, StructuredTool } from '@langchain/core/tools';
 import type { z } from 'zod';
+import { ToolRouter } from '../shared/tool-router.js';
+import { executeMetaTool, isMetaTool } from '../shared/meta-tools.js';
 
 export interface LangChainAdapterOptions {
     /** 
@@ -16,6 +18,12 @@ export interface LangChainAdapterOptions {
      * @default false
      */
     simplifyErrors?: boolean;
+
+    /**
+     * Optional ToolRouter for intelligent tool selection.
+     * See AIAdapterOptions.toolRouter for details.
+     */
+    toolRouter?: ToolRouter;
 }
 
 /**
@@ -37,7 +45,7 @@ export class LangChainAdapter {
         if (!this.DynamicStructuredTool) {
             try {
                 const langchain = await import('@langchain/core/tools');
-                this.DynamicStructuredTool = langchain.DynamicStructuredTool;
+                this.DynamicStructuredTool = langchain.DynamicStructuredTool as any;
 
                 const zod = await import('zod');
                 this.z = zod.z;
@@ -99,6 +107,11 @@ export class LangChainAdapter {
      * Fetches tools from the MCP server and converts them to LangChain StructuredTools.
      */
     async getTools(): Promise<StructuredTool[]> {
+        // If a ToolRouter is provided, use its filtered output
+        if (this.options.toolRouter) {
+            return this.getToolsViaRouter(this.options.toolRouter);
+        }
+
         // Use duck typing instead of instanceof to handle module bundling issues
         const isMultiSession = typeof (this.client as any).getClients === 'function';
         const clients = isMultiSession
@@ -118,6 +131,67 @@ export class LangChainAdapter {
         return results.flat();
     }
 
+    /**
+     * Build StructuredTools from a ToolRouter's filtered output.
+     *
+     * In `search` strategy, only meta-tools are registered with the framework.
+     * Real tool execution is proxied through `mcp_execute_tool` which uses
+     * `router.callTool()` to route to the correct MCP client.
+     */
+    private async getToolsViaRouter(router: ToolRouter): Promise<StructuredTool[]> {
+        await this.ensureDependencies();
+
+        const filteredTools = await router.getFilteredTools();
+
+        return filteredTools.map((tool) => {
+            const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
+            const namespace = routedTool.serverName ?? routedTool.sessionId;
+            const schema = this.jsonSchemaToZod(tool.inputSchema);
+
+            return new this.DynamicStructuredTool!({
+                name: isMetaTool(tool.name)
+                    ? tool.name
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName),
+                description: tool.description || `Tool ${tool.name}`,
+                schema: schema,
+                func: async (args: any) => {
+                    try {
+                        // Handle meta-tool calls via the router
+                        if (isMetaTool(tool.name)) {
+                            const result = await executeMetaTool(
+                                tool.name,
+                                args,
+                                router,
+                                (name, toolArgs, namespace) => router.callTool(name, toolArgs, namespace)
+                            );
+                            if (result) {
+                                return result.content.map((c: any) => c.text ?? '').join('\n');
+                            }
+                        }
+
+                        // For non-meta tools in 'all' or 'groups' strategy,
+                        // route directly to the correct MCP client
+                        return await router.callTool(tool.name, args, namespace);
+                    } catch (error: any) {
+                        if (this.options.simplifyErrors) {
+                            return `Error: ${error.message}`;
+                        }
+                        throw error;
+                    }
+                },
+            });
+        });
+    }
+
+    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
+        const namespace = sessionId ?? serverName ?? 'mcp';
+        const normalized = namespace
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '') || 'mcp';
+        return `tool_${normalized}_${toolName}`;
+    }
+
     /**
      * Convenience static method to fetch tools in a single line.
      */

package/src/client/core/app-host.ts

@@ -6,22 +6,119 @@
  * communication via the AppBridge protocol.
  *
  * Key features:
- * - Secure iframe sandboxing with minimal permissions
+ * - Secure iframe sandboxing with minimal permissions (proxy-based)
  * - Resource preloading for instant MCP App UI loading
  * - Cache-aware resource fetching (SSEClient cache → local cache → direct fetch)
  * - Support for ui:// and mcp-app:// resource URIs
  */
 
-import { AppBridge, PostMessageTransport } from '@modelcontextprotocol/ext-apps/app-bridge';
+import { 
+  AppBridge, 
+  PostMessageTransport
+} from '@modelcontextprotocol/ext-apps/app-bridge';
+import type { LoggingMessageNotification } from '@modelcontextprotocol/sdk/types.js';
 import type { AppHostClient } from './types';
+import { setupSandboxProxyIframe } from '../utils/app-host-utils.js';
+import { APP_HOST_DEFAULTS } from './constants.js';
+
+export type McpUiResourceCsp = Record<string, string>;
+export type McpUiHostContext = Record<string, unknown>;
+
+// Define types dynamically from AppBridge properties instead of direct imports
+// which seem to fail in this tsconfig environment
+type OnMessageHandler = NonNullable<AppBridge['onmessage']>;
+export type McpUiMessageParams = Parameters<OnMessageHandler>[0];
+export type RequestHandlerExtra = Parameters<OnMessageHandler>[1];
+export type McpUiMessageResult = ReturnType<OnMessageHandler> extends Promise<infer R> ? R : never;
+
+type OnOpenLinkHandler = NonNullable<AppBridge['onopenlink']>;
+export type McpUiOpenLinkParams = Parameters<OnOpenLinkHandler>[0];
+export type McpUiOpenLinkResult = ReturnType<OnOpenLinkHandler> extends Promise<infer R> ? R : never;
+
+type OnSizeChangeHandler = NonNullable<AppBridge['onsizechange']>;
+export type McpUiSizeChangedParams = Parameters<OnSizeChangeHandler>[0];
+
+type OnRequestDisplayModeHandler = NonNullable<AppBridge['onrequestdisplaymode']>;
+export type McpUiRequestDisplayModeParams = Parameters<OnRequestDisplayModeHandler>[0];
+export type McpUiRequestDisplayModeResult = ReturnType<OnRequestDisplayModeHandler> extends Promise<infer R> ? R : never;
+
 
 // ============================================
 // Types & Interfaces
 // ============================================
 
+export interface SandboxConfig {
+  url: URL | string;
+  permissions?: string;
+  csp?: McpUiResourceCsp;
+}
+
+/**
+ * Default Content-Security-Policy for MCP App iframes.
+ *
+ * Allows inline scripts/styles (required by most MCP App frameworks),
+ * outbound network connections, and common asset sources, while blocking
+ * nested frames and plugin objects.
+ *
+ * Pass this (or a spread of it) as `sandbox.csp` to enforce it:
+ * @example
+ * sandbox={{ url: '/sandbox.html', csp: DEFAULT_MCP_APP_CSP }}
+ * // or to extend:
+ * sandbox={{ url: '/sandbox.html', csp: { ...DEFAULT_MCP_APP_CSP, 'connect-src': "'self' https://api.example.com" } }}
+ */
+export const DEFAULT_MCP_APP_CSP: McpUiResourceCsp = {
+  'default-src': "'self'",
+  'script-src':  "'self' 'unsafe-inline' 'unsafe-eval' https: blob:",
+  'style-src':   "'self' 'unsafe-inline' https:",
+  'connect-src': "'self' https: wss:",
+  'img-src':     "'self' data: https: blob:",
+  'font-src':    "'self' data: https:",
+  'media-src':   "'self' https: blob:",
+  'frame-src':   "'none'",
+  'object-src':  "'none'",
+  'base-uri':    "'self'",
+};
+
 export interface AppHostOptions {
   /** Enable debug logging @default false */
   debug?: boolean;
+  /** Sandbox proxy configuration */
+  sandbox?: SandboxConfig;
+  /** Host context for theming, viewport, locale */
+  hostContext?: McpUiHostContext;
+  /** Custom handler for call tool requests, overriding automatic client forwarding */
+  onCallTool?: (params: ToolCallParams) => Promise<unknown>;
+  /** Custom handler for resources/read */
+  onReadResource?: (uri: string) => Promise<ResourceResponse>;
+  /** Custom handler for fallback JSON-RPC requests */
+  onFallbackRequest?: (request: any) => Promise<any>;
+  
+  /** Handler for open-link requests from the guest UI */
+  onOpenLink?: (
+    params: McpUiOpenLinkParams,
+    extra: RequestHandlerExtra,
+  ) => Promise<McpUiOpenLinkResult>;
+
+  /** Handler for message requests from the guest UI */
+  onMessage?: (
+    params: McpUiMessageParams,
+    extra: RequestHandlerExtra,
+  ) => Promise<McpUiMessageResult>;
+
+  /** Handler for logging messages from the guest UI */
+  onLoggingMessage?: (params: LoggingMessageNotification['params']) => void;
+
+  /** Handler for size change notifications from the guest UI */
+  onSizeChanged?: (params: McpUiSizeChangedParams) => void;
+
+  /** Callback invoked when an error occurs during setup or message handling */
+  onError?: (error: Error) => void;
+
+  /** Handler for display mode change requests from the guest UI */
+  onRequestDisplayMode?: (
+    params: McpUiRequestDisplayModeParams,
+    extra: RequestHandlerExtra,
+  ) => Promise<McpUiRequestDisplayModeResult>;
 }
 
 export interface AppMessageParams {
@@ -47,20 +144,11 @@ interface ResourceResponse {
 // Constants
 // ============================================
 
-const HOST_INFO = { name: 'mcp-ts-host', version: '1.0.0' };
+const HOST_INFO = APP_HOST_DEFAULTS.HOST_INFO;
 
-/** Sandbox permissions - minimal set required for MCP Apps to function */
-const 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(' ');
 
 /** Supported MCP App URI schemes */
-const MCP_URI_SCHEMES = ['ui://', 'mcp-app://'] as const;
+const MCP_URI_SCHEMES = APP_HOST_DEFAULTS.URI_SCHEMES;
 
 // ============================================
 // AppHost Class
@@ -76,16 +164,19 @@ export class AppHost {
   private resourceCache = new Map<string, Promise<ResourceResponse | null>>();
   private debug: boolean;
 
-  /** Callback for app messages (e.g., chat messages from the app) */
+  private sandboxConfig?: SandboxConfig;
+  private options: AppHostOptions;
   public onAppMessage?: (params: AppMessageParams) => void;
 
   constructor(
-    private readonly client: AppHostClient,
+    private readonly client: AppHostClient | null,
     private readonly iframe: HTMLIFrameElement,
     options?: AppHostOptions
   ) {
-    this.debug = options?.debug ?? false;
-    this.configureSandbox();
+    this.options = options || {};
+    this.debug = this.options.debug ?? false;
+    this.sandboxConfig = this.options.sandbox;
+
     this.bridge = this.initializeBridge();
   }
 
@@ -119,29 +210,42 @@ export class AppHost {
   }
 
   /**
-   * Launch an MCP App from a URL or MCP resource URI.
+   * Launch an MCP App from a URL, MCP resource URI, or RAW HTML.
    * Loads the HTML first, then establishes bridge connection.
    */
-  async launch(url: string, sessionId?: string): Promise<void> {
+  async launch(source: { uri?: string; html?: string }, sessionId?: string): Promise<void> {
     if (sessionId) this.sessionId = sessionId;
 
-    // Set up initialization promise BEFORE connecting
     const initializedPromise = this.onAppReady();
 
-    // Load HTML into iframe first
-    if (this.isMcpUri(url)) {
-      await this.launchMcpApp(url);
-    } else {
-      this.iframe.src = url;
-    }
+    let htmlToRender = source.html;
 
-    // Wait for iframe to load before connecting bridge
-    await this.onIframeReady();
+    if (!htmlToRender && source.uri) {
+      if (this.isMcpUri(source.uri)) {
+        htmlToRender = await this.readMcpAppHtml(source.uri);
+      }
+    }
 
-    // Connect the bridge (HTML is loaded, contentWindow is ready)
-    await this.connectBridge();
+    if (!htmlToRender && source.uri && !this.isMcpUri(source.uri)) {
+        // Fallback for regular urls without proxy
+        this.iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-modals allow-popups allow-downloads');
+        this.iframe.src = source.uri;
+        await this.onIframeReady();
+        await this.connectBridge();
+    } else if (htmlToRender) {
+      if (!this.sandboxConfig) {
+        throw new Error("Sandbox configuration requires a proxy URL to render HTML safely.");
+      }
+      await this.launchSandboxedHtml(htmlToRender, this.sandboxConfig);
+      await this.connectBridge();
+
+      this.log('Sending HTML resource to sandbox proxy (MCP Apps notification)');
+      await this.bridge.sendSandboxResourceReady({
+        html: htmlToRender,
+        csp: this.sandboxConfig.csp,
+      });
+    }
 
-    // Wait for app to signal it's initialized (with timeout)
     this.log('Waiting for app initialization');
     await Promise.race([
       initializedPromise,
@@ -153,6 +257,21 @@ export class AppHost {
     this.log('App launched and ready');
   }
 
+  // Set host context manually
+  setHostContext(context: McpUiHostContext): void {
+    this.options.hostContext = context;
+    if (this.bridge) {
+      this.bridge.setHostContext(context);
+    }
+  }
+
+  // Send streaming inputs manually
+  sendToolInputPartial(params: any): void {
+    if (this.bridge) {
+      (this.bridge as any).sendToolInputPartial(params);
+    }
+  }
+
   /**
    * Wait for app to signal initialization complete
    */
@@ -208,15 +327,19 @@ export class AppHost {
     this.bridge.sendToolCancelled({ reason });
   }
 
+  /**
+   * Tell the guest UI the resource is being torn down (unload / cleanup).
+   * Forwards to {@link AppBridge.teardownResource} on `@modelcontextprotocol/ext-apps/app-bridge`.
+   */
+  teardownResource(params: Record<string, unknown> = {}): void {
+    this.log('Sending resource teardown to app');
+    this.bridge.teardownResource(params as never);
+  }
+
   // ============================================
   // Private: Initialization
   // ============================================
 
-  private configureSandbox(): void {
-    if (this.iframe.sandbox.value !== SANDBOX_PERMISSIONS) {
-      this.iframe.sandbox.value = SANDBOX_PERMISSIONS;
-    }
-  }
 
   private initializeBridge(): AppBridge {
     const bridge = new AppBridge(
@@ -226,12 +349,10 @@ export class AppHost {
         openLinks: {},
         serverTools: {},
         logging: {},
-        // Declare support for model context updates
         updateModelContext: { text: {} },
       },
       {
-        // Initial host context
-        hostContext: {
+        hostContext: this.options.hostContext || {
           theme: 'dark',
           platform: 'web',
           containerDimensions: { maxHeight: 6000 },
@@ -241,20 +362,59 @@ export class AppHost {
       }
     );
 
-    // Register handlers - must be done BEFORE connect()
+    ;(bridge as any).fallbackRequestHandler = this.options.onFallbackRequest;
+    
     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}`);
+    if (this.options.onReadResource) {
+       bridge.onreadresource = async (params) => {
+         const resp = await this.options.onReadResource!(params.uri);
+         return { 
+           contents: resp.contents.map(c => ({
+            uri: params.uri,
+            text: c.text as string,
+            blob: c.blob as string,
+           }))
+         };
+       };
+    }
+
+    bridge.onopenlink = async (params, extra) => {
+      if (this.options.onOpenLink) {
+        return await this.options.onOpenLink(params, extra as any);
+      }
+      return this.handleOpenLink(params);
+    };
+    bridge.onmessage = async (params, extra) => {
+      if (this.options.onMessage) {
+        return await this.options.onMessage(params, extra as any);
+      }
+      return this.handleMessage(params as any);
+    };
+    bridge.onloggingmessage = (params) => {
+      this.log(`App log [${params.level}]: ${params.data}`);
+      if (this.options.onLoggingMessage) {
+        this.options.onLoggingMessage(params);
+      }
+    };
     bridge.onupdatemodelcontext = async () => ({});
-    bridge.onsizechange = async ({ width, height }) => {
-      if (height !== undefined) this.iframe.style.height = `${height}px`;
-      if (width !== undefined) this.iframe.style.minWidth = `min(${width}px, 100%)`;
+    bridge.onsizechange = async (params) => {
+      const { width, height } = params;
+      // Guard: ignore transient 0px resize events (e.g. fired by guest during viewport transitions)
+      if (height !== undefined && height > 0) {
+        this.iframe.style.height = `${height}px`;
+      }
+      if (width !== undefined && width > 0) this.iframe.style.minWidth = `min(${width}px, 100%)`;
+      if (this.options.onSizeChanged) {
+        this.options.onSizeChanged(params);
+      }
       return {};
     };
-    bridge.onrequestdisplaymode = async (params) => ({
-      mode: params.mode === 'fullscreen' ? 'fullscreen' : 'inline'
-    });
+    bridge.onrequestdisplaymode = async (params, extra) => {
+      if (this.options.onRequestDisplayMode) {
+        return await this.options.onRequestDisplayMode(params, extra as any);
+      }
+      return { mode: params.mode === 'fullscreen' ? 'fullscreen' : 'inline' };
+    };
 
     return bridge;
   }
@@ -272,6 +432,9 @@ export class AppHost {
       this.log('Bridge connected successfully');
     } catch (error) {
       this.log('Bridge connection failed', 'error');
+      if (this.options.onError) {
+        this.options.onError(error instanceof Error ? error : new Error(String(error)));
+      }
       throw error;
     }
   }
@@ -281,8 +444,12 @@ export class AppHost {
   // ============================================
 
   private async handleToolCall(params: ToolCallParams) {
-    if (!this.client.isConnected()) {
-      throw new Error('Client disconnected');
+    if (this.options.onCallTool) {
+      return await this.options.onCallTool(params);
+    }
+    
+    if (!this.client || !this.client.isConnected()) {
+      throw new Error('Client disconnected or not provided');
     }
 
     const sessionId = await this.getSessionId();
@@ -312,34 +479,49 @@ export class AppHost {
   // Private: Resource Loading
   // ============================================
 
-  private async launchMcpApp(uri: string): Promise<void> {
-    if (!this.client.isConnected()) {
-      throw new Error('Client must be connected');
+  private async launchSandboxedHtml(html: string, config: SandboxConfig): Promise<void> {
+    const sandboxUrlString = config.url instanceof URL ? config.url.href : config.url;
+    const url = new URL(sandboxUrlString, globalThis.location?.href);
+    if (config.csp && Object.keys(config.csp).length > 0) {
+      url.searchParams.set('csp', JSON.stringify(config.csp));
     }
 
+    const { onReady } = await setupSandboxProxyIframe(this.iframe, url);
+    await onReady;
+  }
+
+
+  private async readMcpAppHtml(uri: string): Promise<string> {
     const sessionId = await this.getSessionId();
-    if (!sessionId) {
-      throw new Error('No active session');
+    if (!sessionId && !this.options.onReadResource) {
+      throw new Error('No active session.');
     }
-
-    // Fetch resource using cache hierarchy: SSEClient cache → local cache → direct fetch
     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}`);
     }
-
-    // Render via Blob URL for clean isolation
-    const blob = new Blob([html], { type: 'text/html' });
-    this.iframe.src = URL.createObjectURL(blob);
+    return html;
   }
 
-  private async fetchResourceWithCache(sessionId: string, uri: string): Promise<ResourceResponse> {
+  private async fetchResourceWithCache(sessionId: string | undefined, uri: string): Promise<ResourceResponse> {
+    if (this.options.onReadResource) {
+      return await this.options.onReadResource(uri);
+    }
+    
+    if (!sessionId) {
+      throw new Error('No active session');
+    }
+
+    if (!this.client) {
+      throw new Error('No client to read resource from');
+    }
+    
     // Priority 1: SSEClient's built-in cache (best performance)
     if (this.hasClientCache()) {
       return (this.client as any).getOrFetchResource(sessionId, uri);
@@ -358,8 +540,11 @@ export class AppHost {
 
   private async preloadResource(uri: string): Promise<ResourceResponse | null> {
     try {
+      if (this.options.onReadResource) {
+         return await this.options.onReadResource(uri);
+      }
       const sessionId = await this.getSessionId();
-      if (!sessionId) return null;
+      if (!sessionId || !this.client) return null;
       return await this.client.readResource(sessionId, uri) as ResourceResponse;
     } catch (error) {
       this.log(`Preload failed for ${uri}`, 'warn');
@@ -373,6 +558,7 @@ export class AppHost {
 
   private async getSessionId(): Promise<string | undefined> {
     if (this.sessionId) return this.sessionId;
+    if (!this.client) return undefined;
     const result = await this.client.getSessions();
     return result.sessions?.[0]?.sessionId;
   }
@@ -382,6 +568,7 @@ export class AppHost {
   }
 
   private hasClientCache(): boolean {
+    if (!this.client) return false;
     return 'getOrFetchResource' in this.client &&
            typeof (this.client as any).getOrFetchResource === 'function';
   }