From bd5a34ba0707f6aadf5288581eda9444741ba2af Mon Sep 17 00:00:00 2001 From: Anton Pidkuiko MacBook Date: Fri, 21 Nov 2025 19:32:46 +0000 Subject: [PATCH 1/3] fix: use consistent text/vnd.mcp.ui+html mimeType throughout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace all occurrences of text/html with text/vnd.mcp.ui+html in the specification and example code for consistency. The spec already defined text/vnd.mcp.ui+html in the capability negotiation section but used text/html in other places. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- examples/simple-server/server.ts | 4 ++-- specification/draft/apps.mdx | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/examples/simple-server/server.ts b/examples/simple-server/server.ts index ab17489..b2a4f42 100644 --- a/examples/simple-server/server.ts +++ b/examples/simple-server/server.ts @@ -47,7 +47,7 @@ const getServer = async () => { uri: "ui://vanilla", title: "Vanilla UI Template", description: "A simple vanilla JS UI", - mimeType: "text/html", + mimeType: "text/vnd.mcp.ui+html", }; server.registerResource( @@ -89,7 +89,7 @@ const getServer = async () => { uri: "ui://react", title: "React UI Template", description: "A React-based UI", - mimeType: "text/html", + mimeType: "text/vnd.mcp.ui+html", }; server.registerResource( diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index 8dc343a..070c7f6 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -43,7 +43,7 @@ MCP Apps extends the Model Context Protocol to enable servers to deliver interac - **Bidirectional Communication:** UI iframes communicate with hosts using standard MCP JSON-RPC protocol - **Security Model:** Mandatory iframe sandboxing with auditable communication -This specification focuses on HTML content (`text/html`) as the initial content type, with extensibility for future formats. +This specification focuses on HTML content (`text/vnd.mcp.ui+html`) as the initial content type, with extensibility for future formats. As an extension, MCP Apps is optional and must be explicitly negotiated between clients and servers through the extension capabilities mechanism (see Capability Negotiation section). @@ -56,7 +56,7 @@ interface UIResource { uri: string; // MUST start with 'ui://' name: string; // Human-readable identifier description?: string; // Description of the UI resource - mimeType: string; // SHOULD be 'text/html' in MVP + mimeType: string; // SHOULD be 'text/vnd.mcp.ui+html' in MVP } ``` @@ -67,7 +67,7 @@ The resource content is returned via `resources/read`: { contents: [{ uri: string; // Matching UI resource URI - mimeType: "text/html"; // MUST be "text/html" + mimeType: "text/vnd.mcp.ui+html"; // MUST be "text/vnd.mcp.ui+html" text?: string; // HTML content as string blob?: string; // OR base64-encoded HTML _meta?: { @@ -85,7 +85,7 @@ The resource content is returned via `resources/read`: #### Content Requirements: - URI MUST start with `ui://` scheme -- `mimeType` MUST be `text/html` (other types reserved for future extensions) +- `mimeType` MUST be `text/vnd.mcp.ui+html` (other types reserved for future extensions) - Content MUST be provided via either `text` (string) or `blob` (base64-encoded) - Content MUST be valid HTML5 document @@ -144,14 +144,14 @@ Example: "uri": "ui://weather-server/dashboard-template", "name": "weather_dashboard", "description": "Interactive weather dashboard widget", - "mimeType": "text/html" + "mimeType": "text/vnd.mcp.ui+html" } // Resource content with metadata { "contents": [{ "uri": "ui://weather-server/dashboard-template", - "mimeType": "text/html", + "mimeType": "text/vnd.mcp.ui+html", "text": "...", "_meta": { "ui/csp": { @@ -841,7 +841,7 @@ Servers SHOULD check client (host would-be) capabilities before registering UI-e ```typescript const hasUISupport = - clientCapabilities?.extensions?.["io.modelcontextprotocol/ui"]?.mimeTypes?.includes("text/html"); + clientCapabilities?.extensions?.["io.modelcontextprotocol/ui"]?.mimeTypes?.includes("text/vnd.mcp.ui+html"); if (hasUISupport) { // Register tools with UI templates @@ -925,7 +925,7 @@ This proposal synthesizes feedback from the UI CWG and MCP-UI community, host im #### 3. Support Raw HTML Content Type -**Decision:** MVP supports only `text/html` (rawHtml), with other types explicitly deferred. +**Decision:** MVP supports only `text/vnd.mcp.ui+html` (rawHtml), with other types explicitly deferred. **Rationale:** From 797c3690ced5f0099cf2b309d84de02f89d387bc Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 21 Nov 2025 20:10:04 +0000 Subject: [PATCH 2/3] Update README.md --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e3b7088..1e05756 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,29 @@ # @modelcontextprotocol/ext-apps -This repo contains the SDK and [specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)). +This repo contains the SDK and [specification](./main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)). MCP Apps are a standard inspired by [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) and [MCP-UI](https://mcpui.dev/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots. +This repo provides: +- [types.ts](./src/types.ts): Types of JSON-RPC messages used to communicate between Apps & their host + - Note that MCP Apps also use some standard MCP messages (e.g. `tools/call` for the App to trigger actions on its originating Server - these calls are proxied through the Host), but these types are the additional messages defined by the extension +- [examples/simple-example](./examples/simple-example): + - [server.ts](./examples/simple-server/server.ts): MCP server with two tools that declare UI resources of Apps to be show in the chat when called + - [ui-react.tsx](./examples/simple-server/src/ui-react.tsx): React App returned by the `create-ui-react` tool shows how to use the `useApp` hook to register MCP callbacks + - [ui-vanilla.tsx](./examples/simple-server/src/ui-vanilla.ts): vanilla App returned by the `create-ui-vanilla` +- [main/specification/draft/apps.mdx](./main/specification/draft/apps.mdx): The Draft Extension Specification. It's still... in flux! Feedback welcome! (also see discussions in [SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)). +- [message-transport](./src/message-transport.ts): `PostMessageTransport` class that uses `postMessage` to exchange JSON-RPC messages between windows / iframes +- [app.ts](./src/app.ts): `App` class used by an App to talk to its host +- [app-bridge.ts](./src/app-bridge.ts): `AppBridge` class used by the host to talk to a single App + +What this repo does NOT provide: +- There's no host implementation here (beyond the `AppBridge` just used for communications). + - We have contributed a tentative implementation of hosting / iframing / sandboxing logic to the [MCP-UI](https://github.com/idosal/mcp-ui) repository, and expect OSS clients may use it, while other clients might roll their own hosting logic. + - A prior iteration of an e2e prototype w/ client, server and hosting parts is available [in this gist](https://gist.github.com/ochafik/a9603ba2d6757d6038ce066eded4c354) + ## Installation -This repo is in flux and isn't published to npm (when it is, we'll probably use the `@modelcontextprotocol/ext-apps` package). Please install it from git for now: +This repo is in flux and isn't published to npm (when it is, it will use the `@modelcontextprotocol/ext-apps` package). Please install it from git for now: ```bash npm install git+https://github.com/modelcontextprotocol/ext-apps.git From d07e6363a0d052202beb0e5fb703216121652ccc Mon Sep 17 00:00:00 2001 From: Olivier Chafik Date: Fri, 21 Nov 2025 20:22:06 +0000 Subject: [PATCH 3/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1e05756..1626121 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This repo contains the SDK and [specification](./main/specification/draft/apps.mdx) for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)). -MCP Apps are a standard inspired by [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) and [MCP-UI](https://mcpui.dev/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots. +MCP Apps are proposed standard inspired by [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) and [MCP-UI](https://mcpui.dev/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots. This repo provides: - [types.ts](./src/types.ts): Types of JSON-RPC messages used to communicate between Apps & their host