Merge remote-tracking branch 'origin/main' into ochafik/mcp-apps-widgetSessionId

Author: ochafik

.gitignore

@@ -11,3 +11,5 @@ intermediate-findings/
 # Playwright
 playwright-report/
 test-results/
+__pycache__/
+*.pyc

AGENTS.md

@@ -88,4 +88,7 @@ Uses npm workspaces. Examples in `examples/` are separate packages:
 
 ## Claude Code Plugin
 
-The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via the plugin marketplace. It provides the "Create MCP App" skill (`plugins/mcp-apps/skills/create-mcp-app/SKILL.md`) that guides users through building MCP Apps with interactive UIs.
+The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via the plugin marketplace. It provides the following Claude Code skills files:
+
+- `plugins/mcp-apps/skills/create-mcp-app/SKILL.md` — for creating an MCP App
+- `plugins/mcp-apps/skills/migrate-oai-app/SKILL.md` — for migrating an app from the OpenAI Apps SDK to the MCP Apps SDK

README.md

@@ -67,8 +67,8 @@ Or edit your `package.json` manually:
 | [**Scenario Modeler**](examples/scenario-modeler-server) | [**Budget Allocator**](examples/budget-allocator-server) | [**Customer Segmentation**](examples/customer-segmentation-server) |
 | [![System Monitor](examples/system-monitor-server/grid-cell.png "Real-time OS metrics")](examples/system-monitor-server) | [![Transcript](examples/transcript-server/grid-cell.png "Live speech transcription")](examples/transcript-server) | [![Video Resource](examples/video-resource-server/grid-cell.png "Binary video via MCP resources")](examples/video-resource-server) |
 | [**System Monitor**](examples/system-monitor-server) | [**Transcript**](examples/transcript-server) | [**Video Resource**](examples/video-resource-server) |
-| [![PDF Server](examples/pdf-server/grid-cell.png "Interactive PDF viewer with chunked loading")](examples/pdf-server) | [![QR Code](examples/qr-server/grid-cell.png "QR code generator")](examples/qr-server) | |
-| [**PDF Server**](examples/pdf-server) | [**QR Code (Python)**](examples/qr-server) | |
+| [![PDF Server](examples/pdf-server/grid-cell.png "Interactive PDF viewer with chunked loading")](examples/pdf-server) | [![QR Code](examples/qr-server/grid-cell.png "QR code generator")](examples/qr-server) | [![Say Demo](examples/say-server/grid-cell.png "Text-to-speech demo")](examples/say-server) |
+| [**PDF Server**](examples/pdf-server) | [**QR Code (Python)**](examples/qr-server) | [**Say Demo**](examples/say-server) |
 
 ### Starter Templates
 
@@ -79,7 +79,231 @@ Or edit your `package.json` manually:
 
 The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
 
-To run all examples:
+<details>
+<summary>MCP client configuration for all examples</summary>
+
+Add to your MCP client configuration (stdio transport):
+
+```json
+{
+  "mcpServers": {
+    "basic-react": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-react",
+        "--stdio"
+      ]
+    },
+    "basic-vanillajs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-vanillajs",
+        "--stdio"
+      ]
+    },
+    "basic-vue": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-vue",
+        "--stdio"
+      ]
+    },
+    "basic-svelte": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-svelte",
+        "--stdio"
+      ]
+    },
+    "basic-preact": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-preact",
+        "--stdio"
+      ]
+    },
+    "basic-solid": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-basic-solid",
+        "--stdio"
+      ]
+    },
+    "budget-allocator": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-budget-allocator",
+        "--stdio"
+      ]
+    },
+    "cohort-heatmap": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-cohort-heatmap",
+        "--stdio"
+      ]
+    },
+    "customer-segmentation": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-customer-segmentation",
+        "--stdio"
+      ]
+    },
+    "map": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-map",
+        "--stdio"
+      ]
+    },
+    "pdf": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-pdf",
+        "--stdio"
+      ]
+    },
+    "scenario-modeler": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-scenario-modeler",
+        "--stdio"
+      ]
+    },
+    "shadertoy": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-shadertoy",
+        "--stdio"
+      ]
+    },
+    "sheet-music": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-sheet-music",
+        "--stdio"
+      ]
+    },
+    "system-monitor": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-system-monitor",
+        "--stdio"
+      ]
+    },
+    "threejs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-threejs",
+        "--stdio"
+      ]
+    },
+    "transcript": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-transcript",
+        "--stdio"
+      ]
+    },
+    "video-resource": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-video-resource",
+        "--stdio"
+      ]
+    },
+    "wiki-explorer": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--silent",
+        "--registry=https://registry.npmjs.org/",
+        "@modelcontextprotocol/server-wiki-explorer",
+        "--stdio"
+      ]
+    },
+    "qr": {
+      "command": "uv",
+      "args": [
+        "run",
+        "/path/to/ext-apps/examples/qr-server/server.py",
+        "--stdio"
+      ]
+    },
+    "say": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--default-index",
+        "https://pypi.org/simple",
+        "https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** The `qr` server requires cloning the repository first. See [qr-server README](examples/qr-server) for details.
+
+</details>
+
+To run all examples locally in dev mode:
 
 ```bash
 npm install

docs/migrate_from_openai_apps.md

@@ -24,20 +24,30 @@ This guide helps you migrate from the OpenAI Apps SDK to the MCP Apps SDK (`@mod
 
 ### Resource Metadata
 
-| OpenAI                                | MCP Apps                 | Notes                                                                              |
-| ------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- |
-| `_meta["openai/widgetCSP"]`           | `_meta.ui.csp`           | `connect_domains` → `connectDomains`, `resource_domains` → `resourceDomains`, etc. |
-| —                                     | `_meta.ui.permissions`   | MCP adds: permissions for camera, microphone, geolocation, clipboard               |
-| `_meta["openai/widgetDomain"]`        | `_meta.ui.domain`        | Dedicated sandbox origin                                                           |
-| `_meta["openai/widgetPrefersBorder"]` | `_meta.ui.prefersBorder` | Visual boundary preference                                                         |
-| `_meta["openai/widgetDescription"]`   | —                        | Not yet implemented; use `app.updateModelContext()` for dynamic context            |
+| OpenAI                                | MCP Apps                 | Notes                                                                   |
+| ------------------------------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `_meta["openai/widgetCSP"]`           | `_meta.ui.csp`           | See [CSP field mapping](#csp-field-mapping) below                       |
+| —                                     | `_meta.ui.permissions`   | MCP adds: permissions for camera, microphone, geolocation, clipboard    |
+| `_meta["openai/widgetDomain"]`        | `_meta.ui.domain`        | Dedicated sandbox origin                                                |
+| `_meta["openai/widgetPrefersBorder"]` | `_meta.ui.prefersBorder` | Visual boundary preference                                              |
+| `_meta["openai/widgetDescription"]`   | —                        | Not yet implemented; use `app.updateModelContext()` for dynamic context |
 
 ### Resource MIME Type
 
 | OpenAI                | MCP Apps                    | Notes                                                                            |
 | --------------------- | --------------------------- | -------------------------------------------------------------------------------- |
 | `text/html+skybridge` | `text/html;profile=mcp-app` | Auto-set by `registerAppResource()`; use `RESOURCE_MIME_TYPE` constant if manual |
 
+### CSP Field Mapping
+
+| OpenAI             | MCP Apps          | Notes                                                      |
+| ------------------ | ----------------- | ---------------------------------------------------------- |
+| `resource_domains` | `resourceDomains` | Origins for static assets (images, fonts, styles, scripts) |
+| `connect_domains`  | `connectDomains`  | Origins for fetch/XHR/WebSocket requests                   |
+| `frame_domains`    | `frameDomains`    | Origins for nested iframes                                 |
+| `redirect_domains` | —                 | OpenAI-only: origins for `openExternal` redirects          |
+| —                  | `baseUriDomains`  | MCP-only: `base-uri` CSP directive                         |
+
 ### Server-Side Migration Example
 
 ### Before (OpenAI)
@@ -84,6 +94,13 @@ function createServer() {
           uri: "ui://widget/cart.html",
           mimeType: "text/html+skybridge",
           text: getCartHtml(),
+          _meta: {
+            "openai/widgetCSP": {
+              resource_domains: ["https://cdn.example.com"],
+              connect_domains: ["https://api.example.com"],
+              frame_domains: ["https://embed.example.com"],
+            },
+          },
         },
       ],
     }),
@@ -139,6 +156,15 @@ function createServer() {
           uri: "ui://widget/cart.html",
           mimeType: RESOURCE_MIME_TYPE,
           text: getCartHtml(),
+          _meta: {
+            ui: {
+              csp: {
+                resourceDomains: ["https://cdn.example.com"],
+                connectDomains: ["https://api.example.com"],
+                frameDomains: ["https://embed.example.com"],
+              },
+            },
+          },
         },
       ],
     }),
@@ -152,7 +178,7 @@ function createServer() {
 
 1. **Metadata Structure**: OpenAI uses flat `_meta["openai/..."]` properties; MCP uses nested `_meta.ui.*` structure
 2. **Tool Visibility**: OpenAI uses boolean/string (`true`/`"public"`); MCP uses string arrays (`["app", "model"]`)
-3. **CSP Property Names**: snake_case → camelCase (`connect_domains` → `connectDomains`)
+3. **CSP Field Names**: snake_case → camelCase (e.g., `connect_domains` → `connectDomains`)
 4. **App Permissions**: MCP adds `_meta.ui.permissions` for camera, microphone, geolocation, clipboard (not in OpenAI)
 5. **Resource MIME Type**: `text/html+skybridge` → `text/html;profile=mcp-app` (use `RESOURCE_MIME_TYPE` constant)
 6. **Helper Functions**: MCP provides `registerAppTool()` and `registerAppResource()` helpers
@@ -172,7 +198,7 @@ function createServer() {
 
 | OpenAI                           | MCP Apps                                           | Notes                                                                                                           |
 | -------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `window.openai` (auto-available) | `const app = new App({name, version}, {})`         | MCP requires explicit instantiation                                                                             |
+| `window.openai` (auto-available) | `const app = new App({name, version})`             | MCP requires explicit instantiation                                                                             |
 | (implicit)                       | Vanilla: `await app.connect()` / React: `useApp()` | MCP requires async connection; auto-detects OpenAI env                                                          |
 | —                                | `await app.connect(new OpenAITransport())`         | Force OpenAI mode (not yet available, see [PR #172](https://github.com/modelcontextprotocol/ext-apps/pull/172)) |
 | —                                | `await app.connect(new PostMessageTransport(...))` | Force MCP mode explicitly                                                                                       |

examples/basic-host/src/implementation.ts

@@ -1,5 +1,6 @@
 import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
 
@@ -24,11 +25,8 @@ export interface ServerInfo {
 
 
 export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
-  const client = new Client(IMPLEMENTATION);
-
   log.info("Connecting to server:", serverUrl.href);
-  await client.connect(new StreamableHTTPClientTransport(serverUrl));
-  log.info("Connection successful");
+  const client = await connectWithFallback(serverUrl);
 
   const name = client.getServerVersion()?.name ?? serverUrl.href;
 
@@ -39,6 +37,28 @@ export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
   return { name, client, tools, appHtmlCache: new Map() };
 }
 
+async function connectWithFallback(serverUrl: URL): Promise<Client> {
+  // Try Streamable HTTP first (modern transport)
+  try {
+    const client = new Client(IMPLEMENTATION);
+    await client.connect(new StreamableHTTPClientTransport(serverUrl));
+    log.info("Connected via Streamable HTTP transport");
+    return client;
+  } catch (streamableError) {
+    log.info("Streamable HTTP failed:", streamableError);
+  }
+
+  // Fall back to SSE (deprecated but needed for older servers)
+  try {
+    const client = new Client(IMPLEMENTATION);
+    await client.connect(new SSEClientTransport(serverUrl));
+    log.info("Connected via SSE transport");
+    return client;
+  } catch (sseError) {
+    throw new Error(`Could not connect with any transport. SSE error: ${sseError}`);
+  }
+}
+
 
 interface UiResourceData {
   html: string;