diff --git a/README.md b/README.md index b3f68e7..a514e19 100644 --- a/README.md +++ b/README.md @@ -121,17 +121,27 @@ resources: ## Getting Started +For a View or host: + ```bash npm install -S @modelcontextprotocol/ext-apps \ - @modelcontextprotocol/client@2.0.0-beta.4 \ - @modelcontextprotocol/server@2.0.0-beta.4 \ - @modelcontextprotocol/core@2.0.0-beta.4 \ + @modelcontextprotocol/client@2.0.0-beta.5 \ + @modelcontextprotocol/core@2.0.0-beta.5 \ zod@^4.2.0 ``` -This release uses the split base MCP SDK v2 packages. Install all three at the -exact published beta.4 version so the Apps SDK and your MCP client/server share -one compatible protocol implementation. +For an MCP server: + +```bash +npm install -S @modelcontextprotocol/ext-apps \ + @modelcontextprotocol/server@2.0.0-beta.5 \ + @modelcontextprotocol/core@2.0.0-beta.5 \ + zod@^4.2.0 +``` + +Applications that implement both roles should install both `client` and +`server`. Keep all installed base MCP SDK packages on the exact same published +beta so they share one compatible protocol implementation. **New here?** Start with the [Quickstart Guide](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html) diff --git a/docs/overview.md b/docs/overview.md index 63156ec..5f3852d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -56,11 +56,11 @@ flowchart LR - **Host** — The chat client (e.g., Claude Desktop) that connects to servers, embeds Views in iframes, and proxies communication between them. - **View** — The UI running inside a sandboxed iframe. It receives tool data from the Host and can call server tools or send messages back to the chat. -The View's `App` subclasses the base MCP SDK `Client`. The Host's `AppBridge` -subclasses the base MCP SDK `Server` for the inner iframe channel, while a -separate outer `Client` connects the Host to the actual MCP Server. Keeping -those two connections separate prevents iframe negotiation and capabilities -from leaking into the server connection. +The View's `App` and the Host's `AppBridge` both subclass the base MCP SDK's +public `Protocol` for the iframe channel. A separate outer `Client` connects +the Host to the actual MCP Server. Keeping those two connections separate +preserves the Apps-only iframe handshake and prevents iframe capabilities from +leaking into the server connection. ## Lifecycle diff --git a/docs/quickstart.md b/docs/quickstart.md index eb6b096..3cac872 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -37,7 +37,7 @@ Install the dependencies you'll need: ```bash npm init -y -npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 @modelcontextprotocol/node@2.0.0-beta.4 @modelcontextprotocol/express@2.0.0-beta.4 zod@^4.2.0 express cors +npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 @modelcontextprotocol/node@2.0.0-beta.5 @modelcontextprotocol/express@2.0.0-beta.5 zod@^4.2.0 express cors npm install -D typescript vite vite-plugin-singlefile @types/express @types/cors @types/node tsx concurrently cross-env ``` diff --git a/plugins/mcp-apps/skills/add-app-to-server/SKILL.md b/plugins/mcp-apps/skills/add-app-to-server/SKILL.md index 69e41f8..fda72b0 100644 --- a/plugins/mcp-apps/skills/add-app-to-server/SKILL.md +++ b/plugins/mcp-apps/skills/add-app-to-server/SKILL.md @@ -77,7 +77,7 @@ Before writing any code, analyze the server's existing tools and determine which ## Step 2: Add Dependencies ```bash -npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 zod@^4.2.0 +npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 zod@^4.2.0 npm install -D vite vite-plugin-singlefile ``` diff --git a/plugins/mcp-apps/skills/convert-web-app/SKILL.md b/plugins/mcp-apps/skills/convert-web-app/SKILL.md index 22686ef..03fc8d7 100644 --- a/plugins/mcp-apps/skills/convert-web-app/SKILL.md +++ b/plugins/mcp-apps/skills/convert-web-app/SKILL.md @@ -115,7 +115,7 @@ Create a new MCP server with tool and resource registration. This wraps the exis ### Dependencies ```bash -npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 zod@^4.2.0 +npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 zod@^4.2.0 npm install -D tsx vite vite-plugin-singlefile ``` diff --git a/plugins/mcp-apps/skills/create-mcp-app/SKILL.md b/plugins/mcp-apps/skills/create-mcp-app/SKILL.md index fc41e70..6f1c466 100644 --- a/plugins/mcp-apps/skills/create-mcp-app/SKILL.md +++ b/plugins/mcp-apps/skills/create-mcp-app/SKILL.md @@ -110,7 +110,7 @@ See `/tmp/mcp-ext-apps/docs/patterns.md` for detailed recipes: **Always** use `npm install` to add dependencies rather than manually writing version numbers: ```bash -npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.4 @modelcontextprotocol/core@2.0.0-beta.4 @modelcontextprotocol/server@2.0.0-beta.4 @modelcontextprotocol/node@2.0.0-beta.4 @modelcontextprotocol/express@2.0.0-beta.4 zod@^4.2.0 express cors +npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/client@2.0.0-beta.5 @modelcontextprotocol/core@2.0.0-beta.5 @modelcontextprotocol/server@2.0.0-beta.5 @modelcontextprotocol/node@2.0.0-beta.5 @modelcontextprotocol/express@2.0.0-beta.5 zod@^4.2.0 express cors npm install -D typescript vite vite-plugin-singlefile concurrently cross-env @types/node @types/express @types/cors ``` diff --git a/src/app-bridge.ts b/src/app-bridge.ts index d6a2368..59ea586 100644 --- a/src/app-bridge.ts +++ b/src/app-bridge.ts @@ -241,11 +241,11 @@ export type AppBridgeEventMap = { /** * Host-side bridge for communicating with a single View ({@link app!App `App`}). * - * `AppBridge` extends the base MCP SDK's public `Server` class and acts as a proxy between - * the host application and a view running in an iframe. When an MCP client - * is provided to the constructor, it automatically forwards MCP server capabilities - * (tools, resources, prompts) to the view. It also handles the initialization - * handshake. + * `AppBridge` extends the base MCP SDK's public `Protocol` class and acts as a + * proxy between the host application and a view running in an iframe. When a + * separate MCP client is provided to the constructor, it automatically forwards + * MCP server capabilities (tools, resources, prompts) to the view. It also + * handles the Apps initialization handshake. * * ## Architecture * diff --git a/src/app.ts b/src/app.ts index 0ff369e..34ef284 100644 --- a/src/app.ts +++ b/src/app.ts @@ -297,7 +297,8 @@ export type AppEventMap = { * * The `App` class provides a framework-agnostic way to build interactive MCP Apps * that run inside host applications. It extends the base MCP SDK's public - * `Client` class and adds the Apps handshake, lifecycle, and high-level APIs. + * `Protocol` class, composes an {@link EventDispatcher}, and adds the Apps + * handshake, lifecycle, and high-level APIs. * * ## Architecture * @@ -314,9 +315,11 @@ export type AppEventMap = { * * ## Protocol and event methods * - * As a subclass of the base MCP SDK's `Client`, `App` provides: + * From the base MCP SDK's `Protocol`, `App` provides: * - `setRequestHandler()` - Register handlers for requests from host * - `setNotificationHandler()` - Register handlers for notifications from host + * + * From its composed {@link EventDispatcher}, `App` also provides: * - `addEventListener()` - Append a listener for a notification event (multi-listener) * - `removeEventListener()` - Remove a previously added listener *