298e884ec3* chore: add stable spec release 2026-01-26 - Use git mv to copy specification from draft to specification/2026-01-26/apps.mdx (preserves history) - Update status from 'Draft' to 'Stable (2026-01-26)' - Add specification version table to README - Update Resources section with links to both stable and draft specs * chore: bump version to 1.0.0 - Update main package version from 0.4.2 to 1.0.0 - Update all example package versions to 1.0.0 - Regenerate package-lock.json * prettier * chore: align protocol version with spec release 2026-01-26 - Add 'Protocol Version: 2026-01-26' to spec header - Update LATEST_PROTOCOL_VERSION from '2025-11-21' to '2026-01-26' - Update spec examples to use '2026-01-26' protocol version - Add '2025-11-21' to SUPPORTED_PROTOCOL_VERSIONS for backwards compatibility * chore: update spec references to stable 2026-01-26 - Update typedoc.config.mjs navigation link - Update docs/overview.md spec links (10 occurrences) - Update plugins/mcp-apps/skills/create-mcp-app/SKILL.md spec link - Update src/spec.types.ts @see links - Update AGENTS.md spec path - Regenerate src/generated/schema.ts with updated links * chore: simplify versioning - first stable release - Remove backwards compatibility version (2025-11-21) - this is the first stable release - Remove redundant 'Protocol Version' header - spec version IS the protocol version * chore: add history reference comment to stable spec
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# MCP Apps SDK
|
|
|
|
## Project Overview
|
|
|
|
MCP Apps SDK (`@modelcontextprotocol/ext-apps`) enables MCP servers to display interactive UIs in conversational clients.
|
|
|
|
Key abstractions:
|
|
|
|
- **View** - 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 (stable): `specification/2026-01-26/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
|
|
|
|
```
|
|
View (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server
|
|
```
|
|
|
|
1. Host creates iframe with view HTML
|
|
2. View creates `App` instance and calls `connect()` with `PostMessageTransport`
|
|
3. View sends `ui/initialize` request, receives host capabilities and context
|
|
4. Host sends `sendToolInput()` with tool arguments after initialization
|
|
5. View 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
|
|
|
|
## 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; 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.
|
|
|
|
## Full Examples
|
|
|
|
Uses npm workspaces. Full 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 Code Plugin
|
|
|
|
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
|