@modelcontextprotocol/ext-apps 0.3.1 → 0.4.0

package/README.md

@@ -6,6 +6,17 @@ This repo contains the SDK and [specification](https://github.com/modelcontextpr
 
 MCP Apps are a proposed standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
 
+## How It Works
+
+MCP Apps extend the Model Context Protocol to let servers deliver **interactive UIs** to MCP hosts. Here's how it works:
+
+1. **Tool call** — The LLM calls a tool on your server
+2. **UI Resource** — The tool's definition links to a predeclared `ui://` resource containing its HTML interface
+3. **Host renders** — The host fetches the resource and displays it in a sandboxed iframe
+4. **Bidirectional communication** — The host passes tool data to the UI via notifications, and the UI can call other tools through the host
+
+This enables dashboards, forms, visualizations, and other rich experiences inside chat interfaces.
+
 ## Overview
 
 This SDK serves two audiences:

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

@@ -1,8 +1,8 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { CallToolRequest, CallToolResult, Implementation, ListPromptsRequest, ListPromptsResult, ListResourcesRequest, ListResourcesResult, ListResourceTemplatesRequest, ListResourceTemplatesResult, LoggingMessageNotification, PingRequest, PromptListChangedNotification, ReadResourceRequest, ReadResourceResult, ResourceListChangedNotification, ToolListChangedNotification } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequest, CallToolResult, EmptyResult, 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 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";
+import { type AppNotification, type AppRequest, type AppResult, type McpUiSandboxResourceReadyNotification, type McpUiSizeChangedNotification, type McpUiToolCancelledNotification, type McpUiToolInputNotification, type McpUiToolInputPartialNotification, type McpUiToolResultNotification, McpUiAppCapabilities, McpUiUpdateModelContextRequest, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiInitializedNotification, McpUiMessageRequest, McpUiMessageResult, McpUiOpenLinkRequest, McpUiOpenLinkResult, McpUiResourceTeardownRequest, McpUiSandboxProxyReadyNotification, McpUiRequestDisplayModeRequest, McpUiRequestDisplayModeResult, McpUiResourcePermissions } from "./types";
 export * from "./types";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from "./app";
 export { PostMessageTransport } from "./message-transport";
@@ -33,6 +33,23 @@ export { PostMessageTransport } from "./message-transport";
 export declare function getToolUiResourceUri(tool: {
     _meta?: Record<string, unknown>;
 }): string | undefined;
+/**
+ * Build iframe `allow` attribute string from permissions.
+ *
+ * Maps McpUiResourcePermissions to the Permission Policy allow attribute
+ * format used by iframes (e.g., "microphone; clipboard-write").
+ *
+ * @param permissions - Permissions requested by the UI resource
+ * @returns Space-separated permission directives, or empty string if none
+ *
+ * @example
+ * ```typescript
+ * const allow = buildAllowAttribute({ microphone: {}, clipboardWrite: {} });
+ * // Returns: "microphone; clipboard-write"
+ * iframe.setAttribute("allow", allow);
+ * ```
+ */
+export declare function buildAllowAttribute(permissions: McpUiResourcePermissions | undefined): string;
 /**
  * Options for configuring AppBridge behavior.
  *
@@ -432,6 +449,35 @@ export declare class AppBridge extends Protocol<AppRequest, AppNotification, App
      * ```
      */
     set onloggingmessage(callback: (params: LoggingMessageNotification["params"]) => void);
+    /**
+     * Register a handler for model context updates from the Guest UI.
+     *
+     * The Guest UI sends `ui/update-model-context` requests to update the Host's
+     * model context. Each request overwrites the previous context stored by the Guest UI.
+     * Unlike logging messages, context updates are intended to be available to
+     * the model in future turns. Unlike messages, context updates do not trigger follow-ups.
+     *
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * bridge.onupdatemodelcontext = async ({ content, structuredContent }, extra) => {
+     *   // Update the model context with the new snapshot
+     *   modelContext = {
+     *     type: "app_context",
+     *     content,
+     *     structuredContent,
+     *     timestamp: Date.now()
+     *   };
+     *   return {};
+     * };
+     * ```
+     *
+     * @see {@link McpUiUpdateModelContextRequest} for the request type
+     */
+    set onupdatemodelcontext(callback: (params: McpUiUpdateModelContextRequest["params"], extra: RequestHandlerExtra) => Promise<EmptyResult>);
     /**
      * Register a handler for tool call requests from the Guest UI.
      *