Add Claude Code plugin with "Create MCP App" skill (#256)
Add a Claude Code plugin (`plugins/mcp-apps/`) for distribution via the plugin marketplace. The plugin provides the "Create MCP App" skill that guides the agent through building MCP Apps with interactive UIs. The skill includes: - Instructions to clone SDK repo for reference templates - Framework selection guidance (React, Vanilla JS, Vue, Svelte, etc.) - Tool visibility configuration (`_meta.ui.visibility`) - Host styling integration patterns - Testing workflow using `basic-host` - Common mistakes to avoid Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
969b905c10
commit
6166242136
5 changed files with 264 additions and 0 deletions
|
|
@ -3,3 +3,4 @@ examples/basic-host/**/*.tsx
|
||||||
examples/basic-server-*/**/*.ts
|
examples/basic-server-*/**/*.ts
|
||||||
examples/basic-server-*/**/*.tsx
|
examples/basic-server-*/**/*.tsx
|
||||||
**/vendor/**
|
**/vendor/**
|
||||||
|
SKILL.md
|
||||||
|
|
|
||||||
|
|
@ -85,3 +85,7 @@ Uses npm workspaces. Examples in `examples/` are separate packages:
|
||||||
- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
|
- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
|
||||||
- `basic-host` - Reference host implementation
|
- `basic-host` - Reference host implementation
|
||||||
- Other examples showcase specific features (charts, 3D, video, etc.)
|
- Other examples showcase specific features (charts, 3D, video, etc.)
|
||||||
|
|
||||||
|
## Claude Code Plugin
|
||||||
|
|
||||||
|
The `plugins/mcp-apps/` directory contains a Claude Code plugin distributed via the plugin marketplace. It provides the "Create MCP App" skill (`plugins/mcp-apps/skills/create-mcp-app/SKILL.md`) that guides users through building MCP Apps with interactive UIs.
|
||||||
|
|
|
||||||
11
plugins/mcp-apps/.claude-plugin/plugin.json
Normal file
11
plugins/mcp-apps/.claude-plugin/plugin.json
Normal file
|
|
@ -0,0 +1,11 @@
|
||||||
|
{
|
||||||
|
"name": "mcp-apps",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "Claude Code skill for building MCP Apps with interactive UIs",
|
||||||
|
"author": {
|
||||||
|
"name": "MCP Apps"
|
||||||
|
},
|
||||||
|
"repository": "https://github.com/anthropics/mcp-ext-apps",
|
||||||
|
"license": "MIT",
|
||||||
|
"keywords": ["mcp", "mcp-apps", "model-context-protocol", "ui", "interactive"]
|
||||||
|
}
|
||||||
20
plugins/mcp-apps/README.md
Normal file
20
plugins/mcp-apps/README.md
Normal file
|
|
@ -0,0 +1,20 @@
|
||||||
|
# MCP Apps Plugin for Claude Code
|
||||||
|
|
||||||
|
A Claude Code plugin that provides the "Create MCP App" skill for building MCP Apps with interactive UIs.
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Install via Claude Code:
|
||||||
|
|
||||||
|
1. Run `/plugin` in Claude Code
|
||||||
|
2. Navigate to the Discover tab
|
||||||
|
3. Install "mcp-apps"
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
Invoke the skill by asking Claude Code to:
|
||||||
|
|
||||||
|
- "Create an MCP App"
|
||||||
|
- "Add a UI to an MCP tool"
|
||||||
|
- "Build an interactive MCP widget"
|
||||||
|
- "Scaffold an MCP App"
|
||||||
228
plugins/mcp-apps/skills/create-mcp-app/SKILL.md
Normal file
228
plugins/mcp-apps/skills/create-mcp-app/SKILL.md
Normal file
|
|
@ -0,0 +1,228 @@
|
||||||
|
---
|
||||||
|
name: Create MCP App
|
||||||
|
description: This skill should be used when the user asks to "create an MCP App", "add a UI to an MCP tool", "build an interactive MCP widget", "scaffold an MCP App", or needs guidance on MCP Apps SDK patterns, UI-resource registration, MCP App lifecycle, or host integration. Provides comprehensive guidance for building MCP Apps with interactive UIs.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Create MCP App
|
||||||
|
|
||||||
|
Build interactive UIs that run inside MCP-enabled hosts like Claude Desktop. An MCP App combines an MCP tool with an HTML resource to display rich, interactive content.
|
||||||
|
|
||||||
|
## Core Concept: Tool + Resource
|
||||||
|
|
||||||
|
Every MCP App requires two parts linked together:
|
||||||
|
|
||||||
|
1. **Tool** - Called by the LLM/host, returns data
|
||||||
|
2. **Resource** - Serves the bundled HTML UI that displays the data
|
||||||
|
3. **Link** - The tool's `_meta.ui.resourceUri` references the resource
|
||||||
|
|
||||||
|
```
|
||||||
|
Host calls tool → Server returns result → Host renders resource UI → UI receives result
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start Decision Tree
|
||||||
|
|
||||||
|
### Framework Selection
|
||||||
|
|
||||||
|
| Framework | SDK Support | Best For |
|
||||||
|
|-----------|-------------|----------|
|
||||||
|
| React | `useApp` hook provided | Teams familiar with React |
|
||||||
|
| Vanilla JS | Manual lifecycle | Simple apps, no build complexity |
|
||||||
|
| Vue/Svelte/Preact/Solid | Manual lifecycle | Framework preference |
|
||||||
|
|
||||||
|
### Project Context
|
||||||
|
|
||||||
|
**Adding to existing MCP server:**
|
||||||
|
- Import `registerAppTool`, `registerAppResource` from SDK
|
||||||
|
- Add tool registration with `_meta.ui.resourceUri`
|
||||||
|
- Add resource registration serving bundled HTML
|
||||||
|
|
||||||
|
**Creating new MCP server:**
|
||||||
|
- Set up server with transport (stdio or HTTP)
|
||||||
|
- Register tools and resources
|
||||||
|
- Configure build system with `vite-plugin-singlefile`
|
||||||
|
|
||||||
|
## Getting Reference Code
|
||||||
|
|
||||||
|
Clone the SDK repository for working examples and API documentation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps
|
||||||
|
```
|
||||||
|
|
||||||
|
### Framework Templates
|
||||||
|
|
||||||
|
Learn and adapt from `/tmp/mcp-ext-apps/examples/basic-server-{framework}/`:
|
||||||
|
|
||||||
|
| Template | Key Files |
|
||||||
|
|----------|-----------|
|
||||||
|
| `basic-server-vanillajs/` | `server.ts`, `src/mcp-app.ts`, `mcp-app.html` |
|
||||||
|
| `basic-server-react/` | `server.ts`, `src/mcp-app.tsx` (uses `useApp` hook) |
|
||||||
|
| `basic-server-vue/` | `server.ts`, `src/App.vue` |
|
||||||
|
| `basic-server-svelte/` | `server.ts`, `src/App.svelte` |
|
||||||
|
| `basic-server-preact/` | `server.ts`, `src/mcp-app.tsx` |
|
||||||
|
| `basic-server-solid/` | `server.ts`, `src/mcp-app.tsx` |
|
||||||
|
|
||||||
|
Each template includes:
|
||||||
|
- Complete `server.ts` with `registerAppTool` and `registerAppResource`
|
||||||
|
- Client-side app with all lifecycle handlers
|
||||||
|
- `vite.config.ts` with `vite-plugin-singlefile`
|
||||||
|
- `package.json` with all required dependencies
|
||||||
|
- `.gitignore` excluding `node_modules/` and `dist/`
|
||||||
|
|
||||||
|
### API Reference (Source Files)
|
||||||
|
|
||||||
|
Read JSDoc documentation directly from source:
|
||||||
|
|
||||||
|
| File | Contents |
|
||||||
|
|------|----------|
|
||||||
|
| `src/app.ts` | `App` class, handlers (`ontoolinput`, `ontoolresult`, `onhostcontextchanged`, `onteardown`), lifecycle |
|
||||||
|
| `src/server/index.ts` | `registerAppTool`, `registerAppResource`, tool visibility options |
|
||||||
|
| `src/spec.types.ts` | All type definitions: `McpUiHostContext`, CSS variable keys, display modes |
|
||||||
|
| `src/styles.ts` | `applyDocumentTheme`, `applyHostStyleVariables`, `applyHostFonts` |
|
||||||
|
| `src/react/useApp.tsx` | `useApp` hook for React apps |
|
||||||
|
| `src/react/useHostStyles.ts` | `useHostStyles`, `useHostStyleVariables`, `useHostFonts` hooks |
|
||||||
|
|
||||||
|
### Advanced Examples
|
||||||
|
|
||||||
|
| Example | Pattern Demonstrated |
|
||||||
|
|---------|---------------------|
|
||||||
|
| `examples/wiki-explorer-server/` | `callServerTool` for interactive data fetching |
|
||||||
|
| `examples/system-monitor-server/` | Polling pattern with interval management |
|
||||||
|
| `examples/video-resource-server/` | Binary/blob resources |
|
||||||
|
| `examples/sheet-music-server/` | `ontoolinput` - processing tool args before execution completes |
|
||||||
|
| `examples/threejs-server/` | `ontoolinputpartial` - streaming/progressive rendering |
|
||||||
|
| `examples/map-server/` | `updateModelContext` - keeping model informed of UI state |
|
||||||
|
| `examples/transcript-server/` | `updateModelContext` + `sendMessage` - background context updates + user-initiated messages |
|
||||||
|
| `examples/basic-host/` | Reference host implementation using `AppBridge` |
|
||||||
|
|
||||||
|
## Critical Implementation Notes
|
||||||
|
|
||||||
|
### Adding Dependencies
|
||||||
|
|
||||||
|
Use `npm install` to add dependencies rather than manually writing version numbers:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod
|
||||||
|
```
|
||||||
|
|
||||||
|
This lets npm resolve the latest compatible versions. Never specify version numbers from memory.
|
||||||
|
|
||||||
|
### TypeScript Server Execution
|
||||||
|
|
||||||
|
Use `tsx` as a devDependency for running TypeScript server files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install -D tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
"scripts": {
|
||||||
|
"serve": "tsx server.ts"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: The SDK examples use `bun` but generated projects should use `tsx` for broader compatibility.
|
||||||
|
|
||||||
|
### Handler Registration Order
|
||||||
|
|
||||||
|
Register ALL handlers BEFORE calling `app.connect()`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const app = new App({ name: "My App", version: "1.0.0" });
|
||||||
|
|
||||||
|
// Register handlers first
|
||||||
|
app.ontoolinput = (params) => { /* handle input */ };
|
||||||
|
app.ontoolresult = (result) => { /* handle result */ };
|
||||||
|
app.onhostcontextchanged = (ctx) => { /* handle context */ };
|
||||||
|
app.onteardown = async () => { return {}; };
|
||||||
|
|
||||||
|
// Then connect
|
||||||
|
await app.connect();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tool Visibility
|
||||||
|
|
||||||
|
Control who can access tools via `_meta.ui.visibility`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Default: visible to both model and app
|
||||||
|
_meta: { ui: { resourceUri, visibility: ["model", "app"] } }
|
||||||
|
|
||||||
|
// UI-only (hidden from model) - for refresh buttons, form submissions
|
||||||
|
_meta: { ui: { resourceUri, visibility: ["app"] } }
|
||||||
|
|
||||||
|
// Model-only (app cannot call)
|
||||||
|
_meta: { ui: { resourceUri, visibility: ["model"] } }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Host Styling Integration
|
||||||
|
|
||||||
|
**Vanilla JS** - Use helper functions:
|
||||||
|
```typescript
|
||||||
|
import { applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";
|
||||||
|
|
||||||
|
app.onhostcontextchanged = (ctx) => {
|
||||||
|
if (ctx.theme) applyDocumentTheme(ctx.theme);
|
||||||
|
if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
|
||||||
|
if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
**React** - Use hooks:
|
||||||
|
```typescript
|
||||||
|
import { useApp, useHostStyles } from "@modelcontextprotocol/ext-apps/react";
|
||||||
|
|
||||||
|
const { app } = useApp({ appInfo, capabilities, onAppCreated });
|
||||||
|
useHostStyles(app); // Handles theme, styles, fonts automatically
|
||||||
|
```
|
||||||
|
|
||||||
|
### Safe Area Handling
|
||||||
|
|
||||||
|
Always respect `safeAreaInsets`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
app.onhostcontextchanged = (ctx) => {
|
||||||
|
if (ctx.safeAreaInsets) {
|
||||||
|
const { top, right, bottom, left } = ctx.safeAreaInsets;
|
||||||
|
document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Mistakes to Avoid
|
||||||
|
|
||||||
|
1. **Handlers after connect()** - Register ALL handlers BEFORE calling `app.connect()`
|
||||||
|
2. **Missing single-file bundling** - Must use `vite-plugin-singlefile`
|
||||||
|
3. **Forgetting resource registration** - Both tool AND resource must be registered
|
||||||
|
4. **Missing resourceUri link** - Tool must have `_meta.ui.resourceUri`
|
||||||
|
5. **Ignoring safe area insets** - Always handle `ctx.safeAreaInsets`
|
||||||
|
6. **No text fallback** - Always provide `content` array for non-UI hosts
|
||||||
|
7. **Hardcoded styles** - Use host CSS variables for theme integration
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Using basic-host
|
||||||
|
|
||||||
|
Test MCP Apps locally with the basic-host example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1: Build and run your server
|
||||||
|
npm run build && npm run serve
|
||||||
|
|
||||||
|
# Terminal 2: Run basic-host (from cloned repo)
|
||||||
|
cd /tmp/mcp-ext-apps/examples/basic-host
|
||||||
|
npm install
|
||||||
|
SERVERS='["http://localhost:3001/mcp"]' npm run start
|
||||||
|
# Open http://localhost:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
Configure `SERVERS` with a JSON array of your server URLs (default: `http://localhost:3001/mcp`).
|
||||||
|
|
||||||
|
### Debug with sendLog
|
||||||
|
|
||||||
|
Send debug logs to the host application (rather than just the iframe's dev console):
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await app.sendLog({ level: "info", data: "Debug message" });
|
||||||
|
await app.sendLog({ level: "error", data: { error: err.message } });
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue