MCP App Builder
Overview
Create MCP Apps that expose tools with visual React UIs for ChatGPT or Claude. Follow the exact dependency versions and server/UI patterns in
references/mcp-app-spec.md.
Workflow
- 1. Clarify requirements: what data to visualize, UI pattern (card, table, chart, dashboard, form), data source, and how many tools (start with 1-2).
- Design tools and UI mapping: define tool names, zod input schemas, output shape, and UI resource URIs (
ui://.../app.html). Map each tool to one React entrypoint and one HTML file. - Scaffold the project: start from
assets/mcp-app-template/ when possible, then customize tool names, schemas, and UI. Ensure package.json uses the exact versions, plus tsconfig.json, vite.config.ts, Tailwind + PostCSS, and per-tool build scripts. - Implement the server: use
registerAppTool/registerAppResource, zod schemas directly, createServer() factory per request, and createMcpExpressApp with app.all("/mcp", ...). - Implement the UI: use
useApp + useHostStyles, parse tool results, handle loading/error/empty states, and apply safe-area insets. - Build and test: run
npm run build, then npm run serve, then verify via a tunnel if needed.
Hard Requirements
- - Use the exact dependency versions listed in
references/mcp-app-spec.md. - Use
registerAppTool/registerAppResource and zod schemas directly (not JSON Schema objects). - Create a new
McpServer instance per request via createServer(). - Use
createMcpExpressApp and app.all("/mcp", ...). - Bundle UI into single-file HTML via
vite-plugin-singlefile. - Use host CSS variables for theme compatibility.
References
- -
references/mcp-app-spec.md (authoritative spec, patterns, code templates, gotchas)
Assets
- -
assets/mcp-app-template/ (ready-to-copy MCP App skeleton with one tool + UI)
MCP App Builder
概述
创建MCP应用，为ChatGPT或Claude提供带有可视化React UI的工具。严格遵循references/mcp-app-spec.md中的依赖版本和服务器/UI模式。
工作流程
- 1. 明确需求：需要可视化的数据、UI模式（卡片、表格、图表、仪表盘、表单）、数据源以及工具数量（从1-2个开始）。
- 设计工具和UI映射：定义工具名称、zod输入模式、输出形状以及UI资源URI（ui://.../app.html）。将每个工具映射到一个React入口点和一个HTML文件。
- 搭建项目结构：尽可能从assets/mcp-app-template/开始，然后自定义工具名称、模式和UI。确保package.json使用精确版本，以及tsconfig.json、vite.config.ts、Tailwind + PostCSS和每个工具的构建脚本。
- 实现服务器：直接使用registerAppTool/registerAppResource、zod模式、每个请求使用createServer()工厂方法，以及使用app.all(/mcp, ...)的createMcpExpressApp。
- 实现UI：使用useApp + useHostStyles，解析工具结果，处理加载/错误/空状态，并应用安全区域边距。
- 构建和测试：运行npm run build，然后npm run serve，必要时通过隧道进行验证。
硬性要求
- - 使用references/mcp-app-spec.md中列出的精确依赖版本。
- 直接使用registerAppTool/registerAppResource和zod模式（而非JSON Schema对象）。
- 通过createServer()为每个请求创建新的McpServer实例。
- 使用createMcpExpressApp和app.all(/mcp, ...)。
- 通过vite-plugin-singlefile将UI打包为单文件HTML。
- 使用宿主CSS变量实现主题兼容性。
参考
- - references/mcp-app-spec.md（权威规范、模式、代码模板、注意事项）
资源
- - assets/mcp-app-template/（可直接复制的MCP应用骨架，包含一个工具和UI）
