quality-inspection-platform/docs/mcp_tools_for_ai.md

# MCP 工具能力说明（AI 专用）

> **读者**：Codex / Claude / Cursor 等通过 `quality-inspection-platform` MCP 工作的 Agent。  
> **目的**：在调用 `tools/list` 之外，提供「何时用哪个工具、按什么顺序、参数怎么填」的固定上下文。  
> **维护**：工具以 `app/main.py` 中 `MCP_TOOL_SPECS` 和平台 `GET /mcp/tools` 为准；增删工具时请同步更新本文档。  
> **重要**：某些 MCP 客户端可能缓存、裁剪或延迟刷新工具列表；不要仅凭当前客户端可见工具反向删减本文档能力。

---

## 0. Agent 必读（30 秒）

1. **先** `catalog_snapshot` 了解现有 apis / workflows / workflow_batches / mocks / folders / ssh_tree，避免重复创建。
2. **写操作与执行**必须带 `sto-` API Key（MCP 请求头 `Authorization: Bearer` 或 `X-API-Key`；HTTP 脚本可在 body 传 `api_key`，兼容旧名 `AI_TEST_API_KEY`）。
3. **接口**用 `api_upsert`；**流程**用 `workflow_upsert` 或 `workflow_patch_json`；**跑批**固定三步：`workflow_batch_create` → `workflow_batch_update` → `workflow_batch_run`。
4. **排障**：`workflow_run_get` 看 request/response → `workflow_run_loki_link` 查日志。
5. 如果当前客户端没有显示某个工具，先用 MCP `tools/list` 或 `GET /mcp/tools` 核对，再重启 MCP 客户端 / 会话。
6. 人类可读安装见 `docs/mcp_install.md`；curl 示例见 `docs/mcp_quickstart.md`。

### 0.1 工具来源与客户端刷新

- 权威工具清单来自后端 `app/main.py` 的 `MCP_TOOL_SPECS`，平台通过 `GET /mcp/tools` 对外暴露。
- 平台内置 Streamable HTTP MCP（`GET/POST /mcp`），`tools/list` 由 `MCP_TOOL_SPECS` 提供；兼容 HTTP 网关 `GET /mcp/tools`。
- Codex / Cursor / Claude 等客户端可能在会话启动时缓存工具列表；平台新增工具后，通常需要重启 MCP 客户端或重启会话。
- 如果客户端只显示部分工具，不代表平台没有该能力。先用 `/mcp/tools` 或本文档核对，再决定是否降级。
- Agent 更新本文档时，应以源码和 `/mcp/tools` 为准，不以单个客户端当前暴露的工具子集为准。

---

## 1. 平台在做什么

| 层级 | 含义 | MCP 主要工具 |
|------|------|----------------|
| 接口库 | 单个 HTTP API 定义（method、url、headers、body…） | `api_upsert`、`catalog_snapshot` |
| 工作流 | 多节点编排（HTTP / 条件 / 循环 / 提取） | `workflow_upsert`、`workflow_run` |
| 跑批 | 一次任务顺序执行多个工作流 | `workflow_batch_*` |
| 执行历史 | 每次运行的 request/response 快照 | `workflow_run_list`、`workflow_run_get` |
| Mock | 命名数据集，供节点 mock 使用 | `mock_upsert` |

**数据约定**：`url` 只存**路径**（如 `/api/user/{id}`），环境域名放在执行时的 `base_url`。

---

## 2. 鉴权

### 2.1 平台地址

Codex 等客户端在个人 MCP 配置中配置平台 URL 与 API Key，例如：

| 配置项 | 含义 | 示例 |
|--------|------|------|
| `url` | MCP 端点 | `http://10.20.30.42:8000/mcp` |
| `http_headers.Authorization` / `headers.Authorization` | `Bearer sto-...` | `Bearer sto-xxx` |

Agent 通过 MCP 工具访问平台；平台进程由质量检测平台项目或共享内网服务负责。兼容环境变量名 `AI_TEST_API_KEY` 仅适用于旧 HTTP 脚本，MCP 客户端请用请求头传 Key。

### 2.2 调用鉴权

| 类型 | 工具示例 | 无 Key 时 |
|------|----------|-----------|
| 只读 | `catalog_snapshot`、`workflow_get`、`workflow_run_list` | 以 superadmin 读全库（不推荐生产暴露） |
| 写入 | `api_upsert`、`workflow_upsert`、`folder_ensure`… | **401** |
| 执行 | `workflow_run`、`workflow_batch_run`、`ssh_script_run`、`workflow_run_replay` | **401** |

环境变量 `MCP_REQUIRE_API_KEY=true` 时，**所有**工具（含 `GET /mcp/tools`）均需 Key。

写操作与执行类工具必须使用有效 Key。不要把 Key 写入文档、日志或对话输出；只允许放在 MCP 配置、环境变量或请求头中。

---

## 3. 按场景选工具（决策表）

| 用户意图 | 推荐工具链 |
|----------|------------|
| 我不知道项目里有什么 | `catalog_snapshot` |
| 客户端看不到某个工具 | 查 `GET /mcp/tools` → 重启 MCP 客户端 / 会话 → 再调用 |
| 从 Apifox/文档批量建接口 | `folder_ensure` → 多次 `api_upsert`（或 `invoke-batch`） |
| 新建/改流程图 | `workflow_validate`（可选）→ `workflow_upsert` |
| 只改流程里某几个字段 | `workflow_patch_json` |
| 跑一条流程 | `workflow_run`（`base_url` + `workflow_id`） |
| 只调试一个节点 | `workflow_run_node` |
| 版本/回归一次跑多条流程 | `workflow_batch_create` → `workflow_batch_update` → `workflow_batch_run` → `workflow_batch_get` |
| 看某次执行详情 | `workflow_run_get`（`run_id`） |
| 看历史列表 | `workflow_run_list`（`workflow_id` / `batch_id`） |
| 失败后续跑 | `workflow_run_replay`（`run_id`） |
| 查服务端日志 | `workflow_run_loki_link`（`run_id` + `node_id`） |
| 看节点上次结果 | `workflow_node_status` 或 `workflow_get` |
| 快速看上次成败统计 | `workflow_analyze_last_run` |
| 准备 Mock 数据 | `mock_upsert` |
| 运维脚本 | `ssh_tree` → `ssh_script_upsert` → `ssh_script_run` |

---

## 4. 工具清单（按分类）

下文参数均为各工具的 **`arguments` 对象**（MCP `tools/call` 直接传该对象）。仅在使用 HTTP 网关时，外层再包一层 `{"tool":"<名称>","arguments":{...}}`，见 [mcp_quickstart.md](./mcp_quickstart.md)。

### 4.1 发现与目录

#### `catalog_snapshot`

- **用途**：一次拉取 apis、workflows、mocks、**workflow_batches**、folders、ssh_tree。
- **参数**：无。
- **何时用**：任务开始、批量导入前、避免重复 `api_upsert`。

#### `folder_ensure`

- **用途**：登记 apis 或 workflows 目录（空目录也可）。
- **参数**：`target`：`apis` | `workflows`；`path`：如 `auth/login`（不要前导 `/`）。
- **需 Key**：是。

#### `folder_list`

- **用途**：列出已登记目录。
- **参数**：可选 `target`。

#### `api_move_folder` / `workflow_move_folder`

- **用途**：移动资源到目录；workflow 目标目录须已 `folder_ensure`。

---

### 4.2 接口（API）

#### `api_upsert`

- **用途**：创建或更新接口定义。
- **必填**：`name`、`method`、`url`。
- **常用可选**：`api_id`（更新）、`folder_path`、`headers`、`body`、`query`、`path_params`、`timeout_seconds`。
- **需 Key**：是。
- **示例**：

```json
{
  "tool": "api_upsert",
  "arguments": {
    "name": "用户登录",
    "folder_path": "auth",
    "method": "POST",
    "url": "/api/login",
    "headers": { "Content-Type": "application/json" },
    "body": { "username": "admin", "password": "{{password}}" },
    "query": {},
    "path_params": {}
  }
}
```

---

### 4.3 工作流（Workflow）

#### `workflow_upsert`

- **用途**：创建/更新完整 `definition`（Drawflow JSON）。
- **必填**：`name`、`definition`（`nodes`、`edges`、`variables`）。
- **需 Key**：是。
- **注意**：非空 `folder_path` 须先 `folder_ensure`（workflows）。

#### `workflow_get`

- **用途**：读取流程及各节点 `last_run`。

#### `workflow_patch_json`

- **用途**：对 `definition` / `variables` 等深度合并 patch；小改动优先于全量 upsert。

#### `workflow_validate`

- **用途**：检查节点 id、边是否引用合法；**upsert 前**建议调用。

#### `workflow_move_folder`

- **用途**：移动工作流到已登记目录。

#### `workflow_node_status`

- **用途**：单节点最近 `last_run`。

#### `workflow_analyze_last_run`

- **用途**：上次执行汇总（成功/失败节点 id）；细节不足时再 `workflow_get`。

---

### 4.4 执行

#### `workflow_run`

- **用途**：执行整条工作流。
- **必填**：`workflow_id`。
- **可选**：`base_url`（环境根地址）、`fail_fast`（默认 true）。
- **需 Key**：是。
- **返回**：`status`、`variables`、`results[]`（含每节点 request/response）、`run_id`。

#### `workflow_run_node`

- **用途**：只跑一个节点（调试参数）。
- **必填**：`workflow_id`、`node_id`。
- **需 Key**：是。

#### `workflow_run_replay`

- **用途**：按历史 run 内保存的 definition 快照重放。
- **必填**：`run_id`。
- **需 Key**：是。

---

### 4.5 跑批（Batch）

| 步骤 | 工具 | 说明 |
|------|------|------|
| 1 | `workflow_batch_create` | 建草稿，可带 `name`、`base_url`、`fail_fast` |
| 2 | `workflow_batch_update` | **必填** `batch_id`；设置 `workflow_ids: [1,2,3]` |
| 3 | `workflow_batch_run` | 执行，仅 `draft` 可跑 |
| 4 | `workflow_batch_get` | 查看结果及关联 `run_id` |

辅助：`workflow_batch_list`（`status` 过滤：draft|running|success|failed|partial）。

**需 Key**：create/update/run 需 Key；get/list 只读。

---

### 4.6 执行历史与日志

#### `workflow_run_list`

- **参数**：可选 `workflow_id`、`batch_id`、`limit`、`after_id`。
- **返回**：`items[]` 摘要（无完整 body 时用 `workflow_run_get`）。

#### `workflow_run_get`

- **参数**：`run_id`。
- **返回**：含 `payload`（`results`、`variables`、`workflow_snapshot`）。

#### `workflow_run_loki_link`

- **参数**：`run_id`、`node_id`（HTTP 节点）。
- **返回**：`explore_url`、`logql`、时间窗；未配 `GENERAL_LOKI_EXPLORE_URL` 时 `enabled=false`。

---

### 4.7 Mock 与其它

#### `mock_upsert`

- **用途**：按 `name` 创建/更新 Mock 数据集（`data` 对象）。
- **需 Key**：是。

#### `mcp_tool_upsert`

- **用途**：平台内「自定义 MCP 工具配置」表，**不是** Codex / Claude / Cursor 所见的内置 MCP 工具列表本身。

#### SSH 系列

| 工具 | 用途 |
|------|------|
| `ssh_tree` | 主机与脚本树 |
| `ssh_script_get` | 读脚本内容 |
| `ssh_script_upsert` | 创建/更新内联 bash（`profile_id`+`name`+`content`） |
| `ssh_script_run` | 远端执行（**需 password**，需 Key） |

---

## 5. 工作流 definition 约定（简版）

```json
{
  "nodes": [
    { "id": "n1", "position": {"x": 0, "y": 0}, "data": { "type": "http", "api_id": 1, "save_as": "resp1" } },
    { "id": "n2", "data": { "type": "extract", "source_var": "resp1", "field": "json.token", "save_as": "token" } }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "data": { "branch": "success" } }
  ],
  "variables": {}
}
```

| `data.type` | 说明 |
|-------------|------|
| `start` / `end` | 透传 |
| `http` | 引用 `api_id` 或内联 method/url/headers/body/query/path_params；支持 mock、expect |
| `extract` | 从 `source_var` 取 `field` 写入 `save_as` |
| `condition` | 出边 `branch`: `true` / `false`；支持 `left_mode=json_path` |
| `loop` | BODY 边进入子图；`while_*` 控制下一轮；DONE 边退出 |

变量替换：字符串中的 `{{token}}` 由 `variables` 注入。工作流级 `default_headers` 与节点 headers 合并，**节点覆盖同名 key**。

---

## 6. 调用协议

### 6.1 Codex / MCP 客户端（推荐）

- **端点**：`http://10.20.30.42:8000/mcp`（Streamable HTTP）
- **鉴权**：请求头 `Authorization: Bearer sto-...`（Codex 配置在个人 `config.toml` 的 `mcp_servers.<name>.http_headers`）
- **工具发现**：MCP 方法 `tools/list`（与 `MCP_TOOL_SPECS` 一致）
- **工具调用**：MCP 方法 `tools/call`（`name` + `arguments`）→ `content[0].text` 为 JSON 字符串，解析后字段为 `ok` / `tool` / `data` / `error`；失败时 `isError` 可能为 true

### 6.2 HTTP 网关（curl / CI）

- **发现**：`GET /mcp/tools` → `{ tools, require_api_key, ai_guide }`
- **单次**：`POST /mcp/invoke` → `{ ok, tool, data, error }`
- **批量**：`POST /mcp/invoke-batch` → `{ results: [...] }`，`stop_on_error: true` 时任一步失败即停

`ok=false` 时读 `error`，修正参数后重试；不要臆造未在 `tools/list` 中出现的工具名。

---

## 7. 推荐 Recipe

### R1：新建接口并跑通单接口流程

```
catalog_snapshot → folder_ensure(apis) → api_upsert
→ workflow_upsert → workflow_run → workflow_analyze_last_run
```

### R2：Apifox 迁移一批接口

```
catalog_snapshot → folder_ensure(apis, 模块路径)
→ invoke-batch: N × api_upsert → 核对 catalog
```

### R3：版本回归跑批

```
workflow_batch_create → workflow_batch_update(workflow_ids)
→ workflow_batch_run → workflow_batch_get
→ 对失败项 workflow_run_get + workflow_run_loki_link
```

### R4：失败节点最小修复

```
workflow_analyze_last_run → workflow_patch_json(只改变量/单节点 data)
→ workflow_run → 仍失败则 workflow_run_get 看 payload
```

---

## 8. 常见错误

| error / 现象 | 处理 |
|--------------|------|
| 401 MCP requires API Key | Codex：个人 `config.toml` 中配置 `Authorization: Bearer sto-...`；curl：请求头或 body `api_key` |
| workflow folder not registered | 先 `folder_ensure` workflows |
| 仅 draft 批次可执行 | 已对 running/success 的 batch 再 run |
| unknown mcp tool | `GET /mcp/tools` 刷新名称 |
| Loki enabled=false | 配置 `GENERAL_LOKI_EXPLORE_URL` |
| 重复接口 | 同 method+url 视为同一接口，更新时传 `api_id` |

---

## 9. 文档索引

| 文件 | 受众 |
|------|------|
| **本文** `docs/mcp_tools_for_ai.md` | **AI Agent（首选）** |
| `docs/mcp_quickstart.md` | 人类 + curl 示例 |
| `docs/mcp_install.md` | MCP Server 安装、Codex/内网/远程环境 |
| 项目根 `AGENTS.md` | Codex 自动加载的短指引 |

---

*文档版本：与 `MCP_TOOL_SPECS`（28 个工具）同步；接入方式为内置 Streamable HTTP `/mcp`，见 `docs/mcp_install.md`。*