@modelcontextprotocol/ext-apps 1.0.1 → 1.1.1

package/dist/src/spec.types.d.ts

@@ -404,43 +404,137 @@ export interface McpUiInitializedNotification {
 }
 /**
  * @description Content Security Policy configuration for UI resources.
+ *
+ * Servers declare which origins their UI requires. Hosts use this to enforce appropriate CSP headers.
+ *
+ * > [!IMPORTANT]
+ * > MCP App HTML runs in a sandboxed iframe with no same-origin server.
+ * > **All** origins must be declared—including where your bundled JS/CSS is
+ * > served from (`localhost` in dev, your CDN in production).
  */
 export interface McpUiResourceCsp {
-    /** @description Origins for network requests (fetch/XHR/WebSocket). */
+    /**
+     * @description Origins for network requests (fetch/XHR/WebSocket).
+     *
+     * - Maps to CSP `connect-src` directive
+     * - Empty or omitted → no network connections (secure default)
+     *
+     * @example
+     * ```ts
+     * ["https://api.weather.com", "wss://realtime.service.com"]
+     * ```
+     */
     connectDomains?: string[];
-    /** @description Origins for static resources (scripts, images, styles, fonts). */
+    /**
+     * @description Origins for static resources (images, scripts, stylesheets, fonts, media).
+     *
+     * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src`, `media-src` directives
+     * - Wildcard subdomains supported: `https://*.example.com`
+     * - Empty or omitted → no network resources (secure default)
+     *
+     * @example
+     * ```ts
+     * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
+     * ```
+     */
     resourceDomains?: string[];
-    /** @description Origins for nested iframes (frame-src directive). */
+    /**
+     * @description Origins for nested iframes.
+     *
+     * - Maps to CSP `frame-src` directive
+     * - Empty or omitted → no nested iframes allowed (`frame-src 'none'`)
+     *
+     * @example
+     * ```ts
+     * ["https://www.youtube.com", "https://player.vimeo.com"]
+     * ```
+     */
     frameDomains?: string[];
-    /** @description Allowed base URIs for the document (base-uri directive). */
+    /**
+     * @description Allowed base URIs for the document.
+     *
+     * - Maps to CSP `base-uri` directive
+     * - Empty or omitted → only same origin allowed (`base-uri 'self'`)
+     *
+     * @example
+     * ```ts
+     * ["https://cdn.example.com"]
+     * ```
+     */
     baseUriDomains?: string[];
 }
 /**
  * @description Sandbox permissions requested by the UI resource.
+ *
+ * Servers declare which browser capabilities their UI needs.
  * Hosts MAY honor these by setting appropriate iframe `allow` attributes.
  * Apps SHOULD NOT assume permissions are granted; use JS feature detection as fallback.
  */
 export interface McpUiResourcePermissions {
-    /** @description Request camera access (Permission Policy `camera` feature). */
+    /**
+     * @description Request camera access.
+     *
+     * Maps to Permission Policy `camera` feature.
+     */
     camera?: {};
-    /** @description Request microphone access (Permission Policy `microphone` feature). */
+    /**
+     * @description Request microphone access.
+     *
+     * Maps to Permission Policy `microphone` feature.
+     */
     microphone?: {};
-    /** @description Request geolocation access (Permission Policy `geolocation` feature). */
+    /**
+     * @description Request geolocation access.
+     *
+     * Maps to Permission Policy `geolocation` feature.
+     */
     geolocation?: {};
-    /** @description Request clipboard write access (Permission Policy `clipboard-write` feature). */
+    /**
+     * @description Request clipboard write access.
+     *
+     * Maps to Permission Policy `clipboard-write` feature.
+     */
     clipboardWrite?: {};
 }
 /**
  * @description UI Resource metadata for security and rendering configuration.
  */
 export interface McpUiResourceMeta {
-    /** @description Content Security Policy configuration. */
+    /** @description Content Security Policy configuration for UI resources. */
     csp?: McpUiResourceCsp;
-    /** @description Sandbox permissions requested by the UI. */
+    /** @description Sandbox permissions requested by the UI resource. */
     permissions?: McpUiResourcePermissions;
-    /** @description Dedicated origin for view sandbox. */
+    /**
+     * @description Dedicated origin for view sandbox.
+     *
+     * Useful when views need stable, dedicated origins for OAuth callbacks, CORS policies, or API key allowlists.
+     *
+     * **Host-dependent:** The format and validation rules for this field are determined by each host. Servers MUST consult host-specific documentation for the expected domain format. Common patterns include:
+     * - Hash-based subdomains (e.g., `{hash}.claudemcpcontent.com`)
+     * - URL-derived subdomains (e.g., `www-example-com.oaiusercontent.com`)
+     *
+     * If omitted, host uses default sandbox origin (typically per-conversation).
+     *
+     * @example
+     * ```ts
+     * "a904794854a047f6.claudemcpcontent.com"
+     * ```
+     *
+     * @example
+     * ```ts
+     * "www-example-com.oaiusercontent.com"
+     * ```
+     */
     domain?: string;
-    /** @description Visual boundary preference - true if UI prefers a visible border. */
+    /**
+     * @description Visual boundary preference - true if view prefers a visible border.
+     *
+     * Boolean requesting whether a visible border and background is provided by the host. Specifying an explicit value for this is recommended because hosts' defaults may vary.
+     *
+     * - `true`: request visible border + background
+     * - `false`: request no visible border + background
+     * - omitted: host decides border
+     */
     prefersBorder?: boolean;
 }
 /**
@@ -481,7 +575,10 @@ export interface McpUiToolMeta {
      * URI of the UI resource to display for this tool, if any.
      * This is converted to `_meta["ui/resourceUri"]`.
      *
-     * @example "ui://weather/view.html"
+     * @example
+     * ```ts
+     * "ui://weather/view.html"
+     * ```
      */
     resourceUri?: string;
     /**

package/dist/src/styles.d.ts

@@ -31,9 +31,9 @@ export declare function getDocumentTheme(): McpUiTheme;
  * @example Apply theme from host context
  * ```ts source="./styles.examples.ts#applyDocumentTheme_fromHostContext"
  * // Apply when host context changes
- * app.onhostcontextchanged = (params) => {
- *   if (params.theme) {
- *     applyDocumentTheme(params.theme);
+ * app.onhostcontextchanged = (ctx) => {
+ *   if (ctx.theme) {
+ *     applyDocumentTheme(ctx.theme);
  *   }
  * };
  *
@@ -77,9 +77,9 @@ export declare function applyDocumentTheme(theme: McpUiTheme): void;
  * document.body.style.background = "var(--color-background-primary)";
  *
  * // Apply when host context changes
- * app.onhostcontextchanged = (params) => {
- *   if (params.styles?.variables) {
- *     applyHostStyleVariables(params.styles.variables);
+ * app.onhostcontextchanged = (ctx) => {
+ *   if (ctx.styles?.variables) {
+ *     applyHostStyleVariables(ctx.styles.variables);
  *   }
  * };
  *
@@ -94,10 +94,10 @@ export declare function applyDocumentTheme(theme: McpUiTheme): void;
  *
  * @example Apply to a specific element
  * ```ts source="./styles.examples.ts#applyHostStyleVariables_toElement"
- * app.onhostcontextchanged = (params) => {
+ * app.onhostcontextchanged = (ctx) => {
  *   const container = document.getElementById("app-root");
- *   if (container && params.styles?.variables) {
- *     applyHostStyleVariables(params.styles.variables, container);
+ *   if (container && ctx.styles?.variables) {
+ *     applyHostStyleVariables(ctx.styles.variables, container);
  *   }
  * };
  * ```
@@ -135,9 +135,9 @@ export declare function applyHostStyleVariables(styles: McpUiStyles, root?: HTML
  * @example Apply fonts from host context
  * ```ts source="./styles.examples.ts#applyHostFonts_fromHostContext"
  * // Apply when host context changes
- * app.onhostcontextchanged = (params) => {
- *   if (params.styles?.css?.fonts) {
- *     applyHostFonts(params.styles.css.fonts);
+ * app.onhostcontextchanged = (ctx) => {
+ *   if (ctx.styles?.css?.fonts) {
+ *     applyHostFonts(ctx.styles.css.fonts);
  *   }
  * };
  *

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/modelcontextprotocol/ext-apps"
   },
   "homepage": "https://github.com/modelcontextprotocol/ext-apps",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "license": "MIT",
   "description": "MCP Apps SDK — Enable MCP servers to display interactive user interfaces in conversational clients.",
   "type": "module",
@@ -99,7 +99,7 @@
     "ts-to-zod": "^5.1.0",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.14",
-    "typedoc-github-theme": "^0.3.1",
+    "typedoc-github-theme": "^0.4.0",
     "typescript": "^5.9.3",
     "zod": "^4.1.13"
   },