@modelcontextprotocol/ext-apps 0.0.7 → 0.1.0

package/dist/src/app.d.ts

@@ -1,6 +1,6 @@
 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 { McpUiAppCapabilities, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiResourceTeardownRequest, McpUiResourceTeardownResult, McpUiSizeChangedNotification, McpUiToolCancelledNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification } from "./types";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 export { PostMessageTransport } from "./message-transport";
 export * from "./types";
@@ -143,6 +143,7 @@ export declare class App extends Protocol<Request, Notification, Result> {
     private options;
     private _hostCapabilities?;
     private _hostInfo?;
+    private _hostContext?;
     /**
      * Create a new MCP App instance.
      *
@@ -209,6 +210,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 +339,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 +398,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.
      *
@@ -489,7 +582,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.
      *
@@ -535,7 +631,10 @@ 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>;
+    sendOpenLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        isError?: boolean | undefined;
+    }>;
     /**
      * Notify the host of UI size changes.
      *