Merge branch 'main' of https://github.com/modelcontextprotocol/ext-apps
This commit is contained in:
Olivier Chafik
commit
ff7c2107e2
3 changed files with 31 additions and 14 deletions
23
README.md
23
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.
|
||||
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
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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(
|
||||
|
|
|
|||
|
|
@ -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": "<!DOCTYPE html><html>...</html>",
|
||||
"_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:**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue