@modelcontextprotocol/ext-apps 0.0.7 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @modelcontextprotocol/ext-apps
 
-[![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
+[![npm version](https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg)](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) [![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
 
 This repo contains the SDK and [specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
 
@@ -55,7 +55,7 @@ The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/exa
 
 To run all examples together:
 
-```
+```bash
 npm install
 npm run examples:start
 ```

package/dist/src/app-bridge.d.ts

@@ -1,11 +1,38 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { Implementation, LoggingMessageNotification, Notification, PingRequest, Request, Result } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequest, CallToolResult, Implementation, ListPromptsRequest, ListPromptsResult, ListResourcesRequest, ListResourcesResult, ListResourceTemplatesRequest, ListResourceTemplatesResult, LoggingMessageNotification, PingRequest, PromptListChangedNotification, ReadResourceRequest, ReadResourceResult, ResourceListChangedNotification, ToolListChangedNotification } from "@modelcontextprotocol/sdk/types.js";
 import { Protocol, ProtocolOptions, RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import { type McpUiSandboxResourceReadyNotification, type McpUiSizeChangedNotification, type McpUiToolInputNotification, type McpUiToolInputPartialNotification, type McpUiToolResultNotification, McpUiAppCapabilities, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiInitializedNotification, McpUiMessageRequest, McpUiMessageResult, McpUiOpenLinkRequest, McpUiOpenLinkResult, McpUiResourceTeardownRequest, McpUiSandboxProxyReadyNotification } from "./types";
+import { type AppNotification, type AppRequest, type AppResult, type McpUiSandboxResourceReadyNotification, type McpUiSizeChangedNotification, type McpUiToolCancelledNotification, type McpUiToolInputNotification, type McpUiToolInputPartialNotification, type McpUiToolResultNotification, McpUiAppCapabilities, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiInitializedNotification, McpUiMessageRequest, McpUiMessageResult, McpUiOpenLinkRequest, McpUiOpenLinkResult, McpUiResourceTeardownRequest, McpUiSandboxProxyReadyNotification, McpUiRequestDisplayModeRequest, McpUiRequestDisplayModeResult } from "./types";
 export * from "./types";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from "./app";
 export { PostMessageTransport } from "./message-transport";
+/**
+ * Extract UI resource URI from tool metadata.
+ *
+ * Supports both the new nested format (`_meta.ui.resourceUri`) and the
+ * deprecated flat format (`_meta["ui/resourceUri"]`). The new nested format
+ * takes precedence if both are present.
+ *
+ * @param tool - A tool object with optional `_meta` property
+ * @returns The UI resource URI if valid, undefined if not present
+ * @throws Error if resourceUri is present but invalid (not starting with "ui://")
+ *
+ * @example
+ * ```typescript
+ * // New nested format (preferred)
+ * const uri = getToolUiResourceUri({
+ *   _meta: { ui: { resourceUri: "ui://server/app.html" } }
+ * });
+ *
+ * // Deprecated flat format (still supported)
+ * const uri = getToolUiResourceUri({
+ *   _meta: { "ui/resourceUri": "ui://server/app.html" }
+ * });
+ * ```
+ */
+export declare function getToolUiResourceUri(tool: {
+    _meta?: Record<string, unknown>;
+}): string | undefined;
 /**
  * Options for configuring AppBridge behavior.
  *
@@ -53,7 +80,7 @@ type RequestHandlerExtra = Parameters<Parameters<AppBridge["setRequestHandler"]>
  * 2. **Connect**: Call `connect()` with transport to establish communication
  * 3. **Wait for init**: Guest UI sends initialize request, bridge responds
  * 4. **Send data**: Call `sendToolInput()`, `sendToolResult()`, etc.
- * 5. **Teardown**: Call `sendResourceTeardown()` before unmounting iframe
+ * 5. **Teardown**: Call `teardownResource()` before unmounting iframe
  *
  * @example Basic usage
  * ```typescript
@@ -90,7 +117,7 @@ type RequestHandlerExtra = Parameters<Parameters<AppBridge["setRequestHandler"]>
  * await bridge.connect(transport);
  * ```
  */
-export declare class AppBridge extends Protocol<Request, Notification, Result> {
+export declare class AppBridge extends Protocol<AppRequest, AppNotification, AppResult> {
     private _client;
     private _hostInfo;
     private _capabilities;
@@ -100,12 +127,15 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
     /**
      * Create a new AppBridge instance.
      *
-     * @param _client - MCP client connected to the server (for proxying requests)
+     * @param _client - MCP client connected to the server, or `null`. When provided,
+     *   {@link connect} will automatically set up forwarding of MCP requests/notifications
+     *   between the Guest UI and the server. When `null`, you must register handlers
+     *   manually using the `oncalltool`, `onlistresources`, etc. setters.
      * @param _hostInfo - Host application identification (name and version)
      * @param _capabilities - Features and capabilities the host supports
      * @param options - Configuration options (inherited from Protocol)
      *
-     * @example
+     * @example With MCP client (automatic forwarding)
      * ```typescript
      * const bridge = new AppBridge(
      *   mcpClient,
@@ -113,8 +143,18 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      *   { openLinks: {}, serverTools: {}, logging: {} }
      * );
      * ```
+     *
+     * @example Without MCP client (manual handlers)
+     * ```typescript
+     * const bridge = new AppBridge(
+     *   null,
+     *   { name: "MyHost", version: "1.0.0" },
+     *   { openLinks: {}, serverTools: {}, logging: {} }
+     * );
+     * bridge.oncalltool = async (params, extra) => { ... };
+     * ```
      */
-    constructor(_client: Client, _hostInfo: Implementation, _capabilities: McpUiHostCapabilities, options?: HostOptions);
+    constructor(_client: Client | null, _hostInfo: Implementation, _capabilities: McpUiHostCapabilities, options?: HostOptions);
     /**
      * Get the Guest UI's capabilities discovered during initialization.
      *
@@ -331,6 +371,39 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * @see {@link McpUiOpenLinkResult} for the result type
      */
     set onopenlink(callback: (params: McpUiOpenLinkRequest["params"], extra: RequestHandlerExtra) => Promise<McpUiOpenLinkResult>);
+    /**
+     * Register a handler for display mode change requests from the Guest UI.
+     *
+     * The Guest UI sends `ui/request-display-mode` requests when it wants to change
+     * its display mode (e.g., from "inline" to "fullscreen"). The handler should
+     * check if the requested mode is in `availableDisplayModes` from the host context,
+     * update the display mode if supported, and return the actual mode that was set.
+     *
+     * If the requested mode is not available, the handler should return the current
+     * display mode instead.
+     *
+     * @param callback - Handler that receives the requested mode and returns the actual mode set
+     *   - params.mode - The display mode being requested ("inline" | "fullscreen" | "pip")
+     *   - extra - Request metadata (abort signal, session info)
+     *   - Returns: Promise<McpUiRequestDisplayModeResult> with the actual mode set
+     *
+     * @example
+     * ```typescript
+     * bridge.onrequestdisplaymode = async ({ mode }, extra) => {
+     *   const availableModes = hostContext.availableDisplayModes ?? ["inline"];
+     *   if (availableModes.includes(mode)) {
+     *     setDisplayMode(mode);
+     *     return { mode };
+     *   }
+     *   // Return current mode if requested mode not available
+     *   return { mode: currentDisplayMode };
+     * };
+     * ```
+     *
+     * @see {@link McpUiRequestDisplayModeRequest} for the request type
+     * @see {@link McpUiRequestDisplayModeResult} for the result type
+     */
+    set onrequestdisplaymode(callback: (params: McpUiRequestDisplayModeRequest["params"], extra: RequestHandlerExtra) => Promise<McpUiRequestDisplayModeResult>);
     /**
      * Register a handler for logging messages from the Guest UI.
      *
@@ -359,21 +432,216 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * ```
      */
     set onloggingmessage(callback: (params: LoggingMessageNotification["params"]) => void);
+    /**
+     * Register a handler for tool call requests from the Guest UI.
+     *
+     * The Guest UI sends `tools/call` requests to execute MCP server tools. This
+     * handler allows the host to intercept and process these requests, typically
+     * by forwarding them to the MCP server.
+     *
+     * @param callback - Handler that receives tool call params and returns a
+     *   {@link CallToolResult}
+     * @param callback.params - Tool call parameters (name and arguments)
+     * @param callback.extra - Request metadata (abort signal, session info)
+     *
+     * @example
+     * ```typescript
+     * bridge.oncalltool = async ({ name, arguments: args }, extra) => {
+     *   return mcpClient.request(
+     *     { method: "tools/call", params: { name, arguments: args } },
+     *     CallToolResultSchema,
+     *     { signal: extra.signal }
+     *   );
+     * };
+     * ```
+     *
+     * @see {@link CallToolRequest} for the request type
+     * @see {@link CallToolResult} for the result type
+     */
+    set oncalltool(callback: (params: CallToolRequest["params"], extra: RequestHandlerExtra) => Promise<CallToolResult>);
+    /**
+     * Notify the Guest UI that the MCP server's tool list has changed.
+     *
+     * The host sends `notifications/tools/list_changed` to the Guest UI when it
+     * receives this notification from the MCP server. This allows the Guest UI
+     * to refresh its tool cache or UI accordingly.
+     *
+     * @param params - Optional notification params (typically empty)
+     *
+     * @example
+     * ```typescript
+     * // In your MCP client notification handler:
+     * mcpClient.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+     *   bridge.sendToolListChanged();
+     * });
+     * ```
+     *
+     * @see {@link ToolListChangedNotification} for the notification type
+     */
+    sendToolListChanged(params?: ToolListChangedNotification["params"]): Promise<void>;
+    /**
+     * Register a handler for list resources requests from the Guest UI.
+     *
+     * The Guest UI sends `resources/list` requests to enumerate available MCP
+     * resources. This handler allows the host to intercept and process these
+     * requests, typically by forwarding them to the MCP server.
+     *
+     * @param callback - Handler that receives list params and returns a
+     *   {@link ListResourcesResult}
+     * @param callback.params - Request params (may include cursor for pagination)
+     * @param callback.extra - Request metadata (abort signal, session info)
+     *
+     * @example
+     * ```typescript
+     * bridge.onlistresources = async (params, extra) => {
+     *   return mcpClient.request(
+     *     { method: "resources/list", params },
+     *     ListResourcesResultSchema,
+     *     { signal: extra.signal }
+     *   );
+     * };
+     * ```
+     *
+     * @see {@link ListResourcesRequest} for the request type
+     * @see {@link ListResourcesResult} for the result type
+     */
+    set onlistresources(callback: (params: ListResourcesRequest["params"], extra: RequestHandlerExtra) => Promise<ListResourcesResult>);
+    /**
+     * Register a handler for list resource templates requests from the Guest UI.
+     *
+     * The Guest UI sends `resources/templates/list` requests to enumerate available
+     * MCP resource templates. This handler allows the host to intercept and process
+     * these requests, typically by forwarding them to the MCP server.
+     *
+     * @param callback - Handler that receives list params and returns a
+     *   {@link ListResourceTemplatesResult}
+     * @param callback.params - Request params (may include cursor for pagination)
+     * @param callback.extra - Request metadata (abort signal, session info)
+     *
+     * @example
+     * ```typescript
+     * bridge.onlistresourcetemplates = async (params, extra) => {
+     *   return mcpClient.request(
+     *     { method: "resources/templates/list", params },
+     *     ListResourceTemplatesResultSchema,
+     *     { signal: extra.signal }
+     *   );
+     * };
+     * ```
+     *
+     * @see {@link ListResourceTemplatesRequest} for the request type
+     * @see {@link ListResourceTemplatesResult} for the result type
+     */
+    set onlistresourcetemplates(callback: (params: ListResourceTemplatesRequest["params"], extra: RequestHandlerExtra) => Promise<ListResourceTemplatesResult>);
+    /**
+     * Register a handler for read resource requests from the Guest UI.
+     *
+     * The Guest UI sends `resources/read` requests to retrieve the contents of an
+     * MCP resource. This handler allows the host to intercept and process these
+     * requests, typically by forwarding them to the MCP server.
+     *
+     * @param callback - Handler that receives read params and returns a
+     *   {@link ReadResourceResult}
+     * @param callback.params - Read parameters including the resource URI
+     * @param callback.extra - Request metadata (abort signal, session info)
+     *
+     * @example
+     * ```typescript
+     * bridge.onreadresource = async ({ uri }, extra) => {
+     *   return mcpClient.request(
+     *     { method: "resources/read", params: { uri } },
+     *     ReadResourceResultSchema,
+     *     { signal: extra.signal }
+     *   );
+     * };
+     * ```
+     *
+     * @see {@link ReadResourceRequest} for the request type
+     * @see {@link ReadResourceResult} for the result type
+     */
+    set onreadresource(callback: (params: ReadResourceRequest["params"], extra: RequestHandlerExtra) => Promise<ReadResourceResult>);
+    /**
+     * Notify the Guest UI that the MCP server's resource list has changed.
+     *
+     * The host sends `notifications/resources/list_changed` to the Guest UI when it
+     * receives this notification from the MCP server. This allows the Guest UI
+     * to refresh its resource cache or UI accordingly.
+     *
+     * @param params - Optional notification params (typically empty)
+     *
+     * @example
+     * ```typescript
+     * // In your MCP client notification handler:
+     * mcpClient.setNotificationHandler(ResourceListChangedNotificationSchema, () => {
+     *   bridge.sendResourceListChanged();
+     * });
+     * ```
+     *
+     * @see {@link ResourceListChangedNotification} for the notification type
+     */
+    sendResourceListChanged(params?: ResourceListChangedNotification["params"]): Promise<void>;
+    /**
+     * Register a handler for list prompts requests from the Guest UI.
+     *
+     * The Guest UI sends `prompts/list` requests to enumerate available MCP
+     * prompts. This handler allows the host to intercept and process these
+     * requests, typically by forwarding them to the MCP server.
+     *
+     * @param callback - Handler that receives list params and returns a
+     *   {@link ListPromptsResult}
+     * @param callback.params - Request params (may include cursor for pagination)
+     * @param callback.extra - Request metadata (abort signal, session info)
+     *
+     * @example
+     * ```typescript
+     * bridge.onlistprompts = async (params, extra) => {
+     *   return mcpClient.request(
+     *     { method: "prompts/list", params },
+     *     ListPromptsResultSchema,
+     *     { signal: extra.signal }
+     *   );
+     * };
+     * ```
+     *
+     * @see {@link ListPromptsRequest} for the request type
+     * @see {@link ListPromptsResult} for the result type
+     */
+    set onlistprompts(callback: (params: ListPromptsRequest["params"], extra: RequestHandlerExtra) => Promise<ListPromptsResult>);
+    /**
+     * Notify the Guest UI that the MCP server's prompt list has changed.
+     *
+     * The host sends `notifications/prompts/list_changed` to the Guest UI when it
+     * receives this notification from the MCP server. This allows the Guest UI
+     * to refresh its prompt cache or UI accordingly.
+     *
+     * @param params - Optional notification params (typically empty)
+     *
+     * @example
+     * ```typescript
+     * // In your MCP client notification handler:
+     * mcpClient.setNotificationHandler(PromptListChangedNotificationSchema, () => {
+     *   bridge.sendPromptListChanged();
+     * });
+     * ```
+     *
+     * @see {@link PromptListChangedNotification} for the notification type
+     */
+    sendPromptListChanged(params?: PromptListChangedNotification["params"]): Promise<void>;
     /**
      * Verify that the guest supports the capability required for the given request method.
      * @internal
      */
-    assertCapabilityForMethod(method: Request["method"]): void;
+    assertCapabilityForMethod(method: AppRequest["method"]): void;
     /**
      * Verify that a request handler is registered and supported for the given method.
      * @internal
      */
-    assertRequestHandlerCapability(method: Request["method"]): void;
+    assertRequestHandlerCapability(method: AppRequest["method"]): void;
     /**
      * Verify that the host supports the capability required for the given notification method.
      * @internal
      */
-    assertNotificationCapability(method: Notification["method"]): void;
+    assertNotificationCapability(method: AppNotification["method"]): void;
     /**
      * Verify that task creation is supported for the given request method.
      * @internal
@@ -510,6 +778,37 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * @see {@link sendToolInput} for sending tool arguments before results
      */
     sendToolResult(params: McpUiToolResultNotification["params"]): Promise<void>;
+    /**
+     * Notify the Guest UI that tool execution was cancelled.
+     *
+     * The host MUST send this notification if tool execution was cancelled for any
+     * reason, including user action, sampling error, classifier intervention, or
+     * any other interruption. This allows the Guest UI to update its state and
+     * display appropriate feedback to the user.
+     *
+     * @param params - Optional cancellation details:
+     *   - `reason`: Human-readable explanation for why the tool was cancelled
+     *
+     * @example User-initiated cancellation
+     * ```typescript
+     * // User clicked "Cancel" button
+     * bridge.sendToolCancelled({ reason: "User cancelled the operation" });
+     * ```
+     *
+     * @example System-level cancellation
+     * ```typescript
+     * // Sampling error or timeout
+     * bridge.sendToolCancelled({ reason: "Request timeout after 30 seconds" });
+     *
+     * // Classifier intervention
+     * bridge.sendToolCancelled({ reason: "Content policy violation detected" });
+     * ```
+     *
+     * @see {@link McpUiToolCancelledNotification} for the notification type
+     * @see {@link sendToolResult} for sending successful results
+     * @see {@link sendToolInput} for sending tool arguments
+     */
+    sendToolCancelled(params: McpUiToolCancelledNotification["params"]): Promise<void>;
     /**
      * Send HTML resource to the sandbox proxy for secure loading.
      *
@@ -542,7 +841,7 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * @example
      * ```typescript
      * try {
-     *   await bridge.sendResourceTeardown({});
+     *   await bridge.teardownResource({});
      *   // Guest UI is ready, safe to unmount iframe
      *   iframe.remove();
      * } catch (error) {
@@ -550,18 +849,22 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * }
      * ```
      */
-    sendResourceTeardown(params: McpUiResourceTeardownRequest["params"], options?: RequestOptions): Promise<import("./types").McpUiResourceTeardownResult>;
-    private forwardRequest;
-    private forwardNotification;
+    teardownResource(params: McpUiResourceTeardownRequest["params"], options?: RequestOptions): Promise<Record<string, unknown>>;
+    /** @deprecated Use {@link teardownResource} instead */
+    sendResourceTeardown: AppBridge["teardownResource"];
     /**
-     * Connect to the Guest UI via transport and set up message forwarding.
+     * Connect to the Guest UI via transport and optionally set up message forwarding.
+     *
+     * This method establishes the transport connection. If an MCP client was passed
+     * to the constructor, it also automatically sets up request/notification forwarding
+     * based on the MCP server's capabilities, proxying the following to the Guest UI:
+     * - Tools (tools/call, notifications/tools/list_changed)
+     * - Resources (resources/list, resources/read, resources/templates/list, notifications/resources/list_changed)
+     * - Prompts (prompts/list, notifications/prompts/list_changed)
      *
-     * This method establishes the transport connection and automatically sets up
-     * request/notification forwarding based on the MCP server's capabilities.
-     * It proxies the following server capabilities to the Guest UI:
-     * - Tools (tools/call, tools/list_changed)
-     * - Resources (resources/list, resources/read, resources/templates/list, resources/list_changed)
-     * - Prompts (prompts/list, prompts/list_changed)
+     * If no client was passed to the constructor, no automatic forwarding is set up
+     * and you must register handlers manually using the `oncalltool`, `onlistresources`,
+     * etc. setters.
      *
      * After calling connect, wait for the `oninitialized` callback before sending
      * tool input and other data to the Guest UI.
@@ -569,12 +872,12 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      * @param transport - Transport layer (typically PostMessageTransport)
      * @returns Promise resolving when connection is established
      *
-     * @throws {Error} If server capabilities are not available. This occurs when
-     *   connect() is called before the MCP client has completed its initialization
-     *   with the server. Ensure `await client.connect()` completes before calling
-     *   `bridge.connect()`.
+     * @throws {Error} If a client was passed but server capabilities are not available.
+     *   This occurs when connect() is called before the MCP client has completed its
+     *   initialization with the server. Ensure `await client.connect()` completes
+     *   before calling `bridge.connect()`.
      *
-     * @example
+     * @example With MCP client (automatic forwarding)
      * ```typescript
      * const bridge = new AppBridge(mcpClient, hostInfo, capabilities);
      * const transport = new PostMessageTransport(
@@ -589,6 +892,18 @@ export declare class AppBridge extends Protocol<Request, Notification, Result> {
      *
      * await bridge.connect(transport);
      * ```
+     *
+     * @example Without MCP client (manual handlers)
+     * ```typescript
+     * const bridge = new AppBridge(null, hostInfo, capabilities);
+     *
+     * // Register handlers manually
+     * bridge.oncalltool = async (params, extra) => {
+     *   // Custom tool call handling
+     * };
+     *
+     * await bridge.connect(transport);
+     * ```
      */
     connect(transport: Transport): Promise<void>;
 }