open-source/quality-inspection-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
32cfb20999
quality-inspection-platform/docs/mcp_quickstart.md
qihongkun f5143aee09 feat: 添加 Docker 部署支持和 MCP 原生集成 
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置
- 新增 MCP 原生集成模块 (mcp_native.py)
- 移除旧的 mcp_bridge.py，更新依赖和文档
- 添加部署文档 (Docker 和服务器部署指南)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-25 14:21:43 +08:00

21 KiB
Raw Blame History

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 和本文档工具清单