初始化仓库：AI 接口自动化测试平台
纳入 FastAPI 后端、Vue 管理端、MCP 桥接与文档；通过 .gitignore 排除本地数据库与构建产物。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -0,0 +1,201 @@
|
||||
# 把本平台注册成真正的 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/ai_auto_test
|
||||
# 可选：生产/共享环境建议开启，所有 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/ai_auto_test/mcp_bridge.py"],
|
||||
"env": {
|
||||
"AI_TEST_BASE_URL": "http://127.0.0.1:8000",
|
||||
"AI_TEST_API_KEY": "sto-你的API密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `AI_TEST_BASE_URL`：平台后端地址。
|
||||
- `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/ai_auto_test/mcp_bridge.py"],
|
||||
"env": {
|
||||
"AI_TEST_BASE_URL": "http://127.0.0.1:8000",
|
||||
"AI_TEST_API_KEY": "sto-你的API密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 安装到 Codex CLI
|
||||
|
||||
```bash
|
||||
codex mcp add quality-inspection-platform \
|
||||
--command python3 \
|
||||
--args /Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py \
|
||||
--env AI_TEST_BASE_URL=http://127.0.0.1:8000 \
|
||||
--env AI_TEST_API_KEY=sto-你的API密钥
|
||||
```
|
||||
|
||||
或在 `~/.codex/config.toml` 中：
|
||||
|
||||
```toml
|
||||
[mcp.servers.quality-inspection-platform]
|
||||
command = "python3"
|
||||
args = ["/Users/qihongkun/work/My_app/ai_auto_test/mcp_bridge.py"]
|
||||
|
||||
[mcp.servers.quality-inspection-platform.env]
|
||||
AI_TEST_BASE_URL = "http://127.0.0.1:8000"
|
||||
AI_TEST_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":{}}}' \
|
||||
| AI_TEST_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`**
|
||||
@@ -0,0 +1,484 @@
|
||||
# MCP 快速接入与 AI 调用说明书
|
||||
|
||||
> **AI Agent 请优先阅读**：[mcp_tools_for_ai.md](./mcp_tools_for_ai.md)（工具决策表、鉴权、Recipe、节点约定）。
|
||||
> 本文档侧重 curl 示例与人工接入；项目根 [AGENTS.md](../AGENTS.md) 供 Codex 自动加载。
|
||||
|
||||
本文档给 AI Agent 和开发者使用，目标是让 AI 可以直接通过本平台的 MCP 接口完成：
|
||||
|
||||
- 接口创建/更新
|
||||
- Mock 数据创建/更新
|
||||
- Workflow JSON 创建/修改（含循环节点、条件分支）
|
||||
- 单次执行工作流 / 单节点调试
|
||||
- **跑批工作流**（先建任务、再选流程、再执行）
|
||||
- 执行结果分析
|
||||
- 批量编排调用
|
||||
|
||||
---
|
||||
|
||||
## 1. 基础信息
|
||||
|
||||
- 服务地址：`http://127.0.0.1:8000`
|
||||
- 工具发现：`GET /mcp/tools`
|
||||
- 单次调用：`POST /mcp/invoke`
|
||||
- 批量调用：`POST /mcp/invoke-batch`
|
||||
- MCP 鉴权：在平台右上角「个人中心」生成 `sto-` 开头的 API Key，配置到 MCP Bridge 环境变量 `AI_TEST_API_KEY`，或在请求头使用 `Authorization: Bearer <api_key>` / `X-API-Key: <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`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"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 导出结构一致：
|
||||
|
||||
```json
|
||||
{
|
||||
"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 通用调用模板
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
"tool": "tool_name",
|
||||
"arguments": {}
|
||||
}'
|
||||
```
|
||||
|
||||
### 4.2 批量调用模板
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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 自动创建接口
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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 数据
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "mock_upsert",
|
||||
"arguments": {
|
||||
"name": "demo_user",
|
||||
"data": {"uid": 1001, "token": "abc"}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 示例 C：AI 自动创建 Workflow（含条件分支）
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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 执行工作流并分析结果
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "workflow_analyze_last_run",
|
||||
"arguments": {"workflow_id": 1}
|
||||
}'
|
||||
```
|
||||
|
||||
### 示例 F：AI 批量编排（创建接口 → Mock → Patch → 执行）
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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：按目录分功能管理
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1: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 三步）
|
||||
|
||||
```bash
|
||||
# 1) 创建草稿批跑任务
|
||||
curl -s -X POST http://127.0.0.1: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://127.0.0.1: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://127.0.0.1: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://127.0.0.1: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（可直接复用）
|
||||
|
||||
```text
|
||||
你是本平台的自动化编排 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` 和本文档工具清单
|
||||
@@ -0,0 +1,357 @@
|
||||
# MCP 工具能力说明（AI 专用）
|
||||
|
||||
> **读者**：Cursor / Codex / Claude 等通过 `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（`Authorization: Bearer` 或桥接环境变量 `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. 如果当前客户端没有显示某个工具，先确认平台 `GET /mcp/tools` 是否包含该工具，再刷新或重启 MCP 客户端。
|
||||
6. 人类可读安装与 curl 示例见 `docs/mcp_quickstart.md`；桥接安装见 `docs/mcp_install.md`。
|
||||
|
||||
### 0.1 工具来源与客户端刷新
|
||||
|
||||
- 权威工具清单来自后端 `app/main.py` 的 `MCP_TOOL_SPECS`，平台通过 `GET /mcp/tools` 对外暴露。
|
||||
- `mcp_bridge.py` 启动后会从 `AI_TEST_BASE_URL/mcp/tools` 拉取工具并转换为 MCP `tools/list`。
|
||||
- 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 平台地址
|
||||
|
||||
MCP Bridge 通过环境变量访问平台：
|
||||
|
||||
| 环境变量 | 含义 | 示例 |
|
||||
|----------|------|------|
|
||||
| `AI_TEST_BASE_URL` | 质量检测平台后端地址 | `http://127.0.0.1:8000` |
|
||||
| `AI_TEST_API_KEY` | `sto-` 开头的 API Key | `sto-...` |
|
||||
|
||||
Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服务；平台进程由质量检测平台项目本身或共享服务负责。
|
||||
|
||||
### 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. 工具清单（按分类）
|
||||
|
||||
### 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 工具配置」表，**不是**本桥接工具列表本身。
|
||||
|
||||
#### 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. 调用协议
|
||||
|
||||
- **发现**：`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 | 配置 `AI_TEST_API_KEY` 或请求头 Bearer |
|
||||
| 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 桥接安装 |
|
||||
| 项目根 `AGENTS.md` | Codex 自动加载的短指引 |
|
||||
|
||||
---
|
||||
|
||||
*文档版本：与仓库 `MCP_TOOL_SPECS` 同步（含 workflow_run_* / workflow_validate / 执行类鉴权）。*
|
||||
Reference in New Issue
Block a user