Skip to content

Commit 3518380

Browse files
idosalidosal
committed
Merge branch 'main' into feat/sandbox-flags
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # examples/basic-host/src/implementation.ts # src/app-bridge.test.ts # src/app-bridge.ts # src/generated/schema.ts # src/spec.types.ts
2 parents 3480b98 + 8dbc06a commit 3518380

86 files changed

Lines changed: 2329 additions & 443 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ jobs:
3030
runs-on: ${{ matrix.os }}
3131

3232
steps:
33-
- uses: actions/checkout@v4
33+
- uses: actions/checkout@v6
3434

3535
- name: Verify no private URLs in package-lock.json
3636
shell: bash
@@ -40,7 +40,7 @@ jobs:
4040
shell: bash
4141
run: node scripts/check-versions.mjs
4242

43-
- uses: actions/setup-node@v4
43+
- uses: actions/setup-node@v6
4444
with:
4545
node-version: "20"
4646

@@ -69,17 +69,17 @@ jobs:
6969
e2e:
7070
runs-on: ubuntu-latest
7171
steps:
72-
- uses: actions/checkout@v4
72+
- uses: actions/checkout@v6
7373

7474
- uses: oven-sh/setup-bun@v2
7575
with:
7676
bun-version: latest
7777

78-
- uses: actions/setup-node@v4
78+
- uses: actions/setup-node@v6
7979
with:
8080
node-version: "20"
8181

82-
- uses: astral-sh/setup-uv@v5
82+
- uses: astral-sh/setup-uv@v7
8383

8484
- run: npm ci
8585

@@ -90,7 +90,7 @@ jobs:
9090
run: npx playwright test --reporter=list
9191

9292
- name: Upload test results
93-
uses: actions/upload-artifact@v4
93+
uses: actions/upload-artifact@v6
9494
if: failure()
9595
with:
9696
name: test-results
@@ -103,9 +103,9 @@ jobs:
103103
runs-on: windows-latest
104104

105105
steps:
106-
- uses: actions/checkout@v4
106+
- uses: actions/checkout@v6
107107

108-
- uses: Vampire/setup-wsl@v5
108+
- uses: Vampire/setup-wsl@v6
109109
with:
110110
distribution: Ubuntu-24.04
111111

@@ -146,7 +146,7 @@ jobs:
146146
runs-on: ${{ matrix.os }}
147147

148148
steps:
149-
- uses: actions/setup-node@v4
149+
- uses: actions/setup-node@v6
150150
with:
151151
node-version: "20"
152152

‎.github/workflows/docs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ jobs:
1212
deploy:
1313
runs-on: ubuntu-latest
1414
steps:
15-
- uses: actions/checkout@v4
15+
- uses: actions/checkout@v6
1616
- uses: oven-sh/setup-bun@v2
17-
- uses: actions/setup-node@v4
17+
- uses: actions/setup-node@v6
1818
with:
1919
node-version: "20"
2020
- run: npm install

‎.github/workflows/npm-publish.yml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,11 @@ jobs:
1414
permissions:
1515
contents: read
1616
steps:
17-
- uses: actions/checkout@v4
17+
- uses: actions/checkout@v6
1818
- uses: oven-sh/setup-bun@v2
1919
with:
2020
bun-version: latest
21-
- uses: actions/setup-node@v4
21+
- uses: actions/setup-node@v6
2222
with:
2323
node-version: "22"
2424
cache: npm
@@ -31,11 +31,11 @@ jobs:
3131
permissions:
3232
contents: read
3333
steps:
34-
- uses: actions/checkout@v4
34+
- uses: actions/checkout@v6
3535
- uses: oven-sh/setup-bun@v2
3636
with:
3737
bun-version: latest
38-
- uses: actions/setup-node@v4
38+
- uses: actions/setup-node@v6
3939
with:
4040
node-version: "22"
4141
cache: npm
@@ -53,11 +53,11 @@ jobs:
5353
id-token: write
5454

5555
steps:
56-
- uses: actions/checkout@v4
56+
- uses: actions/checkout@v6
5757
- uses: oven-sh/setup-bun@v2
5858
with:
5959
bun-version: latest
60-
- uses: actions/setup-node@v4
60+
- uses: actions/setup-node@v6
6161
with:
6262
node-version: "22"
6363
cache: npm
@@ -119,11 +119,11 @@ jobs:
119119
- wiki-explorer-server
120120

121121
steps:
122-
- uses: actions/checkout@v4
122+
- uses: actions/checkout@v6
123123
- uses: oven-sh/setup-bun@v2
124124
with:
125125
bun-version: latest
126-
- uses: actions/setup-node@v4
126+
- uses: actions/setup-node@v6
127127
with:
128128
node-version: "22"
129129
cache: npm

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ jobs:
1313
pkg-publish:
1414
runs-on: ubuntu-latest
1515
steps:
16-
- uses: actions/checkout@v4
17-
- uses: actions/setup-node@v4
16+
- uses: actions/checkout@v6
17+
- uses: actions/setup-node@v6
1818
with:
1919
node-version: 22
2020
cache: npm

‎.github/workflows/update-snapshots.yml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
- name: Get PR branch
2626
if: github.event_name == 'issue_comment'
2727
id: pr
28-
uses: actions/github-script@v7
28+
uses: actions/github-script@v8
2929
with:
3030
script: |
3131
const pr = await github.rest.pulls.get({
@@ -38,7 +38,7 @@ jobs:
3838
3939
- name: Add reaction to comment
4040
if: github.event_name == 'issue_comment'
41-
uses: actions/github-script@v7
41+
uses: actions/github-script@v8
4242
with:
4343
script: |
4444
await github.rest.reactions.createForIssueComment({
@@ -48,7 +48,7 @@ jobs:
4848
content: 'rocket'
4949
});
5050
51-
- uses: actions/checkout@v4
51+
- uses: actions/checkout@v6
5252
with:
5353
ref: ${{ github.event.inputs.branch || steps.pr.outputs.ref || github.ref }}
5454
token: ${{ secrets.GITHUB_TOKEN }}
@@ -57,11 +57,11 @@ jobs:
5757
with:
5858
bun-version: latest
5959

60-
- uses: actions/setup-node@v4
60+
- uses: actions/setup-node@v6
6161
with:
6262
node-version: "20"
6363

64-
- uses: astral-sh/setup-uv@v5
64+
- uses: astral-sh/setup-uv@v7
6565

6666
- run: npm ci
6767

@@ -88,7 +88,7 @@ jobs:
8888
8989
- name: Comment on PR
9090
if: github.event_name == 'issue_comment'
91-
uses: actions/github-script@v7
91+
uses: actions/github-script@v8
9292
with:
9393
script: |
9494
const changed = '${{ steps.commit.outputs.changed }}' === 'true';

‎.playwright-mcp/page-2026-01-29T16-44-20-392Z.png‎

636 KB
Loading

‎.playwright-mcp/page-2026-01-29T16-45-07-754Z.png‎

638 KB
Loading

‎README.md‎

Lines changed: 68 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,59 @@
1-
# @modelcontextprotocol/ext-apps
2-
3-
[![npm version](https://img.shields.io/npm/v/@modelcontextprotocol/ext-apps.svg)](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) [![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blue)](https://modelcontextprotocol.github.io/ext-apps/api/)
4-
5-
This repo contains the SDK and specification for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
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/claude-colorpicker-apps.gif" alt="MCP Apps demo" width="600">
32+
<br><em>Color picker built with MCP Apps, running in Claude</em>
33+
</p>
34+
35+
## Table of Contents
36+
37+
- [Specification](#specification)
38+
- [Why MCP Apps?](#why-mcp-apps)
39+
- [How It Works](#how-it-works)
40+
- [Getting Started](#getting-started)
41+
- [Using the SDK](#using-the-sdk)
42+
- [Agent Skills](#agent-skills)
43+
- [Examples](#examples)
44+
- [Resources](#resources)
45+
- [Contributing](#contributing)
646

747
## Specification
848

49+
<div align="center">
50+
951
| Version | Status | Link |
1052
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
1153
| **2026-01-26** | Stable | [specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) |
12-
| draft | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
54+
| **draft** | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
55+
56+
</div>
1357

1458
MCP Apps are a proposed standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
1559

@@ -28,34 +72,30 @@ MCP Apps extend the Model Context Protocol by letting tools declare UI resources
2872
3. **Host renders** — The host fetches the resource and displays it in a sandboxed iframe
2973
4. **Bidirectional communication** — The host passes tool data to the UI via notifications, and the UI can call other tools through the host
3074

31-
## Using the SDK
75+
## Getting Started
3276

33-
This SDK serves two audiences:
34-
35-
### For App Developers
36-
37-
Build interactive UIs that run inside MCP-enabled chat clients.
77+
```bash
78+
npm install -S @modelcontextprotocol/ext-apps
79+
```
3880

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)
81+
**New here?** Start with the [Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) to build your first MCP App.
4182

42-
### For Host Developers
83+
## Using the SDK
4384

44-
Embed and communicate with MCP Apps in your chat application.
85+
The SDK serves three roles: app developers building interactive Views, host developers embedding those Views, and MCP server authors registering tools with UI metadata.
4586

46-
- **SDK for Hosts**: `@modelcontextprotocol/ext-apps/app-bridge` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html)
87+
| Package | Purpose | Docs |
88+
|---------|---------|------|
89+
| `@modelcontextprotocol/ext-apps` | Build interactive Views (App class, PostMessageTransport) | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html) |
90+
| `@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) |
91+
| `@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) |
92+
| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/server.html) |
4793

4894
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).
4995

5096
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.
5197

52-
## Installation
53-
54-
```bash
55-
npm install -S @modelcontextprotocol/ext-apps
56-
```
57-
58-
### Install Agent Skills
98+
## Agent Skills
5999

60100
This repository provides two [Agent Skills](https://agentskills.io/) for building MCP Apps. You can install the skills as a Claude Code plugin:
61101

@@ -512,3 +552,7 @@ This configuration rebuilds each server on launch, ensuring your local changes a
512552
- [API Documentation](https://modelcontextprotocol.github.io/ext-apps/api/)
513553
- [Specification (2026-01-26)](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) ([Draft](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx))
514554
- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
555+
556+
## Contributing
557+
558+
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started, submit pull requests, and report issues.

‎docs/overview.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ See the [Display Modes](https://github.com/modelcontextprotocol/ext-apps/blob/ma
201201

202202
All Views run in sandboxed iframes with no access to the Host's DOM, cookies, or storage. Communication happens only through [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage), making it auditable.
203203

204-
Servers declare which external domains their UI needs via [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) metadata. Hosts enforce these declarations — if no domains are declared, no external connections are allowed. This "restrictive by default" approach prevents data exfiltration to undeclared servers.
204+
Servers declare which network domains their UI needs via [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) metadata. Hosts enforce these declarations — if no domains are declared, no external connections are allowed. This "restrictive by default" approach prevents data exfiltration to undeclared servers.
205205

206206
See the [Security Implications](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#security-implications) section of the specification for the threat model and mitigations.
207207

0 commit comments

Comments
 (0)