@modelcontextprotocol/ext-apps 1.0.1 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -417
- package/dist/src/app-bridge.d.ts +14 -0
- package/dist/src/app-bridge.js +25 -8
- package/dist/src/app-with-deps.js +24 -7
- package/dist/src/app.d.ts +15 -21
- package/dist/src/app.js +26 -9
- package/dist/src/generated/schema.d.ts +9 -0
- package/dist/src/react/index.js +20 -3
- package/dist/src/react/react-with-deps.js +20 -3
- package/dist/src/react/useApp.d.ts +2 -2
- package/dist/src/server/index.d.ts +91 -18
- package/dist/src/server/index.js +25 -8
- package/dist/src/spec.types.d.ts +110 -13
- package/dist/src/styles.d.ts +12 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,74 +1,156 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- LOGO -->
|
|
2
|
+
<div align="center">
|
|
3
|
+
<img src="media/mcp.svg#gh-light-mode-only" alt="MCP Apps" width="128">
|
|
4
|
+
<img src="media/mcp-white.svg#gh-dark-mode-only" alt="MCP Apps" width="128">
|
|
5
|
+
<h1>MCP Apps</h1>
|
|
6
|
+
<p>
|
|
7
|
+
Build interactive UIs for MCP tools — charts, forms, dashboards — that render inline in any compliant chat client.
|
|
8
|
+
<br /><br />
|
|
9
|
+
<a href="#why-mcp-apps">Why</a>
|
|
10
|
+
·
|
|
11
|
+
<a href="https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html">Quickstart</a>
|
|
12
|
+
·
|
|
13
|
+
<a href="https://modelcontextprotocol.github.io/ext-apps/api/">API Docs</a>
|
|
14
|
+
·
|
|
15
|
+
<a href="https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx">Spec</a>
|
|
16
|
+
·
|
|
17
|
+
<a href="CONTRIBUTING.md">Contributing</a>
|
|
18
|
+
</p>
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<p align="center">
|
|
22
|
+
<a href="https://github.com/modelcontextprotocol/ext-apps/actions/workflows/ci.yml"><img src="https://github.com/modelcontextprotocol/ext-apps/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
23
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
|
|
24
|
+
<a href="https://www.npmjs.com/package/@modelcontextprotocol/ext-apps"><img src="https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg" alt="npm version"></a>
|
|
25
|
+
<a href="https://www.npmjs.com/package/@modelcontextprotocol/ext-apps"><img src="https://img.shields.io/npm/dm/@modelcontextprotocol/ext-apps.svg" alt="npm downloads"></a>
|
|
26
|
+
<a href="https://github.com/modelcontextprotocol/ext-apps"><img src="https://img.shields.io/github/stars/modelcontextprotocol/ext-apps" alt="GitHub stars"></a>
|
|
27
|
+
<a href="https://modelcontextprotocol.github.io/ext-apps/api/"><img src="https://img.shields.io/badge/docs-API%20Reference-blue" alt="API Documentation"></a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<img src="media/excalidraw.gif" alt="MCP Apps demo" width="600">
|
|
32
|
+
<br><em>Excalidraw built with MCP Apps, running in Claude</em>
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
## Table of Contents
|
|
36
|
+
|
|
37
|
+
- [Build with Agent Skills](#build-with-agent-skills)
|
|
38
|
+
- [Supported Clients](#supported-clients)
|
|
39
|
+
- [Why MCP Apps?](#why-mcp-apps)
|
|
40
|
+
- [How It Works](#how-it-works)
|
|
41
|
+
- [Getting Started](#getting-started)
|
|
42
|
+
- [Using the SDK](#using-the-sdk)
|
|
43
|
+
- [Examples](#examples)
|
|
44
|
+
- [Specification](#specification)
|
|
45
|
+
- [Resources](#resources)
|
|
46
|
+
- [Contributing](#contributing)
|
|
47
|
+
|
|
48
|
+
## Build with Agent Skills
|
|
49
|
+
|
|
50
|
+
The fastest way to build an MCP App is to let your AI coding agent do it. This
|
|
51
|
+
repo ships four [Agent Skills](https://agentskills.io/) — install them once,
|
|
52
|
+
then just ask:
|
|
53
|
+
|
|
54
|
+
| Skill | What it does | Try it |
|
|
55
|
+
| --------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------- |
|
|
56
|
+
| [`create-mcp-app`](./plugins/mcp-apps/skills/create-mcp-app/SKILL.md) | Scaffolds a new MCP App with an interactive UI from scratch | _"Create an MCP App"_ |
|
|
57
|
+
| [`migrate-oai-app`](./plugins/mcp-apps/skills/migrate-oai-app/SKILL.md) | Converts an existing OpenAI App to use MCP Apps | _"Migrate from OpenAI Apps SDK"_ |
|
|
58
|
+
| [`add-app-to-server`](./plugins/mcp-apps/skills/add-app-to-server/SKILL.md) | Adds interactive UI to an existing MCP server's tools | _"Add UI to my MCP server"_ |
|
|
59
|
+
| [`convert-web-app`](./plugins/mcp-apps/skills/convert-web-app/SKILL.md) | Turns an existing web app into a hybrid web + MCP App | _"Add MCP App support to my web app"_ |
|
|
60
|
+
|
|
61
|
+
### Install the Skills
|
|
62
|
+
|
|
63
|
+
**Claude Code** — install via the plugin marketplace:
|
|
2
64
|
|
|
3
|
-
|
|
65
|
+
```
|
|
66
|
+
/plugin marketplace add modelcontextprotocol/ext-apps
|
|
67
|
+
/plugin install mcp-apps@modelcontextprotocol-ext-apps
|
|
68
|
+
```
|
|
4
69
|
|
|
5
|
-
|
|
70
|
+
**Other agents** — any AI coding agent that supports
|
|
71
|
+
[Agent Skills](https://agentskills.io/) can use these skills. See the
|
|
72
|
+
[agent skills guide](./docs/agent-skills.md) for manual installation
|
|
73
|
+
instructions.
|
|
6
74
|
|
|
7
|
-
|
|
75
|
+
Once installed, verify by asking your agent _"What skills do you have?"_ — you
|
|
76
|
+
should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and
|
|
77
|
+
`convert-web-app` in the list. Then just ask it to create or migrate an app and
|
|
78
|
+
it will guide you through the rest.
|
|
8
79
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
80
|
+
## Supported Clients
|
|
81
|
+
|
|
82
|
+
<p align="center">
|
|
83
|
+
<a href="https://claude.ai"><img src="https://img.shields.io/badge/Claude-web-d97706?logo=claude&logoColor=white" alt="Claude"></a>
|
|
84
|
+
<a href="https://claude.ai/download"><img src="https://img.shields.io/badge/Claude_Desktop-app-d97706?logo=claude&logoColor=white" alt="Claude Desktop"></a>
|
|
85
|
+
<a href="https://code.visualstudio.com/insiders"><img src="https://img.shields.io/badge/VS_Code-Insiders-007ACC?logo=visualstudiocode&logoColor=white" alt="VS Code Insiders"></a>
|
|
86
|
+
<a href="https://block.github.io/goose/"><img src="https://img.shields.io/badge/Goose-Block-000000?logo=goose&logoColor=white" alt="Goose"></a>
|
|
87
|
+
<a href="https://postman.com"><img src="https://img.shields.io/badge/Postman-client-FF6C37?logo=postman&logoColor=white" alt="Postman"></a>
|
|
88
|
+
<a href="https://www.mcpjam.com/"><img src="https://img.shields.io/badge/MCPJam-client-8B5CF6" alt="MCPJam"></a>
|
|
89
|
+
</p>
|
|
13
90
|
|
|
14
|
-
|
|
91
|
+
> [!NOTE]
|
|
92
|
+
> MCP Apps is an extension to the
|
|
93
|
+
> [core MCP specification](https://modelcontextprotocol.io/specification). Host
|
|
94
|
+
> support varies — see the
|
|
95
|
+
> [clients page](https://modelcontextprotocol.io/clients) for the full list.
|
|
15
96
|
|
|
16
97
|
## Why MCP Apps?
|
|
17
98
|
|
|
18
|
-
MCP tools return text and structured data. That works for many cases, but not
|
|
99
|
+
MCP tools return text and structured data. That works for many cases, but not
|
|
100
|
+
when you need an interactive UI, like a chart, form, or video player.
|
|
19
101
|
|
|
20
|
-
MCP Apps provide a standardized way to deliver interactive UIs from MCP servers.
|
|
102
|
+
MCP Apps provide a standardized way to deliver interactive UIs from MCP servers.
|
|
103
|
+
Your UI renders inline in the conversation, in context, in any compliant host.
|
|
21
104
|
|
|
22
105
|
## How It Works
|
|
23
106
|
|
|
24
|
-
MCP Apps extend the Model Context Protocol by letting tools declare UI
|
|
107
|
+
MCP Apps extend the Model Context Protocol by letting tools declare UI
|
|
108
|
+
resources:
|
|
25
109
|
|
|
26
|
-
1. **Tool definition** — Your tool declares a `ui://` resource containing its
|
|
110
|
+
1. **Tool definition** — Your tool declares a `ui://` resource containing its
|
|
111
|
+
HTML interface
|
|
27
112
|
2. **Tool call** — The LLM calls the tool on your server
|
|
28
|
-
3. **Host renders** — The host fetches the resource and displays it in a
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
113
|
+
3. **Host renders** — The host fetches the resource and displays it in a
|
|
114
|
+
sandboxed iframe
|
|
115
|
+
4. **Bidirectional communication** — The host passes tool data to the UI via
|
|
116
|
+
notifications, and the UI can call other tools through the host
|
|
32
117
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
### For App Developers
|
|
36
|
-
|
|
37
|
-
Build interactive UIs that run inside MCP-enabled chat clients.
|
|
38
|
-
|
|
39
|
-
- **SDK for Apps**: `@modelcontextprotocol/ext-apps` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html)
|
|
40
|
-
- **React hooks**: `@modelcontextprotocol/ext-apps/react` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/_modelcontextprotocol_ext-apps_react.html)
|
|
41
|
-
|
|
42
|
-
### For Host Developers
|
|
43
|
-
|
|
44
|
-
Embed and communicate with MCP Apps in your chat application.
|
|
45
|
-
|
|
46
|
-
- **SDK for Hosts**: `@modelcontextprotocol/ext-apps/app-bridge` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html)
|
|
47
|
-
|
|
48
|
-
There's no _supported_ host implementation in this repo (beyond the [examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example).
|
|
49
|
-
|
|
50
|
-
The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a fully-featured MCP Apps framework used by a few hosts. Clients may choose to use it or roll their own implementation.
|
|
51
|
-
|
|
52
|
-
## Installation
|
|
118
|
+
## Getting Started
|
|
53
119
|
|
|
54
120
|
```bash
|
|
55
121
|
npm install -S @modelcontextprotocol/ext-apps
|
|
56
122
|
```
|
|
57
123
|
|
|
58
|
-
|
|
124
|
+
**New here?** Start with the
|
|
125
|
+
[Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html)
|
|
126
|
+
to build your first MCP App.
|
|
59
127
|
|
|
60
|
-
|
|
128
|
+
## Using the SDK
|
|
61
129
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
130
|
+
The SDK serves three roles: app developers building interactive Views, host
|
|
131
|
+
developers embedding those Views, and MCP server authors registering tools with
|
|
132
|
+
UI metadata.
|
|
133
|
+
|
|
134
|
+
| Package | Purpose | Docs |
|
|
135
|
+
| ------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
136
|
+
| `@modelcontextprotocol/ext-apps` | Build interactive Views (App class, PostMessageTransport) | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html) |
|
|
137
|
+
| `@modelcontextprotocol/ext-apps/react` | React hooks for Views (useApp, useHostStyles, etc.) | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/_modelcontextprotocol_ext-apps_react.html) |
|
|
138
|
+
| `@modelcontextprotocol/ext-apps/app-bridge` | Embed and communicate with Views in your chat client | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html) |
|
|
139
|
+
| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/server.html) |
|
|
66
140
|
|
|
67
|
-
|
|
141
|
+
There's no _supported_ host implementation in this repo (beyond the
|
|
142
|
+
[examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
|
|
143
|
+
example).
|
|
144
|
+
|
|
145
|
+
The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a
|
|
146
|
+
fully-featured MCP Apps framework used by a few hosts. Clients may choose to use
|
|
147
|
+
it or roll their own implementation.
|
|
68
148
|
|
|
69
149
|
## Examples
|
|
70
150
|
|
|
71
|
-
The
|
|
151
|
+
The
|
|
152
|
+
[`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
|
|
153
|
+
directory contains demo apps showcasing real-world use cases.
|
|
72
154
|
|
|
73
155
|
<!-- prettier-ignore-start -->
|
|
74
156
|
| | | |
|
|
@@ -95,7 +177,9 @@ The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/exa
|
|
|
95
177
|
|
|
96
178
|
#### With basic-host
|
|
97
179
|
|
|
98
|
-
To run all examples locally using
|
|
180
|
+
To run all examples locally using
|
|
181
|
+
[basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host)
|
|
182
|
+
(the reference host implementation included in this repo):
|
|
99
183
|
|
|
100
184
|
```bash
|
|
101
185
|
git clone https://github.com/modelcontextprotocol/ext-apps.git
|
|
@@ -108,407 +192,64 @@ Then open http://localhost:8080/.
|
|
|
108
192
|
|
|
109
193
|
#### With MCP Clients
|
|
110
194
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
<summary>MCP client configuration for all examples (using stdio)</summary>
|
|
195
|
+
Every Node.js example is published as `@modelcontextprotocol/server-<name>`. To
|
|
196
|
+
add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.),
|
|
197
|
+
use this pattern:
|
|
115
198
|
|
|
116
199
|
```json
|
|
117
200
|
{
|
|
118
201
|
"mcpServers": {
|
|
119
|
-
"
|
|
120
|
-
"command": "npx",
|
|
121
|
-
"args": [
|
|
122
|
-
"-y",
|
|
123
|
-
"--silent",
|
|
124
|
-
"--registry=https://registry.npmjs.org/",
|
|
125
|
-
"@modelcontextprotocol/server-basic-react",
|
|
126
|
-
"--stdio"
|
|
127
|
-
]
|
|
128
|
-
},
|
|
129
|
-
"basic-vanillajs": {
|
|
130
|
-
"command": "npx",
|
|
131
|
-
"args": [
|
|
132
|
-
"-y",
|
|
133
|
-
"--silent",
|
|
134
|
-
"--registry=https://registry.npmjs.org/",
|
|
135
|
-
"@modelcontextprotocol/server-basic-vanillajs",
|
|
136
|
-
"--stdio"
|
|
137
|
-
]
|
|
138
|
-
},
|
|
139
|
-
"basic-vue": {
|
|
140
|
-
"command": "npx",
|
|
141
|
-
"args": [
|
|
142
|
-
"-y",
|
|
143
|
-
"--silent",
|
|
144
|
-
"--registry=https://registry.npmjs.org/",
|
|
145
|
-
"@modelcontextprotocol/server-basic-vue",
|
|
146
|
-
"--stdio"
|
|
147
|
-
]
|
|
148
|
-
},
|
|
149
|
-
"basic-svelte": {
|
|
150
|
-
"command": "npx",
|
|
151
|
-
"args": [
|
|
152
|
-
"-y",
|
|
153
|
-
"--silent",
|
|
154
|
-
"--registry=https://registry.npmjs.org/",
|
|
155
|
-
"@modelcontextprotocol/server-basic-svelte",
|
|
156
|
-
"--stdio"
|
|
157
|
-
]
|
|
158
|
-
},
|
|
159
|
-
"basic-preact": {
|
|
160
|
-
"command": "npx",
|
|
161
|
-
"args": [
|
|
162
|
-
"-y",
|
|
163
|
-
"--silent",
|
|
164
|
-
"--registry=https://registry.npmjs.org/",
|
|
165
|
-
"@modelcontextprotocol/server-basic-preact",
|
|
166
|
-
"--stdio"
|
|
167
|
-
]
|
|
168
|
-
},
|
|
169
|
-
"basic-solid": {
|
|
170
|
-
"command": "npx",
|
|
171
|
-
"args": [
|
|
172
|
-
"-y",
|
|
173
|
-
"--silent",
|
|
174
|
-
"--registry=https://registry.npmjs.org/",
|
|
175
|
-
"@modelcontextprotocol/server-basic-solid",
|
|
176
|
-
"--stdio"
|
|
177
|
-
]
|
|
178
|
-
},
|
|
179
|
-
"budget-allocator": {
|
|
202
|
+
"<name>": {
|
|
180
203
|
"command": "npx",
|
|
181
|
-
"args": [
|
|
182
|
-
"-y",
|
|
183
|
-
"--silent",
|
|
184
|
-
"--registry=https://registry.npmjs.org/",
|
|
185
|
-
"@modelcontextprotocol/server-budget-allocator",
|
|
186
|
-
"--stdio"
|
|
187
|
-
]
|
|
188
|
-
},
|
|
189
|
-
"cohort-heatmap": {
|
|
190
|
-
"command": "npx",
|
|
191
|
-
"args": [
|
|
192
|
-
"-y",
|
|
193
|
-
"--silent",
|
|
194
|
-
"--registry=https://registry.npmjs.org/",
|
|
195
|
-
"@modelcontextprotocol/server-cohort-heatmap",
|
|
196
|
-
"--stdio"
|
|
197
|
-
]
|
|
198
|
-
},
|
|
199
|
-
"customer-segmentation": {
|
|
200
|
-
"command": "npx",
|
|
201
|
-
"args": [
|
|
202
|
-
"-y",
|
|
203
|
-
"--silent",
|
|
204
|
-
"--registry=https://registry.npmjs.org/",
|
|
205
|
-
"@modelcontextprotocol/server-customer-segmentation",
|
|
206
|
-
"--stdio"
|
|
207
|
-
]
|
|
208
|
-
},
|
|
209
|
-
"map": {
|
|
210
|
-
"command": "npx",
|
|
211
|
-
"args": [
|
|
212
|
-
"-y",
|
|
213
|
-
"--silent",
|
|
214
|
-
"--registry=https://registry.npmjs.org/",
|
|
215
|
-
"@modelcontextprotocol/server-map",
|
|
216
|
-
"--stdio"
|
|
217
|
-
]
|
|
218
|
-
},
|
|
219
|
-
"pdf": {
|
|
220
|
-
"command": "npx",
|
|
221
|
-
"args": [
|
|
222
|
-
"-y",
|
|
223
|
-
"--silent",
|
|
224
|
-
"--registry=https://registry.npmjs.org/",
|
|
225
|
-
"@modelcontextprotocol/server-pdf",
|
|
226
|
-
"--stdio"
|
|
227
|
-
]
|
|
228
|
-
},
|
|
229
|
-
"scenario-modeler": {
|
|
230
|
-
"command": "npx",
|
|
231
|
-
"args": [
|
|
232
|
-
"-y",
|
|
233
|
-
"--silent",
|
|
234
|
-
"--registry=https://registry.npmjs.org/",
|
|
235
|
-
"@modelcontextprotocol/server-scenario-modeler",
|
|
236
|
-
"--stdio"
|
|
237
|
-
]
|
|
238
|
-
},
|
|
239
|
-
"shadertoy": {
|
|
240
|
-
"command": "npx",
|
|
241
|
-
"args": [
|
|
242
|
-
"-y",
|
|
243
|
-
"--silent",
|
|
244
|
-
"--registry=https://registry.npmjs.org/",
|
|
245
|
-
"@modelcontextprotocol/server-shadertoy",
|
|
246
|
-
"--stdio"
|
|
247
|
-
]
|
|
248
|
-
},
|
|
249
|
-
"sheet-music": {
|
|
250
|
-
"command": "npx",
|
|
251
|
-
"args": [
|
|
252
|
-
"-y",
|
|
253
|
-
"--silent",
|
|
254
|
-
"--registry=https://registry.npmjs.org/",
|
|
255
|
-
"@modelcontextprotocol/server-sheet-music",
|
|
256
|
-
"--stdio"
|
|
257
|
-
]
|
|
258
|
-
},
|
|
259
|
-
"system-monitor": {
|
|
260
|
-
"command": "npx",
|
|
261
|
-
"args": [
|
|
262
|
-
"-y",
|
|
263
|
-
"--silent",
|
|
264
|
-
"--registry=https://registry.npmjs.org/",
|
|
265
|
-
"@modelcontextprotocol/server-system-monitor",
|
|
266
|
-
"--stdio"
|
|
267
|
-
]
|
|
268
|
-
},
|
|
269
|
-
"threejs": {
|
|
270
|
-
"command": "npx",
|
|
271
|
-
"args": [
|
|
272
|
-
"-y",
|
|
273
|
-
"--silent",
|
|
274
|
-
"--registry=https://registry.npmjs.org/",
|
|
275
|
-
"@modelcontextprotocol/server-threejs",
|
|
276
|
-
"--stdio"
|
|
277
|
-
]
|
|
278
|
-
},
|
|
279
|
-
"transcript": {
|
|
280
|
-
"command": "npx",
|
|
281
|
-
"args": [
|
|
282
|
-
"-y",
|
|
283
|
-
"--silent",
|
|
284
|
-
"--registry=https://registry.npmjs.org/",
|
|
285
|
-
"@modelcontextprotocol/server-transcript",
|
|
286
|
-
"--stdio"
|
|
287
|
-
]
|
|
288
|
-
},
|
|
289
|
-
"video-resource": {
|
|
290
|
-
"command": "npx",
|
|
291
|
-
"args": [
|
|
292
|
-
"-y",
|
|
293
|
-
"--silent",
|
|
294
|
-
"--registry=https://registry.npmjs.org/",
|
|
295
|
-
"@modelcontextprotocol/server-video-resource",
|
|
296
|
-
"--stdio"
|
|
297
|
-
]
|
|
298
|
-
},
|
|
299
|
-
"wiki-explorer": {
|
|
300
|
-
"command": "npx",
|
|
301
|
-
"args": [
|
|
302
|
-
"-y",
|
|
303
|
-
"--silent",
|
|
304
|
-
"--registry=https://registry.npmjs.org/",
|
|
305
|
-
"@modelcontextprotocol/server-wiki-explorer",
|
|
306
|
-
"--stdio"
|
|
307
|
-
]
|
|
308
|
-
},
|
|
309
|
-
"qr": {
|
|
310
|
-
"command": "uv",
|
|
311
|
-
"args": [
|
|
312
|
-
"run",
|
|
313
|
-
"/path/to/ext-apps/examples/qr-server/server.py",
|
|
314
|
-
"--stdio"
|
|
315
|
-
]
|
|
316
|
-
},
|
|
317
|
-
"say": {
|
|
318
|
-
"command": "uv",
|
|
319
|
-
"args": [
|
|
320
|
-
"run",
|
|
321
|
-
"--default-index",
|
|
322
|
-
"https://pypi.org/simple",
|
|
323
|
-
"https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py",
|
|
324
|
-
"--stdio"
|
|
325
|
-
]
|
|
204
|
+
"args": ["-y", "@modelcontextprotocol/server-<name>", "--stdio"]
|
|
326
205
|
}
|
|
327
206
|
}
|
|
328
207
|
}
|
|
329
208
|
```
|
|
330
209
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
> The `qr` server requires cloning the repository first. See [qr-server README](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/qr-server) for details.
|
|
210
|
+
For example, to add the map server: `@modelcontextprotocol/server-map`. The
|
|
211
|
+
Python examples (`qr-server`, `say-server`) use `uv run` instead — see their
|
|
212
|
+
READMEs for details.
|
|
335
213
|
|
|
336
214
|
#### Local Development
|
|
337
215
|
|
|
338
|
-
To test local modifications with MCP
|
|
339
|
-
|
|
340
|
-
```bash
|
|
341
|
-
git clone https://github.com/modelcontextprotocol/ext-apps.git
|
|
342
|
-
cd ext-apps
|
|
343
|
-
npm install
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
Then configure your MCP client to build and run the local server. Replace `~/code/ext-apps` with your actual clone path:
|
|
347
|
-
|
|
348
|
-
<details>
|
|
349
|
-
<summary>MCP client configuration for local development (all examples)</summary>
|
|
216
|
+
To test local modifications with an MCP client, clone the repo, install, then
|
|
217
|
+
point your client at a local build:
|
|
350
218
|
|
|
351
219
|
```json
|
|
352
220
|
{
|
|
353
221
|
"mcpServers": {
|
|
354
|
-
"
|
|
355
|
-
"command": "bash",
|
|
356
|
-
"args": [
|
|
357
|
-
"-c",
|
|
358
|
-
"cd ~/code/ext-apps/examples/basic-server-react && npm run build >&2 && node dist/index.js --stdio"
|
|
359
|
-
]
|
|
360
|
-
},
|
|
361
|
-
"basic-vanillajs": {
|
|
362
|
-
"command": "bash",
|
|
363
|
-
"args": [
|
|
364
|
-
"-c",
|
|
365
|
-
"cd ~/code/ext-apps/examples/basic-server-vanillajs && npm run build >&2 && node dist/index.js --stdio"
|
|
366
|
-
]
|
|
367
|
-
},
|
|
368
|
-
"basic-vue": {
|
|
369
|
-
"command": "bash",
|
|
370
|
-
"args": [
|
|
371
|
-
"-c",
|
|
372
|
-
"cd ~/code/ext-apps/examples/basic-server-vue && npm run build >&2 && node dist/index.js --stdio"
|
|
373
|
-
]
|
|
374
|
-
},
|
|
375
|
-
"basic-svelte": {
|
|
376
|
-
"command": "bash",
|
|
377
|
-
"args": [
|
|
378
|
-
"-c",
|
|
379
|
-
"cd ~/code/ext-apps/examples/basic-server-svelte && npm run build >&2 && node dist/index.js --stdio"
|
|
380
|
-
]
|
|
381
|
-
},
|
|
382
|
-
"basic-preact": {
|
|
222
|
+
"<name>": {
|
|
383
223
|
"command": "bash",
|
|
384
224
|
"args": [
|
|
385
225
|
"-c",
|
|
386
|
-
"cd ~/code/ext-apps/examples
|
|
387
|
-
]
|
|
388
|
-
},
|
|
389
|
-
"basic-solid": {
|
|
390
|
-
"command": "bash",
|
|
391
|
-
"args": [
|
|
392
|
-
"-c",
|
|
393
|
-
"cd ~/code/ext-apps/examples/basic-server-solid && npm run build >&2 && node dist/index.js --stdio"
|
|
394
|
-
]
|
|
395
|
-
},
|
|
396
|
-
"budget-allocator": {
|
|
397
|
-
"command": "bash",
|
|
398
|
-
"args": [
|
|
399
|
-
"-c",
|
|
400
|
-
"cd ~/code/ext-apps/examples/budget-allocator-server && npm run build >&2 && node dist/index.js --stdio"
|
|
401
|
-
]
|
|
402
|
-
},
|
|
403
|
-
"cohort-heatmap": {
|
|
404
|
-
"command": "bash",
|
|
405
|
-
"args": [
|
|
406
|
-
"-c",
|
|
407
|
-
"cd ~/code/ext-apps/examples/cohort-heatmap-server && npm run build >&2 && node dist/index.js --stdio"
|
|
408
|
-
]
|
|
409
|
-
},
|
|
410
|
-
"customer-segmentation": {
|
|
411
|
-
"command": "bash",
|
|
412
|
-
"args": [
|
|
413
|
-
"-c",
|
|
414
|
-
"cd ~/code/ext-apps/examples/customer-segmentation-server && npm run build >&2 && node dist/index.js --stdio"
|
|
415
|
-
]
|
|
416
|
-
},
|
|
417
|
-
"map": {
|
|
418
|
-
"command": "bash",
|
|
419
|
-
"args": [
|
|
420
|
-
"-c",
|
|
421
|
-
"cd ~/code/ext-apps/examples/map-server && npm run build >&2 && node dist/index.js --stdio"
|
|
422
|
-
]
|
|
423
|
-
},
|
|
424
|
-
"pdf": {
|
|
425
|
-
"command": "bash",
|
|
426
|
-
"args": [
|
|
427
|
-
"-c",
|
|
428
|
-
"cd ~/code/ext-apps/examples/pdf-server && npm run build >&2 && node dist/index.js --stdio"
|
|
429
|
-
]
|
|
430
|
-
},
|
|
431
|
-
"scenario-modeler": {
|
|
432
|
-
"command": "bash",
|
|
433
|
-
"args": [
|
|
434
|
-
"-c",
|
|
435
|
-
"cd ~/code/ext-apps/examples/scenario-modeler-server && npm run build >&2 && node dist/index.js --stdio"
|
|
436
|
-
]
|
|
437
|
-
},
|
|
438
|
-
"shadertoy": {
|
|
439
|
-
"command": "bash",
|
|
440
|
-
"args": [
|
|
441
|
-
"-c",
|
|
442
|
-
"cd ~/code/ext-apps/examples/shadertoy-server && npm run build >&2 && node dist/index.js --stdio"
|
|
443
|
-
]
|
|
444
|
-
},
|
|
445
|
-
"sheet-music": {
|
|
446
|
-
"command": "bash",
|
|
447
|
-
"args": [
|
|
448
|
-
"-c",
|
|
449
|
-
"cd ~/code/ext-apps/examples/sheet-music-server && npm run build >&2 && node dist/index.js --stdio"
|
|
450
|
-
]
|
|
451
|
-
},
|
|
452
|
-
"system-monitor": {
|
|
453
|
-
"command": "bash",
|
|
454
|
-
"args": [
|
|
455
|
-
"-c",
|
|
456
|
-
"cd ~/code/ext-apps/examples/system-monitor-server && npm run build >&2 && node dist/index.js --stdio"
|
|
457
|
-
]
|
|
458
|
-
},
|
|
459
|
-
"threejs": {
|
|
460
|
-
"command": "bash",
|
|
461
|
-
"args": [
|
|
462
|
-
"-c",
|
|
463
|
-
"cd ~/code/ext-apps/examples/threejs-server && npm run build >&2 && node dist/index.js --stdio"
|
|
464
|
-
]
|
|
465
|
-
},
|
|
466
|
-
"transcript": {
|
|
467
|
-
"command": "bash",
|
|
468
|
-
"args": [
|
|
469
|
-
"-c",
|
|
470
|
-
"cd ~/code/ext-apps/examples/transcript-server && npm run build >&2 && node dist/index.js --stdio"
|
|
471
|
-
]
|
|
472
|
-
},
|
|
473
|
-
"video-resource": {
|
|
474
|
-
"command": "bash",
|
|
475
|
-
"args": [
|
|
476
|
-
"-c",
|
|
477
|
-
"cd ~/code/ext-apps/examples/video-resource-server && npm run build >&2 && node dist/index.js --stdio"
|
|
478
|
-
]
|
|
479
|
-
},
|
|
480
|
-
"wiki-explorer": {
|
|
481
|
-
"command": "bash",
|
|
482
|
-
"args": [
|
|
483
|
-
"-c",
|
|
484
|
-
"cd ~/code/ext-apps/examples/wiki-explorer-server && npm run build >&2 && node dist/index.js --stdio"
|
|
485
|
-
]
|
|
486
|
-
},
|
|
487
|
-
"qr": {
|
|
488
|
-
"command": "bash",
|
|
489
|
-
"args": [
|
|
490
|
-
"-c",
|
|
491
|
-
"uv run ~/code/ext-apps/examples/qr-server/server.py --stdio"
|
|
492
|
-
]
|
|
493
|
-
},
|
|
494
|
-
"say": {
|
|
495
|
-
"command": "bash",
|
|
496
|
-
"args": [
|
|
497
|
-
"-c",
|
|
498
|
-
"uv run --index https://pypi.org/simple ~/code/ext-apps/examples/say-server/server.py --stdio"
|
|
226
|
+
"cd ~/code/ext-apps/examples/<name>-server && npm run build >&2 && node dist/index.js --stdio"
|
|
499
227
|
]
|
|
500
228
|
}
|
|
501
229
|
}
|
|
502
230
|
}
|
|
503
231
|
```
|
|
504
232
|
|
|
505
|
-
|
|
233
|
+
## Specification
|
|
506
234
|
|
|
507
|
-
|
|
235
|
+
<div align="center">
|
|
236
|
+
|
|
237
|
+
| Version | Status | Link |
|
|
238
|
+
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
239
|
+
| **2026-01-26** | Stable | [specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) |
|
|
240
|
+
| **draft** | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
|
|
241
|
+
|
|
242
|
+
</div>
|
|
508
243
|
|
|
509
244
|
## Resources
|
|
510
245
|
|
|
511
246
|
- [Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html)
|
|
512
247
|
- [API Documentation](https://modelcontextprotocol.github.io/ext-apps/api/)
|
|
513
|
-
- [Specification (2026-01-26)](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
|
|
248
|
+
- [Specification (2026-01-26)](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
|
|
249
|
+
([Draft](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx))
|
|
514
250
|
- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
|
|
251
|
+
|
|
252
|
+
## Contributing
|
|
253
|
+
|
|
254
|
+
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
|
|
255
|
+
guidelines on how to get started, submit pull requests, and report issues.
|
package/dist/src/app-bridge.d.ts
CHANGED
|
@@ -31,6 +31,20 @@ export { PostMessageTransport } from "./message-transport";
|
|
|
31
31
|
* ```
|
|
32
32
|
*/
|
|
33
33
|
export declare function getToolUiResourceUri(tool: Partial<Tool>): string | undefined;
|
|
34
|
+
/**
|
|
35
|
+
* Check if a tool is visible to the model only.
|
|
36
|
+
*
|
|
37
|
+
* @param tool - Tool object with visibility metadata
|
|
38
|
+
* @returns True if the tool is visible to the model only, false otherwise
|
|
39
|
+
*/
|
|
40
|
+
export declare function isToolVisibilityModelOnly(tool: Partial<Tool>): boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Check if a tool is visible to the app only.
|
|
43
|
+
*
|
|
44
|
+
* @param tool - Tool object with visibility metadata
|
|
45
|
+
* @returns True if the tool is visible to the app only, false otherwise
|
|
46
|
+
*/
|
|
47
|
+
export declare function isToolVisibilityAppOnly(tool: Partial<Tool>): boolean;
|
|
34
48
|
/**
|
|
35
49
|
* Build iframe `allow` attribute string from permissions.
|
|
36
50
|
*
|