Merge pull request #463 from modelcontextprotocol/localden/readme
README update
This commit is contained in:
Anton Pidkuiko
GitHub
commit
0b48dfab7d
4 changed files with 92 additions and 24 deletions
98
README.md
98
README.md
|
|
@ -1,15 +1,59 @@
|
|||
# @modelcontextprotocol/ext-apps
|
||||
<!-- LOGO -->
|
||||
<div align="center">
|
||||
<img src="media/mcp.svg#gh-light-mode-only" alt="MCP Apps" width="128">
|
||||
<img src="media/mcp-white.svg#gh-dark-mode-only" alt="MCP Apps" width="128">
|
||||
<h1>MCP Apps</h1>
|
||||
<p>
|
||||
Build interactive UIs for MCP tools — charts, forms, dashboards — that render inline in any compliant chat client.
|
||||
<br /><br />
|
||||
<a href="#why-mcp-apps">Why</a>
|
||||
·
|
||||
<a href="https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html">Quickstart</a>
|
||||
·
|
||||
<a href="https://modelcontextprotocol.github.io/ext-apps/api/">API Docs</a>
|
||||
·
|
||||
<a href="https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx">Spec</a>
|
||||
·
|
||||
<a href="CONTRIBUTING.md">Contributing</a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
[](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) [](https://modelcontextprotocol.github.io/ext-apps/api/)
|
||||
<p align="center">
|
||||
<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>
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
|
||||
<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>
|
||||
<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>
|
||||
<a href="https://github.com/modelcontextprotocol/ext-apps"><img src="https://img.shields.io/github/stars/modelcontextprotocol/ext-apps" alt="GitHub stars"></a>
|
||||
<a href="https://modelcontextprotocol.github.io/ext-apps/api/"><img src="https://img.shields.io/badge/docs-API%20Reference-blue" alt="API Documentation"></a>
|
||||
</p>
|
||||
|
||||
This repo contains the SDK and specification for MCP Apps Extension ([SEP-1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)).
|
||||
<p align="center">
|
||||
<img src="media/claude-colorpicker-apps.gif" alt="MCP Apps demo" width="600">
|
||||
<br><em>Color picker built with MCP Apps, running in Claude</em>
|
||||
</p>
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Specification](#specification)
|
||||
- [Why MCP Apps?](#why-mcp-apps)
|
||||
- [How It Works](#how-it-works)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Using the SDK](#using-the-sdk)
|
||||
- [Agent Skills](#agent-skills)
|
||||
- [Examples](#examples)
|
||||
- [Resources](#resources)
|
||||
- [Contributing](#contributing)
|
||||
|
||||
## Specification
|
||||
|
||||
<div align="center">
|
||||
|
||||
| Version | Status | Link |
|
||||
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **2026-01-26** | Stable | [specification/2026-01-26/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) |
|
||||
| draft | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
|
||||
| **draft** | Development | [specification/draft/apps.mdx](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) |
|
||||
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -28,34 +72,30 @@ MCP Apps extend the Model Context Protocol by letting tools declare UI resources
|
|||
3. **Host renders** — The host fetches the resource and displays it in a sandboxed iframe
|
||||
4. **Bidirectional communication** — The host passes tool data to the UI via notifications, and the UI can call other tools through the host
|
||||
|
||||
## Using the SDK
|
||||
|
||||
This SDK serves two audiences:
|
||||
|
||||
### For App Developers
|
||||
|
||||
Build interactive UIs that run inside MCP-enabled chat clients.
|
||||
|
||||
- **SDK for Apps**: `@modelcontextprotocol/ext-apps` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html)
|
||||
- **React hooks**: `@modelcontextprotocol/ext-apps/react` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/_modelcontextprotocol_ext-apps_react.html)
|
||||
|
||||
### For Host Developers
|
||||
|
||||
Embed and communicate with MCP Apps in your chat application.
|
||||
|
||||
- **SDK for Hosts**: `@modelcontextprotocol/ext-apps/app-bridge` — [API Docs](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html)
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
## Installation
|
||||
## Getting Started
|
||||
|
||||
```bash
|
||||
npm install -S @modelcontextprotocol/ext-apps
|
||||
```
|
||||
|
||||
### Install Agent Skills
|
||||
**New here?** Start with the [Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) to build your first MCP App.
|
||||
|
||||
## Using the SDK
|
||||
|
||||
The SDK serves three roles: app developers building interactive Views, host developers embedding those Views, and MCP server authors registering tools with UI metadata.
|
||||
|
||||
| Package | Purpose | Docs |
|
||||
|---------|---------|------|
|
||||
| `@modelcontextprotocol/ext-apps` | Build interactive Views (App class, PostMessageTransport) | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/app.html) |
|
||||
| `@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) |
|
||||
| `@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) |
|
||||
| `@modelcontextprotocol/ext-apps/server` | Register tools and resources on your MCP server | [API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/server.html) |
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
## Agent Skills
|
||||
|
||||
This repository provides two [Agent Skills](https://agentskills.io/) for building MCP Apps. You can install the skills as a Claude Code plugin:
|
||||
|
||||
|
|
@ -512,3 +552,7 @@ This configuration rebuilds each server on launch, ensuring your local changes a
|
|||
- [API Documentation](https://modelcontextprotocol.github.io/ext-apps/api/)
|
||||
- [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))
|
||||
- [SEP-1865 Discussion](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865)
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started, submit pull requests, and report issues.
|
||||
|
|
|
|||
BIN
media/claude-colorpicker-apps.gif
Normal file
BIN
media/claude-colorpicker-apps.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
12
media/mcp-white.svg
Normal file
12
media/mcp-white.svg
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<g clip-path="url(#clip0_19_13)">
|
||||
<path d="M18 84.8528L85.8822 16.9706C95.2548 7.59798 110.451 7.59798 119.823 16.9706V16.9706C129.196 26.3431 129.196 41.5391 119.823 50.9117L68.5581 102.177" stroke="white" stroke-width="12" stroke-linecap="round"/>
|
||||
<path d="M69.2652 101.47L119.823 50.9117C129.196 41.5391 144.392 41.5391 153.765 50.9117L154.118 51.2652C163.491 60.6378 163.491 75.8338 154.118 85.2063L92.7248 146.6C89.6006 149.724 89.6006 154.789 92.7248 157.913L105.331 170.52" stroke="white" stroke-width="12" stroke-linecap="round"/>
|
||||
<path d="M102.853 33.9411L52.6482 84.1457C43.2756 93.5183 43.2756 108.714 52.6482 118.087V118.087C62.0208 127.459 77.2167 127.459 86.5893 118.087L136.794 67.8822" stroke="white" stroke-width="12" stroke-linecap="round"/>
|
||||
</g>
|
||||
<defs>
|
||||
<clipPath id="clip0_19_13">
|
||||
<rect width="180" height="180" fill="none"/>
|
||||
</clipPath>
|
||||
</defs>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 972 B |
12
media/mcp.svg
Normal file
12
media/mcp.svg
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<g clip-path="url(#clip0_19_13)">
|
||||
<path d="M18 84.8528L85.8822 16.9706C95.2548 7.59798 110.451 7.59798 119.823 16.9706V16.9706C129.196 26.3431 129.196 41.5391 119.823 50.9117L68.5581 102.177" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||
<path d="M69.2652 101.47L119.823 50.9117C129.196 41.5391 144.392 41.5391 153.765 50.9117L154.118 51.2652C163.491 60.6378 163.491 75.8338 154.118 85.2063L92.7248 146.6C89.6006 149.724 89.6006 154.789 92.7248 157.913L105.331 170.52" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||
<path d="M102.853 33.9411L52.6482 84.1457C43.2756 93.5183 43.2756 108.714 52.6482 118.087V118.087C62.0208 127.459 77.2167 127.459 86.5893 118.087L136.794 67.8822" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||
</g>
|
||||
<defs>
|
||||
<clipPath id="clip0_19_13">
|
||||
<rect width="180" height="180" fill="white"/>
|
||||
</clipPath>
|
||||
</defs>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 973 B |
Loading…
Reference in a new issue