qihongkun
f5143aee09
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置 - 新增 MCP 原生集成模块 (mcp_native.py) - 移除旧的 mcp_bridge.py，更新依赖和文档 - 添加部署文档 (Docker 和服务器部署指南) Co-authored-by: Cursor <cursoragent@cursor.com>
249 lines
9.0 KiB
Markdown
249 lines
9.0 KiB
Markdown
# MCP Server 安装与接入说明
|
||
|
||
平台在 **同一个 `uvicorn` 进程** 内提供：
|
||
|
||
| 能力 | 路径 | 适用场景 |
|
||
|------|------|----------|
|
||
| **Web 管理端** | `/`、`/api/*` | 人工在浏览器操作 |
|
||
| **MCP Server（推荐 AI 用）** | `/mcp` | Codex / Claude / Cursor（Streamable HTTP） |
|
||
| **HTTP 工具网关（兼容）** | `/mcp/tools`、`/mcp/invoke` | curl、CI、自研脚本 |
|
||
|
||
三者共用数据库与工作流引擎；**Web UI 与 MCP 可同时使用，互不影响**。
|
||
|
||
> **历史变更**：已移除 `mcp_bridge.py`。不再需要本机 `python3` 子进程桥接；客户端直接连 `http://10.20.30.42:8000/mcp`。
|
||
|
||
---
|
||
|
||
## 1. 架构
|
||
|
||
```
|
||
┌─────────────────┐ MCP (Streamable HTTP) ┌──────────────────────────┐
|
||
│ Codex / Claude │ ──────────────────────────────►│ uvicorn app.main:app │
|
||
│ Claude Desktop │ Authorization: Bearer │ ├─ /mcp (mcp_native) │
|
||
└─────────────────┘ │ ├─ /api/* (Web) │
|
||
┌─────────────────┐ HTTP 登录 / 点击 │ └─ /mcp/invoke (curl) │
|
||
│ 浏览器 Web UI │ ──────────────────────────────►└──────────────────────────┘
|
||
└─────────────────┘
|
||
```
|
||
|
||
实现位置：`app/mcp_native.py`（挂载路由 + `lifespan`），工具逻辑：`app/main.py` 中 `MCP_TOOL_SPECS` 与 `_dispatch_mcp_tool`。
|
||
|
||
---
|
||
|
||
## 2. 服务端部署（管理员）
|
||
|
||
> **完整步骤**（用户、Git、前端构建、systemd、Nginx、备份）：[`deploy_server.md`](./deploy_server.md)
|
||
|
||
### 2.1 安装与启动
|
||
|
||
```bash
|
||
cd /path/to/quality-inspection-platform
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
|
||
# 生产建议：所有 MCP 调用必须带 API Key
|
||
# export MCP_REQUIRE_API_KEY=true
|
||
|
||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 2.2 启动后确认
|
||
|
||
| 检查项 | 命令或地址 |
|
||
|--------|------------|
|
||
| 健康 | `curl -s http://10.20.30.42:8000/health` |
|
||
| Web | 浏览器打开 `http://10.20.30.42:8000/` |
|
||
| 工具列表 | `curl -s http://10.20.30.42:8000/mcp/tools -H "Authorization: Bearer sto-密钥"` |
|
||
| MCP 端点 | `http://10.20.30.42:8000/mcp`（供 Codex 配置，非浏览器页面） |
|
||
|
||
### 2.3 内网 systemd 示例（可选）
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Quality Inspection Platform
|
||
After=network.target
|
||
|
||
[Service]
|
||
User=qip
|
||
WorkingDirectory=/opt/quality-inspection-platform
|
||
Environment="PATH=/opt/quality-inspection-platform/.venv/bin"
|
||
Environment="MCP_REQUIRE_API_KEY=true"
|
||
# 使用内网地址访问且 MCP 连不上时可加：
|
||
# Environment="QIP_MCP_DISABLE_DNS_PROTECTION=true"
|
||
ExecStart=/opt/quality-inspection-platform/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||
Restart=always
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Codex 配置
|
||
|
||
编辑 **`~/.codex/config.toml`**。
|
||
|
||
> **远程环境**：配置文件要写在 Codex 实际运行的机器上。MCP 请求从 Codex 所在机器发出；团队默认 MCP 地址为 `http://10.20.30.42:8000/mcp`。
|
||
|
||
### 3.1 默认内网地址
|
||
|
||
```toml
|
||
[mcp_servers.quality-inspection-platform]
|
||
url = "http://10.20.30.42:8000/mcp"
|
||
|
||
[mcp_servers.quality-inspection-platform.http_headers]
|
||
Authorization = "Bearer sto-你的API密钥"
|
||
```
|
||
|
||
### 3.2 连接其他部署地址
|
||
|
||
如果 MCP 平台部署到其他服务器，将 `10.20.30.42:8000` 替换为实际 IP、端口或域名，例如：
|
||
|
||
```toml
|
||
[mcp_servers.quality-inspection-platform]
|
||
url = "http://qip.corp:8000/mcp"
|
||
|
||
[mcp_servers.quality-inspection-platform.http_headers]
|
||
Authorization = "Bearer sto-你的API密钥"
|
||
```
|
||
|
||
### 3.3 配置生效
|
||
|
||
配置完成后重启 Codex 会话或 Codex 应用，让 MCP 配置重新加载。验证方式：在对话中要求 Agent 调用 `catalog_snapshot`，应返回 apis / workflows 等 JSON 快照。
|
||
|
||
### 3.4 API Key 获取
|
||
|
||
1. 浏览器登录 Web → 右上角「个人中心」
|
||
2. 创建 `sto-` 开头的 API Key（仅显示一次，请妥善保存）
|
||
3. 写入 `~/.codex/config.toml` 的 `http_headers.Authorization`，或在 HTTP 网关调用时使用头 `X-API-Key: sto-...`
|
||
|
||
**写操作**与**执行类**工具无有效 Key 返回 **401**。生产环境建议 `MCP_REQUIRE_API_KEY=true`，此时**只读工具**也须 Key。
|
||
|
||
---
|
||
|
||
## 4. 团队协作（同事无需克隆仓库）
|
||
|
||
| 角色 | 需要做什么 |
|
||
|------|------------|
|
||
| **管理员** | 内网部署 `uvicorn`，开放防火墙，分发内网 URL |
|
||
| **每位开发者** | 配置 `~/.codex/config.toml`（URL + 个人 `sto-` Key） |
|
||
| **不需要** | 本机 Python、`mcp_bridge`、克隆完整项目（除非要改代码） |
|
||
|
||
**远程 Codex 统一配置（推荐）**
|
||
|
||
1. 服务器上部署一次项目（含 `.venv` 与 `uvicorn`）
|
||
2. 同事在远程机器上运行 Codex 或使用远程工作区
|
||
3. 在**远程** `~/.codex/config.toml` 使用 `http://10.20.30.42:8000/mcp`（确保 Codex 所在机器可访问该内网地址）
|
||
4. 每人使用自己的 `sto-` Key，**不要**写入 Git 或共享配置文件
|
||
|
||
---
|
||
|
||
## 5. Cursor / Claude Desktop（可选）
|
||
|
||
使用 **HTTP URL** 连接 MCP（以客户端当前版本支持的 Streamable HTTP / URL 配置为准）：
|
||
|
||
- URL：`http://10.20.30.42:8000/mcp`
|
||
- 头：`Authorization: Bearer sto-...`
|
||
|
||
Cursor 示例：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quality-inspection-platform": {
|
||
"url": "http://10.20.30.42:8000/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer sto-你的API密钥"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Claude Desktop 具体字段名见其 MCP 配置文档。
|
||
|
||
---
|
||
|
||
## 6. 从旧版 `mcp_bridge` 迁移
|
||
|
||
| 旧配置 | 新配置 |
|
||
|--------|--------|
|
||
| `"command": "python3"` | 删除 |
|
||
| `"args": [".../mcp_bridge.py"]` | 删除 |
|
||
| `"env": { "QIP_BASE_URL": "...", "QIP_API_KEY": "..." }` | 改为 Codex `url = "<QIP_BASE_URL>/mcp"` + `http_headers.Authorization = "Bearer <Key>"` |
|
||
|
||
迁移后只需保证 **`uvicorn` 已启动**；无需再单独运行桥接脚本。
|
||
|
||
---
|
||
|
||
## 7. 自检清单
|
||
|
||
```bash
|
||
# 1. 后端存活
|
||
curl -s http://10.20.30.42:8000/health
|
||
|
||
# 2. HTTP 网关（与 MCP 工具集一致）
|
||
curl -s http://10.20.30.42:8000/mcp/tools \
|
||
-H "Authorization: Bearer sto-你的密钥"
|
||
|
||
# 3. 试调一个工具
|
||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||
-H "Authorization: Bearer sto-你的密钥" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"tool":"catalog_snapshot","arguments":{}}'
|
||
```
|
||
|
||
**Codex 侧**：在对话中让 Agent 调用 `catalog_snapshot`，应返回 apis / workflows 等 JSON 快照。
|
||
|
||
---
|
||
|
||
## 8. 排障
|
||
|
||
| 现象 | 可能原因 | 处理 |
|
||
|------|----------|------|
|
||
| Codex 无工具 / 连接失败 | `uvicorn` 未启动或 URL 错误 | 确认 `/health`；检查 `~/.codex/config.toml` 中 URL 以 `/mcp` 结尾 |
|
||
| 401 / requires API Key | 未配置或 Key 无效 | 个人中心重新生成 Key，更新 `Authorization` |
|
||
| 内网 IP 可 curl 但 Codex 连不上 | DNS rebinding 校验 | 设置 `QIP_MCP_DISABLE_DNS_PROTECTION=true` 或配置 `QIP_MCP_ALLOWED_HOSTS` |
|
||
| 修改工具后客户端仍是旧的 | 客户端缓存 | 重启 Codex 会话或应用；服务端重启 `uvicorn` |
|
||
| 远程环境 MCP 失败 | 配在了本机而非 Codex 所在机器 | 改 Codex 实际运行机器上的 `~/.codex/config.toml`；从那台机器验证是否能访问 `http://10.20.30.42:8000/health` |
|
||
| Web 正常、MCP 不行 | 只检查了 Web | MCP 走 `/mcp`，与 `/api` 独立；分别自检 |
|
||
|
||
查看 MCP 相关日志：启动 `uvicorn` 的终端；Codex 客户端 MCP 日志。
|
||
|
||
---
|
||
|
||
## 9. 环境变量
|
||
|
||
| 变量 | 含义 |
|
||
|------|------|
|
||
| `MCP_REQUIRE_API_KEY` | `true` 时所有 MCP 工具（含只读、`GET /mcp/tools`）均需 Key |
|
||
| `QIP_MCP_DISABLE_DNS_PROTECTION` | `true` 时关闭 MCP 传输的 Host/Origin 校验 |
|
||
| `QIP_MCP_ALLOWED_HOSTS` | 逗号分隔 Host 白名单，如 `10.20.30.42:8000,qip.corp:8000` |
|
||
| `QIP_MCP_ALLOWED_ORIGINS` | 逗号分隔 Origin 白名单 |
|
||
|
||
---
|
||
|
||
## 10. 维护与文档索引
|
||
|
||
- **新增 MCP 工具**：修改 `app/main.py` 中 `MCP_TOOL_SPECS` 与 `_dispatch_mcp_tool` 分支 → 重启 `uvicorn` → 重启 MCP 客户端。
|
||
- **AI 选型与 Recipe（Agent 必读）**：[mcp_tools_for_ai.md](./mcp_tools_for_ai.md)
|
||
- **curl / 批量调用示例**：[mcp_quickstart.md](./mcp_quickstart.md)
|
||
- **Codex 短约定**：项目根 [AGENTS.md](../AGENTS.md)
|
||
|
||
---
|
||
|
||
## 11. 常见问题
|
||
|
||
**还需要 bridge 吗？**
|
||
不需要。`/mcp` 已是标准 MCP Server。
|
||
|
||
**每人都要装 Python 吗？**
|
||
仅**运行后端的服务器**需要 Python 环境；只用 Codex 连 MCP 的同事不需要本机 Python。
|
||
|
||
**能和 Web 一起用吗？**
|
||
可以。Web 走登录态 `/api/*`；AI 走 `/mcp` + API Key。
|
||
|
||
**脚本还能用吗？**
|
||
可以。继续 `POST /mcp/invoke` 与 `GET /mcp/tools`，与 MCP 协议共用同一套工具实现。
|