qihongkun a41f61bcf6 重命名项目为 quality-inspection-platform

将仓库目录从 ai_auto_test 迁至 quality-inspection-platform，统一质量检测平台命名；MCP 环境变量新增 QIP_* 并兼容 AI_TEST_*。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-22 15:49:59 +08:00

6.4 KiB

Raw Blame History

把本平台注册成真正的 MCP Server

本仓库已附带 mcp_bridge.py，它是一个标准 stdio MCP Server，
对外暴露 MCP 协议（JSON-RPC over stdio），内部桥接到本平台的 HTTP 网关。

只要先启动平台后端，再让 Cursor / Claude Desktop / Codex CLI 启动这个桥接，
它就会被识别成一个真正的 MCP Server，并自动暴露所有平台工具（含跑批工作流工具）。

1. 启动平台后端

cd /Users/qihongkun/work/My_app/quality-inspection-platform
# 可选：生产/共享环境建议开启，所有 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（不存在则新建），加入：

{
  "mcpServers": {
    "quality-inspection-platform": {
      "command": "python3",
      "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"],
      "env": {
        "QIP_BASE_URL": "http://127.0.0.1:8000",
        "QIP_API_KEY": "sto-你的API密钥"
      }
    }
  }
}

QIP_BASE_URL：平台后端地址（兼容旧环境变量 AI_TEST_BASE_URL）。
QIP_API_KEY：必须配置（兼容旧名 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：

{
  "mcpServers": {
    "quality-inspection-platform": {
      "command": "python3",
      "args": ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"],
      "env": {
        "QIP_BASE_URL": "http://127.0.0.1:8000",
        "QIP_API_KEY": "sto-你的API密钥"
      }
    }
  }
}

4. 安装到 Codex CLI

codex mcp add quality-inspection-platform \
  --command python3 \
  --args /Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py \
  --env QIP_BASE_URL=http://127.0.0.1:8000 \
  --env QIP_API_KEY=sto-你的API密钥

或在 ~/.codex/config.toml 中：

[mcp.servers.quality-inspection-platform]
command = "python3"
args = ["/Users/qihongkun/work/My_app/quality-inspection-platform/mcp_bridge.py"]

[mcp.servers.quality-inspection-platform.env]
QIP_BASE_URL = "http://127.0.0.1:8000"
QIP_API_KEY = "sto-你的API密钥"

5. 自检（不连客户端，先确认桥接可用）

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":{}}}' \
  | QIP_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。

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

6.4 KiB Raw Blame History Unescape Escape