feat(app): guard host-bound methods called before handshake completes

Calling callServerTool/sendMessage/etc. before connect() has finished the
ui/initialize → ui/notifications/initialized handshake can race the
handshake on strict hosts and leave the iframe permanently hidden.

- Add AppOptions.strict (default false). When false, emit console.error;
  when true, throw. Throwing will become the default in a future release.
- Export AppOptions; useApp() now forwards autoResize and strict.
- Guard all 8 host-bound App methods.
- Reset the flag on reconnect.
- link-self.mjs: skip when target is a symlink (was failing pre-commit
  with ERR_FS_CP_EINVAL when node_modules/@mcp/ext-apps -> repo root).

Refs anthropics/claude-ai-mcp#61, anthropics/claude-ai-mcp#149.

Author: ochafik

scripts/link-self.mjs

@@ -5,10 +5,12 @@
  * so examples always type-check against the latest local types.
  * See: https://github.com/npm/feedback/discussions/774
  */
-import { cpSync, existsSync } from "fs";
+import { cpSync, existsSync, lstatSync } from "fs";
 
 const target = "node_modules/@modelcontextprotocol/ext-apps";
 if (!existsSync(target)) process.exit(0);
+// If target is a symlink (e.g. to the repo root), dist is already current.
+if (lstatSync(target).isSymbolicLink()) process.exit(0);
 
 cpSync("dist", `${target}/dist`, { recursive: true });
 cpSync("package.json", `${target}/package.json`);

src/app-bridge.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach, spyOn } from "bun:test";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
@@ -780,6 +780,68 @@ describe("App <-> AppBridge integration", () => {
       );
     });
 
+    describe("pre-handshake guard (claude-ai-mcp#149)", () => {
+      const guardMsg =
+        /called before connect\(\) completed the ui\/initialize handshake/;
+
+      it("callServerTool warns when called before connect() completes", async () => {
+        const errSpy = spyOn(console, "error").mockImplementation(() => {});
+        bridge.oncalltool = async () => ({ content: [] });
+        await bridge.connect(bridgeTransport);
+
+        const connecting = app.connect(appTransport);
+        // Handshake is in flight; _initializedSent is still false.
+        await app.callServerTool({ name: "t", arguments: {} }).catch(() => {});
+
+        expect(errSpy).toHaveBeenCalledTimes(1);
+        expect(errSpy.mock.calls[0][0]).toMatch(guardMsg);
+        expect(errSpy.mock.calls[0][0]).toContain("App.callServerTool()");
+
+        await connecting;
+        errSpy.mockRestore();
+      });
+
+      it("callServerTool does not warn after connect() resolves", async () => {
+        const errSpy = spyOn(console, "error").mockImplementation(() => {});
+        bridge.oncalltool = async () => ({ content: [] });
+        await bridge.connect(bridgeTransport);
+        await app.connect(appTransport);
+
+        await app.callServerTool({ name: "t", arguments: {} });
+
+        expect(errSpy).not.toHaveBeenCalled();
+        errSpy.mockRestore();
+      });
+
+      it("sendMessage and readServerResource also warn before handshake", async () => {
+        const errSpy = spyOn(console, "error").mockImplementation(() => {});
+
+        await app.sendMessage({ role: "user", content: [] }).catch(() => {});
+        await app.readServerResource({ uri: "test://r" }).catch(() => {});
+
+        expect(errSpy).toHaveBeenCalledTimes(2);
+        expect(errSpy.mock.calls[0][0]).toContain("App.sendMessage()");
+        expect(errSpy.mock.calls[1][0]).toContain("App.readServerResource()");
+        errSpy.mockRestore();
+      });
+
+      it("throws instead of warning when strict: true", async () => {
+        const errSpy = spyOn(console, "error").mockImplementation(() => {});
+        const strictApp = new App(
+          testAppInfo,
+          {},
+          { autoResize: false, strict: true },
+        );
+
+        await expect(
+          strictApp.callServerTool({ name: "t", arguments: {} }),
+        ).rejects.toThrow(guardMsg);
+        expect(errSpy).not.toHaveBeenCalled();
+
+        errSpy.mockRestore();
+      });
+    });
+
     it("onlistresources setter registers handler for resources/list requests", async () => {
       const requestParams = {};
       const resources = [{ uri: "test://resource", name: "Test" }];

src/app.ts

@@ -144,7 +144,7 @@ export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
  *
  * @see `ProtocolOptions` from @modelcontextprotocol/sdk for inherited options
  */
-type AppOptions = ProtocolOptions & {
+export type AppOptions = ProtocolOptions & {
   /**
    * Automatically report size changes to the host using `ResizeObserver`.
    *
@@ -155,6 +155,19 @@ type AppOptions = ProtocolOptions & {
    * @default true
    */
   autoResize?: boolean;
+  /**
+   * Throw on detected misuse instead of logging a console error.
+   *
+   * Currently this affects calling host-bound methods (e.g.
+   * {@link App.callServerTool `callServerTool`}, {@link App.sendMessage `sendMessage`})
+   * before {@link App.connect `connect`} has completed the `ui/initialize`
+   * handshake. With `strict: false` (default) a `console.error` is emitted;
+   * with `strict: true` an `Error` is thrown.
+   *
+   * @remarks Throwing will become the default in a future release.
+   * @default false
+   */
+  strict?: boolean;
 };
 
 type RequestHandlerExtra = Parameters<
@@ -244,6 +257,32 @@ export class App extends ProtocolWithEvents<
   private _hostCapabilities?: McpUiHostCapabilities;
   private _hostInfo?: Implementation;
   private _hostContext?: McpUiHostContext;
+  private _initializedSent = false;
+
+  /**
+   * Warn if a host-bound method is called before {@link connect `connect`} has
+   * completed the `ui/initialize` → `ui/notifications/initialized` handshake.
+   *
+   * Calling these methods early can race the handshake on strict hosts and
+   * leave the iframe permanently hidden. See
+   * {@link https://github.com/anthropics/claude-ai-mcp/issues/61 claude-ai-mcp#61} /
+   * {@link https://github.com/anthropics/claude-ai-mcp/issues/149 #149}.
+   *
+   * @remarks This will become a thrown `Error` in a future minor release.
+   */
+  private _assertInitialized(method: string): void {
+    if (this._initializedSent) return;
+    const msg =
+      `[ext-apps] App.${method}() called before connect() completed the ` +
+      `ui/initialize handshake. Await app.connect() before calling this ` +
+      `method, or move data loading to an ontoolresult handler. ` +
+      `See https://github.com/anthropics/claude-ai-mcp/issues/149`;
+    if (this.options?.strict) {
+      throw new Error(msg);
+    }
+    // TODO(next-minor): make `strict: true` the default.
+    console.error(`${msg}. This will throw in a future release.`);
+  }
 
   protected readonly eventSchemas = {
     toolinput: McpUiToolInputNotificationSchema,
@@ -851,6 +890,7 @@ export class App extends ProtocolWithEvents<
     params: CallToolRequest["params"],
     options?: RequestOptions,
   ): Promise<CallToolResult> {
+    this._assertInitialized("callServerTool");
     if (typeof params === "string") {
       throw new Error(
         `callServerTool() expects an object as its first argument, but received a string ("${params}"). ` +
@@ -915,6 +955,7 @@ export class App extends ProtocolWithEvents<
     params: ReadResourceRequest["params"],
     options?: RequestOptions,
   ): Promise<ReadResourceResult> {
+    this._assertInitialized("readServerResource");
     return await this.request(
       { method: "resources/read", params },
       ReadResourceResultSchema,
@@ -962,6 +1003,7 @@ export class App extends ProtocolWithEvents<
     params?: ListResourcesRequest["params"],
     options?: RequestOptions,
   ): Promise<ListResourcesResult> {
+    this._assertInitialized("listServerResources");
     return await this.request(
       { method: "resources/list", params },
       ListResourcesResultSchema,
@@ -1020,6 +1062,7 @@ export class App extends ProtocolWithEvents<
    * @see {@link McpUiMessageRequest `McpUiMessageRequest`} for request structure
    */
   sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions) {
+    this._assertInitialized("sendMessage");
     return this.request(
       <McpUiMessageRequest>{
         method: "ui/message",
@@ -1113,6 +1156,7 @@ export class App extends ProtocolWithEvents<
     params: McpUiUpdateModelContextRequest["params"],
     options?: RequestOptions,
   ) {
+    this._assertInitialized("updateModelContext");
     return this.request(
       <McpUiUpdateModelContextRequest>{
         method: "ui/update-model-context",
@@ -1149,6 +1193,7 @@ export class App extends ProtocolWithEvents<
    * @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for result structure
    */
   openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions) {
+    this._assertInitialized("openLink");
     return this.request(
       <McpUiOpenLinkRequest>{
         method: "ui/open-link",
@@ -1229,6 +1274,7 @@ export class App extends ProtocolWithEvents<
     params: McpUiDownloadFileRequest["params"],
     options?: RequestOptions,
   ) {
+    this._assertInitialized("downloadFile");
     return this.request(
       <McpUiDownloadFileRequest>{
         method: "ui/download-file",
@@ -1313,6 +1359,7 @@ export class App extends ProtocolWithEvents<
     params: McpUiRequestDisplayModeRequest["params"],
     options?: RequestOptions,
   ) {
+    this._assertInitialized("requestDisplayMode");
     return this.request(
       <McpUiRequestDisplayModeRequest>{
         method: "ui/request-display-mode",
@@ -1475,6 +1522,7 @@ export class App extends ProtocolWithEvents<
         "App is already connected. Call close() before connecting again.",
       );
     }
+    this._initializedSent = false;
     await super.connect(transport);
 
     try {
@@ -1502,6 +1550,7 @@ export class App extends ProtocolWithEvents<
       await this.notification(<McpUiInitializedNotification>{
         method: "ui/notifications/initialized",
       });
+      this._initializedSent = true;
 
       if (this.options?.autoResize) {
         this.setupSizeChangedNotifications();

src/react/useApp.tsx

@@ -1,20 +1,28 @@
 import { useEffect, useState } from "react";
 import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import { Client } from "@modelcontextprotocol/sdk/client";
-import { App, McpUiAppCapabilities, PostMessageTransport } from "../app";
+import {
+  App,
+  AppOptions,
+  McpUiAppCapabilities,
+  PostMessageTransport,
+} from "../app";
 export * from "../app";
 
 /**
  * Options for configuring the {@link useApp `useApp`} hook.
  *
- * Note: This interface does NOT expose {@link App `App`} options like `autoResize`.
- * The hook creates the `App` with default options (`autoResize: true`). If you
- * need custom `App` options, create the `App` manually instead of using this hook.
+ * The `autoResize` and `strict` options are forwarded to the underlying
+ * {@link App `App`} instance. For other {@link AppOptions `AppOptions`}, create
+ * the `App` manually instead of using this hook.
  *
  * @see {@link useApp `useApp`} for the hook that uses these options
  * @see {@link useAutoResize `useAutoResize`} for manual auto-resize control with custom `App` options
  */
-export interface UseAppOptions {
+export interface UseAppOptions extends Pick<
+  AppOptions,
+  "autoResize" | "strict"
+> {
   /** App identification (name and version) */
   appInfo: Implementation;
   /**
@@ -121,6 +129,8 @@ export function useApp({
   appInfo,
   capabilities,
   onAppCreated,
+  autoResize = true,
+  strict,
 }: UseAppOptions): AppState {
   const [app, setApp] = useState<App | null>(null);
   const [isConnected, setIsConnected] = useState(false);
@@ -135,7 +145,7 @@ export function useApp({
           window.parent,
           window.parent,
         );
-        const app = new App(appInfo, capabilities);
+        const app = new App(appInfo, capabilities, { autoResize, strict });
 
         // Register handlers BEFORE connecting
         onAppCreated?.(app);