quality-inspection-platform/docs/mcp_install.md

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

2.1 安装与启动

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 示例（可选）

[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 默认内网地址

[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、端口或域名，例如：

[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 示例：

{
  "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. 自检清单

# 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
• curl / 批量调用示例：mcp_quickstart.md
• Codex 短约定：项目根 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 协议共用同一套工具实现。