quality-inspection-platform/docs/mcp_install.md

# 把本平台注册成真正的 MCP Server

本仓库已附带 `mcp_bridge.py`，它是一个标准 stdio MCP Server，  
对外暴露 MCP 协议（JSON-RPC over stdio），内部桥接到本平台的 HTTP 网关。

只要先启动平台后端，再让 Cursor / Claude Desktop / Codex CLI 启动这个桥接，  
它就会被识别成一个真正的 MCP Server，并自动暴露所有平台工具（含跑批工作流工具）。

---

## 1. 启动平台后端

```bash
cd /Users/qihongkun/work/My_app/quality-inspection-platform
# 可选：生产/共享环境建议开启，所有 MCP 调用必须带 API Key
# export MCP_REQUIRE_API_KEY=true
uvicorn app.main:app --host 127.0.0.1 --port 8000
```

确认可访问：

- `http://127.0.0.1:8000/mcp/tools`

---

## 2. 安装到 Cursor

编辑 `~/.cursor/mcp.json`（不存在则新建），加入：

```json
{
  "mcpServers": {
    "quality-inspection-platform": {
      "command": "python3",
      "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"],
      "env": {
        "QIP_BASE_URL": "http://127.0.0.1:8000",
        "QIP_API_KEY": "sto-你的API密钥"
      }
    }
  }
}
```

- `QIP_BASE_URL`：平台后端地址（兼容旧环境变量 `AI_TEST_BASE_URL`）。
- `QIP_API_KEY`：**必须配置**（兼容旧名 `AI_TEST_API_KEY`）。写操作与执行类工具（`workflow_run`、`workflow_batch_run`、`ssh_script_run` 等）无 Key 将返回 401；桥接会把 Key 放到 `Authorization: Bearer` 与 invoke body 的 `api_key` 字段。
- 后端可选 `MCP_REQUIRE_API_KEY=true`：所有 MCP 工具（含只读、`GET /mcp/tools`）均要求 Key。

在平台 Web 端右上角「个人中心」生成 `sto-` 开头的 API Key。

重启 Cursor 后，在 MCP 面板里就能看到 `quality-inspection-platform`，里面会自动列出全部工具。

---

## 3. 安装到 Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "quality-inspection-platform": {
      "command": "python3",
      "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"],
      "env": {
        "QIP_BASE_URL": "http://127.0.0.1:8000",
        "QIP_API_KEY": "sto-你的API密钥"
      }
    }
  }
}
```

---

## 4. 安装到 Codex CLI

```bash
codex mcp add quality-inspection-platform \
  --command python3 \
  --args /Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py \
  --env QIP_BASE_URL=http://127.0.0.1:8000 \
  --env QIP_API_KEY=sto-你的API密钥
```

或在 `~/.codex/config.toml` 中：

```toml
[mcp.servers.quality-inspection-platform]
command = "python3"
args = ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"]

[mcp.servers.quality-inspection-platform.env]
QIP_BASE_URL = "http://127.0.0.1:8000"
QIP_API_KEY = "sto-你的API密钥"
```

---

## 5. 自检（不连客户端，先确认桥接可用）

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"catalog_snapshot","arguments":{}}}' \
  | QIP_API_KEY=sto-你的API密钥 python3 mcp_bridge.py
```

预期：

- `initialize` 返回 `serverInfo`
- `tools/list` 返回工具清单（应包含 `workflow_batch_*` 等）
- `tools/call` 返回 `content[0].text` 内含调用结果

---

## 6. 暴露的工具（自动转发自平台）

桥接启动时从 `GET /mcp/tools` 拉取列表，**无需改 `mcp_bridge.py`** 即可随平台升级获得新工具。

### 资源管理

- `api_upsert` — 创建/更新接口
- `mock_upsert` — 创建/更新 mock 数据
- `mcp_tool_upsert` — 创建/更新 MCP 工具配置
- `catalog_snapshot` — 全量资源快照（含 `workflow_batches`、目录树、SSH 树）

### 工作流（单次）

- `workflow_upsert` — 创建/更新工作流（支持 `loop`、`condition` + `json_path`）
- `workflow_get` — 读取工作流及各节点 `last_run`
- `workflow_node_status` — 单节点最近执行状态
- `workflow_patch_json` — 增量修改工作流 JSON
- `workflow_validate` — 校验 definition JSON
- `workflow_run` / `workflow_run_node` — 执行（需 API Key）
- `workflow_analyze_last_run` — 分析最近一次执行
- `workflow_run_list` / `workflow_run_get` — 执行历史
- `workflow_run_replay` / `workflow_run_loki_link` — 重放与 Loki 链接

### 跑批工作流

- `workflow_batch_create` — 创建草稿批跑任务（需 API Key）
- `workflow_batch_update` — 更新 `workflow_ids` / `base_url` 等（需 API Key）
- `workflow_batch_run` — 按任务配置顺序执行多个工作流
- `workflow_batch_get` — 批跑详情与关联 `workflow_runs`
- `workflow_batch_list` — 批跑任务列表

推荐顺序：`create` → `update`（绑定 `workflow_ids`）→ `run` → `get`。详见 `docs/mcp_quickstart.md` 示例 H。

### 目录

- `folder_ensure` / `folder_list`
- `api_move_folder` / `workflow_move_folder`

### SSH 脚本

- `ssh_tree` / `ssh_script_get`
- `ssh_script_upsert` / `ssh_script_run`

---


## 7. 工作机制

```
Cursor / Claude / Codex
        |
        | (MCP stdio JSON-RPC)
        v
mcp_bridge.py
        |
        | HTTP (httpx) + Authorization / api_key
        v
http://127.0.0.1:8000/mcp/invoke
```

- 桥接会在启动时调用一次 `/mcp/tools`，把工具映射成 MCP `tools/list` 返回值。
- 每次 `tools/call`，桥接会以 `{tool, arguments}` POST 到 `/mcp/invoke`。
- 后端返回 `{ok, tool, data, error}`，桥接将其作为 `content[0].text` 文本返回，并按 `ok` 设置 `isError`。

---

## 8. Loki 日志（可选）

若需在管理端或 API 中打开 General/Grafana Loki 探索页，在后端进程环境中配置：

- `GENERAL_LOKI_EXPLORE_URL` 或 `LOKI_EXPLORE_URL`
- 可选：`LOKI_DATASOURCE`、`LOKI_ORG_ID`、`LOKI_LABEL_SELECTOR`、`LOKI_TIME_PADDING_SECONDS`

配置后，`GET /api/workflow-runs/{run_id}/loki-link` 可为指定 HTTP 节点生成带时间窗与路径过滤的 Explore URL。

---

## 9. 维护建议

- 平台新增工具时，无需改桥接，重启 MCP 客户端即可重新拉取 `tools/list`。
- 团队成员：`git pull` + `pip install -r requirements.txt` + 配置上述 MCP 入口与 `AI_TEST_API_KEY`。
- **AI 能力说明（首选）**：**`docs/mcp_tools_for_ai.md`**
- 人类 curl 示例：**`docs/mcp_quickstart.md`**
- Codex 自动加载：**项目根 `AGENTS.md`**