quality-inspection-platform/docs/mcp_quickstart.md

MCP 快速接入与 AI 调用说明书

AI Agent 请优先阅读：mcp_tools_for_ai.md（工具决策表、鉴权、Recipe、节点约定）。
Codex / 内网安装：mcp_install.md（~/.codex/config.toml、团队协作、排障）。
本文档侧重 HTTP curl 与脚本调用；项目根 AGENTS.md 供 Codex 自动加载。

接入方式选择

方式	端点	适用
MCP 协议（推荐）	http://10.20.30.42:8000/mcp	Codex、Claude、Cursor，见 mcp_install.md
HTTP 网关（本文）	/mcp/tools、/mcp/invoke	curl、CI、自研 Agent
Web UI	/api/*	浏览器人工操作

---

0. MCP 安装与接入（团队必读）

平台现在直接在同一个 uvicorn 进程内提供标准 MCP Server：

Web UI:      http://10.20.30.42:8000/
MCP Server:  http://10.20.30.42:8000/mcp
HTTP 网关:   http://10.20.30.42:8000/mcp/tools、/mcp/invoke

已移除旧版 mcp_bridge.py；不再需要为 Codex / Claude / Cursor 额外启动本机 Python 桥接进程。客户端直接连接 http://10.20.30.42:8000/mcp。

0.1 服务端启动

管理员或本地开发者启动平台：

cd /path/to/quality-inspection-platform
python3 -m venv .venv
source .venv/bin/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

启动后检查：

curl -s http://10.20.30.42:8000/health
curl -s http://10.20.30.42:8000/mcp/tools \
  -H "Authorization: Bearer sto-你的API密钥"

0.2 Codex 配置

编辑 ~/.codex/config.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密钥"

团队默认 MCP 地址为 10.20.30.42:8000。如果 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密钥"

配置完成后重启 Codex 会话或 Codex 应用，让 MCP 配置重新加载。验证方式是在对话中要求调用 catalog_snapshot。

0.3 Codex Remote / 远程环境

如果 Codex 运行在远程主机或远程工作区，~/.codex/config.toml 要配置在 Codex 实际运行的那台机器上。

如果 Codex 运行在远程机器上，URL 仍以 Codex 所在机器能访问到的 MCP 地址为准。团队默认写：

url = "http://10.20.30.42:8000/mcp"

如果你改成其他部署地址，需要先在 Codex 所在机器上确认该地址可访问。

0.4 Cursor 配置（可选）

如果团队中有人使用 Cursor，再配置 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "quality-inspection-platform": {
      "url": "http://10.20.30.42:8000/mcp",
      "headers": {
        "Authorization": "Bearer sto-你的API密钥"
      }
    }
  }
}

部分 Cursor 版本需要显式指定传输类型：

{
  "mcpServers": {
    "quality-inspection-platform": {
      "type": "streamableHttp",
      "url": "http://10.20.30.42:8000/mcp",
      "headers": {
        "Authorization": "Bearer sto-你的API密钥"
      }
    }
  }
}

Cursor Remote-SSH 时，mcp.json 要配置在远程主机的 ~/.cursor/mcp.json，不是本机。

0.5 Claude

Claude Desktop 使用 HTTP URL 连接 MCP：

URL: http://10.20.30.42:8000/mcp
Header: Authorization: Bearer sto-你的API密钥

具体字段名按 Claude 当前 MCP 配置格式填写。优先使用 Streamable HTTP / URL 型 MCP，不再配置 command + args + mcp_bridge.py。

0.6 API Key 获取与安全

1. 浏览器登录 Web UI。
2. 右上角进入「个人中心」。
3. 创建 sto- 开头的 API Key。
4. 写入 MCP 客户端配置的 Authorization: Bearer sto-...。

写操作和执行类工具必须带有效 Key；生产环境建议设置 MCP_REQUIRE_API_KEY=true，让只读工具也必须鉴权。API Key 不要提交到 Git，不要写入共享文档。

0.7 旧版 bridge 迁移

旧配置：

{
  "command": "python3",
  "args": ["/path/to/mcp_bridge.py"],
  "env": {
    "QIP_BASE_URL": "http://10.20.30.42:8000",
    "QIP_API_KEY": "sto-..."
  }
}

新配置：

[mcp_servers.quality-inspection-platform]
url = "http://10.20.30.42:8000/mcp"

[mcp_servers.quality-inspection-platform.http_headers]
Authorization = "Bearer sto-你的API密钥"

完整安装、团队协作、systemd 与排障说明见 mcp_install.md。

---

本文档给开发者和自动化脚本使用，目标是让调用方通过 HTTP 网关完成：

• 接口创建/更新
• Mock 数据创建/更新
• Workflow JSON 创建/修改（含循环节点、条件分支）
• 单次执行工作流 / 单节点调试
• 跑批工作流（先建任务、再选流程、再执行）
• 执行结果分析
• 批量编排调用

---

1. 基础信息

• 服务地址：http://10.20.30.42:8000
• Codex MCP 端点：http://10.20.30.42:8000/mcp（Streamable HTTP，见 mcp_install.md）
• 工具发现（HTTP 兼容）：GET /mcp/tools
• 单次调用（HTTP 兼容）：POST /mcp/invoke
• 批量调用：POST /mcp/invoke-batch
• MCP 鉴权：在平台右上角「个人中心」生成 sto- 开头的 API Key；Codex 在 ~/.codex/config.toml 的 http_headers.Authorization 中配置，curl/脚本可用 Authorization: Bearer <api_key> / X-API-Key: <api_key>（body 字段 api_key 仍兼容）。
• 写操作（创建/更新资源）与 执行类操作（跑工作流、批跑、单节点、SSH 执行、重放）必须带有效 Key，禁止无 Key 回落为 superadmin。
• 可选 MCP_REQUIRE_API_KEY=true（后端环境变量）：所有 MCP 工具（含只读）均要求 Key；GET /mcp/tools 同样校验。

需要 API Key 的写操作：folder_ensure、api_upsert、workflow_upsert、workflow_patch_json、workflow_move_folder、api_move_folder、mock_upsert、mcp_tool_upsert、ssh_script_upsert、workflow_batch_create、workflow_batch_update

需要 API Key 的执行操作：workflow_run、workflow_run_node、workflow_batch_run、workflow_run_replay、ssh_script_run

统一返回结构（/mcp/invoke）：

{
  "ok": true,
  "tool": "tool_name",
  "data": {},
  "error": null
}

---

2. 当前可用 MCP 工具

资源与工作流

工具	用途	关键参数
api_upsert	创建或更新接口	name, method, url；可选 api_id, headers, body, query, path_params, timeout_seconds, folder_path
mock_upsert	创建或更新 Mock	name, data
workflow_upsert	创建或更新工作流 JSON	name, definition；可选 workflow_id, folder_path
workflow_get	读取完整工作流（含各节点 last_run）	workflow_id
workflow_node_status	读取单节点最近执行状态	workflow_id, node_id
workflow_patch_json	对工作流 definition 深度合并 patch	workflow_id, patch
workflow_run	执行整个工作流	workflow_id；可选 base_url, fail_fast
workflow_run_node	执行单个节点	workflow_id, node_id；可选 base_url
workflow_analyze_last_run	分析最近一次执行摘要	workflow_id
workflow_run_list	执行历史列表	可选 workflow_id、batch_id、limit、after_id
workflow_run_get	单次执行详情（含完整 payload）	run_id
workflow_run_replay	按历史快照重放	run_id；可选 base_url、fail_fast
workflow_run_loki_link	生成 Loki Explore 链接	run_id、node_id
workflow_validate	校验 definition JSON	definition

跑批工作流（推荐顺序见 §5 示例 H）

工具	用途	关键参数
workflow_batch_create	创建批跑任务（draft）	可选 name, base_url, fail_fast, workflow_ids
workflow_batch_update	更新草稿批跑任务	batch_id；可选 name, base_url, fail_fast, workflow_ids
workflow_batch_run	执行批跑（按 workflow_ids 顺序跑多个工作流）	batch_id
workflow_batch_get	批跑详情（含关联的 workflow_runs）	batch_id
workflow_batch_list	列出当前用户的批跑任务	可选 limit, after_id, status（draft/running/success/failed/partial）

跑批 MCP 约定：必须先 workflow_batch_create（或 create 时带上 workflow_ids），再 workflow_batch_update 绑定工作流，最后 workflow_batch_run。不要跳过草稿阶段直接「匿名批量跑」。

目录管理

工具	用途
folder_ensure	创建/登记目录（target: apis / workflows，path）
folder_list	列出目录
api_move_folder	移动接口到目录（api_id, folder_path）
workflow_move_folder	移动工作流到目录（workflow_id, folder_path）

全局与其它

工具	用途
catalog_snapshot	一次返回 APIs / Workflows / Mocks / workflow_batches / MCP 配置及 SSH 树
mcp_tool_upsert	创建或更新 MCP 工具配置

SSH 脚本管理

工具	用途
ssh_tree	SSH 主机与脚本树
ssh_script_get	读取脚本详情
ssh_script_upsert	创建/更新内联 bash 脚本（name, content；创建需 profile_id，更新需 script_id）
ssh_script_run	远端执行脚本（profile_id, script_id, password；可选 timeout_seconds）

---

3. 工作流节点与连线约定

workflow_upsert / workflow_patch_json 中的 definition 与前端 Drawflow 导出结构一致：

{
  "nodes": [{ "id": "n1", "position": {"x": 0, "y": 0}, "data": { "type": "http", ... } }],
  "edges": [{ "id": "e1", "source": "n1", "target": "n2", "label": "success", "data": { "branch": "success" } }],
  "variables": {}
}

节点类型

data.type	说明
start / end	透传，无 HTTP
http	发请求；可内联 method/url/headers/body/query/path_params，或 api_id；支持 mock、expect
extract	从变量提取字段写入新变量
condition	条件分支：连线 data.branch 为 true / false（或 label IF/ELSE）
loop	循环体：从 loop 节点连出的 BODY 边进入子图，多轮执行后再走 DONE

条件节点（condition）

• left_mode / right_mode：template（默认，变量替换后比较）或 json_path（从 left_source_var 对应响应里按 left_field 取 JSON 路径值）。
• op：==、!=、>、<、contains 等。
• 出边：edge.data.branch 为 true / false（引擎也识别 label 中的 IF/ELSE）。

循环节点（loop）

• BODY 边：edge.data.branch 取 body、loop、in、next、continue 之一（或空字符串），目标节点构成循环体子图。
• DONE 边：branch 为 done、out、exit、end 等，循环结束后继续主流程。
• 节点字段示例：
  • max_iterations：最大轮数（默认 10）
  • iteration_var：每轮写入变量的下标名（默认 loop_index）
  • while_left_mode / while_left / while_left_source_var / while_left_field / while_op / while_right_*：每轮 BODY 执行完后判断是否继续下一轮（语义同 condition，支持 json_path）

HTTP 出边分支

• 成功：branch: success
• 失败：branch: failed

---

4. AI 调用协议（推荐）

4.1 通用调用模板

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "tool_name",
    "arguments": {}
  }'

4.2 批量调用模板

curl -s -X POST http://10.20.30.42:8000/mcp/invoke-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "stop_on_error": true,
    "calls": [
      {"tool": "tool_a", "arguments": {}},
      {"tool": "tool_b", "arguments": {}}
    ]
  }'

---

5. 常见 AI 任务示例

示例 A：AI 自动创建接口

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "api_upsert",
    "arguments": {
      "name": "登录接口",
      "method": "POST",
      "url": "/api/login",
      "headers": {"token": "{{token}}"},
      "body": {"username": "admin", "password": "123456"},
      "query": {},
      "path_params": {},
      "timeout_seconds": 10
    }
  }'

示例 B：AI 自动创建 Mock 数据

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "mock_upsert",
    "arguments": {
      "name": "demo_user",
      "data": {"uid": 1001, "token": "abc"}
    }
  }'

示例 C：AI 自动创建 Workflow（含条件分支）

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "workflow_upsert",
    "arguments": {
      "name": "登录流程",
      "definition": {
        "nodes": [
          {"id": "n1", "position": {"x": 120, "y": 120}, "data": {"type": "http", "api_id": 1, "save_as": "login_resp"}},
          {"id": "n2", "position": {"x": 380, "y": 120}, "data": {"type": "extract", "source_var": "login_resp", "field": "json.token", "save_as": "token"}},
          {"id": "n3", "position": {"x": 640, "y": 120}, "data": {"type": "condition", "left_mode": "json_path", "left_source_var": "login_resp", "left_field": "json.code", "op": "==", "right": "0"}}
        ],
        "edges": [
          {"id": "e1", "source": "n1", "target": "n2", "label": "success", "data": {"branch": "success"}},
          {"id": "e2", "source": "n2", "target": "n3"},
          {"id": "e3", "source": "n3", "target": "n4", "label": "IF", "data": {"branch": "true"}},
          {"id": "e4", "source": "n3", "target": "n5", "label": "ELSE", "data": {"branch": "false"}}
        ],
        "variables": {}
      }
    }
  }'

示例 D：AI 自动 Patch Workflow JSON

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "workflow_patch_json",
    "arguments": {
      "workflow_id": 1,
      "patch": {
        "variables": {"env": "test"}
      }
    }
  }'

示例 E：AI 执行工作流并分析结果

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "workflow_run",
    "arguments": {
      "workflow_id": 1,
      "base_url": "http://127.0.0.1:8080",
      "fail_fast": true
    }
  }'

curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "workflow_analyze_last_run",
    "arguments": {"workflow_id": 1}
  }'

示例 F：AI 批量编排（创建接口 → Mock → Patch → 执行）

curl -s -X POST http://10.20.30.42:8000/mcp/invoke-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "stop_on_error": true,
    "calls": [
      {
        "tool": "api_upsert",
        "arguments": {
          "name": "用户详情接口",
          "method": "GET",
          "url": "/api/user/{uid}",
          "headers": {"token": "{{token}}"},
          "query": {},
          "path_params": {"uid": "{{uid}}"}
        }
      },
      {
        "tool": "mock_upsert",
        "arguments": {
          "name": "seed_user",
          "data": {"uid": 1001, "token": "abc"}
        }
      },
      {
        "tool": "workflow_patch_json",
        "arguments": {
          "workflow_id": 1,
          "patch": {"variables": {"uid": 1001, "token": "abc"}}
        }
      },
      {
        "tool": "workflow_run",
        "arguments": {"workflow_id": 1, "base_url": "http://127.0.0.1:8080", "fail_fast": true}
      }
    ]
  }'

示例 G：按目录分功能管理

curl -s -X POST http://10.20.30.42:8000/mcp/invoke-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "stop_on_error": true,
    "calls": [
      {"tool": "folder_ensure", "arguments": {"target": "apis", "path": "auth/login"}},
      {"tool": "folder_ensure", "arguments": {"target": "workflows", "path": "auth/smoke"}},
      {
        "tool": "api_upsert",
        "arguments": {
          "name": "登录接口",
          "folder_path": "auth/login",
          "method": "POST",
          "url": "/api/login",
          "body": {"username": "admin", "password": "123456"}
        }
      },
      {
        "tool": "workflow_upsert",
        "arguments": {
          "name": "登录冒烟",
          "folder_path": "auth/smoke",
          "definition": {"nodes": [], "edges": [], "variables": {}}
        }
      }
    ]
  }'

示例 H：跑批工作流（MCP 三步）

# 1) 创建草稿批跑任务
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "workflow_batch_create",
    "arguments": {
      "name": "nightly-smoke",
      "base_url": "http://127.0.0.1:8080",
      "fail_fast": false
    }
  }'

# 假设返回 data.id = 3

# 2) 绑定要执行的工作流 ID 列表
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sto-api-key>" \
  -d '{
    "tool": "workflow_batch_update",
    "arguments": {
      "batch_id": 3,
      "workflow_ids": [1, 2, 5]
    }
  }'

# 3) 执行批跑
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "workflow_batch_run",
    "arguments": {"batch_id": 3}
  }'

# 4) 查询结果（含每次 workflow_run 的 run_id）
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "workflow_batch_get",
    "arguments": {"batch_id": 3}
  }'

也可用 invoke-batch 将 create + update + run 串在一次请求里（stop_on_error: true 时任一步失败即中断）。

---

6. Loki 环境变量

Loki 相关环境变量（后端 app/services/loki.py）：

变量	说明
GENERAL_LOKI_EXPLORE_URL 或 LOKI_EXPLORE_URL	Grafana Explore 页基础 URL（必填其一才生成链接）
LOKI_DATASOURCE	数据源名，默认 Loki
LOKI_ORG_ID	组织 ID，默认 1
LOKI_LABEL_SELECTOR	完整 LogQL 标签选择器；未设则用 LOKI_SERVICE_LABEL / LOKI_SERVICE_VALUE
LOKI_TIME_PADDING_SECONDS	执行时间窗口前后扩展秒数，默认 120

---

7. AI 调用策略建议

推荐执行顺序（单工作流调试）

1. catalog_snapshot 读取现状
2. api_upsert / mock_upsert 补全资源
3. workflow_upsert 或 workflow_patch_json 组装流程
4. workflow_run 或 workflow_run_node 执行
5. workflow_analyze_last_run / workflow_get 分析
6. 根据失败节点二次 patch + 重跑

推荐执行顺序（跑批）

1. catalog_snapshot 确认 workflow_id 列表
2. workflow_batch_create（草稿）
3. workflow_batch_update（写入 workflow_ids、base_url、fail_fast）
4. workflow_batch_run
5. workflow_batch_get 汇总；排错用 workflow_run_get / workflow_run_replay / workflow_run_loki_link

失败处理策略

• ok=false：优先读取 error，只修最小必要字段后重试
• 工具不存在：先调用 GET /mcp/tools 刷新工具列表
• JSON 错误：确保 arguments 中对象字段是 JSON 对象（不是字符串）
• 运行失败：先看 failed_nodes，再做针对性 patch，不要全量重建 workflow
• 批跑 partial：用 workflow_batch_get 里每条 run 的 status 定位失败工作流

---

8. 给 AI 的最小 Prompt（可直接复用）

你是本平台的自动化编排 Agent。
目标：最小改动下让 workflow / 批跑 执行成功。

单工作流：
1) catalog_snapshot
2) 缺什么补什么（api_upsert / mock_upsert / workflow_patch_json）
3) workflow_run
4) workflow_analyze_last_run
5) 失败则只修失败节点相关配置后重试

跑批：
1) workflow_batch_create
2) workflow_batch_update（workflow_ids）
3) workflow_batch_run
4) workflow_batch_get 核对每条 run

约束：保持 JSON 可读、禁止无关改动、每步输出工具调用和结果摘要。
写操作必须带 sto- API Key。

---

9. 版本说明

• 文档对应：app/main.py 中 MCP_TOOL_SPECS 与 /mcp/invoke 实现
• 跑批、循环节点、json_path 条件、Loki 链接为当前仓库已上线能力
• 若后续新增工具，请同步更新 /mcp/tools 和本文档工具清单