Merge remote-tracking branch 'origin/main' into ochafik/host-filter-tools

Author: ochafik

.github/workflows/npm-publish.yml

@@ -107,10 +107,13 @@ jobs:
           - budget-allocator-server
           - cohort-heatmap-server
           - customer-segmentation-server
+          - map-server
           - scenario-modeler-server
+          - shadertoy-server
           - sheet-music-server
           - system-monitor-server
           - threejs-server
+          - transcript-server
           - video-resource-server
           - wiki-explorer-server
 

.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/package.json

@@ -1,12 +1,12 @@
 {
   "homepage": "https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host",
   "name": "@modelcontextprotocol/ext-apps-basic-host",
-  "version": "1.0.0",
+  "version": "0.4.0",
   "type": "module",
   "scripts": {
     "build": "tsc --noEmit && concurrently \"cross-env INPUT=index.html vite build\" \"cross-env INPUT=sandbox.html vite build\"",
     "watch": "concurrently \"cross-env INPUT=index.html vite build --watch\" \"cross-env INPUT=sandbox.html vite build --watch\"",
-    "serve": "bun serve.ts",
+    "serve": "bun --watch serve.ts",
     "start": "cross-env NODE_ENV=development npm run build && npm run serve",
     "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\""
   },

examples/basic-host/sandbox.html

@@ -3,8 +3,8 @@
   <head>
     <meta charset="utf-8" />
     <meta name="color-scheme" content="light dark">
-    <!-- CSP is set by serve.ts HTTP header - no meta tag needed here
-         The inner iframe's CSP is dynamically injected based on resource metadata -->
+    <!-- CSP is set via HTTP headers by serve.ts (based on ?csp= query param).
+         The inner iframe inherits this CSP since we use document.write(). -->
     <title>MCP-UI Proxy</title>
     <style>
       html,