Merge remote-tracking branch 'origin/main' into ochafik/map-fullscreen-keyboard-shortcuts

Author: ochafik

.prettierignore

@@ -2,3 +2,4 @@ examples/basic-host/**/*.ts
 examples/basic-host/**/*.tsx
 examples/basic-server-*/**/*.ts
 examples/basic-server-*/**/*.tsx
+**/vendor/**

AGENTS.md

@@ -0,0 +1,87 @@
+# MCP Apps SDK
+
+## Project Overview
+
+MCP Apps SDK (`@modelcontextprotocol/ext-apps`) enables MCP servers to display interactive UIs in conversational clients.
+
+Key abstractions:
+
+- **Guest** - UI running in an iframe, uses `App` class with `PostMessageTransport` to communicate with host
+- **Host** - Chat client embedding the iframe, uses `AppBridge` class to proxy MCP requests
+- **Server** - MCP server that registers tools/resources with UI metadata
+
+Specification (draft): `specification/draft/apps.mdx`
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK only (generates schemas + bundles, does not build examples)
+npm run build
+
+# Build everything (SDK + all examples)
+npm run build:all
+
+# Type check + build a single example
+npm run --workspace examples/<example-name> build
+
+# Run all examples (starts server at http://localhost:8080)
+npm start
+
+# Run E2E tests (primary testing mechanism - starts examples server automatically)
+npm run test:e2e
+
+# Run unit tests (E2E tests have broader coverage; unit tests cover specific modules)
+npm test
+
+# Check JSDoc comment syntax and `{@link}` references
+npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
+
+# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+rm -fR  package-lock.json node_modules && \
+  docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
+  rm -fR node_modules && \
+  npm  i  --cache=~/.npm-mcp-apps --registry=https://registry.npmjs.org/
+```
+
+## Architecture
+
+### SDK Entry Points
+
+- `@modelcontextprotocol/ext-apps` - Main SDK for Apps (`App` class, `PostMessageTransport`)
+- `@modelcontextprotocol/ext-apps/react` - React hooks (`useApp`, `useHostStyleVariables`, etc.)
+- `@modelcontextprotocol/ext-apps/app-bridge` - SDK for hosts (`AppBridge` class)
+- `@modelcontextprotocol/ext-apps/server` - Server helpers (`registerAppTool`, `registerAppResource`)
+
+### Key Source Files
+
+- `src/app.ts` - `App` class extends MCP Protocol, handles guest initialization, tool calls, messaging
+- `src/app-bridge.ts` - `AppBridge` class for hosts, proxies MCP requests, sends tool input/results to guests
+- `src/server/index.ts` - Helpers for MCP servers to register tools/resources with UI metadata
+- `src/types.ts` - Protocol types re-exported from `spec.types.ts` and Zod schemas from `generated/schema.ts` (auto-generated during build)
+- `src/message-transport.ts` - `PostMessageTransport` for iframe communication
+- `src/react/` - React hooks: `useApp`, `useHostStyles`, `useAutoResize`, `useDocumentTheme`
+
+### Protocol Flow
+
+```
+Guest UI (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server
+```
+
+1. Host creates iframe with Guest UI HTML
+2. Guest UI creates `App` instance and calls `connect()` with `PostMessageTransport`
+3. App sends `ui/initialize` request, receives host capabilities and context
+4. Host sends `sendToolInput()` with tool arguments after initialization
+5. Guest UI can call server tools via `app.callServerTool()` or send messages via `app.sendMessage()`
+6. Host sends `sendToolResult()` when tool execution completes
+7. Host calls `teardownResource()` before unmounting iframe
+
+## Examples
+
+Uses npm workspaces. Examples in `examples/` are separate packages:
+
+- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
+- `basic-host` - Reference host implementation
+- Other examples showcase specific features (charts, 3D, video, etc.)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -6,6 +6,17 @@ 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.
 
+## How It Works
+
+MCP Apps extend the Model Context Protocol to let servers deliver **interactive UIs** to MCP hosts. Here's how it works:
+
+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
+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
 
 This SDK serves two audiences:

docs/quickstart.md

@@ -15,8 +15,12 @@ A simple app that fetches the current server time and displays it in a clickable
 
 ## Prerequisites
 
-- Node.js 18+
+- Familiarity with MCP concepts, especially [Tools](https://modelcontextprotocol.io/docs/learn/server-concepts#tools) and [Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
 - Familiarity with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- Node.js 18+
+
+> [!TIP]
+> New to building MCP servers? Start with the [official MCP quickstart guide](https://modelcontextprotocol.io/docs/develop/build-server) to learn the core concepts first.
 
 ## 1. Project Setup
 
@@ -30,7 +34,7 @@ npm init -y
 Install dependencies:
 
 ```bash
-npm install github:modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod
+npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk
 npm install -D typescript vite vite-plugin-singlefile express cors @types/express @types/cors tsx
 ```
 
@@ -98,64 +102,68 @@ Create `server.ts`:
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import {
+  registerAppTool,
+  registerAppResource,
   RESOURCE_MIME_TYPE,
-  type McpUiToolMeta,
-} from "@modelcontextprotocol/ext-apps";
+} from "@modelcontextprotocol/ext-apps/server";
 import cors from "cors";
 import express from "express";
 import fs from "node:fs/promises";
 import path from "node:path";
-import * as z from "zod";
 
 const server = new McpServer({
   name: "My MCP App Server",
   version: "1.0.0",
 });
 
-// Two-part registration: tool + resource
+// Two-part registration: tool + resource, tied together by the resource URI.
 const resourceUri = "ui://get-time/mcp-app.html";
 
-server.registerTool(
+// Register a tool with UI metadata. When the host calls this tool, it reads
+// `_meta.ui.resourceUri` to know which resource to fetch and render as an
+// interactive UI.
+registerAppTool(
+  server,
   "get-time",
   {
     title: "Get Time",
     description: "Returns the current server time.",
     inputSchema: {},
-    outputSchema: { time: z.string() },
-    _meta: { ui: { resourceUri } as McpUiToolMeta }, // Links tool to UI
+    _meta: { ui: { resourceUri } },
   },
   async () => {
     const time = new Date().toISOString();
     return {
       content: [{ type: "text", text: time }],
-      structuredContent: { time },
     };
   },
 );
 
-server.registerResource(
+// Register the resource, which returns the bundled HTML/JavaScript for the UI.
+registerAppResource(
+  server,
   resourceUri,
   resourceUri,
-  { mimeType: "text/html;profile=mcp-app" },
+  { mimeType: RESOURCE_MIME_TYPE },
   async () => {
     const html = await fs.readFile(
       path.join(import.meta.dirname, "dist", "mcp-app.html"),
       "utf-8",
     );
     return {
       contents: [
-        { uri: resourceUri, mimeType: "text/html;profile=mcp-app", text: html },
+        { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
       ],
     };
   },
 );
 
-// Express server for MCP endpoint
-const app = express();
-app.use(cors());
-app.use(express.json());
+// Start an Express server that exposes the MCP endpoint.
+const expressApp = express();
+expressApp.use(cors());
+expressApp.use(express.json());
 
-app.post("/mcp", async (req, res) => {
+expressApp.post("/mcp", async (req, res) => {
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
     enableJsonResponse: true,
@@ -165,7 +173,7 @@ app.post("/mcp", async (req, res) => {
   await transport.handleRequest(req, res, req.body);
 });
 
-app.listen(3001, (err) => {
+expressApp.listen(3001, (err) => {
   if (err) {
     console.error("Error starting server:", err);
     process.exit(1);
@@ -209,7 +217,7 @@ Create `mcp-app.html`:
 Create `src/mcp-app.ts`:
 
 ```typescript
-import { App, PostMessageTransport } from "@modelcontextprotocol/ext-apps";
+import { App } from "@modelcontextprotocol/ext-apps";
 
 // Get element references
 const serverTimeEl = document.getElementById("server-time")!;
@@ -220,30 +228,30 @@ const app = new App({ name: "Get Time App", version: "1.0.0" });
 
 // Register handlers BEFORE connecting
 app.ontoolresult = (result) => {
-  const { time } = (result.structuredContent as { time?: string }) ?? {};
+  const time = result.content?.find((c) => c.type === "text")?.text;
   serverTimeEl.textContent = time ?? "[ERROR]";
 };
 
 // Wire up button click
 getTimeBtn.addEventListener("click", async () => {
   const result = await app.callServerTool({ name: "get-time", arguments: {} });
-  const { time } = (result.structuredContent as { time?: string }) ?? {};
+  const time = result.content?.find((c) => c.type === "text")?.text;
   serverTimeEl.textContent = time ?? "[ERROR]";
 });
 
 // Connect to host
-app.connect(new PostMessageTransport(window.parent));
+app.connect();
 ```
 
+> [!NOTE]
+> **Full files:** [`mcp-app.html`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/mcp-app.html), [`src/mcp-app.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/src/mcp-app.ts)
+
 Build the UI:
 
 ```bash
 npm run build
 ```
 
-> [!NOTE]
-> **Full files:** [`mcp-app.html`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/mcp-app.html), [`src/mcp-app.ts`](https://github.com/modelcontextprotocol/ext-apps/blob/main/examples/basic-server-vanillajs/src/mcp-app.ts)
-
 This produces `dist/mcp-app.html` which contains your bundled app:
 
 ```console

examples/basic-host/src/implementation.ts

@@ -1,4 +1,4 @@
-import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions } from "@modelcontextprotocol/ext-apps/app-bridge";
+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 { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
@@ -122,12 +122,19 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
 export function loadSandboxProxy(
   iframe: HTMLIFrameElement,
   csp?: McpUiResourceCsp,
+  permissions?: McpUiResourcePermissions,
 ): Promise<boolean> {
   // Prevent reload
   if (iframe.src) return Promise.resolve(false);
 
   iframe.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms");
 
+  // Set Permission Policy allow attribute based on requested permissions
+  const allowAttribute = buildAllowAttribute(permissions);
+  if (allowAttribute) {
+    iframe.setAttribute("allow", allowAttribute);
+  }
+
   const readyNotification: McpUiSandboxProxyReadyNotification["method"] =
     "ui/notifications/sandbox-proxy-ready";
 
@@ -215,12 +222,26 @@ function hookInitializedCallback(appBridge: AppBridge): Promise<void> {
 }
 
 
-export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement): AppBridge {
+export type ModelContext = McpUiUpdateModelContextRequest["params"];
+export type AppMessage = McpUiMessageRequest["params"];
+
+export interface AppBridgeCallbacks {
+  onContextUpdate?: (context: ModelContext | null) => void;
+  onMessage?: (message: AppMessage) => void;
+}
+
+export function newAppBridge(
+  serverInfo: ServerInfo,
+  iframe: HTMLIFrameElement,
+  callbacks?: AppBridgeCallbacks,
+): AppBridge {
   const serverCapabilities = serverInfo.client.getServerCapabilities();
   const appBridge = new AppBridge(serverInfo.client, IMPLEMENTATION, {
     openLinks: {},
     serverTools: serverCapabilities?.tools,
     serverResources: serverCapabilities?.resources,
+    // Declare support for model context updates
+    updateModelContext: { text: {} },
   });
 
   // Register all handlers before calling connect(). The Guest UI can start
@@ -229,6 +250,7 @@ export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement):
 
   appBridge.onmessage = async (params, _extra) => {
     log.info("Message from MCP App:", params);
+    callbacks?.onMessage?.(params);
     return {};
   };
 
@@ -242,6 +264,15 @@ export function newAppBridge(serverInfo: ServerInfo, iframe: HTMLIFrameElement):
     log.info("Log message from MCP App:", params);
   };
 
+  appBridge.onupdatemodelcontext = async (params) => {
+    log.info("Model context update from MCP App:", params);
+    // Normalize: empty content array means clear context
+    const hasContent = params.content && params.content.length > 0;
+    const hasStructured = params.structuredContent && Object.keys(params.structuredContent).length > 0;
+    callbacks?.onContextUpdate?.(hasContent || hasStructured ? params : null);
+    return {};
+  };
+
   appBridge.onsizechange = async ({ width, height }) => {
     // The MCP App has requested a `width` and `height`, but if
     // `box-sizing: border-box` is applied to the outer iframe element, then we