MCP应用游乐场
一个用于学习和尝试MCP应用程序的多应用程序游乐场。从一个存储库构建、测试和部署多个交互式MCP应用程序-适用于两者 ChatGPT 和 克劳德桌面.
🎮 这是什么？
这是一个演示MCP（模型上下文协议）应用程序架构的学习游乐场。您可以构建并运行一个应用程序，而不仅仅是一个 多个应用程序 独立或共同 ChatGPT 和 克劳德桌面，使尝试不同的工具和UI模式变得容易。
目前包括：
- 🔊 Echo应用程序 -带有字符/单词计数的文本回声（紫色渐变UI）
- 🧮 计算器应用程序 -算术运算：加、减、乘、除（蓝/绿渐变UI）
- 🏥 霍斯皮副驾驶 -生产就绪的多语言（EN/NL/FR）住院旅程，包括下拉菜单、日期选择器、保险数据、验证（医疗保健UI）
- 📄 PDF生成器 -服务器端PDF生成，具有多个模板、画布渲染和可下载输出（紫色渐变UI）
- 📁 文件处理器 -具有验证、幻数验证和分析功能的安全文件上传（紫色渐变UI）
- 📦 应用模板 -在大约5分钟内创建新应用程序的脚手架
- 🌐 双平台 -同样的应用程序可以在ChatGPT和Claude Desktop上运行
- ✅ ChatGPT就绪 -所有应用程序都包含CSP和用于应用程序提交的域配置
🎯 目的
了解如何使用适用于ChatGPT和Claude Desktop的现代MCP apps SDK（2026年1月）构建MCP应用程序：
- 具有共享基础设施的多应用程序架构
- MCP服务器实现与工具注册
- iframe中的UI组件通过JSON-RPC进行通信
- 三部分响应架构（结构化内容、内容、\_meta）
- 单文件HTML捆绑，简化部署
- 应用脚手架和自动化
🏗️ 建筑
双平台设计：
ChatGPT (HTTP) ┐
├──→ MCP Server ←→ UI Component (iframe)
Claude (STDIO) ┘ ↓ ↓
JSON-RPC ────────→ App Bridge
(postMessage)关键部件：
- 应用 -独立的MCP应用程序（回声、计算器等）
- 基础设施 -共享、可重用的MCP服务器代码（HTTP+STDIO传输）
- 脚本 -构建、运行和创建应用程序的自动化
- 统一标准 -相同的代码库在ChatGPT和Claude Desktop上都有效
🚀 快速开始
先决条件
对于ChatGPT：
- Node.js 18+（项目使用v24.8.0，通过锁定
.nvmrc) - npm 7+
- ngrok（安装：
brew install ngrok/ngrok/ngrok) - 启用开发者模式的ChatGPT Plus/Pro
对于Claude Desktop：
- Node.js 18+
- npm 7+
- 已安装Claude Desktop(下载)
- Claude Pro、团队或企业订阅
安装
# Clone the repository
git clone https://github.com/januxprobe/mcp-apps-playground.git
cd mcp-apps-playground
# Use correct Node.js version (if using nvm)
nvm use
# Install dependencies
npm install选择您的平台
选项1:ChatGPT（HTTP模式）
启动计算器应用程序：
./scripts/start-app.sh calculator此脚本将：
- ✅ 构建应用程序
- ✅ 在端口3001上启动MCP服务器
- ✅ 自动启动ngrok隧道
- ✅ 显示ChatGPT配置URL
然后：
- 从输出中复制ngrok URL
- 打开ChatGPT→ 设置→ 连接器→ 创建
- 输入脚本输出中显示的详细信息
- 开始聊天并尝试应用程序的工具！
停止： 按 Ctrl+C 或奔跑 ./scripts/stop-app.sh
______________________________________________________________________
选项2：克劳德桌面（STDIO模式）
为Claude Desktop配置所有应用程序：
./scripts/claude-desktop-config.sh然后：
- 完全重新启动克劳德桌面 （退出并重新打开）
- 打开连接器面板（锤子图标）
- 验证应用程序是否出现：
echo,calculator - 开始聊天并尝试应用程序！
______________________________________________________________________
示例提示（两个平台）：
- 计算器：
"Add 15 and 27"或"Divide 100 by 5" - 回声：
"Echo back 'Hello from my playground!'"
🌐 平台支持
这个游乐场支持 ChatGPT和克劳德桌面 使用MCP Apps统一标准。相同的应用程序可以在两个平台上运行，无需更改代码。
ChatGPT（HTTP模式-默认）
通过ngrok隧道运行应用程序以访问ChatGPT：
./scripts/start-app.sh echo这提供了：
- 通过ngrok公共URL进行远程访问
- 用于调试的服务器日志
设置：
- 运行启动脚本
- 从输出中复制ngrok URL
- 在ChatGPT设置中配置连接器→ 连接器
- 开始在对话中使用该应用程序
克劳德桌面（STDIO模式）
将应用程序配置为Claude Desktop的本地MCP服务器：
./scripts/claude-desktop-config.sh这将：
- ✅ 构建所有可用应用程序
- ✅ 备份现有的Claude桌面配置
- ✅ 将应用程序添加到
claude_desktop_config.json - ✅ 验证配置
然后：
- 完全重新启动克劳德桌面 （退出并重新打开）
- 打开连接器面板（锤子图标）
- 验证应用程序是否出现：
echo,calculator,hospi-copilot - 对话中的测试
测试提示：
- 回声：
"Echo back 'Hello Claude!'" - 计算器：
"What is 42 times 17?" - 霍斯皮副驾驶：
"Start a hospital admission for myself"
要求：
- 已安装Claude Desktop(在这里下载)
- Claude Pro、团队或企业订阅（MCP应用程序功能）
平台比较
| 功能 | ChatGPT | Claude桌面 |
|---|---|---|
| 运输 | HTTP（远程） | STDIO（本地子进程） |
| 设置 | 一次性ngrok配置 | JSON配置文件 |
| 发展 | 使用监视模式进行热重新加载 | 需要重建+重新启动 |
| 调试 | 服务器日志+ngrok检查器 | 仅限stderr日志 |
| 连接 | 需要公共互联网 | 仅限本地进程 |
| 演出 | 网络延迟 | 近乎即时 |
| 安全 | 通过ngrok隧道 | 孤立的局部过程 |
验证
检查Claude Desktop是否配置正确：
./scripts/verify-claude-desktop.sh这验证了：
- Claude桌面安装
- 配置文件有效性
- 应用程序文件存在
- 构建工件
- STDIO模式功能
🎮 可用应用程序
🔊 Echo应用程序
简单的文本回声与元数据显示。
工具：
echo-用字符和字数对文本进行回声处理
特征：
- 紫色渐变UI
- 字符和字数
- 时间戳显示
- “再次回声”交互式按钮
开始： ./scripts/start-app.sh echo
______________________________________________________________________
🧮 计算器应用程序
具有交互式UI的基本算术运算。
工具：
add-加两个数字subtract-减去两个数字multiply-将两个数字相乘divide-将两个数字除（使用零除法处理）
特征：
- 蓝/绿渐变UI
- 带方程式的操作显示
- 每个操作的交互式按钮
- 错误处理
开始： ./scripts/start-app.sh calculator
______________________________________________________________________
🏥 霍斯皮副驾驶
具有专业用户体验的保险申报生产就绪住院旅行助理。
工具：
hospital_journey-引导用户完成7步入场流程
特征：
- 专业医疗保险UI（蓝/绿主题）
- 多语言支持 -英语、荷兰语（荷兰语）或法语（法语）的完整用户界面，具有自动语言检测功能
- 医院下拉列表 -15家比利时医院，提供定制选项
- 日期选取器 -带约束的HTML5日期输入（从今天到+1年）
- 完整的保险演示数据 -会员号、保险明细、第三方支付信息
- 进度指示器 -可视化进度条显示“第X步，共5步”
- 输入验证 -带有错误消息的实时验证
- 工具提示 -保险条款说明
- 返回导航 -在保留状态的同时向后导航
- 具有数据累积功能的状态机
- 演示数据生成：
- 申报ID（HSP-XXXXXXX格式） - 比利时NISS风格会员编号 - 覆盖率徽章（100%或75%） - 第三方付款详细信息 - 事先授权标志 - 附加注释和说明
旅程步骤：
- 选择成员 -患者姓名（可能时根据上下文自动填写）
- 医院选择 -与15家比利时医院或海关入境
- 入场详情 -日期选择器、原因、事故复选框
- 房型 -多人（100%覆盖）、单人（75%）或日间入场
- 审查 -完整的保险数据，包括保险范围徽章和付款详情
- 已提交 -申报ID和全额保险确认
开始： ./scripts/start-app.sh hospi-copilot
示例提示（任何语言）：
- 中文：“自己开始住院”
- 荷兰语：“开始为自己住院”
- 法语：“为自己开始住院”
- “我需要申报在鲁汶大学住院”
- “膝盖手术住院”
______________________________________________________________________
📄 PDF生成器
使用服务器端渲染和交互式预览从模板生成专业PDF文档。
工具：
generate_pdf-从模板和数据创建PDF
特征：
- 服务器端PDF生成 使用pdfkit
- 多个模板 -简单的文档和发票布局
- PDF.js画布渲染 -使用页面导航查看PDF
- 多页支持 -上一页/下一页导航按钮
- 下载工作流程 -将blob URL复制到浏览器以查看/下载
- 文件元数据显示 -文件名、大小、模板信息
- Base64数据传输 -将PDF安全地传递到小部件
- 符合CSP标准 -从CDN加载PDF.js worker
模板：
- 简单 -带有标题、内容和页脚的基本文档
- 发票 -带有金额和总计计算的行项目
开始： ./scripts/start-app.sh pdf-generator
示例提示：
- “生成一个名为“会议笔记”的简单PDF，内容为“讨论了第四季度目标”
- “为项目XYZ创建包含3个项目的发票PDF”
- “生成一个名为“报告”的PDF文档，其中包含一些示例文本”
注： 目前在ChatGPT中工作。Claude Desktop支持正在调查中（请参阅 apps/pdf-generator/docs/KNOWN_ISSUES.md).
______________________________________________________________________
📁 文件处理器
通过全面的验证和分析，确保文件上传和处理的安全性。
工具：
process_file-验证和处理上传的文件
特征：
- 安全文件验证 -MIME类型和幻数验证
- 支持多种文件格式 -图像（PNG、JPEG、GIF）、PDF、文本文件、CSV、JSON
- 幻数检测 -15+文件签名模式，防止文件类型欺骗
- 拖放上传 -带有拖动事件的现代HTML5文件API
- 三个处理操作:
- 分析 -具有特定类型见解的完整文件分析 - 验证 -仅限安全检查 - 元数据 -提取文件信息、大小、校验和
- SHA-256校验和 -内容完整性验证
- 文件名清理 -防止路径遍历，删除不安全字符
- 文件大小限制 -可配置的最大大小（默认为10MB）
- Base64传输 -安全的文件内容交付
- 实时反馈 -加载状态、错误消息、成功指示器
安全措施：
- ✅ 根据白名单进行MIME类型验证
- ✅ 幻数验证（实际文件签名）
- ✅ 文件大小限制强制执行
- ✅ 文件名净化（无路径遍历，空字节）
- ✅ 通过SHA-256实现内容完整性
- ✅ 无服务器端文件存储
开始： ./scripts/start-app.sh file-processor
示例提示：
- “处理此图像文件”（然后通过拖放上传）
- “验证我的PDF文档”（从文件选择器中选择）
- “分析此文本文件并向我显示元数据”
文档： 看 apps/file-processor/docs/file-upload-patterns.md 以获取全面的实施指南。
注： 目前在ChatGPT中工作。Claude Desktop支持正在调查中（请参阅 apps/file-processor/docs/KNOWN_ISSUES.md).
______________________________________________________________________
🛠️ 创建自己的应用程序
快速方法（5分钟）
./scripts/new-app.sh myapp这将：
- 将模板复制到
apps/myapp/ - 提示输入应用程序详细信息（名称、工具名称等）
- 自动替换所有占位符
- 将构建脚本添加到
package.json - 创建可自定义的工作骨架
然后：
- 编辑
apps/myapp/server.ts-实现您的工具逻辑 - 编辑
apps/myapp/widget/myapp-widget.html-设计你的用户界面 - 编辑
apps/myapp/widget/myapp-widget.ts-添加UI逻辑 - 测试：
./scripts/start-app.sh myapp
手动方法
请参阅模板文档： apps/_template/README.md
📁 项目结构
mcp-apps-playground/
├── docs/ # General documentation
│ └── CLAUDE_DESKTOP_COMPATIBILITY.md
├── apps/ # All applications
│ ├── echo/
│ │ ├── server.ts # Echo MCP server
│ │ ├── standalone.ts # Entry point
│ │ ├── docs/ # Echo-specific docs
│ │ └── widget/
│ │ ├── echo-widget.html
│ │ └── echo-widget.ts
│ ├── calculator/
│ │ ├── server.ts # Calculator MCP server
│ │ ├── standalone.ts
│ │ ├── docs/ # Calculator-specific docs
│ │ └── widget/
│ │ ├── calculator-widget.html
│ │ └── calculator-widget.ts
│ ├── hospi-copilot/
│ │ ├── server.ts # Hospitalization journey MCP server
│ │ ├── standalone.ts
│ │ ├── docs/ # Hospi-specific docs
│ │ └── widget/
│ │ ├── hospi-copilot-widget.html
│ │ └── hospi-copilot-widget.ts
│ ├── pdf-generator/
│ │ ├── server.ts # PDF generation MCP server
│ │ ├── standalone.ts
│ │ ├── docs/ # PDF generator-specific docs
│ │ │ └── KNOWN_ISSUES.md # Claude Desktop compatibility notes
│ │ └── widget/
│ │ ├── pdf-generator-widget.html
│ │ └── pdf-generator-widget.ts
│ ├── file-processor/
│ │ ├── server.ts # File upload/processing MCP server
│ │ ├── standalone.ts
│ │ ├── docs/ # File processor-specific docs
│ │ │ └── file-upload-patterns.md # Complete file upload guide
│ │ ├── tests/ # File handling tests
│ │ │ └── file-handling.test.ts
│ │ └── widget/
│ │ ├── file-processor-widget.html
│ │ └── file-processor-widget.ts
│ └── _template/ # Template for new apps
│ ├── README.md
│ ├── server.ts.template
│ ├── standalone.ts.template
│ └── widget/
├── infrastructure/ # Shared infrastructure
│ └── server/
│ ├── main.ts # Generic HTTP/STDIO server
│ ├── types.ts # TypeScript interfaces
│ ├── i18n.ts # Internationalization utilities
│ └── utils/
│ └── file-handling.ts # File upload & validation utilities
├── scripts/
│ ├── start-app.sh # Start any app
│ ├── new-app.sh # Create new app
│ ├── build-app.sh # Build specific app
│ └── stop-app.sh # Stop all services
├── dist/ # Build output
│ ├── infrastructure/
│ ├── echo/
│ ├── calculator/
│ ├── hospi-copilot/
│ └── pdf-generator/
├── vite.app.config.ts # Widget build config
├── tsconfig.json # Base TypeScript config
├── tsconfig.app.json # App compilation
├── tsconfig.infrastructure.json # Infrastructure compilation
└── package.json # Dependencies and scripts🛠️ 发展
构建命令
npm run build # Build all apps + infrastructure
npm run build:echo # Build echo app only
npm run build:calculator # Build calculator app only
npm run build:hospi-copilot # Build hospi-copilot app only
npm run build:pdf-generator # Build pdf-generator app only
npm run build:file-processor # Build file-processor app only
npm run build:infrastructure # Build infrastructure only开发模式（仅限本地开发，不适用于ChatGPT）
⚠️ 这些命令在监视模式下运行vite，这会产生大量未统一的构建（2MB+）。使用 ./scripts/start-app.sh 用于ChatGPT测试。npm run start:echo # Echo app dev mode (hot reload)
npm run start:calculator # Calculator app dev mode (hot reload)
npm run start:hospi-copilot # Hospi-copilot app dev mode (hot reload)
npm run start:pdf-generator # PDF generator app dev mode (hot reload)
npm run start:file-processor # File processor app dev mode (hot reload)MCP检验员测试
npm run inspector:echo # Test echo with MCP Inspector
npm run inspector:calculator # Test calculator with MCP Inspector
npm run inspector:hospi-copilot # Test hospi-copilot with MCP Inspector
npm run inspector:pdf-generator # Test pdf-generator with MCP Inspector
npm run inspector:file-processor # Test file-processor with MCP Inspector⚠️ 注： MCP Inspector对带有UI组件的MCP应用程序的支持有限。要进行全面测试，请通过ngrok使用ChatGPT。
脚本
./scripts/start-app.sh # Start app with ngrok
./scripts/build-app.sh # Build specific app
./scripts/new-app.sh # Create new app from template
./scripts/stop-app.sh # Stop all services🔑 关键概念
多应用架构
每个应用程序都是 独立的 有自己的：
server.ts-带工具注册的MCP服务器standalone.ts-独立跑步的切入点widget/-UI组件（HTML+TypeScript）
应用程序共享 基础设施:
- 通用HTTP/STDIO传输(
infrastructure/server/main.ts) - 类型定义(
infrastructure/server/types.ts) - 国际化实用程序(
infrastructure/server/i18n.ts) - 构建系统（Vite、TypeScript配置）
多语言支持
构建自动适应用户语言的应用程序：
// Server-side: Add language parameter to tool schema
language: z.enum(["en", "nl", "fr"]).optional().default("en")
.describe("Detect from user's prompt language")
// Widget-side: Use translations
const TRANSLATIONS = {
en: { welcome: "Welcome" },
nl: { welcome: "Welkom" },
fr: { welcome: "Bienvenue" },
};特征：
- LLM根据用户提示自动检测语言
- 可重复使用的实用程序
infrastructure/server/i18n.ts - 模板包括注释的多语言示例
- 完整示例：
apps/hospi-copilot
无单独清单
现代MCP应用程序不使用清单文件。UI链接嵌入在工具定义中：
_meta: { ui: { resourceUri: "ui://calculator/widget.html" } }三部分回应
工具处理程序返回：
structuredContent-数据用于 两者 模型和UI（保证到达小部件）content-模型的可选叙述_meta-仅UI数据（可能无法通过ChatGPT传递）
重要提示： 始终将关键数据放入 structuredContent，不仅 _meta!
单个HTML捆绑包
Vite与 vite-plugin-singlefile 将HTML、CSS和JavaScript捆绑到一个文件中，以简化部署。
安全与提交（CSP）
所有应用程序都是 ChatGPT提交就绪 使用内容安全策略（CSP）和域配置：
_meta: {
ui: {
domain: "app-unique-id", // Unique identifier for sandboxing
csp: {
connectDomains: [], // External API domains
resourceDomains: [], // External asset domains (CDN, fonts, images)
}
}
}当前应用程序状态：
- ✅ 回声 -域名：
echo-mcp-app独立式CSP - ✅ 计算器 -域名：
calculator-mcp-app独立式CSP - ✅ 副驾驶 -域名：
hospi-copilot独立式CSP - ✅ pdf生成器 -域名：
pdf-generator，用于PDF.js worker的CDN CSP - ✅ 文件处理机 -域名：
file-processor独立式CSP - ✅ 经过测试和验证 -ChatGPT中没有CSP警告
所有应用程序都使用自包含的CSP（空数组），因为Vite捆绑了资产。看 CLAUDE.md 获取详细的CSP文档。
🔧 故障排除
端口已在使用中
lsof -ti:3001 | xargs kill -9或者使用停止脚本：
./scripts/stop-app.shSTDIO模式记录
在STDIO模式下， stdout 保留用于JSON-RPC通信。所有日志记录必须使用 console.error() （stderr）而不是 console.log().
小部件未更新
更改UI代码后：
- 重建：
npm run build: - 重新启动服务器
- 刷新ChatGPT设置中的连接器 获取更改
MCP检查员问题
如果您遇到“沙盒未加载”错误或小部件无限期显示“正在加载…”：
- 这是MCP应用程序中MCP检查器的一个已知限制
- 通过ngrok使用ChatGPT进行全面测试
浏览器扩展
像Grammarly这样的浏览器扩展可能会干扰JSON-RPC验证。在浏览器中测试小部件时禁用扩展。
Claude桌面问题
未出现在连接器面板中的应用程序：
- 验证配置语法：
jq . ~/Library/Application\ Support/Claude/claude_desktop_config.json - 检查到的绝对路径
.ts文件正确 - 完全重新启动克劳德桌面 （退出并重新打开，而不仅仅是刷新）
- 确保Claude Pro/团队/企业订阅（MCP应用程序需要付费计划）
工具执行但小部件不呈现：
- 验证小部件是否已构建：
ls dist/echo/widget/ - 检查小部件HTML文件是否存在且不为空
- 在Claude Desktop日志中查找控制台错误
- 确保使用最新的Claude Desktop版本
STDIO错误或连接失败：
- 验证
tsx可用：npx -y tsx --version - 检查Node.js版本：
node -v（应该是18+） - 确保
--stdio标志存在于配置参数中 - 使用以下工具查看启动日志：
./scripts/verify-claude-desktop.sh
配置问题：
- 还原备份：
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json.backup-* ~/Library/Application\ Support/Claude/claude_desktop_config.json - 重新生成配置：
./scripts/claude-desktop-config.sh - 验证JSON：
jq . ~/Library/Application\ Support/Claude/claude_desktop_config.json
平台间测试：
如果一个应用程序可以在ChatGPT上运行，但不能在Claude Desktop上运行：
- 使用检查器测试STDIO模式：
npm run inspector:echo - 检查stdout日志记录（必须使用
console.error()仅） - 验证小部件是否作为单个HTML文件加载
- 将行为与验证脚本进行比较
📚 资源
💡 示例与灵感
正在为您的下一个应用程序寻找想法？尝试构建：
- 🌤️ 天气应用程序 -获取各地点的天气信息
- 📝 记录员 -保存和检索笔记
- 🎲 摇骰子 -带有自定义规则的RPG骰子
- 📊 数据可视化工具 -数据图表
- 🔍 搜索工具 -使用过滤器进行自定义搜索
- 🎨 颜色选择器 -配色方案生成器
- 📅 日历助手 -日期计算
- 🔢 单元转换器 -单位间转换
使用 ./scripts/new-app.sh 开始吧！
📝 许可证
麻省理工学院
🤝 贡献
这是一个学习项目-请随意分叉和实验！欢迎拉取请求。
🙏 致谢
内置：
- MCP-SDK -模型上下文协议
- 维特 -快速构建工具
- TypeScript -类型安全
- 快速 -HTTP服务器
- 佐德 -架构验证