全栈MCP实验场

Name: 全栈MCP实验场
Author: leonobitech

作者：leonobitech2 星标更新：2025-10-11

安装使用来源：spider==github.com

项目介绍

技术文档摘要

🤖 全栈 MCP 实验场

使用模型上下文协议（MCP）和 Claude 作为语言模型引擎构建端到端全栈人工智能应用程序。

从本地环境到生产环境——黑客风格搭建

<a href="https://github.com/leonobitech/fullstack-infrastructure-blueprint/stargazers"> <img src="https://img.shields.io/github/stars/leonobitech/fullstack-infrastructure-blueprint?style=flat-square" alt="GitHub stars" /> </a> <a href="https://github.com/leonobitech/fullstack-infrastructure-blueprint/network/members"> <img src="https://img.shields.io/github/forks/leonobitech/fullstack-infrastructure-blueprint?style=flat-square" alt="GitHub forks" /> </a> <a href="https://github.com/leonobitech/fullstack-infrastructure-blueprint/issues"> <img src="https://img.shields.io/github/issues/leonobitech/fullstack-infrastructure-blueprint?style=flat-square" alt="Open issues" /> </a> <a href="https://github.com/leonobitech/fullstack-infrastructure-blueprint/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/leonobitech/fullstack-infrastructure-blueprint?style=flat-square" alt="License" /> </a> <img src="https://img.shields.io/github/last-commit/leonobitech/fullstack-infrastructure-blueprint?style=flat-square" alt="Last commit" />  <a href="https://www.docker.com/"> <img src="https://img.shields.io/badge/Docker-ready-blue.svg?style=flat-square" alt="Docker" /> </a> <a href="https://traefik.io/"> <img src="https://img.shields.io/badge/Traefik-3.x-green.svg?style=flat-square" alt="Traefik 3.x" /> </a> <a href="https://github.com/FiloSottile/mkcert"> <img src="https://img.shields.io/badge/HTTPS-mkcert-orange.svg?style=flat-square" alt="HTTPS mkcert" /> </a> <img src="https://img.shields.io/badge/status-stable-success.svg?style=flat-square" alt="状态：稳定" />

🧠 概述

这是一个使用模型上下文协议（MCP）构建人工智能驱动应用的全栈模板。它展示了如何：

创建多个 MCP 服务器作为微服务（数据库、文件、自定义工具）
构建一个 MCP 主机（前端），连接到多个服务器
集成 Claude AI 来使用所有连接服务器中的工具
通过添加新的 MCP 服务器实现水平扩展，而无需修改现有代码

架构

┌─────────────────────────────────────────────────────────────┐
│              前端（Next.js）= MCP 主机                       │
│  • 用户界面（聊天、服务器管理）                               │
│  • MCP 调度器（连接到多个服务器）                            │
│  • Claude 客户端（消费所有服务器中的工具）                    │
└─────────────────────────────────────────────────────────────┘
          ↕                ↕                ↕
    [HTTPS/SSE]      [HTTPS/SSE]      [HTTPS/SSE]
          ↕                ↕                ↕
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ MCP 服务器   │  │ MCP 服务器   │  │ MCP 服务器   │
│   核心       │  │  数据库      │  │   文件        │
│ (健康状况,   │  │ (查询,       │  │ (读取,       │
│  指标,       │  │  插入,       │  │  写入,       │
│  配置)       │  │  表结构)     │  │  列表)       │
└──────────────┘  └──────────────┘  └──────────────┘

🚀 快速开始

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
# 将您的 Anthropic API 密钥添加到 .env 文件中

3. 设置 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 --build

5. 访问

前端: https://app.localhost
核心 API: https://api.localhost
Traefik: https://traefik.localhost

🔧 创建新的 MCP 服务器

# 生成新服务器
./scripts/create-mcp-server.sh weather

cd repositories/mcp-weather
npm install

# 在 src/mcp/tools/ 中添加工具
# 在 docker-compose.yml 和 config/mcp-servers.json 中注册

📂 结构

fullstack-mcp-playground/
├── config/
│   └── mcp-servers.json          # 服务器注册表
├── repositories/
│   ├── core/                     # MCP 核心服务器
│   ├── mcp-database/             # MCP 数据库服务器
│   ├── mcp-files/                # MCP 文件服务器
│   ├── mcp-template/             # 模板
│   └── frontend/                 # MCP 主机（Next.js）
├── scripts/
│   └── create-mcp-server.sh      # 生成器 CLI
├── traefik/                      # 代理配置
├── docker-compose.yml
└── .env.example

🛠️ 可用的 MCP 服务器

核心 (`mcp-core`)

get_health - 系统健康状况
get_metrics - CPU/内存指标
get_config - 配置

数据库 (`mcp-database`)

query_database - SQL 查询
insert_record - 插入数据
get_database_schema - 表结构

文件 (`mcp-files`)

example_tool - 模板工具

🧪 测试应用程序

1. 获取您的 Anthropic API 密钥

您需要一个 Claude API 密钥来测试 AI 代理：

前往 Anthropic 控制台
注册或登录（这与 Claude Pro 订阅是分开的）
获取 $5 的免费 API 信用额度（足够进行广泛的测试）
创建一个 API 密钥
将其添加到您的 .env 文件中：

ANTHROPIC_API_KEY=sk-ant-api03-...

重启前端容器：

docker compose restart frontend

2. 访问聊天界面

打开浏览器并访问：

聊天: https://app.localhost/chat
服务器管理: https://app.localhost/servers

3. 可用工具 - 真实功能

✅ 真实功能工具 (mcp-core)

mcp-core 服务器暴露了 3 个真实工具，这些工具与实际运行的 Node.js 进程交互：

🩺 工具 1: `get_health`

功能：

返回 mcp-core 服务的实时健康状况
显示实际运行时间（服务已运行的时间）
显示实际内存使用情况（堆和 RSS）
提供时间戳和服务名称

返回的真实数据：

{
  "status": "healthy",
  "uptime": "142s",
  "memory": {
    "heapUsed": "45MB",    // 实际堆内存使用量
    "heapTotal": "67MB",   // 实际分配的总堆内存
    "rss": "89MB"          // 实际驻留集大小
  },
  "timestamp": "2025-10-10T...",
  "service": "mcp-core"
}

示例问题以测试：

系统状态如何？
核心服务已运行多长时间？
显示当前内存使用情况
系统是否健康？
检查 mcp-core 健康和内存

📊 工具 2: `get_metrics`

功能：

返回 Node.js 进程的实际 CPU 使用率指标
显示实际内存消耗（以字节为单位）
可按指标类型过滤：cpu、memory 或 all
提供每个读数的时间戳

输入参数：

metric（可选）："cpu" | "memory" | "all"（默认值："all"）

返回的真实数据：

{
  "timestamp": "2025-10-10T...",
  "cpu": {
    "user": 156789,      // 实际用户模式下的 CPU 微秒数
    "system": 34567      // 实际系统模式下的 CPU 微秒数
  },
  "memory": {
    "heapUsed": 47185920,    // 实际字节数
    "heapTotal": 70254592,   // 实际字节数
    "rss": 93450240,         // 实际字节数
    "external": 1234567      // 实际字节数
  }
}

示例问题以测试：

显示系统指标
当前 CPU 使用率是多少？
仅获取内存指标
显示所有指标
核心服务正在使用多少内存？
获取 CPU 和内存指标

⚙️ 工具 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",    // 实际 Node.js 版本
  "platform": "linux",          // 实际平台（Docker）
  "arch": "x64"                 // 实际架构
}

示例问题以测试：

服务配置是什么？
正在运行的是哪个版本的 Node.js？
显示服务配置
mcp-core 使用哪个端口？
获取环境设置
CORS 原点配置为何？

🔧 模拟工具 (mcp-database) - 尚未实现

工具	状态
`query_database`	🟡 返回模拟数据（待办事项：连接真实的 PostgreSQL）
`insert_record`	🟡 返回模拟数据（待办事项：连接真实的 PostgreSQL）
`get_database_schema`	🟡 返回模拟数据（待办事项：连接真实的 PostgreSQL）

这些工具是占位符。您可以使用它们来测试流程，但直到连接上真实的数据库之前，它们会返回虚假数据。

4. 完整测试指南

复制并粘贴以下提示进入聊天以测试每个工具：

🧪 单独测试工具

测试 get_health：

系统状态如何？显示运行时间和内存。

当前系统健康状况如何？显示运行时间和内存使用情况。

预期结果： Claude 使用 get_health → 返回实际运行时间（例如，“142s”）和内存使用情况

测试 get_metrics：

显示系统 CPU 和内存指标。

详细显示当前 CPU 和内存指标。

预期结果： Claude 使用 get_metrics → 返回实际 CPU 微秒数和内存字节数

测试 get_config：

服务配置是什么？正在运行的是哪个版本的 Node.js？

服务配置是什么？正在运行的是哪个版本的 Node.js？

预期结果： Claude 使用 get_config → 返回实际 Node.js 版本、平台和设置

🚀 测试高级场景

测试单个请求中的多个工具：

给我一份完整的系统报告：健康状况、指标和配置。

给我一份包含健康状况、指标和配置的完整系统报告。

预期结果： Claude 使用所有 3 个工具（get_health、get_metrics、get_config）并编译一份综合报告

测试带有参数的工具：

仅获取内存指标，不要 CPU。

预期结果： Claude 使用 get_metrics 并传递参数 {"metric": "memory"}

测试对话流程：

检查系统健康状况。如果内存超过 100MB，请也获取完整指标。

预期结果： Claude 首先使用 get_health，分析结果，然后决定是否调用 get_metrics

测试西班牙语：

告诉我 mcp-core 服务已经运行了多久以及它正在使用多少内存。

预期结果： Claude 理解西班牙语，使用 get_health 并用西班牙语回复实际数据

5. 您应该看到的内容

您的消息 出现在左侧
“思考中...” 指示器显示 Claude 正在处理
工具执行 指示器显示 Claude 使用了哪些工具
最终响应 由 Claude 发出，包含工具的数据
工具面板 显示来自启用服务器的所有可用工具

6. 流程是如何工作的

您: “检查系统健康状况”
  ↓
前端 → Claude API（带可用工具）
  ↓
Claude 决定使用：get_health
  ↓
前端 → MCP 调度器 → mcp-core 服务器
  ↓
工具执行：返回实际运行时间 + 内存
  ↓
前端 → Claude API（带工具结果）
  ↓
Claude: “系统已运行 142 秒，堆内存使用量为 45MB...”

7. 启用/禁用服务器

前往 https://app.localhost/servers 来：

开启/关闭服务器
查看每个服务器提供的工具
观察聊天中的可用工具实时更新

示例： 禁用 mcp-core → 聊天现在只有数据库工具（模拟）

8. 成本估算

测试非常便宜：

每次对话约 $0.002（包括工具调用）
$5 免费信用额度 = 约 2,500 次测试对话
大多数提示成本不到 1 分钱

📖 下一步

现在您已经验证了端到端流程可以正常工作：

创建真实的 MCP 服务器（天气、电子邮件、日历等）
替换模拟数据库工具 为真实的 PostgreSQL 查询
构建特定于您用例的自定义工具
切换服务器 给代理不同的能力

“画廊”概念已经准备好：创建新的服务器，从 UI 启用/禁用它们，并观察您的 AI 代理获得新的超能力！

🐳 Docker 命令

docker compose up -d              # 启动
docker compose up -d --build      # 重新构建
docker compose logs -f mcp-core   # 日志
docker compose down               # 停止

🔐 环境变量

变量	描述
`ANTHROPIC_API_KEY`	Claude API 密钥（必需）
`FRONTEND_DOMAIN`	前端主机名
`BACKEND_DOMAIN`	后端主机名
`DATABASE_URL`	数据库连接

📜 许可证

🥷 Leonobitech 开发团队 <a href="https://www.leonobitech.com">www.leonobitech.com</a> 由 🧠 和 AI 爱情 🤖 制作

全栈MCP实验场

项目介绍

技术文档摘要

🤖 全栈 MCP 实验场

🧠 概述

架构

🚀 快速开始

1. 先决条件

2. 克隆并配置

3. 设置 HTTPS

4. 启动

5. 访问

🔧 创建新的 MCP 服务器

📂 结构

🛠️ 可用的 MCP 服务器

核心 (mcp-core)

数据库 (mcp-database)

文件 (mcp-files)

🧪 测试应用程序

1. 获取您的 Anthropic API 密钥

2. 访问聊天界面

3. 可用工具 - 真实功能

✅ 真实功能工具 (mcp-core)

🩺 工具 1: get_health

📊 工具 2: get_metrics

⚙️ 工具 3: get_config

🔧 模拟工具 (mcp-database) - 尚未实现

4. 完整测试指南

🧪 单独测试工具

🚀 测试高级场景

5. 您应该看到的内容

6. 流程是如何工作的

7. 启用/禁用服务器

8. 成本估算

📖 下一步

🐳 Docker 命令

🔐 环境变量

📜 许可证

核心 (`mcp-core`)

数据库 (`mcp-database`)

文件 (`mcp-files`)

🩺 工具 1: `get_health`

📊 工具 2: `get_metrics`

⚙️ 工具 3: `get_config`