open-source/quality-inspection-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
quality-inspection-platform/docs/mcp_install.md
qihongkun f5143aee09 feat: 添加 Docker 部署支持和 MCP 原生集成 
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置
- 新增 MCP 原生集成模块 (mcp_native.py)
- 移除旧的 mcp_bridge.py，更新依赖和文档
- 添加部署文档 (Docker 和服务器部署指南)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-25 14:21:43 +08:00

249 lines
9.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 协议共用同一套工具实现。
Reference in New Issue View Git Blame Copy Permalink