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。

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：是。
• 示例：

{
  "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 约定（简版）

{
  "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。