@modelcontextprotocol/ext-apps 1.0.0 → 1.1.0

package/dist/src/react/useApp.d.ts

@@ -97,8 +97,8 @@ export interface AppState {
  *       app.onerror = (error) => {
  *         console.log("Error:", error);
  *       };
- *       app.onhostcontextchanged = (params) => {
- *         setHostContext((prev) => ({ ...prev, ...params }));
+ *       app.onhostcontextchanged = (ctx) => {
+ *         setHostContext((prev) => ({ ...prev, ...ctx }));
  *       };
  *     },
  *   });

package/dist/src/server/index.d.ts

@@ -31,11 +31,11 @@
  * ```
  */
 import { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE, McpUiResourceMeta, McpUiToolMeta, McpUiClientCapabilities } from "../app.js";
-import type { McpServer, RegisteredTool, ResourceMetadata, ToolCallback, ReadResourceCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer, RegisteredTool, ResourceMetadata, ToolCallback, ReadResourceCallback as _ReadResourceCallback, RegisteredResource } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
-import type { ClientCapabilities, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ClientCapabilities, ReadResourceResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
-export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
+export type { ResourceMetadata, ToolCallback };
 /**
  * Base tool configuration matching the standard MCP server tool options.
  * Extended by {@link McpUiAppToolConfig `McpUiAppToolConfig`} to add UI metadata requirements.
@@ -81,12 +81,19 @@ export interface McpUiAppToolConfig extends ToolConfig {
  * Extends the base MCP SDK `ResourceMetadata` with optional UI metadata
  * for configuring security policies and rendering preferences.
  *
+ * The `_meta.ui` field here is included in the `resources/list` response and serves as
+ * a static default for hosts to review at connection time. When the `resources/read`
+ * content item also includes `_meta.ui`, the content-item value takes precedence.
+ *
  * @see {@link registerAppResource `registerAppResource`} for usage
  */
 export interface McpUiAppResourceConfig extends ResourceMetadata {
     /**
      * Optional UI metadata for the resource.
-     * Used to configure security policies (CSP) and rendering preferences.
+     *
+     * This appears on the resource entry in `resources/list` and acts as a listing-level
+     * fallback. Individual content items returned by `resources/read` may include their
+     * own `_meta.ui` which takes precedence over this value.
      */
     _meta?: {
         /**
@@ -177,6 +184,14 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
     inputSchema?: InputArgs;
     outputSchema?: OutputArgs;
 }, cb: ToolCallback<InputArgs>): RegisteredTool;
+export type McpUiReadResourceResult = ReadResourceResult & {
+    _meta?: {
+        ui?: McpUiResourceMeta;
+        [key: string]: unknown;
+    };
+};
+export type McpUiReadResourceCallback = (uri: URL, extra: Parameters<_ReadResourceCallback>[1]) => McpUiReadResourceResult | Promise<McpUiReadResourceResult>;
+export type ReadResourceCallback = McpUiReadResourceCallback;
 /**
  * Register an app resource with the MCP server.
  *
@@ -211,7 +226,7 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
  * );
  * ```
  *
- * @example With CSP configuration for external domains
+ * @example With CSP configuration for network access
  * ```ts source="./index.examples.ts#registerAppResource_withCsp"
  * registerAppResource(
  *   server,
@@ -240,9 +255,57 @@ export declare function registerAppTool<OutputArgs extends ZodRawShapeCompat | A
  * );
  * ```
  *
+ * @example With stable origin for external API CORS allowlists
+ * ```ts source="./index.examples.ts#registerAppResource_withDomain"
+ * // Computes a stable origin from an MCP server URL for hosting in Claude.
+ * function computeAppDomainForClaude(mcpServerUrl: string): string {
+ *   const hash = crypto
+ *     .createHash("sha256")
+ *     .update(mcpServerUrl)
+ *     .digest("hex")
+ *     .slice(0, 32);
+ *   return `${hash}.claudemcpcontent.com`;
+ * }
+ *
+ * const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp");
+ *
+ * registerAppResource(
+ *   server,
+ *   "Company Dashboard",
+ *   "ui://dashboard/view.html",
+ *   {
+ *     description: "Internal dashboard with company data",
+ *   },
+ *   async () => ({
+ *     contents: [
+ *       {
+ *         uri: "ui://dashboard/view.html",
+ *         mimeType: RESOURCE_MIME_TYPE,
+ *         text: dashboardHtml,
+ *         _meta: {
+ *           ui: {
+ *             // CSP: tell browser the app is allowed to make requests
+ *             csp: {
+ *               connectDomains: ["https://api.example.com"],
+ *             },
+ *             // CORS: give app a stable origin for the API server to allowlist
+ *             //
+ *             // (Public APIs that use `Access-Control-Allow-Origin: *` or API
+ *             // key auth don't need this.)
+ *             domain: APP_DOMAIN,
+ *           },
+ *         },
+ *       },
+ *     ],
+ *   }),
+ * );
+ * ```
+ *
+ * @see {@link McpUiResourceMeta `McpUiResourceMeta`} for `_meta.ui` configuration options
+ * @see {@link McpUiResourceCsp `McpUiResourceCsp`} for CSP domain allowlist configuration
  * @see {@link registerAppTool `registerAppTool`} to register tools that reference this resource
  */
-export declare function registerAppResource(server: Pick<McpServer, "registerResource">, name: string, uri: string, config: McpUiAppResourceConfig, readCallback: ReadResourceCallback): void;
+export declare function registerAppResource(server: Pick<McpServer, "registerResource">, name: string, uri: string, config: McpUiAppResourceConfig, readCallback: McpUiReadResourceCallback): RegisteredResource;
 /**
  * Extension identifier for MCP Apps capability negotiation.
  *
@@ -263,21 +326,31 @@ export declare const EXTENSION_ID = "io.modelcontextprotocol/ui";
  * @returns The MCP Apps capability settings, or `undefined` if not supported
  *
  * @example Check for MCP Apps support in server initialization
- * ```typescript
- * import { getUiCapability, RESOURCE_MIME_TYPE, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
- *
- * server.oninitialized = ({ clientCapabilities }) => {
+ * ```ts source="./index.examples.ts#getUiCapability_checkSupport"
+ * server.server.oninitialized = () => {
+ *   const clientCapabilities = server.server.getClientCapabilities();
  *   const uiCap = getUiCapability(clientCapabilities);
+ *
  *   if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
- *     registerAppTool(server, "weather", {
- *       description: "Get weather with interactive dashboard",
- *       _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
- *     }, weatherHandler);
+ *     // App-enhanced tool
+ *     registerAppTool(
+ *       server,
+ *       "weather",
+ *       {
+ *         description: "Get weather information with interactive dashboard",
+ *         _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
+ *       },
+ *       weatherHandler,
+ *     );
  *   } else {
- *     // Register text-only fallback
- *     server.registerTool("weather", {
- *       description: "Get weather as text",
- *     }, textWeatherHandler);
+ *     // Text-only fallback
+ *     server.registerTool(
+ *       "weather",
+ *       {
+ *         description: "Get weather information",
+ *       },
+ *       textWeatherHandler,
+ *     );
  *   }
  * };
  * ```