@modelcontextprotocol/ext-apps 0.3.1 → 0.4.1

package/dist/src/app.d.ts

@@ -1,7 +1,7 @@
 import { type RequestOptions, Protocol, ProtocolOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { CallToolRequest, CallToolResult, Implementation, ListToolsRequest, LoggingMessageNotification } from "@modelcontextprotocol/sdk/types.js";
 import { AppNotification, AppRequest, AppResult } from "./types";
-import { McpUiAppCapabilities, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiResourceTeardownRequest, McpUiResourceTeardownResult, McpUiSizeChangedNotification, McpUiToolCancelledNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification, McpUiRequestDisplayModeRequest } from "./types";
+import { McpUiAppCapabilities, McpUiUpdateModelContextRequest, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiResourceTeardownRequest, McpUiResourceTeardownResult, McpUiSizeChangedNotification, McpUiToolCancelledNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification, McpUiRequestDisplayModeRequest } from "./types";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 export { PostMessageTransport } from "./message-transport";
 export * from "./types";
@@ -11,7 +11,7 @@ export { applyHostStyleVariables, applyHostFonts, getDocumentTheme, applyDocumen
  *
  * MCP servers include this key in tool call result metadata to indicate which
  * UI resource should be displayed for the tool. When hosts receive a tool result
- * containing this metadata, they resolve and render the corresponding App.
+ * containing this metadata, they resolve and render the corresponding {@link App}.
  *
  * **Note**: This constant is provided for reference. MCP servers set this metadata
  * in their tool handlers; App developers typically don't need to use it directly.
@@ -39,20 +39,24 @@ export { applyHostStyleVariables, applyHostFonts, getDocumentTheme, applyDocumen
 export declare const RESOURCE_URI_META_KEY = "ui/resourceUri";
 /**
  * MIME type for MCP UI resources.
+ *
+ * Identifies HTML content as an MCP App UI resource.
+ *
+ * Used by {@link server-helpers!registerAppResource} as the default MIME type for app resources.
  */
 export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
 /**
- * Options for configuring App behavior.
+ * Options for configuring {@link App} behavior.
  *
- * Extends ProtocolOptions from the MCP SDK with App-specific configuration.
+ * Extends `ProtocolOptions` from the MCP SDK with `App`-specific configuration.
  *
- * @see ProtocolOptions from @modelcontextprotocol/sdk for inherited options
+ * @see `ProtocolOptions` from @modelcontextprotocol/sdk for inherited options
  */
 type AppOptions = ProtocolOptions & {
     /**
-     * Automatically report size changes to the host using ResizeObserver.
+     * Automatically report size changes to the host using `ResizeObserver`.
      *
-     * When enabled, the App monitors `document.body` and `document.documentElement`
+     * When enabled, the {@link App} monitors `document.body` and `document.documentElement`
      * for size changes and automatically sends `ui/notifications/size-changed`
      * notifications to the host.
      *
@@ -64,8 +68,8 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
 /**
  * Main class for MCP Apps to communicate with their host.
  *
- * The App class provides a framework-agnostic way to build interactive MCP Apps
- * that run inside host applications. It extends the MCP SDK's Protocol class and
+ * The `App` class provides a framework-agnostic way to build interactive MCP Apps
+ * that run inside host applications. It extends the MCP SDK's `Protocol` class and
  * handles the connection lifecycle, initialization handshake, and bidirectional
  * communication with the host.
  *
@@ -84,19 +88,20 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
  *
  * ## Inherited Methods
  *
- * As a subclass of Protocol, App inherits key methods for handling communication:
+ * As a subclass of `Protocol`, `App` inherits key methods for handling communication:
  * - `setRequestHandler()` - Register handlers for requests from host
  * - `setNotificationHandler()` - Register handlers for notifications from host
  *
- * @see Protocol from @modelcontextprotocol/sdk for all inherited methods
+ * @see `Protocol` from @modelcontextprotocol/sdk for all inherited methods
  *
  * ## Notification Setters
  *
- * For common notifications, the App class provides convenient setter properties
+ * For common notifications, the `App` class provides convenient setter properties
  * that simplify handler registration:
  * - `ontoolinput` - Complete tool arguments from host
  * - `ontoolinputpartial` - Streaming partial tool arguments
  * - `ontoolresult` - Tool execution results
+ * - `ontoolcancelled` - Tool execution was cancelled by user or host
  * - `onhostcontextchanged` - Host context changes (theme, locale, etc.)
  *
  * These setters are convenience wrappers around `setNotificationHandler()`.
@@ -128,7 +133,7 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
  *   }
  * );
  *
- * await app.connect(new PostMessageTransport(window.parent));
+ * await app.connect(new PostMessageTransport(window.parent, window.parent));
  * ```
  *
  * @example Sending a message to the host's chat
@@ -151,7 +156,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * @param _appInfo - App identification (name and version)
      * @param _capabilities - Features and capabilities this app provides
-     * @param options - Configuration options including autoResize behavior
+     * @param options - Configuration options including `autoResize` behavior
      *
      * @example
      * ```typescript
@@ -257,7 +262,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * Register handlers before calling {@link connect} to avoid missing notifications.
      *
-     * @param callback - Function called with the tool input params
+     * @param callback - Function called with the tool input params ({@link McpUiToolInputNotification.params})
      *
      * @example Using the setter (simpler)
      * ```typescript
@@ -295,7 +300,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * Register handlers before calling {@link connect} to avoid missing notifications.
      *
-     * @param callback - Function called with each partial tool input update
+     * @param callback - Function called with each partial tool input update ({@link McpUiToolInputPartialNotification.params})
      *
      * @example Progressive rendering of tool arguments
      * ```typescript
@@ -322,7 +327,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * Register handlers before calling {@link connect} to avoid missing notifications.
      *
-     * @param callback - Function called with the tool result
+     * @param callback - Function called with the tool result ({@link McpUiToolResultNotification.params})
      *
      * @example Display tool execution results
      * ```typescript
@@ -354,7 +359,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * Register handlers before calling {@link connect} to avoid missing notifications.
      *
-     * @param callback - Function called when tool execution is cancelled
+     * @param callback - Function called when tool execution is cancelled. Receives optional cancellation reason — see {@link McpUiToolCancelledNotification.params}.
      *
      * @example Handle tool cancellation
      * ```typescript
@@ -380,6 +385,10 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
+     * Notification params are automatically merged into the internal host context
+     * before the callback is invoked. This means {@link getHostContext} will
+     * return the updated values even before your callback runs.
+     *
      * Register handlers before calling {@link connect} to avoid missing notifications.
      *
      * @param callback - Function called with the updated host context
@@ -416,7 +425,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * Register handlers before calling {@link connect} to avoid missing requests.
      *
      * @param callback - Function called when teardown is requested.
-     *   Can return void or a Promise that resolves when cleanup is complete.
+     *   Must return `McpUiResourceTeardownResult` (can be an empty object `{}`) or a Promise resolving to it.
      *
      * @example Perform cleanup before teardown
      * ```typescript
@@ -424,6 +433,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *   await saveState();
      *   closeConnections();
      *   console.log("App ready for teardown");
+     *   return {};
      * };
      * ```
      *
@@ -477,9 +487,9 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * Register handlers before calling {@link connect} to avoid missing requests.
      *
-     * @param callback - Async function that returns the list of available tools.
-     *   The callback will only be invoked if the app declared tool capabilities
-     *   in the constructor.
+     * @param callback - Async function that returns tool names as strings (simplified
+     *   from full `ListToolsResult` with `Tool` objects). Registration is always
+     *   allowed; capability validation occurs when handlers are invoked.
      *
      * @example Return available tools
      * ```typescript
@@ -608,6 +618,47 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @returns Promise that resolves when the log notification is sent
      */
     sendLog(params: LoggingMessageNotification["params"]): Promise<void>;
+    /**
+     * Update the host's model context with app state.
+     *
+     * Unlike `sendLog`, which is for debugging/telemetry, context updates
+     * are intended to be available to the model in future reasoning,
+     * without requiring a follow-up action (like `sendMessage`).
+     *
+     * The host will typically defer sending the context to the model until the
+     * next user message (including `ui/message`), and will only send the last
+     * update received. Each call overwrites any previous context update.
+     *
+     * @param params - Context content and/or structured content
+     * @param options - Request options (timeout, etc.)
+     *
+     * @throws {Error} If the host rejects the context update (e.g., unsupported content type)
+     *
+     * @example Update model context with current app state
+     * ```typescript
+     * await app.updateModelContext({
+     *   content: [{ type: "text", text: "User selected 3 items totaling $150.00" }]
+     * });
+     * ```
+     *
+     * @example Update with structured content
+     * ```typescript
+     * await app.updateModelContext({
+     *   structuredContent: { selectedItems: 3, total: 150.00, currency: "USD" }
+     * });
+     * ```
+     *
+     * @returns Promise that resolves when the context update is acknowledged
+     */
+    updateModelContext(params: McpUiUpdateModelContextRequest["params"], options?: RequestOptions): Promise<{
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
     /**
      * Request the host to open an external URL in the default browser.
      *
@@ -727,7 +778,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * If initialization fails, the connection is automatically closed and an error
      * is thrown.
      *
-     * @param transport - Transport layer (typically PostMessageTransport)
+     * @param transport - Transport layer (typically {@link PostMessageTransport})
      * @param options - Request options for the initialize request
      *
      * @throws {Error} If initialization fails or connection is lost
@@ -740,7 +791,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * );
      *
      * try {
-     *   await app.connect(new PostMessageTransport(window.parent));
+     *   await app.connect(new PostMessageTransport(window.parent, window.parent));
      *   console.log("Connected successfully!");
      * } catch (error) {
      *   console.error("Failed to connect:", error);