quality-inspection-platform/docs/mcp_quickstart.md

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

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

## 接入方式选择

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

---

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

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

```text
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 服务端启动

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

```bash
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
```

启动后检查：

```bash
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`：

```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、端口或域名：

```toml
[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 地址为准。团队默认写：

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

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

### 0.4 Cursor 配置（可选）

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

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

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

```json
{
  "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：

```text
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 迁移

旧配置：

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

新配置：

```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密钥"
```

完整安装、团队协作、systemd 与排障说明见 [mcp_install.md](./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](./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`）：

```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://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 批量调用模板

```bash
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 自动创建接口

```bash
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 数据

```bash
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（含条件分支）

```bash
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

```bash
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 执行工作流并分析结果

```bash
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
    }
  }'
```

```bash
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 → 执行）

```bash
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：按目录分功能管理

```bash
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 三步）

```bash
# 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（可直接复用）

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