# 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 协议共用同一套工具实现。