Mirror of https://github.com/modelcontextprotocol/ext-apps — Official repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers
- TypeScript 76.4%
- MDX 19.3%
- JavaScript 4.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
974862237b* fix: Windows compatibility for npm scripts and cross-platform CI Fixes #142 - Windows PowerShell install bug Changes: - Replace single quotes with escaped double quotes in generate:schemas (cmd.exe passes single quotes literally, breaking prettier glob matching) - Simplify prettier scripts: remove redundant --ignore-path flags (prettier auto-loads .gitignore and .prettierignore by default) - Remove $(pwd) from prettier scripts (bash-only syntax) - Add cross-platform CI matrix: Linux x64, Windows x64, macOS ARM64, macOS x64 - Use shell: bash for grep commands in CI (not available in Windows cmd.exe) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: remove bun npm package from all workspaces The bun npm package tries to install platform-specific binaries which fails on Windows CI. Since bun is installed via oven-sh/setup-bun action in CI (and developers install it globally), we don't need the npm package. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: skip examples:build on Windows (uses Unix-only INPUT=... syntax) The examples use `INPUT=mcp-app.html vite build` which is bash syntax for setting environment variables. This doesn't work on Windows cmd.exe. Since examples aren't published to npm, we can skip building them on Windows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: force LF line endings for cross-platform prettier consistency Git on Windows auto-converts line endings to CRLF, causing prettier to report formatting issues. Force LF for all text files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: add test for git-based npm install (cross-platform) This verifies that `npm install git+https://...` works on all platforms, which triggers the prepare script and requires bun to be available. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: add Linux ARM64 and Windows ARM64 to CI matrix - Added ubuntu-24.04-arm (Linux ARM64) - Added windows-11-arm (Windows ARM64) Note: WSL is not available on GitHub-hosted runners (requires nested virtualization which isn't supported). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: disable Windows ARM64 (Bun lacks stable ARM64 binaries) The oven-sh/setup-bun action fails with 404 when trying to download Bun for Windows ARM64. Re-enable when Bun adds proper support. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: add Windows WSL build test Uses Vampire/setup-wsl action to install Ubuntu-24.04 in WSL and run the full build/test cycle. This tests the Linux-in-Windows scenario that was reported in issue #142. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: fix WSL build - install unzip for Bun installer 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: add setup-bun to publish.yml workflow The pkg-pr-new publish workflow was missing bun setup, causing "bun: not found" errors during npm ci (which triggers prepare script). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: enable Windows ARM64 with x64-baseline Bun (via emulation) Windows ARM64 can run x64 binaries via emulation. Use bun-download-url to force x64-baseline build since native ARM64 Bun isn't available yet. Reference: https://github.com/oven-sh/bun/issues/9824 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: remove macOS x64 (macos-13 runner retired) The macos-13 based runner images are now retired. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Bun installation instructions per platform Documents that Bun is required for development, with platform-specific install commands in collapsible sections. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: note Bun requirement in README examples section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add bun as optional dependency (no global install required) - Add @oven/bun-* platform packages as optionalDependencies - Create postinstall script to set up bun binary from optional deps - Handle Windows ARM64 by downloading x64-baseline for emulation - Remove setup-bun from CI workflows (npm install handles it now) - Remove manual Bun install instructions from docs This alternative approach eliminates the need for global Bun installation or setup-bun action in CI. npm install automatically installs the platform-appropriate bun binary. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: add debug logging to setup-bun script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: force stdout flush in setup-bun for CI debugging 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: add more debugging to setup-bun 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: remove accidental test artifacts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: run setup-bun in prepare script (before build) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: use cross-env for Windows-compatible example builds - Add cross-env to devDependencies - Update all example package.json scripts to use cross-env for INPUT and NODE_ENV - Enable examples:build on Windows in CI (no longer Unix-only) - Add examples:build to WSL CI job 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: remove unused imports in setup-bun.mjs Address github-code-quality bot comments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: use run-bun.mjs wrapper for prepare hook compatibility During npm install's prepare hook, node_modules/.bin is not in PATH, so calling 'bun' directly fails. The new run-bun.mjs wrapper finds bun at node_modules/.bin/bun and runs it with the correct path. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: restore setup-bun action for build jobs - Add setup-bun action to build and test-git-install jobs - Disable Windows ARM64 (Bun doesn't support this platform) - Add bun installation to WSL build 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: remove bun devDep, add libc detection for Linux ARM64 - Remove 'bun' from devDependencies (its postinstall fails on Windows ARM64) - Add libc detection (glibc vs musl) to setup-bun.mjs - Only try compatible binaries based on detected libc - Re-enable Windows ARM64 in CI (now uses x64 emulation fallback) - Remove setup-bun action from CI (no longer needed) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ci: simplify WSL build - let setup-bun.mjs handle bun installation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
| .github/workflows | ||
| .husky | ||
| docs | ||
| examples | ||
| scripts | ||
| specification/draft | ||
| src | ||
| tests/e2e | ||
| .gitattributes | ||
| .gitignore | ||
| .prettierignore | ||
| .prettierrc.json | ||
| build.bun.ts | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| playwright.config.ts | ||
| README.md | ||
| tsconfig.json | ||
| typedoc.json | ||
@modelcontextprotocol/ext-apps
This repo contains the SDK and specification for MCP Apps Extension (SEP-1865).
MCP Apps are a proposed standard inspired by MCP-UI and OpenAI's Apps SDK to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.
Overview
This SDK serves two audiences:
App Developers
Build interactive UIs that run inside MCP-enabled chat clients.
- SDK for Apps:
@modelcontextprotocol/ext-apps— API Docs - React hooks:
@modelcontextprotocol/ext-apps/react— API Docs
Host Developers
Embed and communicate with MCP Apps in your chat application.
- SDK for Hosts:
@modelcontextprotocol/ext-apps/app-bridge— API Docs
There's no supported host implementation in this repo (beyond the examples/basic-host example).
We have contributed a tentative implementation of hosting / iframing / sandboxing logic to the MCP-UI repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.
Installation
npm install -S @modelcontextprotocol/ext-apps
Or edit your package.json manually:
{
"dependencies": {
"@modelcontextprotocol/ext-apps": "^0.0.1"
}
}
Examples
Start with these foundational examples to learn the SDK:
examples/basic-server-vanillajs— Example MCP server with tools that return UI Apps (vanilla JS)examples/basic-server-react— Example MCP server with tools that return UI Apps (React)examples/basic-host— Bare-bones example of hosting MCP Apps
The examples/ directory contains additional demo apps showcasing real-world use cases.
To run all examples together:
npm install
npm run examples:start
Then open http://localhost:8080/.