Apigene MCP Apps Templates

MCP应用程序

 ](https://www.npmjs.com/package/@apigene/mcp-app-playground) ](https://nodejs.org) 

______________________________________________________________________

什么是MCP应用程序游乐场？

MCP应用程序游乐场 是一个集合 数十个模拟MCP应用程序示例 灵感来自现实世界的服务（GitHub、Slack、谷歌分析、Shopify、Datadog等等）。每个示例都是一个小型、自包含的UI，展示了如何构建 MCP应用程序 --一个交互式HTML/TypeScript/CSS组件，在Claude和其他AI主机的iframe内运行，并显示工具结果。

使用此仓库 了解MCP应用程序是如何实现的 并到 模拟和评估 他们在当地。它与 一台MCP服务器 你可以在你的机器上运行：将你的AI客户端（例如Claude、Cursor）指向它，调用演示工具，看看应用程序是如何呈现和表现的——不需要先构建自己的服务器或真正的集成。

快速开始

运行Playground（立即预览任何模板）

无克隆（来自任何地方）：

npx @apigene/mcp-app-playground

打开：

• MCP应用游乐场 在 http://localhost:4311 --使用模拟数据预览模板
• MCP HTTP端点 在 http://localhost:3001/mcp --用于完全主机集成

从仓库（克隆后）：

cd mcp-apps
npm install
npm start

创建新模板

# Copy the base template
cp -r examples/base-template examples/my-app
cd examples/my-app
npm install
npm run build
# Output: dist/mcp-app.html (single-file bundle)

然后打开 examples/my-app/src/mcp-app.ts 并实施 renderData().

______________________________________________________________________

模板示例

______________________________________________________________________

基础模板

examples/base-template

所有MCP应用程序的单一基础模板。它使用官方 @modelcontextprotocol/ext-apps SDK（主题、字体、主机样式）和构建到单个 dist/mcp-app.html 通过快速。

包括： 暗模式、响应式布局、主机上下文（主题/字体/显示模式）、工具结果/取消/拆卸处理。

cd examples/base-template
npm install && npm run build

看 examples/base-template/README.md 用于SDK使用、事件处理程序和自定义。有关内容安全策略（例如外部脚本/字体），请参阅 examples/base-template/CSP_GUIDE.md.

______________________________________________________________________

模板架构

每个MCP应用程序模板都遵循相同的合同（来自 examples/base-template):

my-app/
├── mcp-app.html          # Entry point (loads CSS and TS module for dev)
├── src/
│   ├── mcp-app.ts        # ★ Implement renderData() here; SDK + handlers
│   ├── mcp-app.css       # App-specific styles
│   └── global.css        # Shared base styles (do not modify)
├── package.json          # Scripts: build, dev; deps: @modelcontextprotocol/ext-apps
├── vite.config.ts        # Vite + single-file output
├── response.json         # Optional: mock payload for playground preview
└── dist/
    └── mcp-app.html      # Built single-file bundle (npm run build)

关键定制点 src/mcp-app.ts

模板使用SDK App 并在之前注册处理程序 app.connect(): app.ontoolresult, app.onhostcontextchanged, app.ontoolcancelled, app.onteardown等等。看 examples/base-template/README.md 查看完整列表。

MCP协议（SDK下）

______________________________________________________________________

CLI参考

npx @apigene/mcp-app-playground                 # Start playground + MCP server
npx @apigene/mcp-app-playground start           # Same as above
npx @apigene/mcp-app-playground lab             # Playground only
npx @apigene/mcp-app-playground mcp http        # MCP HTTP server only
npx @apigene/mcp-app-playground mcp stdio       # MCP stdio transport
npx @apigene/mcp-app-playground list            # List all examples
npx @apigene/mcp-app-playground build           # Build all examples

从repo根目录：

npm run dev              # Start playground + MCP server
npm run lab              # Playground only
npm run mcp:http         # MCP HTTP server only
npm run mcp:stdio        # MCP stdio transport
npm run build:examples   # Build all examples
npm run list             # List all examples

______________________________________________________________________

发展

先决条件

• Node.js≥18（建议使用节点22——请参阅 .nvmrc)
• npm

设置

git clone https://github.com/apigene/mcp-apps.git
cd mcp-apps
npm install
npm run dev

创建模板（逐步）

1. 复制基础模板

   cp -r examples/base-template examples/my-service-my-tool
   cd examples/my-service-my-tool

1. 安装和构建

   npm install
   npm run build

1. 设置应用元数据 在 src/mcp-app.ts:

   const APP_NAME = "my-service-my-tool";
   const APP_VERSION = "1.0.0";

1. 实施 renderData() 根据工具的响应形状：

   function renderData(data: any): void {
     const items = unwrapData(data);
     const app = document.getElementById("app")!;
     app.innerHTML = items.map((item: any) => `
       

         
${escapeHtml(item.title)}

         
${escapeHtml(item.description)}

       

     `).join("");
   }

1. 添加 response.json -用于本地预览的真实API响应：

   { "results": [{ "title": "Example", "description": "Test item" }] }

1. 预览 在操场上：

   cd ../..
   npm run lab
   # Open http://localhost:4311 and select your template

惯例

• 从不修改 src/global.css --这是共享基地
• 始终通过以下方式支持黑暗模式 body.dark CSS类
• 始终使用以下方式转义用户数据 escapeHtml()
• 调用前注册SDK事件处理程序 app.connect()
• 清理资源 app.onteardown
• 仅系统字体——不导入外部字体（或根据 CSP_GUIDE.md)
• 当前协议版本： 2026-01-26

______________________________________________________________________

与游标/AI代理一起使用

这 docs/ 文件夹包含针对AI辅助开发优化的提示：

• docs/CURSOR_PROMPT_MCP_APP_SIMPLE.md --从response.json创建模板
• docs/CURSOR_PROMPT_MCP_APP_FROM_OPENAPI.md --从OpenAPI规范生成模板

每个示例还包含 AGENTS.md 在编码代理特定的指导下。

______________________________________________________________________

贡献

欢迎投稿！看 贡献.md 作为指导方针。

贡献方式：

• 为API/服务添加新的示例模板
• 改进基础模板或游乐场工具
• 修复错误或改进文档
• 通过PR分享您的自定义模板

______________________________________________________________________

许可证

麻省理工学院 © 芹菜素