@modelcontextprotocol/ext-apps 1.1.1 → 1.2.0

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 { CallToolRequest, CallToolResult, Implementation, ListResourcesRequest, ListResourcesResult, ListToolsRequest, LoggingMessageNotification, ReadResourceRequest, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { AppNotification, AppRequest, AppResult } from "./types";
-import { McpUiAppCapabilities, McpUiUpdateModelContextRequest, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiResourceTeardownRequest, McpUiResourceTeardownResult, McpUiSizeChangedNotification, McpUiToolCancelledNotification, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification, McpUiRequestDisplayModeRequest } from "./types";
+import { McpUiAppCapabilities, McpUiUpdateModelContextRequest, McpUiHostCapabilities, McpUiHostContext, McpUiHostContextChangedNotification, McpUiMessageRequest, McpUiOpenLinkRequest, McpUiDownloadFileRequest, 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";
@@ -14,12 +14,30 @@ export { applyHostStyleVariables, applyHostFonts, getDocumentTheme, applyDocumen
  * When hosts see a tool with this metadata, they fetch and render the
  * corresponding {@link App `App`}.
  *
- * **Note**: This constant is provided for reference. App developers typically
- * don't need to use it directly. Prefer using {@link server-helpers!registerAppTool `registerAppTool`}
- * with the `_meta.ui.resourceUri` format instead.
+ * **Note**: This constant is provided for reference and backwards compatibility.
+ * Server developers should use {@link server-helpers!registerAppTool `registerAppTool`}
+ * with the `_meta.ui.resourceUri` format instead. Host developers must check both
+ * formats for compatibility.
  *
- * @example How MCP servers use this key (server-side, not in Apps)
- * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_serverSide"
+ * @example Modern format (server-side, not in Apps)
+ * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_modernFormat"
+ * // Preferred: Use registerAppTool with nested ui.resourceUri
+ * registerAppTool(
+ *   server,
+ *   "weather",
+ *   {
+ *     description: "Get weather forecast",
+ *     _meta: {
+ *       ui: { resourceUri: "ui://weather/forecast" },
+ *     },
+ *   },
+ *   handler,
+ * );
+ * ```
+ *
+ * @example Legacy format (deprecated, for backwards compatibility)
+ * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_legacyFormat"
+ * // Deprecated: Direct use of RESOURCE_URI_META_KEY
  * server.registerTool(
  *   "weather",
  *   {
@@ -32,10 +50,13 @@ export { applyHostStyleVariables, applyHostFonts, getDocumentTheme, applyDocumen
  * );
  * ```
  *
- * @example How hosts check for this metadata (host-side)
+ * @example How hosts check for this metadata (must support both formats)
  * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_hostSide"
- * // Check tool definition metadata (from tools/list response):
- * const uiUri = tool._meta?.[RESOURCE_URI_META_KEY];
+ * // Hosts should check both modern and legacy formats
+ * const meta = tool._meta;
+ * const uiMeta = meta?.ui as McpUiToolMeta | undefined;
+ * const legacyUri = meta?.[RESOURCE_URI_META_KEY] as string | undefined;
+ * const uiUri = uiMeta?.resourceUri ?? legacyUri;
  * if (typeof uiUri === "string" && uiUri.startsWith("ui://")) {
  *   // Fetch the resource and display the UI
  * }
@@ -541,6 +562,84 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * ```
      */
     callServerTool(params: CallToolRequest["params"], options?: RequestOptions): Promise<CallToolResult>;
+    /**
+     * Read a resource from the originating MCP server (proxied through the host).
+     *
+     * Apps can read resources to access files, data, or other content provided by
+     * the MCP server. Resources are identified by URI (e.g., `file:///path/to/file`
+     * or custom schemes like `videos://bunny-1mb`). The host proxies the request to
+     * the actual MCP server and returns the resource content.
+     *
+     * @param params - Resource URI to read
+     * @param options - Request options (timeout, etc.)
+     * @returns Resource content with URI, name, description, mimeType, and contents array
+     *
+     * @throws {Error} If the resource does not exist on the server
+     * @throws {Error} If the request times out or the connection is lost
+     * @throws {Error} If the host rejects the request
+     *
+     * @example Read a video resource and play it
+     * ```ts source="./app.examples.ts#App_readServerResource_playVideo"
+     * try {
+     *   const result = await app.readServerResource({
+     *     uri: "videos://bunny-1mb",
+     *   });
+     *   const content = result.contents[0];
+     *   if (content && "blob" in content) {
+     *     const binary = Uint8Array.from(atob(content.blob), (c) =>
+     *       c.charCodeAt(0),
+     *     );
+     *     const url = URL.createObjectURL(
+     *       new Blob([binary], { type: content.mimeType || "video/mp4" }),
+     *     );
+     *     videoElement.src = url;
+     *     videoElement.play();
+     *   }
+     * } catch (error) {
+     *   console.error("Failed to read resource:", error);
+     * }
+     * ```
+     *
+     * @see {@link listServerResources `listServerResources`} to discover available resources
+     */
+    readServerResource(params: ReadResourceRequest["params"], options?: RequestOptions): Promise<ReadResourceResult>;
+    /**
+     * List available resources from the originating MCP server (proxied through the host).
+     *
+     * Apps can list resources to discover what content is available on the MCP server.
+     * This enables dynamic resource discovery and building resource browsers or pickers.
+     * The host proxies the request to the actual MCP server and returns the resource list.
+     *
+     * Results may be paginated using the `cursor` parameter for servers with many resources.
+     *
+     * @param params - Optional parameters (omit for all resources, or `{ cursor }` for pagination)
+     * @param options - Request options (timeout, etc.)
+     * @returns List of resources with their URIs, names, descriptions, mimeTypes, and optional pagination cursor
+     *
+     * @throws {Error} If the request times out or the connection is lost
+     * @throws {Error} If the host rejects the request
+     *
+     * @example Discover available videos and build a picker UI
+     * ```ts source="./app.examples.ts#App_listServerResources_buildPicker"
+     * try {
+     *   const result = await app.listServerResources();
+     *   const videoResources = result.resources.filter((r) =>
+     *     r.mimeType?.startsWith("video/"),
+     *   );
+     *   videoResources.forEach((resource) => {
+     *     const option = document.createElement("option");
+     *     option.value = resource.uri;
+     *     option.textContent = resource.description || resource.name;
+     *     selectElement.appendChild(option);
+     *   });
+     * } catch (error) {
+     *   console.error("Failed to list resources:", error);
+     * }
+     * ```
+     *
+     * @see {@link readServerResource `readServerResource`} to read a specific resource
+     */
+    listServerResources(params?: ListResourcesRequest["params"], options?: RequestOptions): Promise<ListResourcesResult>;
     /**
      * Send a message to the host's chat interface.
      *
@@ -708,6 +807,73 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
     }>;
     /** @deprecated Use {@link openLink `openLink`} instead */
     sendOpenLink: App["openLink"];
+    /**
+     * Request the host to download a file.
+     *
+     * Since MCP Apps run in sandboxed iframes where direct downloads are blocked,
+     * this provides a host-mediated mechanism for file exports. The host will
+     * typically show a confirmation dialog before initiating the download.
+     *
+     * Uses standard MCP resource types: `EmbeddedResource` for inline content
+     * and `ResourceLink` for content the host can fetch directly.
+     *
+     * @param params - Resource contents to download
+     * @param options - Request options (timeout, etc.)
+     * @returns Result with `isError: true` if the host denied the request (e.g., user cancelled)
+     *
+     * @throws {Error} If the request times out or the connection is lost
+     *
+     * @example Download a JSON file (embedded text resource)
+     * ```ts
+     * const data = JSON.stringify({ items: selectedItems }, null, 2);
+     * const { isError } = await app.downloadFile({
+     *   contents: [{
+     *     type: "resource",
+     *     resource: {
+     *       uri: "file:///export.json",
+     *       mimeType: "application/json",
+     *       text: data,
+     *     },
+     *   }],
+     * });
+     * if (isError) {
+     *   console.warn("Download denied or cancelled");
+     * }
+     * ```
+     *
+     * @example Download binary content (embedded blob resource)
+     * ```ts
+     * const { isError } = await app.downloadFile({
+     *   contents: [{
+     *     type: "resource",
+     *     resource: {
+     *       uri: "file:///image.png",
+     *       mimeType: "image/png",
+     *       blob: base64EncodedPng,
+     *     },
+     *   }],
+     * });
+     * ```
+     *
+     * @example Download via resource link (host fetches)
+     * ```ts
+     * const { isError } = await app.downloadFile({
+     *   contents: [{
+     *     type: "resource_link",
+     *     uri: "https://api.example.com/reports/q4.pdf",
+     *     name: "Q4 Report",
+     *     mimeType: "application/pdf",
+     *   }],
+     * });
+     * ```
+     *
+     * @see {@link McpUiDownloadFileRequest `McpUiDownloadFileRequest`} for request structure
+     * @see {@link McpUiDownloadFileResult `McpUiDownloadFileResult`} for result structure
+     */
+    downloadFile(params: McpUiDownloadFileRequest["params"], options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        isError?: boolean | undefined;
+    }>;
     /**
      * Request a change to the display mode.
      *