🤖 全栈MCP（多角色玩家）游乐场
使用模型上下文协议（MCP）和Claude作为大型语言模型（LLM）引擎，构建端到端的全栈AI应用。
一个可直接投入生产的模板，具有 针对MCP服务器的微服务架构其中，每个服务器都提供了专门的工具，供AI代理使用。前端则作为 MCP 主机协调多台服务器，并提供由Claude驱动的聊天界面。
从本地环境到生产环境——像黑客一样构建
______________________________________________________________________
🧠 概述
这是一个 用于构建AI驱动应用的全栈模板 使用 模型上下文协议（MCP）它展示了如何：
- 创建多个MCP服务器 作为微服务（数据库、文件、自定义工具）
- 构建一个MCP主机 （前端）连接到多个服务器
- 集成Claude AI 消耗来自所有连接服务器的工具
- 水平扩展 通过添加新的MCP服务器而无需修改现有代码
建筑
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js) = MCP HOST │
│ • UI (Chat, Server Management) │
│ • MCP Orchestrator (connects to multiple servers) │
│ • Claude Client (consumes tools from all servers) │
└─────────────────────────────────────────────────────────────┘
↕ ↕ ↕
[HTTPS/SSE] [HTTPS/SSE] [HTTPS/SSE]
↕ ↕ ↕
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ MCP Server │ │ MCP Server │ │ MCP Server │
│ CORE │ │ DATABASE │ │ FILES │
│ (health, │ │ (query, │ │ (read, │
│ metrics, │ │ insert, │ │ write, │
│ config) │ │ schema) │ │ list) │
└──────────────┘ └──────────────┘ └──────────────┘______________________________________________________________________
🚀 快速入门
1. 前提条件
- Docker & Docker Compose
- Node.js 22及以上版本
- Anthropic API密钥（在这里获取一个)
- mkcert（用于本地HTTPS）
2. 克隆并配置
git clone https://github.com/leonobitech/fullstack-mcp-playground.git
cd fullstack-mcp-playground
cp .env.example .env
# Add your Anthropic API key to .env3. 设置 HTTPS
cd traefik/certs
mkcert "*.localhost" localhost 127.0.0.1 ::1
mv _wildcard.localhost+3.pem dev-local.pem
mv _wildcard.localhost+3-key.pem dev-local-key.pem
cd ../..4. 开始
docker network create leonobitech-net
docker compose up -d --build5. 访问
- 前端： https://app.localhost（注：这是一个本地开发域名，通常用于指向本地运行的应用程序，实际翻译时无需改变其形式，直接保留原样即可，因为“localhost”在中文中没有直接对应的翻译，它通常被理解为“本地主机”或“本机”）
- 核心API： https://api.localhost（该网址在中文语境下可直接表述为“https://api.localhost”，无需额外翻译，因为它是一个网址，保持原样即可。）
- Traefik： https://traefik.localhost（这个网址在中文中通常直接保留原样，因为网址本身是国际化的，并不直接翻译，但可以解释为“本地主机上的Traefik服务网址”）
______________________________________________________________________
🔧 创建新的MCP服务器
# Generate new server
./scripts/create-mcp-server.sh weather
cd repositories/mcp-weather
npm install
# Add tools in src/mcp/tools/
# Register in docker-compose.yml and config/mcp-servers.json______________________________________________________________________
📂 结构
fullstack-mcp-playground/
├── config/
│ └── mcp-servers.json # Server registry
├── repositories/
│ ├── core/ # MCP Core Server
│ ├── mcp-database/ # MCP Database Server
│ ├── mcp-files/ # MCP Files Server
│ ├── mcp-template/ # Template
│ └── frontend/ # MCP Host (Next.js)
├── scripts/
│ └── create-mcp-server.sh # Generator CLI
├── traefik/ # Proxy config
├── docker-compose.yml
└── .env.example______________________________________________________________________
🛠️ 可用的MCP服务器
核心（mcp-core)
get_health- 系统健康状况get_metrics- CPU/内存指标get_config- 配置
数据库（mcp-database）
query_database- SQL SELECT（SQL 选择语句）insert_record- 插入数据get_database_schema- 表模式
文件（mcp-files)
example_tool- 模板工具
______________________________________________________________________
🧪 测试应用程序
获取您的Anthropic API密钥
您需要一个Claude API密钥来测试AI代理：
- 首选 人类控制台
- 注册或登录（这与Claude Pro订阅是分开的）
- 获取5美元的免费API信用额度（足够进行广泛的测试）
- 创建一个API密钥
- 把它加到你的（列表/收藏/等）里
.env文件：
ANTHROPIC_API_KEY=sk-ant-api03-...- 重启前端容器：
docker compose restart frontend2. 访问聊天界面
打开您的浏览器并访问：
- 聊天： https://app.localhost/chat 翻译为中文是：“https://localhost/app/chat”（注：实际网址结构可能因具体实现而异，此处为直译说明，实际访问时可能需要考虑本地开发服务器的配置）。不过，通常我们不会直接翻译网址，而是说明其含义或用途，比如“这是一个指向本地开发服务器上聊天应用的链接”
- 服务器管理： https://app.localhost/servers 翻译为中文是：“https://本地主机应用/服务器”。不过，这里的“localhost”通常在中文语境中直接保留为“localhost”，因为它是一个网络术语，表示本机或本地服务器，所以完整的翻译可以是“https://app.localhost/servers（本地主机应用/服务器）”，但实际使用时，“localhost”可能无需翻译
3. 可用工具 - 什么真正有效
✅ 真实可用的功能工具（mcp-core）
这个（或：该） mcp-core 服务器暴露 3个真实工具 与实际运行的 Node.js 进程进行交互：
______________________________________________________________________
🩺 医生 工具1： get_health
它的功能是：
- 返回mcp-core服务的实时健康状态
- 显示实际运行时间（服务已运行多长时间）
- 显示实际内存使用情况（堆内存和驻留集大小）
- 提供时间戳和服务名称
返回的真实数据：
{
"status": "healthy",
"uptime": "142s",
"memory": {
"heapUsed": "45MB", // Real heap memory used
"heapTotal": "67MB", // Real total heap allocated
"rss": "89MB" // Real resident set size
},
"timestamp": "2025-10-10T...",
"service": "mcp-core"
}测试示例问题：
¿Cuál es el estado de salud del sistema?
How long has the core service been running?
Show me the current memory usage
Is the system healthy?
Check mcp-core health and memory______________________________________________________________________
📊 表格 工具2： get_metrics
它的功能是：
- 从 Node.js 进程中返回真实的 CPU 使用率指标
- 显示实际内存消耗（以字节为单位）
- 可以按指标类型过滤：
cpu，memory，或all - 为每次读数提供时间戳
输入参数：
metric（可选）："cpu"|"memory"|"all"（默认："all")
返回的实际数据：
{
"timestamp": "2025-10-10T...",
"cpu": {
"user": 156789, // Real CPU microseconds in user mode
"system": 34567 // Real CPU microseconds in system mode
},
"memory": {
"heapUsed": 47185920, // Real bytes
"heapTotal": 70254592, // Real bytes
"rss": 93450240, // Real bytes
"external": 1234567 // Real bytes
}
}测试示例问题：
Muéstrame las métricas del sistema
What's the current CPU usage?
Get memory metrics only
Show me all metrics
How much memory is the core service using?
Get CPU and memory metrics______________________________________________________________________
⚙️ 表示齿轮或机械装置的符号，常用于表示机械、工程、技术等相关的内容。 工具3： get_config
它的功能是：
- 从环境变量中返回实际的服务配置
- 显示 Node.js 版本、平台和架构
- 显示服务名称、环境和端口
- 返回CORS设置和日志级别
- 安全未泄露任何秘密（密码、API密钥已过滤掉）
返回的实际数据：
{
"service": "mcp-core",
"environment": "production",
"port": 3333,
"logLevel": "info",
"corsOrigin": "https://app.localhost",
"version": "0.1.0",
"nodeVersion": "v22.x.x", // Real Node.js version
"platform": "linux", // Real platform (docker)
"arch": "x64" // Real architecture
}测试示例问题：
¿Cuál es la configuración del servicio?
What Node.js version is running?
Show me the service configuration
What port is mcp-core using?
Get environment settings
What's the CORS origin configured?______________________________________________________________________
🔧 模拟工具（mcp-database）- 尚未具备功能
| 工具 | 状态 |
|---|---|
query_database | 🟡 退货 模拟数据 （待办事项：连接真实的 PostgreSQL） |
insert_record | 🟡 退货 模拟数据 （待办事项：连接真实的 PostgreSQL） |
get_database_schema | 🟡 退货 模拟数据 （待办事项：连接真实的 PostgreSQL） |
这些工具是占位符。您可以使用它们来测试流程，但在连接到真实数据库之前，它们返回的都是模拟数据。
4. 完整的测试指南
将这些提示复制并粘贴到聊天框中以测试每个工具：
🧪 测试单个工具
测试 get_health:
¿Cuál es el estado de salud del sistema? Muéstrame el uptime y memoria.What's the current system health? Show me uptime and memory usage.预期： 克劳德使用 get_health → 返回实际运行时间（例如，“142秒”）和内存使用情况
______________________________________________________________________
测试 get_metrics：
Muéstrame las métricas de CPU y memoria del sistema.Show me the current CPU and memory metrics in detail.预期： 克劳德使用 get_metrics → 返回真实的CPU微秒数和内存字节数
______________________________________________________________________
测试 get_config：
¿Qué configuración tiene el servicio? ¿Qué versión de Node está corriendo?What's the service configuration? What Node.js version is running?预期： 克劳德使用 get_config → 返回真实的 Node 版本、平台和设置
______________________________________________________________________
🚀 测试高级场景
在一个请求中测试多个工具：
Dame un reporte completo del sistema: salud, métricas y configuración.Give me a complete system report with health, metrics, and configuration.预期： 克劳德使用了全部3种工具（get_health， get_metrics， get_config）并编制一份综合报告
______________________________________________________________________
带参数的测试工具：
Get only memory metrics, not CPU.预期： 克劳德使用 get_metrics 带有参数 {"metric": "memory"}
______________________________________________________________________
测试对话流程：
Check the system health. If memory is over 100MB, also get the full metrics.预期： 克劳德使用 get_health 首先，分析结果，然后决定是否呼叫 get_metrics
______________________________________________________________________
西班牙语测试：
Dime cuánto tiempo lleva corriendo el servicio mcp-core y cuánta memoria está usando.预期： 克劳德懂西班牙语，会使用 get_health，并用西班牙语回复真实数据
5. 你应该看看什么
- 你的信息 出现在左侧
- “思考中……” 指示器显示克劳德正在处理中
- 工具执行 指标显示克劳德正在使用哪些工具
- 最终回复 来自克劳德，携工具数据
- 工具面板 右侧显示了来自已启用服务器的所有可用工具
6. 流程是如何运作的
You: "Check system health"
↓
Frontend → Claude API (with available tools)
↓
Claude decides to use: get_health
↓
Frontend → MCP Orchestrator → mcp-core server
↓
Tool executes: Returns real uptime + memory
↓
Frontend → Claude API (with tool result)
↓
Claude: "The system has been running for 142 seconds with 45MB heap usage..."7. 启用/禁用服务器
访问 https://app.localhost/servers 以：
- 切换服务器的开启/关闭状态
- 查看每台服务器提供的工具
- 实时查看聊天中可用工具的更新情况
示例： 禁用 mcp-core → 当前聊天仅支持数据库工具（模拟）
8. 成本估算
测试是 非常便宜：
- 每条对话（包括工具调用）约0.002美元
- 5美元免费信用额度 = 约2,500次测试对话
- 大多数提示的成本不到1美分
______________________________________________________________________
📖 接下来要做的步骤
既然你已经验证了端到端流程可以正常工作：
- 创建真实的MCP服务器 （天气、电子邮件、日历等）
- 替换模拟数据库工具 使用真实的 PostgreSQL 查询
- 构建自定义工具 特定于您的使用场景
- 切换服务器 为智能体赋予不同的能力
“画廊”概念已就绪：创建新服务器，通过用户界面启用/禁用它们，并见证您的AI代理获得新超能力！
______________________________________________________________________
🐳 Docker 命令
docker compose up -d # Start
docker compose up -d --build # Rebuild
docker compose logs -f mcp-core # Logs
docker compose down # Stop______________________________________________________________________
🔐 环境变量
| 变量 | 描述 |
|---|---|
ANTHROPIC_API_KEY 克劳德API密钥（必需） | |
FRONTEND_DOMAIN | 前端主机名 |
BACKEND_DOMAIN | 后端主机名 |
DATABASE_URL 数据库连接 |
______________________________________________________________________
📜 许可证
麻省理工学院 © 2025 — Leonobitech
______________________________________________________________________
🥷 Leonobitech Dev Team
www.leonobitech.com
Made with 🧠 and AI love 🤖