鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

create-mcp-app

提供构建运行在 MCP 主机(如 Claude Desktop)中的交互式应用的能力,支持将工具逻辑与 HTML UI 资源绑定,实现数据驱动的动态界面渲染,并涵盖生命周期管理、主题适配、安全区处理、流式输入响应及显示模式切换等完整开发实践。

文档处理商业与营销软件开发
访问 GitHub
文档Skills.MD
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
▼
text
复制代码
Host calls tool → Server returns result → Host renders resource UI → UI receives result

Quick Start Decision Tree

Framework Selection

FrameworkSDK SupportBest For
ReactuseApp hook providedTeams familiar with React
Vanilla JSManual lifecycleSimple apps, no build complexity
Vue/Svelte/Preact/SolidManual lifecycleFramework 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}/:

TemplateKey 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 /tmp/mcp-ext-apps/src/:

FileContents
src/app.tsApp class, handlers (ontoolinput, ontoolresult, onhostcontextchanged, onteardown), lifecycle
src/server/index.tsregisterAppTool, registerAppResource, tool visibility options
src/spec.types.tsAll type definitions: McpUiHostContext, CSS variable keys, display modes
src/styles.tsapplyDocumentTheme, applyHostStyleVariables, applyHostFonts
src/react/useApp.tsxuseApp hook for React apps
src/react/useHostStyles.tsuseHostStyles, useHostStyleVariables, useHostFonts hooks

Advanced Examples

ExamplePattern Demonstrated
examples/shadertoy-server/Streaming partial input + visibility-based pause/play (best practice for large inputs)
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); // Injects CSS variables to document, making var(--*) available

Using variables in CSS - After applying, use var():

▼
css
复制代码
.container { background: var(--color-background-secondary); color: var(--color-text-primary); font-family: var(--font-sans); border-radius: var(--border-radius-md); } .code { font-family: var(--font-mono); font-size: var(--font-text-sm-size); line-height: var(--font-text-sm-line-height); color: var(--color-text-secondary); } .heading { font-size: var(--font-heading-lg-size); font-weight: var(--font-weight-semibold); }

Key variable groups: --color-background-*, --color-text-*, --color-border-*, --font-sans, --font-mono, --font-text-*-size, --font-heading-*-size, --border-radius-*. See src/spec.types.ts for full list.

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`; } };

Streaming Partial Input

For large tool inputs, use ontoolinputpartial to show progress during LLM generation. The partial JSON is healed (always valid), enabling progressive UI updates.

Spec: ui/notifications/tool-input-partial

▼
typescript
复制代码
app.ontoolinputpartial = (params) => { const args = params.arguments; // Healed partial JSON - always valid, fields appear as generated // Use args directly for progressive rendering }; app.ontoolinput = (params) => { // Final complete input - switch from preview to full render };

Use cases:

PatternExample
Code previewShow streaming code in <pre>, render on complete (examples/shadertoy-server/)
Progressive formFill form fields as they stream in
Live chartAdd data points to chart as array grows
Partial renderRender incomplete structured data (tables, lists, trees)

Simple pattern (code preview):

▼
typescript
复制代码
app.ontoolinputpartial = (params) => { codePreview.textContent = params.arguments?.code ?? ""; codePreview.style.display = "block"; canvas.style.display = "none"; }; app.ontoolinput = (params) => { codePreview.style.display = "none"; canvas.style.display = "block"; render(params.arguments); };

Visibility-Based Resource Management

Pause expensive operations (animations, WebGL, polling) when widget scrolls out of viewport:

▼
typescript
复制代码
const observer = new IntersectionObserver((entries) => { entries.forEach((entry) => { if (entry.isIntersecting) { animation.play(); // or: startPolling(), shaderToy.play() } else { animation.pause(); // or: stopPolling(), shaderToy.pause() } }); }); observer.observe(document.querySelector(".main"));

Fullscreen Mode

Request fullscreen via app.requestDisplayMode(). Check availability in host context:

▼
typescript
复制代码
let currentMode: "inline" | "fullscreen" = "inline"; app.onhostcontextchanged = (ctx) => { // Check if fullscreen available if (ctx.availableDisplayModes?.includes("fullscreen")) { fullscreenBtn.style.display = "block"; } // Track current mode if (ctx.displayMode) { currentMode = ctx.displayMode; container.classList.toggle("fullscreen", currentMode === "fullscreen"); } }; async function toggleFullscreen() { const newMode = currentMode === "fullscreen" ? "inline" : "fullscreen"; const result = await app.requestDisplayMode({ mode: newMode }); currentMode = result.mode; }

CSS pattern - Remove border radius in fullscreen:

▼
css
复制代码
.main { border-radius: var(--border-radius-lg); overflow: hidden; } .main.fullscreen { border-radius: 0; }

See examples/shadertoy-server/ for complete implementation.

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
  8. No streaming for large inputs - Use ontoolinputpartial to show progress during generation

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 } });
文档处理
商业与营销
软件开发

快捷安装

复制到终端去安装 Skill

npxskillsaddmodelcontextprotocol/ext-apps--skill"create-mcp-app"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。