@modelcontextprotocol/ext-apps 0.0.7 → 0.2.0

package/dist/src/app.d.ts

@@ -1,9 +1,11 @@
 import { type RequestOptions, Protocol, ProtocolOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import { CallToolRequest, CallToolResult, Implementation, ListToolsRequest, LoggingMessageNotification, Notification, Request, Result } from "@modelcontextprotocol/sdk/types.js";
-import { McpUiAppCapabilities, McpUiHostCapabilities, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiSizeChangedNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification } from "./types";
+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 { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 export { PostMessageTransport } from "./message-transport";
 export * from "./types";
+export { applyHostStyleVariables, getDocumentTheme, applyDocumentTheme, } from "./styles";
 /**
  * Metadata key for associating a resource URI with a tool call.
  *
@@ -137,12 +139,13 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
  * });
  * ```
  */
-export declare class App extends Protocol<Request, Notification, Result> {
+export declare class App extends Protocol<AppRequest, AppNotification, AppResult> {
     private _appInfo;
     private _capabilities;
     private options;
     private _hostCapabilities?;
     private _hostInfo?;
+    private _hostContext?;
     /**
      * Create a new MCP App instance.
      *
@@ -209,6 +212,39 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * @see {@link connect} for the initialization handshake
      */
     getHostVersion(): Implementation | undefined;
+    /**
+     * Get the host context discovered during initialization.
+     *
+     * Returns the host context that was provided in the initialization response,
+     * including tool info, theme, viewport, locale, and other environment details.
+     * This context is automatically updated when the host sends
+     * `ui/notifications/host-context-changed` notifications.
+     *
+     * Returns `undefined` if called before connection is established.
+     *
+     * @returns Host context, or `undefined` if not yet connected
+     *
+     * @example Access host context after connection
+     * ```typescript
+     * await app.connect(transport);
+     * const context = app.getHostContext();
+     * if (context === undefined) {
+     *   console.error("Not connected");
+     *   return;
+     * }
+     * if (context.theme === "dark") {
+     *   document.body.classList.add("dark-theme");
+     * }
+     * if (context.toolInfo) {
+     *   console.log("Tool:", context.toolInfo.tool.name);
+     * }
+     * ```
+     *
+     * @see {@link connect} for the initialization handshake
+     * @see {@link onhostcontextchanged} for context change notifications
+     * @see {@link McpUiHostContext} for the context structure
+     */
+    getHostContext(): McpUiHostContext | undefined;
     /**
      * Convenience handler for receiving complete tool input from the host.
      *
@@ -305,6 +341,34 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * @see {@link ontoolinput} for the initial tool input handler
      */
     set ontoolresult(callback: (params: McpUiToolResultNotification["params"]) => void);
+    /**
+     * Convenience handler for receiving tool cancellation notifications from the host.
+     *
+     * Set this property to register a handler that will be called when the host
+     * notifies that tool execution was cancelled. This can occur for various reasons
+     * including user action, sampling error, classifier intervention, or other
+     * interruptions. Apps should update their state and display appropriate feedback.
+     *
+     * This setter is a convenience wrapper around `setNotificationHandler()` that
+     * automatically handles the notification schema and extracts the params for you.
+     *
+     * Register handlers before calling {@link connect} to avoid missing notifications.
+     *
+     * @param callback - Function called when tool execution is cancelled
+     *
+     * @example Handle tool cancellation
+     * ```typescript
+     * app.ontoolcancelled = (params) => {
+     *   console.log("Tool cancelled:", params.reason);
+     *   showCancelledMessage(params.reason ?? "Operation was cancelled");
+     * };
+     * ```
+     *
+     * @see {@link setNotificationHandler} for the underlying method
+     * @see {@link McpUiToolCancelledNotification} for the notification structure
+     * @see {@link ontoolresult} for successful tool completion
+     */
+    set ontoolcancelled(callback: (params: McpUiToolCancelledNotification["params"]) => void);
     /**
      * Convenience handler for host context changes (theme, viewport, locale, etc.).
      *
@@ -336,6 +400,37 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * @see {@link McpUiHostContext} for the full context structure
      */
     set onhostcontextchanged(callback: (params: McpUiHostContextChangedNotification["params"]) => void);
+    /**
+     * Convenience handler for graceful shutdown requests from the host.
+     *
+     * Set this property to register a handler that will be called when the host
+     * requests the app to prepare for teardown. This allows the app to perform
+     * cleanup operations (save state, close connections, etc.) before being unmounted.
+     *
+     * The handler can be sync or async. The host will wait for the returned promise
+     * to resolve before proceeding with teardown.
+     *
+     * This setter is a convenience wrapper around `setRequestHandler()` that
+     * automatically handles the request schema.
+     *
+     * 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.
+     *
+     * @example Perform cleanup before teardown
+     * ```typescript
+     * app.onteardown = async () => {
+     *   await saveState();
+     *   closeConnections();
+     *   console.log("App ready for teardown");
+     * };
+     * ```
+     *
+     * @see {@link setRequestHandler} for the underlying method
+     * @see {@link McpUiResourceTeardownRequest} for the request structure
+     */
+    set onteardown(callback: (params: McpUiResourceTeardownRequest["params"], extra: RequestHandlerExtra) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>);
     /**
      * Convenience handler for tool call requests from the host.
      *
@@ -405,17 +500,17 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * Verify that the host supports the capability required for the given request method.
      * @internal
      */
-    assertCapabilityForMethod(method: Request["method"]): void;
+    assertCapabilityForMethod(method: AppRequest["method"]): void;
     /**
      * Verify that the app declared the capability required for the given request method.
      * @internal
      */
-    assertRequestHandlerCapability(method: Request["method"]): void;
+    assertRequestHandlerCapability(method: AppRequest["method"]): void;
     /**
      * Verify that the app 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
@@ -489,7 +584,10 @@ export declare class App extends Protocol<Request, Notification, Result> {
      *
      * @see {@link McpUiMessageRequest} for request structure
      */
-    sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions): Promise<import("./types").McpUiMessageResult>;
+    sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        isError?: boolean | undefined;
+    }>;
     /**
      * Send log messages to the host for debugging and telemetry.
      *
@@ -526,7 +624,7 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * @example Open documentation link
      * ```typescript
      * try {
-     *   await app.sendOpenLink({ url: "https://docs.example.com" });
+     *   await app.openLink({ url: "https://docs.example.com" });
      * } catch (error) {
      *   console.error("Failed to open link:", error);
      *   // Optionally show fallback: display URL for manual copy
@@ -535,7 +633,40 @@ export declare class App extends Protocol<Request, Notification, Result> {
      *
      * @see {@link McpUiOpenLinkRequest} for request structure
      */
-    sendOpenLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions): Promise<import("./types").McpUiOpenLinkResult>;
+    openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        isError?: boolean | undefined;
+    }>;
+    /** @deprecated Use {@link openLink} instead */
+    sendOpenLink: App["openLink"];
+    /**
+     * Request a change to the display mode.
+     *
+     * Requests the host to change the UI container to the specified display mode
+     * (e.g., "inline", "fullscreen", "pip"). The host will respond with the actual
+     * display mode that was set, which may differ from the requested mode if
+     * the requested mode is not available (check `availableDisplayModes` in host context).
+     *
+     * @param params - The display mode being requested
+     * @param options - Request options (timeout, etc.)
+     * @returns Result containing the actual display mode that was set
+     *
+     * @example Request fullscreen mode
+     * ```typescript
+     * const context = app.getHostContext();
+     * if (context?.availableDisplayModes?.includes("fullscreen")) {
+     *   const result = await app.requestDisplayMode({ mode: "fullscreen" });
+     *   console.log("Display mode set to:", result.mode);
+     * }
+     * ```
+     *
+     * @see {@link McpUiRequestDisplayModeRequest} for request structure
+     * @see {@link McpUiHostContext} for checking availableDisplayModes
+     */
+    requestDisplayMode(params: McpUiRequestDisplayModeRequest["params"], options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        mode: "inline" | "fullscreen" | "pip";
+    }>;
     /**
      * Notify the host of UI size changes.
      *
@@ -620,5 +751,5 @@ export declare class App extends Protocol<Request, Notification, Result> {
      * @see {@link McpUiInitializedNotification} for the initialized notification
      * @see {@link PostMessageTransport} for the typical transport implementation
      */
-    connect(transport: Transport, options?: RequestOptions): Promise<void>;
+    connect(transport?: Transport, options?: RequestOptions): Promise<void>;
 }