fa-mcp-sdk 0.4.73 → 0.4.76

package/cli-template/.claude/skills/mcp-app-add-to-server/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: mcp-app-add-to-server
+description: This skill should be used when the user asks to "add an app to my MCP server", "add UI to my MCP server", "add a view to my MCP tool", "enrich MCP tools with UI", "add interactive UI to existing server", "add MCP Apps to my server", or needs to add interactive UI capabilities to an existing MCP server that already has tools. Provides guidance for analyzing existing tools and adding MCP Apps UI resources.
+---
+
+# Add UI to MCP Server
+
+Enrich an existing MCP server's tools with interactive UIs using the MCP Apps SDK (`@modelcontextprotocol/ext-apps`).
+
+## How It Works
+
+Existing tools get paired with HTML resources that render inline in the host's conversation. The tool continues to work for text-only clients — UI is an enhancement, not a replacement. Each tool that benefits from UI gets linked to a resource via `_meta.ui.resourceUri`, and the host renders that resource in a sandboxed iframe when the tool is called.
+
+## Getting Reference Code
+
+Clone the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) for working examples and API documentation:
+
+```bash
+git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git ./mcp-ext-apps
+```
+
+> Add `mcp-ext-apps/` to the project's `.gitignore` — it's a reference clone, not part of the project.
+
+### Protocol Specification
+
+The formal MCP Apps spec lives in the same repository — read it for authoritative protocol
+semantics that source files and examples only illustrate:
+
+| File | Contents |
+|------|----------|
+| `./mcp-ext-apps/specification/2026-01-26/apps.mdx` | **SEP-1865** (Stable, 2026-01-26) — `ui://` URI scheme, `_meta.ui` contract, iframe sandboxing, host↔UI JSON-RPC messages, security model |
+
+**Where to look first:**
+
+- For **protocol questions** (wire format, required `_meta` keys, mandatory host/server behaviors,
+  message semantics) — consult `./mcp-ext-apps/specification/2026-01-26/apps.mdx`. The spec is the source of
+  truth for what MUST happen.
+- For **TypeScript API questions** (which helper to call, handler signatures, idiomatic usage) —
+  consult `@modelcontextprotocol/ext-apps` sources under `./mcp-ext-apps/src/` and its examples.
+  The package is the source of truth for *how* to invoke the protocol from code.
+
+### API Reference (Source Files)
+
+Read JSDoc documentation directly from `./mcp-ext-apps/src/`:
+
+| File | Contents |
+|------|----------|
+| `src/app.ts` | `App` class, handlers (`ontoolinput`, `ontoolresult`, `onhostcontextchanged`, `onteardown`), lifecycle |
+| `src/server/index.ts` | `registerAppTool`, `registerAppResource`, `getUiCapability`, tool visibility options |
+| `src/spec.types.ts` | All type definitions: `McpUiHostContext`, CSS variable keys, display modes |
+| `src/styles.ts` | `applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts` |
+| `src/react/useApp.tsx` | `useApp` hook for React apps |
+| `src/react/useHostStyles.ts` | `useHostStyles`, `useHostStyleVariables`, `useHostFonts` hooks |
+
+### Key Examples (Mixed Tool Patterns)
+
+These examples demonstrate servers with both App-enhanced and plain tools — the exact pattern you're adding:
+
+| Example | Pattern |
+|---------|---------|
+| `examples/map-server/` | `show-map` (App tool) + `geocode` (plain tool) |
+| `examples/pdf-server/` | `display_pdf` (App tool) + `list_pdfs` (plain tool) + `read_pdf_bytes` (app-only tool) |
+| `examples/system-monitor-server/` | `get-system-info` (App tool) + `poll-system-stats` (app-only polling tool) |
+
+### Domain-Specific Examples
+
+When the new UI matches one of these domains, consult the corresponding example for patterns
+the basic templates and mixed examples don't cover. All paths are under `./mcp-ext-apps/`:
+
+| Domain | Example | What it shows |
+|---|---|---|
+| Charts / dashboards | `examples/scenario-modeler-server/` | Chart.js with structured React (`hooks/`, `lib/`, `components/`); multi-scenario comparison |
+| Analytics drill-down | `examples/cohort-heatmap-server/` | Heatmap with hover tooltips and click drilldown (React) |
+| 3D visualization | `examples/threejs-server/` | Three.js + streaming tool input into canvas, OrbitControls, post-processing |
+| WebGL / shaders | `examples/shadertoy-server/` | GLSL live compilation, fullscreen mode, `vendor/` pattern for custom JS libs |
+| Graph visualization | `examples/wiki-explorer-server/` | 3D force-directed graph (`force-graph`), web scraping with `cheerio` |
+| Audio / music | `examples/sheet-music-server/` | ABC notation → SVG render + MIDI synthesis (`abcjs`) |
+| Streaming + audio | `examples/say-server/` | `ontoolinputpartial` + async audio queue + multi-view lock (**Python FastMCP**) |
+| Browser APIs | `examples/transcript-server/` | Web Speech API for live transcription |
+| Binary / media resources | `examples/video-resource-server/` | Base64 video blobs, `ResourceTemplate`, large-payload limits |
+| SDK surface reference | `examples/debug-server/` | All content types in one place — PNG/WAV blobs, structured output, stateful counter, resource downloads |
+
+### Framework Templates
+
+Learn and adapt from `./mcp-ext-apps/examples/basic-server-{framework}/`:
+
+| Template | Key Files |
+|----------|-----------|
+| `basic-server-vanillajs/` | `server.ts`, `src/mcp-app.ts`, `mcp-app.html` |
+| `basic-server-react/` | `server.ts`, `src/mcp-app.tsx` (uses `useApp` hook) |
+| `basic-server-vue/` | `server.ts`, `src/App.vue` |
+| `basic-server-svelte/` | `server.ts`, `src/App.svelte` |
+| `basic-server-preact/` | `server.ts`, `src/mcp-app.tsx` |
+| `basic-server-solid/` | `server.ts`, `src/mcp-app.tsx` |
+
+## Step 1: Analyze Existing Tools
+
+Before writing any code, analyze the server's existing tools and determine which ones benefit from UI.
+
+1. Read the server source and list all registered tools
+2. For each tool, assess whether it would benefit from UI (returns data that could be visualized, involves user interaction, etc.) vs. is fine as text-only (simple lookups, utility functions)
+3. Identify tools that could become **app-only helpers** (data the UI needs to poll/fetch but the model doesn't need to call directly)
+4. Present the analysis to the user and confirm which tools to enhance
+
+### Decision Framework
+
+| Tool output type | UI benefit | Example |
+|---|---|---|
+| Structured data / lists / tables | High — interactive table, search, filtering | List of items, search results |
+| Metrics / numbers over time | High — charts, gauges, dashboards | System stats, analytics |
+| Media / rich content | High — viewer, player, renderer | Maps, PDFs, images, video |
+| Simple text / confirmations | Low — text is fine | "File created", "Setting updated" |
+| Data for other tools | Consider app-only | Polling endpoints, chunk loaders |
+
+## Step 2: Add Dependencies
+
+```bash
+npm install @modelcontextprotocol/ext-apps
+npm install -D vite vite-plugin-singlefile
+```
+
+Plus framework-specific dependencies if needed (e.g., `react`, `react-dom`, `@vitejs/plugin-react` for React).
+
+Use `npm install` to add dependencies rather than manually writing version numbers. This lets npm resolve the latest compatible versions. Never specify version numbers from memory.
+
+## Step 3: Set Up the Build Pipeline
+
+### Vite Configuration
+
+Create `vite.config.ts` with `vite-plugin-singlefile` to bundle the UI into a single HTML file:
+
+```typescript
+import { defineConfig } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  plugins: [viteSingleFile()],
+  build: {
+    outDir: "dist",
+    rollupOptions: {
+      input: "mcp-app.html", // one per UI, or one shared entry
+    },
+  },
+});
+```
+
+### HTML Entry Point
+
+Create `mcp-app.html` (or one per distinct UI if tools need different views):
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>MCP App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/mcp-app.ts"></script>
+  </body>
+</html>
+```
+
+### Build Scripts
+
+Add build scripts to `package.json`. The UI must be built before the server code bundles it:
+
+```json
+{
+  "scripts": {
+    "build:ui": "vite build",
+    "build:server": "tsc",
+    "build": "npm run build:ui && npm run build:server",
+    "serve": "tsx server.ts"
+  }
+}
+```
+
+## Step 4: Convert Tools to App Tools
+
+Transform plain MCP tools into App tools with UI.
+
+**Before** (plain MCP tool):
+```typescript
+server.tool("my-tool", { param: z.string() }, async (args) => {
+  const data = await fetchData(args.param);
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+```
+
+**After** (App tool with UI):
+```typescript
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+
+const resourceUri = "ui://my-tool/mcp-app.html";
+
+registerAppTool(server, "my-tool", {
+  description: "Shows data with an interactive UI",
+  inputSchema: { param: z.string() },
+  _meta: { ui: { resourceUri } },
+}, async (args) => {
+  const data = await fetchData(args.param);
+  return {
+    content: [{ type: "text", text: JSON.stringify(data) }],   // text fallback for non-UI hosts
+    structuredContent: { data },                                 // structured data for the UI
+  };
+});
+```
+
+Key guidance:
+- **Always keep the `content` array** with a text fallback for text-only clients
+- Add `structuredContent` for data the UI needs to render
+- Link the tool to its resource via `_meta.ui.resourceUri`
+- Leave tools that don't benefit from UI unchanged — they stay as plain tools
+
+## Step 5: Register Resources
+
+Register the HTML resource so the host can fetch it:
+
+```typescript
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const resourceUri = "ui://my-tool/mcp-app.html";
+
+registerAppResource(server, {
+  uri: resourceUri,
+  name: "My Tool UI",
+  mimeType: RESOURCE_MIME_TYPE,
+}, async () => {
+  const html = await fs.readFile(
+    path.resolve(import.meta.dirname, "dist", "mcp-app.html"),
+    "utf-8",
+  );
+  return { contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }] };
+});
+```
+
+If multiple tools share the same UI, they can reference the same `resourceUri` and the same resource registration.
+
+## Step 6: Build the UI
+
+### Handler Registration
+
+Register ALL handlers BEFORE calling `app.connect()`:
+
+```typescript
+import { App, PostMessageTransport, applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";
+
+const app = new App({ name: "My App", version: "1.0.0" });
+
+app.ontoolinput = (params) => {
+  // Render the UI using params.arguments and/or params.structuredContent
+};
+
+app.ontoolresult = (result) => {
+  // Update UI with final tool result
+};
+
+app.onhostcontextchanged = (ctx) => {
+  if (ctx.theme) applyDocumentTheme(ctx.theme);
+  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
+  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
+  if (ctx.safeAreaInsets) {
+    const { top, right, bottom, left } = ctx.safeAreaInsets;
+    document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
+  }
+};
+
+app.onteardown = async () => {
+  return {};
+};
+
+await app.connect(new PostMessageTransport());
+```
+
+### Host Styling
+
+Use host CSS variables for theme integration:
+
+```css
+.container {
+  background: var(--color-background-secondary);
+  color: var(--color-text-primary);
+  font-family: var(--font-sans);
+  border-radius: var(--border-radius-md);
+}
+```
+
+Key variable groups: `--color-background-*`, `--color-text-*`, `--color-border-*`, `--font-sans`, `--font-mono`, `--font-text-*-size`, `--font-heading-*-size`, `--border-radius-*`. See `src/spec.types.ts` for the full list.
+
+For React apps, use the `useApp` and `useHostStyles` hooks instead — see `basic-server-react/` for the pattern.
+
+## Optional Enhancements
+
+### App-Only Helper Tools
+
+Tools the UI calls but the model doesn't need to invoke directly (polling, pagination, chunk loading):
+
+```typescript
+registerAppTool(server, "poll-data", {
+  description: "Polls latest data for the UI",
+  _meta: { ui: { resourceUri, visibility: ["app"] } },
+}, async () => {
+  const data = await getLatestData();
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+```
+
+The UI calls these via `app.callServerTool("poll-data", {})`.
+
+### CSP Configuration
+
+If the UI needs to load external resources (fonts, APIs, CDNs), declare the domains:
+
+```typescript
+registerAppResource(server, {
+  uri: resourceUri,
+  name: "My Tool UI",
+  mimeType: RESOURCE_MIME_TYPE,
+  _meta: {
+    ui: {
+      connectDomains: ["api.example.com"],      // fetch/XHR targets
+      resourceDomains: ["cdn.example.com"],      // scripts, styles, images
+      frameDomains: ["embed.example.com"],        // nested iframes
+    },
+  },
+}, async () => { /* ... */ });
+```
+
+### Streaming Partial Input
+
+For large tool inputs, show progress during LLM generation:
+
+```typescript
+app.ontoolinputpartial = (params) => {
+  const args = params.arguments; // Healed partial JSON - always valid
+  // Render preview with partial data
+};
+
+app.ontoolinput = (params) => {
+  // Final complete input - switch to full render
+};
+```
+
+### Graceful Degradation with `getUiCapability()`
+
+Conditionally register App tools only when the client supports UI, falling back to text-only tools:
+
+```typescript
+import { getUiCapability, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+
+server.server.oninitialized = () => {
+  const clientCapabilities = server.server.getClientCapabilities();
+  const uiCap = getUiCapability(clientCapabilities);
+
+  if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
+    // Client supports UI — register App tool
+    registerAppTool(server, "my-tool", {
+      description: "Shows data with interactive UI",
+      _meta: { ui: { resourceUri } },
+    }, appToolHandler);
+  } else {
+    // Text-only client — register plain tool
+    server.tool("my-tool", "Shows data", { param: z.string() }, plainToolHandler);
+  }
+};
+```
+
+### Fullscreen Mode
+
+Allow the UI to expand to fullscreen:
+
+```typescript
+app.onhostcontextchanged = (ctx) => {
+  if (ctx.availableDisplayModes?.includes("fullscreen")) {
+    fullscreenBtn.style.display = "block";
+  }
+  if (ctx.displayMode) {
+    container.classList.toggle("fullscreen", ctx.displayMode === "fullscreen");
+  }
+};
+
+async function toggleFullscreen() {
+  const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen";
+  const result = await app.requestDisplayMode({ mode: newMode });
+  currentMode = result.mode;
+}
+```
+
+## Common Mistakes to Avoid
+
+1. **Forgetting text `content` fallback** — Always include `content` array with text for non-UI hosts
+2. **Registering handlers after `connect()`** — Register ALL handlers BEFORE calling `app.connect()`
+3. **Missing `vite-plugin-singlefile`** — Without it, assets won't load in the sandboxed iframe
+4. **Forgetting resource registration** — The tool references a `resourceUri` that must have a matching resource
+5. **Hardcoding styles** — Use host CSS variables (`var(--color-*)`) for theme integration
+6. **Not handling safe area insets** — Always apply `ctx.safeAreaInsets` in `onhostcontextchanged`
+
+## Testing
+
+### Using basic-host
+
+Test the enhanced server with the basic-host example:
+
+```bash
+# Terminal 1: Build and run your server
+npm run build && npm run serve
+
+# Terminal 2: Run basic-host (from cloned repo)
+cd ./mcp-ext-apps/examples/basic-host
+npm install
+SERVERS='["http://localhost:3001/mcp"]' npm run start
+# Open http://localhost:8080
+```
+
+Configure `SERVERS` with a JSON array of your server URLs (default: `http://localhost:3001/mcp`).
+
+### Verify
+
+1. Plain tools still work and return text output
+2. App tools render their UI in the iframe
+3. `ontoolinput` handler fires with tool arguments
+4. `ontoolresult` handler fires with tool result
+5. Host styling (theme, fonts, colors) applies correctly

package/cli-template/.claude/skills/mcp-app-create/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: mcp-app-create
+description: This skill should be used when the user asks to "create an MCP App", "add a UI to an MCP tool", "build an interactive MCP View", "scaffold an MCP App", or needs guidance on MCP Apps SDK patterns, UI-resource registration, MCP App lifecycle, or host integration. Provides comprehensive guidance for building MCP Apps with interactive UIs.
+---
+
+# Create MCP App
+
+Build interactive UIs that run inside MCP-enabled hosts like Claude Desktop. An MCP App combines an MCP tool with an HTML resource to display rich, interactive content.
+
+## Core Concept: Tool + Resource
+
+Every MCP App requires two parts linked together:
+
+1. **Tool** - Called by the LLM/host, returns data
+2. **Resource** - Serves the bundled HTML UI that displays the data
+
+The tool's `_meta.ui.resourceUri` references the resource's URI.
+
+Host calls tool → Host renders resource UI → Server returns result → UI receives result.
+
+## Quick Start Decision Tree
+
+### Framework Selection
+
+| Framework | `@modelcontextprotocol/ext-apps` Support | Best For |
+|-----------|-------------|----------|
+| React | `useApp` hook provided | Teams familiar with React |
+| Vanilla JS | Manual lifecycle | Simple apps, no build complexity |
+| Vue/Svelte/Preact/Solid | Manual lifecycle | Framework preference |
+
+### Project Context
+
+**Adding to existing MCP server:**
+- Import `registerAppTool`, `registerAppResource` from `@modelcontextprotocol/ext-apps`
+- Add tool registration with `_meta.ui.resourceUri`
+- Add resource registration serving bundled HTML
+
+**Creating new MCP server:**
+- Set up server with transport (stdio or HTTP)
+- Register tools and resources
+- Configure build system with `vite-plugin-singlefile`
+
+## Getting Reference Code
+
+Clone the MCP Apps SDK repository (`@modelcontextprotocol/ext-apps`) for working examples and API documentation:
+
+```bash
+git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git ./mcp-ext-apps
+```
+
+> Add `mcp-ext-apps/` to the project's `.gitignore` — it's a reference clone, not part of the project.
+
+### Protocol Specification
+
+The formal MCP Apps spec lives in the same repository — read it for authoritative protocol
+semantics that source files and examples only illustrate:
+
+| File | Contents |
+|------|----------|
+| `./mcp-ext-apps/specification/2026-01-26/apps.mdx` | **SEP-1865** (Stable, 2026-01-26) — `ui://` URI scheme, `_meta.ui` contract, iframe sandboxing, host↔UI JSON-RPC messages, security model |
+
+**Where to look first:**
+
+- For **protocol questions** (wire format, required `_meta` keys, mandatory host/server behaviors,
+  message semantics) — consult `./mcp-ext-apps/specification/2026-01-26/apps.mdx`. The spec is the source of
+  truth for what MUST happen.
+- For **TypeScript API questions** (which helper to call, handler signatures, idiomatic usage) —
+  consult `@modelcontextprotocol/ext-apps` sources under `./mcp-ext-apps/src/` and its examples.
+  The package is the source of truth for *how* to invoke the protocol from code.
+
+### Framework Templates
+
+Learn and adapt from `./mcp-ext-apps/examples/basic-server-{framework}/`:
+
+| Template | Key Files |
+|----------|-----------|
+| `basic-server-vanillajs/` | `server.ts`, `src/mcp-app.ts`, `mcp-app.html` |
+| `basic-server-react/` | `server.ts`, `src/mcp-app.tsx` (uses `useApp` hook) |
+| `basic-server-vue/` | `server.ts`, `src/App.vue` |
+| `basic-server-svelte/` | `server.ts`, `src/App.svelte` |
+| `basic-server-preact/` | `server.ts`, `src/mcp-app.tsx` |
+| `basic-server-solid/` | `server.ts`, `src/mcp-app.tsx` |
+
+Each template includes:
+- `server.ts` with `registerAppTool` and `registerAppResource`
+- `main.ts` entry point with HTTP and stdio transport setup
+- Client-side app (e.g., `src/mcp-app.ts`, `src/mcp-app.tsx`) with lifecycle handlers
+- `src/global.css` with global styles and host style variable fallbacks
+- `vite.config.ts` using `vite-plugin-singlefile`
+- `package.json` with `npm run` scripts and required dependencies
+- `.gitignore` excluding `node_modules/` and `dist/`
+
+### Domain-Specific Examples
+
+When the App's UI matches one of these domains, consult the corresponding example for patterns
+the basic templates don't cover. All paths are under `./mcp-ext-apps/`:
+
+| Domain | Example | What it shows |
+|---|---|---|
+| Charts / dashboards | `examples/scenario-modeler-server/` | Chart.js with structured React (`hooks/`, `lib/`, `components/`); multi-scenario comparison |
+| Analytics drill-down | `examples/cohort-heatmap-server/` | Heatmap with hover tooltips and click drilldown (React) |
+| 3D visualization | `examples/threejs-server/` | Three.js + streaming tool input into canvas, OrbitControls, post-processing |
+| WebGL / shaders | `examples/shadertoy-server/` | GLSL live compilation, fullscreen mode, `vendor/` pattern for custom JS libs |
+| Graph visualization | `examples/wiki-explorer-server/` | 3D force-directed graph (`force-graph`), web scraping with `cheerio` |
+| Audio / music | `examples/sheet-music-server/` | ABC notation → SVG render + MIDI synthesis (`abcjs`) |
+| Streaming + audio | `examples/say-server/` | `ontoolinputpartial` + async audio queue + multi-view lock (**Python FastMCP**) |
+| Browser APIs | `examples/transcript-server/` | Web Speech API for live transcription |
+| Binary / media resources | `examples/video-resource-server/` | Base64 video blobs, `ResourceTemplate`, large-payload limits |
+| SDK surface reference | `examples/debug-server/` | All content types in one place — PNG/WAV blobs, structured output, stateful counter, resource downloads |
+
+### API Reference (Source Files)
+
+Read JSDoc documentation directly from `./mcp-ext-apps/src/`:
+
+| File | Contents |
+|------|----------|
+| `src/app.ts` | `App` class, handlers (`ontoolinput`, `ontoolresult`, `onhostcontextchanged`, `onteardown`, etc.), lifecycle |
+| `src/server/index.ts` | `registerAppTool`, `registerAppResource`, helper functions |
+| `src/spec.types.ts` | All type definitions: `McpUiHostContext`, `McpUiStyleVariableKey` (CSS variable names), `McpUiResourceCsp` (CSP configuration), etc. |
+| `src/styles.ts` | `applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts` |
+| `src/react/useApp.tsx` | `useApp` hook for React apps |
+
+### Advanced Patterns
+
+See `./mcp-ext-apps/docs/patterns.md` for detailed recipes:
+
+- **App-only tools** — `visibility: ["app"]`, hiding tools from model
+- **Polling** — real-time dashboards, interval management
+- **Chunked responses** — large files, pagination, base64 encoding
+- **Error handling** — `isError`, informing model of failures
+- **Binary resources** — audio/video/etc via `resources/read`, blob field
+- **Network requests** — assets, fetch, CSP, `_meta.ui.csp`, CORS, `_meta.ui.domain`
+- **Host context** — theme, styling, fonts, safe area insets
+- **Fullscreen mode** — `requestDisplayMode`, display mode changes
+- **Model context** — `updateModelContext`, `sendMessage`, keeping model informed
+- **View state** — `viewUUID`, localStorage, state recovery
+- **Visibility-based pause** — IntersectionObserver, pausing animations/WebGL
+- **Streaming input** — `ontoolinputpartial`, progressive rendering
+
+### Reference Host Implementation
+
+`./mcp-ext-apps/examples/basic-host/` shows one way an MCP Apps-capable host could be implemented. Real-world hosts like Claude Desktop are more sophisticated—use basic-host for local testing and protocol understanding, not as a guarantee of host behavior.
+
+## Critical Implementation Notes
+
+### Adding Dependencies
+
+**Always** use `npm install` to add dependencies rather than manually writing version numbers:
+
+```bash
+npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod express cors
+npm install -D typescript vite vite-plugin-singlefile concurrently cross-env @types/node @types/express @types/cors
+```
+
+This lets npm resolve the latest compatible versions. **Never** specify version numbers from memory.
+
+### TypeScript Server Execution
+
+Unless the user has specified otherwise, use `tsx` for running TypeScript server files. For example:
+
+```bash
+npm install -D tsx
+
+npm pkg set scripts.dev="cross-env NODE_ENV=development concurrently 'cross-env INPUT=mcp-app.html vite build --watch' 'tsx --watch main.ts'"
+```
+
+> [!NOTE]
+> The `@modelcontextprotocol/ext-apps` examples use `bun` but generated projects should default to `tsx` for broader compatibility.
+
+### Handler Registration Order
+
+Register ALL handlers BEFORE calling `app.connect()`:
+
+```typescript
+const app = new App({ name: "My App", version: "1.0.0" });
+
+// Register handlers first
+app.ontoolinput = (params) => { /* handle input */ };
+app.ontoolresult = (result) => { /* handle result */ };
+app.onhostcontextchanged = (ctx) => { /* handle context */ };
+app.onteardown = async () => { return {}; };
+// etc.
+
+// Then connect
+await app.connect();
+```
+
+## Common Mistakes to Avoid
+
+1. **No text fallback** - Always provide `content` array for non-UI hosts
+2. **Missing CSP configuration** - MCP Apps HTML is served as an MCP resource with no same-origin server; ALL network requests—even to `localhost`—require a CSP configuration
+3. **CSP or CORS config in wrong _meta object** - `_meta.ui.csp` and `_meta.ui.domain` go in the `contents[]` objects returned by `registerAppResource()`'s read callback, not in `registerAppResource()`'s config object
+4. **Handlers after app.connect()** - Register ALL handlers BEFORE calling `app.connect()`
+5. **No streaming for large inputs** - Use `ontoolinputpartial` to show progress during input generation
+
+## Testing
+
+### Using basic-host
+
+Test MCP Apps locally with the basic-host example:
+
+```bash
+# Terminal 1: Build and run your server
+npm run build && npm run serve
+
+# Terminal 2: Run basic-host (from cloned repo)
+cd ./mcp-ext-apps/examples/basic-host
+npm install
+SERVERS='["http://localhost:3001/mcp"]' npm run start
+# Open http://localhost:8080
+```
+
+Configure `SERVERS` with a JSON array of your server URLs (default: `http://localhost:3001/mcp`).
+
+### Debug with sendLog
+
+Send debug logs to the host application (rather than just the iframe's dev console):
+
+```typescript
+await app.sendLog({ level: "info", data: "Debug message" });
+await app.sendLog({ level: "error", data: { error: err.message } });
+```