Merge remote-tracking branch 'origin/main' into ochafik/map-server-screenshot

Author: ochafik

.github/workflows/update-snapshots.yml

@@ -0,0 +1,53 @@
+name: Update E2E Snapshots
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to update snapshots on"
+        required: true
+        default: "main"
+  # Temporary: auto-run on this branch to update snapshots
+  push:
+    branches:
+      - "ochafik/fix-e2e-flaky-tests"
+    paths:
+      - ".github/workflows/update-snapshots.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  update-snapshots:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.branch || github.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Update snapshots
+        run: npx playwright test --update-snapshots --reporter=list
+
+      - name: Commit updated snapshots
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add tests/e2e/**/*.png
+          git diff --staged --quiet || git commit -m "chore: update e2e snapshots [skip ci]"
+          git push

.husky/pre-commit

@@ -1,3 +1,12 @@
+# Load Node.js environment for GUI apps (GitHub Desktop, etc.)
+# that don't inherit shell PATH
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"  # nvm
+[ -s "$HOME/.fnm/fnm" ] && eval "$(~/.fnm/fnm env)"  # fnm
+[ -s "$HOME/.volta/bin/volta" ] && export PATH="$HOME/.volta/bin:$PATH"  # volta
+[ -d "/opt/homebrew/bin" ] && export PATH="/opt/homebrew/bin:$PATH"  # homebrew (macOS ARM)
+[ -d "/usr/local/bin" ] && export PATH="/usr/local/bin:$PATH"  # homebrew (macOS Intel)
+
 # Verify no private registry URLs in package-lock.json
 if grep -E '"resolved": "https?://' package-lock.json | grep -v registry.npmjs.org > /dev/null; then
   echo "ERROR: package-lock.json contains non-npmjs.org URLs"

.prettierignore

@@ -2,5 +2,6 @@ examples/basic-host/**/*.ts
 examples/basic-host/**/*.tsx
 examples/basic-server-*/**/*.ts
 examples/basic-server-*/**/*.tsx
+examples/quickstart/**/*.ts
 **/vendor/**
 SKILL.md

AGENTS.md

@@ -80,7 +80,7 @@ View (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Serv
 
 ## Documentation
 
-JSDoc `@example` tags should pull type-checked code from companion `.examples.ts` files (e.g., `app.ts` → `app.examples.ts`). Use ` ```ts source="./file.examples.ts#regionName" ` fences referencing `//#region regionName` blocks, then run `npm run sync:snippets`. Region names follow `exportedName_variant` or `ClassName_methodName_variant` pattern (e.g., `useApp_basicUsage`, `App_hostCapabilities_checkAfterConnection`).
+JSDoc `@example` tags should pull type-checked code from companion `.examples.ts` files (e.g., `app.ts` → `app.examples.ts`). Use ` ```ts source="./file.examples.ts#regionName" ` fences referencing `//#region regionName` blocks; region names follow `exportedName_variant` or `ClassName_methodName_variant` pattern (e.g., `useApp_basicUsage`, `App_hostCapabilities_checkAfterConnection`). For whole-file inclusion (any file type), omit the `#regionName`. Run `npm run sync:snippets` to sync.
 
 Standalone docs in `docs/` (listed in `typedoc.config.mjs` `projectDocuments`) can also have type-checked companion `.ts`/`.tsx` files using the same pattern.
 

README.md

@@ -6,29 +6,33 @@ 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.
 
+## Why MCP Apps?
+
+MCP tools return text and structured data. That works for many cases, but not when you need an interactive UI, like a chart, form, or video player.
+
+MCP Apps provide a standardized way to deliver interactive UIs from MCP servers. Your UI renders inline in the conversation, in context, in any compliant host.
+
 ## How It Works
 
-MCP Apps extend the Model Context Protocol to let servers deliver **interactive UIs** to MCP hosts. Here's how it works:
+MCP Apps extend the Model Context Protocol by letting tools declare UI resources:
 
-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
+1. **Tool definition** — Your tool declares a `ui://` resource containing its HTML interface
+2. **Tool call** — The LLM calls the tool on your server
 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
+## Using the SDK
 
 This SDK serves two audiences:
 
-### App Developers
+### For App Developers
 
 Build interactive UIs that run inside MCP-enabled chat clients.
 
 - **SDK for Apps**: `@modelcontextprotocol/ext-apps` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html)
 - **React hooks**: `@modelcontextprotocol/ext-apps/react` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/_modelcontextprotocol_ext-apps_react.html)
 
-### Host Developers
+### For Host Developers
 
 Embed and communicate with MCP Apps in your chat application.
 
@@ -44,17 +48,21 @@ We have [contributed a tentative implementation](https://github.com/MCP-UI-Org/m
 npm install -S @modelcontextprotocol/ext-apps
 ```
 
-### Claude Code Plugin
+### Install Agent Skills
 
-A [Claude Code plugin](https://github.com/modelcontextprotocol/ext-apps/tree/main/plugins/mcp-apps) is available to help create MCP Apps. To install, run these commands inside Claude Code:
+This repository provides two [Agent Skills](https://agentskills.io/) for building MCP Apps. You can install the skills as a Claude Code plugin:
 
 ```
 /plugin marketplace add modelcontextprotocol/ext-apps
 /plugin install mcp-apps@modelcontextprotocol-ext-apps
 ```
 
+For more information, including instructions for installing the skills in your favorite AI coding agent, see the [agent skills guide](./docs/agent-skills.md).
+
 ## Examples
 
+The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains demo apps showcasing real-world use cases.
+
 <!-- prettier-ignore-start -->
 | | | |
 |:---:|:---:|:---:|
@@ -76,12 +84,27 @@ A [Claude Code plugin](https://github.com/modelcontextprotocol/ext-apps/tree/mai
 | [![Basic](examples/basic-server-react/grid-cell.png "Starter template")](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) | The same app built with different frameworks — pick your favorite!<br><br>[React](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) · [Vue](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vue) · [Svelte](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-svelte) · [Preact](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-preact) · [Solid](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid) · [Vanilla JS](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) |
 <!-- prettier-ignore-end -->
 
-The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
+### Running the Examples
 
-<details>
-<summary>MCP client configuration for all examples</summary>
+#### With basic-host
+
+To run all examples locally using [basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) (the reference host implementation included in this repo):
+
+```bash
+git clone https://github.com/modelcontextprotocol/ext-apps.git
+cd ext-apps
+npm install
+npm start
+```
 
-Add to your MCP client configuration (stdio transport):
+Then open http://localhost:8080/.
+
+#### With MCP Clients
+
+To use these examples with MCP clients that support the stdio transport (such as Claude Desktop or VS Code), add this MCP server configuration to your client's settings:
+
+<details>
+<summary>MCP client configuration for all examples (using stdio)</summary>
 
 ```json
 {
@@ -298,18 +321,10 @@ Add to your MCP client configuration (stdio transport):
 }
 ```
 
-> **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
-npm start
-```
-
-Then open http://localhost:8080/.
+> [!NOTE]
+> The `qr` server requires cloning the repository first. See [qr-server README](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) for details.
 
 ## Resources
 

docs/agent-skills.md

@@ -0,0 +1,67 @@
+---
+title: Agent Skills
+---
+
+# Agent Skills
+
+[Agent Skills](https://agentskills.io/) are instruction sets that guide AI coding agents through tasks. When you invoke a skill, the agent takes the lead — it asks clarifying questions, makes decisions based on your codebase, and executes the work.
+
+This repository provides two skills:
+
+- [**create-mcp-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/create-mcp-app/SKILL.md) — scaffolds a new MCP App with an interactive UI
+- [**migrate-oai-app**](https://github.com/modelcontextprotocol/ext-apps/blob/main/plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) — migrates an existing OpenAI App to the MCP Apps SDK
+
+## Install the Skills
+
+Choose one of the following installation methods based on your agent:
+
+### Option 1: Claude Code Plugin
+
+Install via Claude Code:
+
+```
+/plugin marketplace add modelcontextprotocol/ext-apps
+/plugin install mcp-apps@modelcontextprotocol-ext-apps
+```
+
+### Option 2: Vercel Skills CLI
+
+Use the [Vercel Skills CLI](https://skills.sh/) to install skills across different AI coding agents:
+
+```bash
+npx skills add modelcontextprotocol/ext-apps
+```
+
+### Option 3: Manual Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/modelcontextprotocol/ext-apps.git
+```
+
+Then copy the skills from `plugins/mcp-apps/skills/` to your agent's skills directory. See your agent's documentation for the correct location:
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/skills)
+- [VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills) / [GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
+- [Codex](https://developers.openai.com/codex/skills/)
+- [Gemini CLI](https://geminicli.com/docs/cli/skills/)
+- [Cline](https://docs.cline.bot/features/skills#skills)
+- [Goose](https://block.github.io/goose/docs/guides/context-engineering/using-skills/)
+
+## Verify Installation
+
+Ask your agent "What skills do you have?" — you should see `create-mcp-app` and `migrate-oai-app` among the available skills.
+
+## Invoke a Skill
+
+Try invoking the skills by asking your agent:
+
+- "Create an MCP App" — scaffolds a new MCP App with an interactive UI
+- "Migrate from OpenAI Apps SDK" — converts an existing OpenAI App to use the MCP Apps SDK
+
+The agent will guide you through the process, asking clarifying questions as needed.
+
+## Test Your App
+
+After creating or migrating your MCP App, see the [Testing MCP Apps](./testing-mcp-apps.md) guide to run and debug it locally.

docs/migrate_from_openai_apps.md

@@ -4,10 +4,17 @@ title: Migrate OpenAI App
 
 # Migrating from OpenAI Apps SDK to MCP Apps SDK
 
-This guide helps you migrate from the OpenAI Apps SDK to the MCP Apps SDK (`@modelcontextprotocol/ext-apps`).
+This reference maps OpenAI Apps SDK concepts to their MCP Apps SDK (`@modelcontextprotocol/ext-apps`) equivalents. Use the tables below for quick lookup during migration, and refer to the code examples for complete before/after comparisons.
+
+This guide covers server-side changes first (metadata, tools, resources), then client-side changes (setup, context, events).
+
+> [!NOTE]
+> Some OpenAI Apps SDK features don't have MCP equivalents yet. These are marked "Not yet implemented" in the tables below.
 
 ## Server-Side
 
+The server-side changes involve updating metadata structure and using helper functions.
+
 ### Quick Start Comparison
 
 | OpenAI Apps SDK                                            | MCP Apps SDK                                                   |
@@ -190,6 +197,8 @@ function createServer() {
 
 ## Client-Side
 
+Client-side migration involves replacing the implicit `window.openai` global with an explicit `App` instance.
+
 ### Quick Start Comparison
 
 | OpenAI Apps SDK                   | MCP Apps SDK                       |
@@ -282,16 +291,17 @@ function createServer() {
 | ------------------------------------------- | -------- | ------------------- |
 | `await window.openai.requestModal(options)` | —        | Not yet implemented |
 | `window.openai.requestClose()`              | —        | Not yet implemented |
+| `window.openai.setOpenInAppUrl({ href })`   | —        | Not yet implemented |
 | `window.openai.view`                        | —        | Not yet mapped      |
 
 ### Event Handling
 
-| OpenAI                         | MCP Apps                                    | Notes                            |
-| ------------------------------ | ------------------------------------------- | -------------------------------- |
-| Read `window.openai.*` on load | `app.ontoolinput = (params) => {...}`       | Register before `connect()`      |
-| Read `window.openai.*` on load | `app.ontoolresult = (params) => {...}`      | Register before `connect()`      |
-| Poll or re-read properties     | `app.onhostcontextchanged = (ctx) => {...}` | MCP pushes context changes       |
-| —                              | `app.onteardown = async () => {...}`        | MCP adds: cleanup before unmount |
+| OpenAI                                        | MCP Apps                                    | Notes                                                              |
+| --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ |
+| `window.openai.toolInput` (read on load)      | `app.ontoolinput = (params) => {...}`       | OpenAI: sync property; MCP: callback (register before `connect()`) |
+| `window.openai.toolOutput` (read on load)     | `app.ontoolresult = (params) => {...}`      | OpenAI: sync property; MCP: callback (register before `connect()`) |
+| `addEventListener("openai:set_globals", ...)` | `app.onhostcontextchanged = (ctx) => {...}` | Both push updates; MCP uses callback, OpenAI uses DOM event        |
+| —                                             | `app.onteardown = async () => {...}`        | MCP adds: cleanup before unmount                                   |
 
 ### Logging