feat: 添加 Docker 部署支持和 MCP 原生集成
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置 - 新增 MCP 原生集成模块 (mcp_native.py) - 移除旧的 mcp_bridge.py，更新依赖和文档 - 添加部署文档 (Docker 和服务器部署指南) Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -0,0 +1,242 @@
|
||||
# Docker / Docker Compose 部署
|
||||
|
||||
在 **CentOS 7** 或其它 Linux 上，用容器自带 Python 3.11，**无需**在宿主机安装 Python 3.11 / Node。
|
||||
|
||||
---
|
||||
|
||||
## 0. 宿主机准备
|
||||
|
||||
### CentOS 7 安装 Docker
|
||||
|
||||
```bash
|
||||
sudo yum install -y yum-utils
|
||||
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
|
||||
sudo yum install -y docker-ce docker-ce-cli containerd.io
|
||||
|
||||
sudo systemctl enable docker
|
||||
sudo systemctl start docker
|
||||
|
||||
# Compose 插件（v2）
|
||||
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" \
|
||||
-o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
docker compose version
|
||||
```
|
||||
|
||||
内网无法访问外网时，请改用内网镜像源或离线 rpm 包。
|
||||
|
||||
---
|
||||
|
||||
## 1. 上传源码到服务器
|
||||
|
||||
**方式 A：Git**
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/quality-inspection-platform
|
||||
sudo chown -R "$USER":"$USER" /opt/quality-inspection-platform
|
||||
cd /opt/quality-inspection-platform
|
||||
git clone <内网仓库地址> .
|
||||
```
|
||||
|
||||
**方式 B：本机打包上传（无 Git 时）**
|
||||
|
||||
在本机项目根目录：
|
||||
|
||||
```bash
|
||||
tar czf qip-src.tar.gz \
|
||||
--exclude='.venv' --exclude='node_modules' --exclude='frontend-admin/dist' \
|
||||
--exclude='ai_test.db' --exclude='.git' \
|
||||
.
|
||||
scp qip-src.tar.gz user@<服务器>:/tmp/
|
||||
```
|
||||
|
||||
在服务器上：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/quality-inspection-platform
|
||||
sudo tar xzf /tmp/qip-src.tar.gz -C /opt/quality-inspection-platform
|
||||
sudo chown -R "$USER":"$USER" /opt/quality-inspection-platform
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
vi .env # 修改 AUTH_TOKEN_SECRET、DEFAULT_SUPERADMIN_PASSWORD 等
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 准备数据目录
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /docker_data
|
||||
sudo chown -R "$(id -u)":"$(id -g)" /docker_data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 在服务器上构建并启动
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
|
||||
docker compose build
|
||||
docker compose up -d
|
||||
|
||||
docker compose ps
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8000/health
|
||||
# {"ok":true}
|
||||
|
||||
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/
|
||||
# 200
|
||||
```
|
||||
|
||||
浏览器：`http://<服务器IP>:8000/`
|
||||
默认账号见 `.env` 中 `DEFAULT_SUPERADMIN_*`。
|
||||
|
||||
MCP（Cursor）：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"quality-inspection-platform": {
|
||||
"url": "http://<服务器IP>:8000/mcp",
|
||||
"headers": { "Authorization": "Bearer sto-你的密钥" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据持久化（宿主机 `/docker_data`）
|
||||
|
||||
默认把宿主机的 **`/docker_data`** 挂载到容器 **`/data`**：
|
||||
|
||||
| 宿主机路径 | 容器路径 | 内容 |
|
||||
|------------|----------|------|
|
||||
| `/docker_data/ai_test.db` | `/data/ai_test.db` | SQLite 数据库 |
|
||||
| `/docker_data/ssh-scripts/` | `/data/ssh-scripts/` | SSH 内联脚本等 |
|
||||
|
||||
部署前在服务器上准备目录：
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /docker_data
|
||||
# 官方 python:3.11-slim 镜像内进程用户多为 root；若以后改用非 root 用户，再改属主
|
||||
sudo chown -R "$(id -u)":"$(id -g)" /docker_data
|
||||
```
|
||||
|
||||
改用其它目录时，在 `.env` 中设置：
|
||||
|
||||
```bash
|
||||
QIP_DATA_HOST_DIR=/your/path
|
||||
```
|
||||
|
||||
备份数据库（直接在宿主机）：
|
||||
|
||||
```bash
|
||||
cp /docker_data/ai_test.db /docker_data/ai_test.db.bak.$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 常用命令
|
||||
|
||||
```bash
|
||||
# 停止
|
||||
docker compose down
|
||||
|
||||
# 重启
|
||||
docker compose restart
|
||||
|
||||
# 升级（拉代码后）
|
||||
git pull
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
|
||||
# 进入容器
|
||||
docker compose exec quality-inspection-platform sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 防火墙（CentOS 7）
|
||||
|
||||
```bash
|
||||
sudo firewall-cmd --permanent --add-port=8000/tcp
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 架构说明
|
||||
|
||||
```
|
||||
Dockerfile（多阶段）
|
||||
├─ node:20 → npm run build → frontend-admin/dist
|
||||
└─ python:3.11 → pip install + uvicorn
|
||||
卷 /data → SQLite + SSH 脚本目录
|
||||
```
|
||||
|
||||
- 镜像内已包含前端静态资源，**宿主机不需要 Node**。
|
||||
- 镜像内已包含 Python 与 `mcp` 依赖，**宿主机不需要 Python 3.11**。
|
||||
|
||||
---
|
||||
|
||||
## 10. 排障
|
||||
|
||||
### 10.1 `lookup docker.mirrors.ustc.edu.cn: no such host`
|
||||
|
||||
说明 Docker 配置了**已失效或内网不可达的镜像加速**，且 DNS 解析失败。
|
||||
|
||||
**处理：** 编辑 `/etc/docker/daemon.json`（没有则新建），去掉或更换 `registry-mirrors`：
|
||||
|
||||
```json
|
||||
{
|
||||
"registry-mirrors": []
|
||||
}
|
||||
```
|
||||
|
||||
或改成你们内网可访问的镜像地址。然后：
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart docker
|
||||
docker compose build
|
||||
```
|
||||
|
||||
本仓库 `Dockerfile` 已去掉 `# syntax=docker/dockerfile:1`，避免额外拉取 `docker/dockerfile:1`（在劣质网络下常失败）。
|
||||
|
||||
### 10.2 完全无法访问 Docker Hub
|
||||
|
||||
需任选其一：
|
||||
|
||||
- 配置**内网 Harbor / registry 代理**，在能联网的机器 `docker pull node:20-bookworm-slim python:3.11-slim-bookworm` 后 `docker save`，传到服务器 `docker load`
|
||||
- 让运维开放对 `registry-1.docker.io` 或可靠镜像站的访问
|
||||
|
||||
### 10.3 其它
|
||||
|
||||
| 现象 | 处理 |
|
||||
|------|------|
|
||||
| `git was not found`（WARN） | 可忽略；或 `yum install -y git` |
|
||||
| 前端 503 | `docker compose build --no-cache` |
|
||||
| MCP 连不上 | `.env` 中 `QIP_MCP_DISABLE_DNS_PROTECTION=true` |
|
||||
| `/docker_data` 无写权限 | `chown` 见 §3 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 相关文档
|
||||
|
||||
- 裸机部署（不用 Docker）：[deploy_server.md](./deploy_server.md)
|
||||
- MCP 配置：[mcp_install.md](./mcp_install.md)
|
||||
@@ -0,0 +1,481 @@
|
||||
# 服务器部署完整步骤（Linux）
|
||||
|
||||
本文假设在 **一台内网 Linux 服务器** 上从零部署，所有命令均在服务器上执行（通过 SSH 登录）。
|
||||
|
||||
- 部署目录示例：`/opt/quality-inspection-platform`
|
||||
- 运行用户示例：`qip`（可改成你的业务用户）
|
||||
- 监听端口：`8000`（也可用 Nginx 反代 80/443）
|
||||
|
||||
**CentOS 7 用户**：
|
||||
|
||||
- **推荐**：用 Docker，无需在宿主机装 Python 3.11 → **[deploy_docker.md](./deploy_docker.md)**
|
||||
- 裸机部署：系统自带 Python 3.6 不够用 → **[§1B CentOS 7](#1b-安装系统依赖-centos-7)**，再从 [§2](#2-创建运行用户与目录) 继续
|
||||
|
||||
---
|
||||
|
||||
## 0. 部署前确认
|
||||
|
||||
| 项目 | 要求 |
|
||||
|------|------|
|
||||
| 系统 | **CentOS 7**（见 §1B）或 Ubuntu 20.04+ / Debian 11+（见 §1A） |
|
||||
| Python | **3.10+**（必须，用于 `mcp` / FastAPI） |
|
||||
| Node | **18+**（仅构建 `frontend-admin` 时需要） |
|
||||
| 权限 | 能 `sudo` 安装软件、创建用户 |
|
||||
| 网络 | 能访问内网 Git；`npm` / `pip` 可用（或本机构建 `dist` 后上传） |
|
||||
| 磁盘 | 预留 ≥2GB |
|
||||
|
||||
**交付能力（一个 `uvicorn` 进程）**：
|
||||
|
||||
- Web 管理端：`http://<服务器>:8000/`
|
||||
- API：`/api/*`
|
||||
- MCP（Cursor/Codex）：`http://<服务器>:8000/mcp`
|
||||
- 数据文件：项目根目录 `ai_test.db`（SQLite，需备份）
|
||||
|
||||
---
|
||||
|
||||
## 1A. 安装系统依赖（Ubuntu / Debian）
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y git curl ca-certificates \
|
||||
python3 python3-venv python3-pip \
|
||||
nodejs npm
|
||||
```
|
||||
|
||||
检查版本：
|
||||
|
||||
```bash
|
||||
python3 --version # 须 >= 3.10
|
||||
node --version # 建议 >= 18
|
||||
```
|
||||
|
||||
若 `python3` 低于 3.10，请安装更新的 Python 后再继续。
|
||||
若 `nodejs` 过旧，改用 [NodeSource](https://github.com/nodesource/distributions) 安装 18+。
|
||||
|
||||
---
|
||||
|
||||
## 1B. 安装系统依赖（CentOS 7）
|
||||
|
||||
CentOS 7 默认 `python3` 为 3.6，**无法直接运行本项目**。推荐用 **IUS 的 Python 3.11** + **NodeSource 18**。
|
||||
|
||||
### 1B.1 基础工具与编译依赖
|
||||
|
||||
```bash
|
||||
sudo yum install -y epel-release
|
||||
sudo yum install -y git curl ca-certificates gcc make \
|
||||
openssl-devel bzip2-devel libffi-devel zlib-devel \
|
||||
readline-devel sqlite-devel
|
||||
```
|
||||
|
||||
### 1B.2 安装 Python 3.11（IUS）
|
||||
|
||||
```bash
|
||||
# 若服务器不能访问外网，请改用内网 yum 源或在本机构好 wheel 再上传
|
||||
sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
|
||||
sudo yum install -y python311 python311-pip python311-devel
|
||||
|
||||
python3.11 --version # 应显示 3.11.x
|
||||
```
|
||||
|
||||
后续所有 `python3` / `pip` 命令在 CentOS 7 上请写成 **`python3.11`** / **`python3.11 -m pip`**。
|
||||
|
||||
### 1B.3 安装 Node.js 18（构建前端）
|
||||
|
||||
```bash
|
||||
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
|
||||
sudo yum install -y nodejs
|
||||
|
||||
node --version # 应 >= v18
|
||||
npm --version
|
||||
```
|
||||
|
||||
**无法访问 NodeSource 时**：在开发机 `npm run build` 后，只把 `frontend-admin/dist/` 上传到服务器，可跳过 Node 安装（见 §5 说明）。
|
||||
|
||||
### 1B.4（可选）用 SCL Python 3.8 的说明
|
||||
|
||||
部分环境只有 `rh-python38`（3.8），可能装不上新版 `mcp` 包。**不推荐** CentOS 7 用 3.8 跑本仓库；请优先 3.11。
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 2. 创建运行用户与目录
|
||||
|
||||
```bash
|
||||
sudo useradd -r -m -d /opt/qip -s /bin/bash qip 2>/dev/null || true
|
||||
sudo mkdir -p /opt/quality-inspection-platform
|
||||
sudo chown -R qip:qip /opt/quality-inspection-platform
|
||||
```
|
||||
|
||||
后续命令用 `qip` 执行（或你自己的用户）：
|
||||
|
||||
```bash
|
||||
sudo -iu qip
|
||||
cd /opt/quality-inspection-platform
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取代码
|
||||
|
||||
**方式 A：Git（推荐）**
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
git clone <你的内网仓库地址> .
|
||||
# 或指定分支：git clone -b main <url> .
|
||||
```
|
||||
|
||||
**方式 B：上传压缩包**
|
||||
|
||||
在本机打包后 `scp` 到服务器，再解压：
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
tar xzf quality-inspection-platform.tar.gz --strip-components=1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 安装 Python 依赖
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
|
||||
# Ubuntu / Debian：
|
||||
python3 -m venv .venv
|
||||
|
||||
# CentOS 7（IUS）：
|
||||
# python3.11 -m venv .venv
|
||||
|
||||
source .venv/bin/activate
|
||||
|
||||
pip install --upgrade pip
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 验证关键包
|
||||
python -c "import fastapi, mcp, uvicorn; print('python deps ok')"
|
||||
```
|
||||
|
||||
> CentOS 7 若 `pip install` 编译失败，确认已执行 §1B.1 的 `gcc` 与 `*-devel` 包；或在内网配置 pip 镜像源。
|
||||
|
||||
---
|
||||
|
||||
## 5. 构建前端（生产必做）
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform/frontend-admin
|
||||
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
cd ..
|
||||
ls -la frontend-admin/dist/index.html
|
||||
```
|
||||
|
||||
必须存在 `frontend-admin/dist/index.html`，否则浏览器访问 `/` 会提示前端未构建。
|
||||
|
||||
**CentOS 7 未装 Node 时**：在开发机构建后只上传 `dist`：
|
||||
|
||||
```bash
|
||||
cd frontend-admin && npm install && npm run build
|
||||
scp -r dist qip@<服务器>:/opt/quality-inspection-platform/frontend-admin/
|
||||
```
|
||||
|
||||
**可选**：构建完成后删除 `node_modules` 节省空间（以后升级需重新 `npm install`）：
|
||||
|
||||
```bash
|
||||
rm -rf /opt/quality-inspection-platform/frontend-admin/node_modules
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 配置环境变量
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
mkdir -p data/ssh-scripts
|
||||
|
||||
cat > /opt/quality-inspection-platform/.env <<'EOF'
|
||||
# 生产务必修改下面三项
|
||||
AUTH_TOKEN_SECRET=请替换为随机长字符串
|
||||
DEFAULT_SUPERADMIN_USERNAME=admin
|
||||
DEFAULT_SUPERADMIN_PASSWORD=请替换为强密码
|
||||
|
||||
# MCP：强制所有工具带 API Key
|
||||
MCP_REQUIRE_API_KEY=true
|
||||
|
||||
# 同事从其它机器用 Cursor 连 MCP 时，若连不上可开启：
|
||||
QIP_MCP_DISABLE_DNS_PROTECTION=true
|
||||
# 或精确白名单（二选一）：
|
||||
# QIP_MCP_ALLOWED_HOSTS=10.0.0.5:8000,qip.internal:8000
|
||||
# QIP_MCP_ALLOWED_ORIGINS=http://10.0.0.5:8000
|
||||
|
||||
# 可选：Loki 日志探索
|
||||
# GENERAL_LOKI_EXPLORE_URL=https://grafana.example/explore
|
||||
EOF
|
||||
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
> `.env` 已在 `.gitignore` 中，不会进 Git。
|
||||
> `uvicorn` 默认**不会**自动读 `.env`；下面 systemd 示例用 `EnvironmentFile` 加载。
|
||||
|
||||
---
|
||||
|
||||
## 7. 首次试跑（前台）
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform
|
||||
source .venv/bin/activate
|
||||
|
||||
set -a
|
||||
source .env
|
||||
set +a
|
||||
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
**另开一个 SSH 窗口**自检：
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:8000/health
|
||||
# 期望：{"ok":true}
|
||||
|
||||
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/
|
||||
# 期望：200
|
||||
```
|
||||
|
||||
浏览器访问：`http://<服务器IP>:8000/`
|
||||
使用 `.env` 里的 `DEFAULT_SUPERADMIN_USERNAME` / `DEFAULT_SUPERADMIN_PASSWORD` 登录。
|
||||
|
||||
确认无误后，在前台试跑窗口 `Ctrl+C` 停止，进入第 8 步配置 systemd。
|
||||
|
||||
---
|
||||
|
||||
## 8. 配置 systemd 常驻
|
||||
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/quality-inspection-platform.service <<'EOF'
|
||||
[Unit]
|
||||
Description=Quality Inspection Platform
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=qip
|
||||
Group=qip
|
||||
WorkingDirectory=/opt/quality-inspection-platform
|
||||
EnvironmentFile=/opt/quality-inspection-platform/.env
|
||||
Environment=PATH=/opt/quality-inspection-platform/.venv/bin:/usr/bin:/bin
|
||||
ExecStart=/opt/quality-inspection-platform/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable quality-inspection-platform
|
||||
sudo systemctl start quality-inspection-platform
|
||||
sudo systemctl status quality-inspection-platform
|
||||
```
|
||||
|
||||
查看日志：
|
||||
|
||||
```bash
|
||||
journalctl -u quality-inspection-platform -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 防火墙（按需）
|
||||
|
||||
**CentOS 7（firewalld）** — 仅内网访问 8000：
|
||||
|
||||
```bash
|
||||
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="10.0.0.0/8" port protocol="tcp" port="8000" accept'
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
若用 Nginx 对外 80：
|
||||
|
||||
```bash
|
||||
sudo firewall-cmd --permanent --add-service=http
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
**Ubuntu（ufw）**：
|
||||
|
||||
```bash
|
||||
sudo ufw allow from 10.0.0.0/8 to any port 8000 proto tcp
|
||||
sudo ufw reload
|
||||
```
|
||||
|
||||
若前面有 Nginx 对外 80/443，则只开放 80/443，**不要**把 8000 暴露到公网。
|
||||
|
||||
---
|
||||
|
||||
## 10. Nginx 反向代理（可选）
|
||||
|
||||
适用于希望用域名访问、或只暴露 80/443 的场景。
|
||||
|
||||
```bash
|
||||
# Ubuntu / Debian
|
||||
sudo apt install -y nginx
|
||||
|
||||
# CentOS 7
|
||||
sudo yum install -y nginx
|
||||
sudo systemctl enable nginx
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo tee /etc/nginx/sites-available/quality-inspection-platform <<'EOF'
|
||||
server {
|
||||
listen 80;
|
||||
server_name qip.internal; # 改成你的域名或 IP
|
||||
|
||||
client_max_body_size 50m;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
# MCP Streamable HTTP 可能需要较长连接
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
sudo ln -sf /etc/nginx/sites-available/quality-inspection-platform /etc/nginx/sites-enabled/
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
此时访问地址变为：`http://qip.internal/`
|
||||
MCP URL：`http://qip.internal/mcp`
|
||||
|
||||
可将 systemd 里 uvicorn 改为只监听本机：
|
||||
|
||||
```ini
|
||||
ExecStart=.../uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 同事配置 MCP（不在服务器装 Python）
|
||||
|
||||
每人本机 Cursor `~/.cursor/mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"quality-inspection-platform": {
|
||||
"url": "http://qip.internal/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer sto-个人API密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `sto-` Key：登录 Web → 个人中心创建
|
||||
- 详细说明：[mcp_install.md](./mcp_install.md)
|
||||
|
||||
---
|
||||
|
||||
## 12. 数据备份
|
||||
|
||||
数据库与上传的 SSH 脚本目录：
|
||||
|
||||
```bash
|
||||
# 示例：每日备份 cron
|
||||
0 2 * * * qip cp /opt/quality-inspection-platform/ai_test.db /opt/qip/backup/ai_test.db.$(date +\%Y\%m\%d)
|
||||
```
|
||||
|
||||
**升级代码时不要覆盖** 已有 `ai_test.db`。
|
||||
|
||||
---
|
||||
|
||||
## 13. 版本升级流程
|
||||
|
||||
```bash
|
||||
sudo systemctl stop quality-inspection-platform
|
||||
|
||||
sudo -iu qip
|
||||
cd /opt/quality-inspection-platform
|
||||
|
||||
# 备份
|
||||
cp -a ai_test.db ai_test.db.bak.$(date +%Y%m%d)
|
||||
|
||||
# 拉代码
|
||||
git pull
|
||||
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
cd frontend-admin
|
||||
npm install
|
||||
npm run build
|
||||
cd ..
|
||||
|
||||
exit
|
||||
sudo systemctl start quality-inspection-platform
|
||||
curl -s http://127.0.0.1:8000/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 验收清单
|
||||
|
||||
| # | 检查 | 命令/操作 |
|
||||
|---|------|-----------|
|
||||
| 1 | 服务运行 | `systemctl is-active quality-inspection-platform` |
|
||||
| 2 | 健康检查 | `curl -s http://127.0.0.1:8000/health` |
|
||||
| 3 | Web 首页 | 浏览器打开 `/`，能登录 |
|
||||
| 4 | API 文档 | `http://<主机>:8000/docs` |
|
||||
| 5 | MCP 工具列表 | `curl -s http://127.0.0.1:8000/mcp/tools -H "Authorization: Bearer sto-xxx"` |
|
||||
| 6 | 改密 | 登录后修改超管密码；API Key 仅个人保管 |
|
||||
| 7 | 防火墙 | 仅内网可达 |
|
||||
|
||||
---
|
||||
|
||||
## 15. 常见问题
|
||||
|
||||
| 现象 | 处理 |
|
||||
|------|------|
|
||||
| 访问 `/` 提示 frontend dist not found | 重新执行第 5 步 `npm run build`，或上传 `frontend-admin/dist` |
|
||||
| `ModuleNotFoundError: mcp` | 第 4 步 `pip install -r requirements.txt`；CentOS 7 须用 3.11 的 venv |
|
||||
| CentOS 7 `python3` 是 3.6 | 不要用系统 `python3`，改用 `python3.11` 建 venv |
|
||||
| `pip` 编译卡住 / 失败 | `yum install` §1B.1 开发包；配置内网 pip 镜像 |
|
||||
| IUS / NodeSource 无法访问 | 内网 yum 镜像；或本机构建 `dist` + 离线 wheel 装 Python 包 |
|
||||
| MCP 在 Cursor 里连不上 | `.env` 设 `QIP_MCP_DISABLE_DNS_PROTECTION=true` 或配置 `QIP_MCP_ALLOWED_HOSTS` |
|
||||
| 401 / 无 Key | Web 个人中心创建 `sto-` Key；或设 `MCP_REQUIRE_API_KEY` 后请求头带 Bearer |
|
||||
| 端口被占用 | `ss -lntp \| grep 8000` 查占用进程 |
|
||||
| 权限错误 | 确认 `ai_test.db`、`data/` 目录属主为 `qip` |
|
||||
| SELinux 拦截（CentOS） | 临时：`sudo setenforce 0` 排查；长期：`setsebool -P httpd_can_network_connect 1` 或按策略放行 |
|
||||
|
||||
---
|
||||
|
||||
## 16. 相关文档
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| [mcp_install.md](./mcp_install.md) | MCP / Cursor / 内网排障 |
|
||||
| [mcp_tools_for_ai.md](./mcp_tools_for_ai.md) | AI 工具能力与 Recipe |
|
||||
| [mcp_quickstart.md](./mcp_quickstart.md) | curl / HTTP 网关示例 |
|
||||
|
||||
---
|
||||
|
||||
## 快速命令抄录（已装好环境后）
|
||||
|
||||
```bash
|
||||
cd /opt/quality-inspection-platform && source .venv/bin/activate
|
||||
git pull && pip install -r requirements.txt
|
||||
cd frontend-admin && npm install && npm run build && cd ..
|
||||
sudo systemctl restart quality-inspection-platform
|
||||
```
|
||||
+199
-152
@@ -1,201 +1,248 @@
|
||||
# 把本平台注册成真正的 MCP Server
|
||||
# MCP Server 安装与接入说明
|
||||
|
||||
本仓库已附带 `mcp_bridge.py`，它是一个标准 stdio MCP Server，
|
||||
对外暴露 MCP 协议（JSON-RPC over stdio），内部桥接到本平台的 HTTP 网关。
|
||||
平台在 **同一个 `uvicorn` 进程** 内提供：
|
||||
|
||||
只要先启动平台后端，再让 Cursor / Claude Desktop / Codex CLI 启动这个桥接，
|
||||
它就会被识别成一个真正的 MCP Server，并自动暴露所有平台工具（含跑批工作流工具）。
|
||||
| 能力 | 路径 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| **Web 管理端** | `/`、`/api/*` | 人工在浏览器操作 |
|
||||
| **MCP Server（推荐 AI 用）** | `/mcp` | Codex / Claude / Cursor（Streamable HTTP） |
|
||||
| **HTTP 工具网关（兼容）** | `/mcp/tools`、`/mcp/invoke` | curl、CI、自研脚本 |
|
||||
|
||||
三者共用数据库与工作流引擎；**Web UI 与 MCP 可同时使用，互不影响**。
|
||||
|
||||
> **历史变更**：已移除 `mcp_bridge.py`。不再需要本机 `python3` 子进程桥接；客户端直接连 `http://10.20.30.42:8000/mcp`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 启动平台后端
|
||||
## 1. 架构
|
||||
|
||||
```
|
||||
┌─────────────────┐ MCP (Streamable HTTP) ┌──────────────────────────┐
|
||||
│ Codex / Claude │ ──────────────────────────────►│ uvicorn app.main:app │
|
||||
│ Claude Desktop │ Authorization: Bearer │ ├─ /mcp (mcp_native) │
|
||||
└─────────────────┘ │ ├─ /api/* (Web) │
|
||||
┌─────────────────┐ HTTP 登录 / 点击 │ └─ /mcp/invoke (curl) │
|
||||
│ 浏览器 Web UI │ ──────────────────────────────►└──────────────────────────┘
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
实现位置：`app/mcp_native.py`（挂载路由 + `lifespan`），工具逻辑：`app/main.py` 中 `MCP_TOOL_SPECS` 与 `_dispatch_mcp_tool`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 服务端部署（管理员）
|
||||
|
||||
> **完整步骤**（用户、Git、前端构建、systemd、Nginx、备份）：[`deploy_server.md`](./deploy_server.md)
|
||||
|
||||
### 2.1 安装与启动
|
||||
|
||||
```bash
|
||||
cd /Users/qihongkun/work/My_app/quality-inspection-platform
|
||||
# 可选：生产/共享环境建议开启，所有 MCP 调用必须带 API Key
|
||||
cd /path/to/quality-inspection-platform
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 生产建议：所有 MCP 调用必须带 API Key
|
||||
# export MCP_REQUIRE_API_KEY=true
|
||||
uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||||
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
确认可访问：
|
||||
### 2.2 启动后确认
|
||||
|
||||
- `http://127.0.0.1:8000/mcp/tools`
|
||||
| 检查项 | 命令或地址 |
|
||||
|--------|------------|
|
||||
| 健康 | `curl -s http://10.20.30.42:8000/health` |
|
||||
| Web | 浏览器打开 `http://10.20.30.42:8000/` |
|
||||
| 工具列表 | `curl -s http://10.20.30.42:8000/mcp/tools -H "Authorization: Bearer sto-密钥"` |
|
||||
| MCP 端点 | `http://10.20.30.42:8000/mcp`（供 Codex 配置，非浏览器页面） |
|
||||
|
||||
---
|
||||
### 2.3 内网 systemd 示例（可选）
|
||||
|
||||
## 2. 安装到 Cursor
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Quality Inspection Platform
|
||||
After=network.target
|
||||
|
||||
编辑 `~/.cursor/mcp.json`（不存在则新建），加入：
|
||||
[Service]
|
||||
User=qip
|
||||
WorkingDirectory=/opt/quality-inspection-platform
|
||||
Environment="PATH=/opt/quality-inspection-platform/.venv/bin"
|
||||
Environment="MCP_REQUIRE_API_KEY=true"
|
||||
# 使用内网地址访问且 MCP 连不上时可加：
|
||||
# Environment="QIP_MCP_DISABLE_DNS_PROTECTION=true"
|
||||
ExecStart=/opt/quality-inspection-platform/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
Restart=always
|
||||
|
||||
```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`：
|
||||
|
||||
```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密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 安装到 Codex CLI
|
||||
## 3. Codex 配置
|
||||
|
||||
```bash
|
||||
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`**。
|
||||
|
||||
或在 `~/.codex/config.toml` 中：
|
||||
> **远程环境**：配置文件要写在 Codex 实际运行的机器上。MCP 请求从 Codex 所在机器发出；团队默认 MCP 地址为 `http://10.20.30.42:8000/mcp`。
|
||||
|
||||
### 3.1 默认内网地址
|
||||
|
||||
```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]
|
||||
url = "http://10.20.30.42:8000/mcp"
|
||||
|
||||
[mcp.servers.quality-inspection-platform.env]
|
||||
QIP_BASE_URL = "http://127.0.0.1:8000"
|
||||
QIP_API_KEY = "sto-你的API密钥"
|
||||
[mcp_servers.quality-inspection-platform.http_headers]
|
||||
Authorization = "Bearer sto-你的API密钥"
|
||||
```
|
||||
|
||||
### 3.2 连接其他部署地址
|
||||
|
||||
如果 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密钥"
|
||||
```
|
||||
|
||||
### 3.3 配置生效
|
||||
|
||||
配置完成后重启 Codex 会话或 Codex 应用，让 MCP 配置重新加载。验证方式：在对话中要求 Agent 调用 `catalog_snapshot`，应返回 apis / workflows 等 JSON 快照。
|
||||
|
||||
### 3.4 API Key 获取
|
||||
|
||||
1. 浏览器登录 Web → 右上角「个人中心」
|
||||
2. 创建 `sto-` 开头的 API Key（仅显示一次，请妥善保存）
|
||||
3. 写入 `~/.codex/config.toml` 的 `http_headers.Authorization`，或在 HTTP 网关调用时使用头 `X-API-Key: sto-...`
|
||||
|
||||
**写操作**与**执行类**工具无有效 Key 返回 **401**。生产环境建议 `MCP_REQUIRE_API_KEY=true`，此时**只读工具**也须 Key。
|
||||
|
||||
---
|
||||
|
||||
## 5. 自检（不连客户端，先确认桥接可用）
|
||||
## 4. 团队协作（同事无需克隆仓库）
|
||||
|
||||
| 角色 | 需要做什么 |
|
||||
|------|------------|
|
||||
| **管理员** | 内网部署 `uvicorn`，开放防火墙，分发内网 URL |
|
||||
| **每位开发者** | 配置 `~/.codex/config.toml`（URL + 个人 `sto-` Key） |
|
||||
| **不需要** | 本机 Python、`mcp_bridge`、克隆完整项目（除非要改代码） |
|
||||
|
||||
**远程 Codex 统一配置（推荐）**
|
||||
|
||||
1. 服务器上部署一次项目（含 `.venv` 与 `uvicorn`）
|
||||
2. 同事在远程机器上运行 Codex 或使用远程工作区
|
||||
3. 在**远程** `~/.codex/config.toml` 使用 `http://10.20.30.42:8000/mcp`（确保 Codex 所在机器可访问该内网地址）
|
||||
4. 每人使用自己的 `sto-` Key，**不要**写入 Git 或共享配置文件
|
||||
|
||||
---
|
||||
|
||||
## 5. Cursor / Claude Desktop（可选）
|
||||
|
||||
使用 **HTTP URL** 连接 MCP（以客户端当前版本支持的 Streamable HTTP / URL 配置为准）：
|
||||
|
||||
- URL：`http://10.20.30.42:8000/mcp`
|
||||
- 头：`Authorization: Bearer sto-...`
|
||||
|
||||
Cursor 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"quality-inspection-platform": {
|
||||
"url": "http://10.20.30.42:8000/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer sto-你的API密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Claude Desktop 具体字段名见其 MCP 配置文档。
|
||||
|
||||
---
|
||||
|
||||
## 6. 从旧版 `mcp_bridge` 迁移
|
||||
|
||||
| 旧配置 | 新配置 |
|
||||
|--------|--------|
|
||||
| `"command": "python3"` | 删除 |
|
||||
| `"args": [".../mcp_bridge.py"]` | 删除 |
|
||||
| `"env": { "QIP_BASE_URL": "...", "QIP_API_KEY": "..." }` | 改为 Codex `url = "<QIP_BASE_URL>/mcp"` + `http_headers.Authorization = "Bearer <Key>"` |
|
||||
|
||||
迁移后只需保证 **`uvicorn` 已启动**；无需再单独运行桥接脚本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 自检清单
|
||||
|
||||
```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":{}}}' \
|
||||
| QIP_API_KEY=sto-你的API密钥 python3 mcp_bridge.py
|
||||
# 1. 后端存活
|
||||
curl -s http://10.20.30.42:8000/health
|
||||
|
||||
# 2. HTTP 网关（与 MCP 工具集一致）
|
||||
curl -s http://10.20.30.42:8000/mcp/tools \
|
||||
-H "Authorization: Bearer sto-你的密钥"
|
||||
|
||||
# 3. 试调一个工具
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Authorization: Bearer sto-你的密钥" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tool":"catalog_snapshot","arguments":{}}'
|
||||
```
|
||||
|
||||
预期：
|
||||
|
||||
- `initialize` 返回 `serverInfo`
|
||||
- `tools/list` 返回工具清单（应包含 `workflow_batch_*` 等）
|
||||
- `tools/call` 返回 `content[0].text` 内含调用结果
|
||||
**Codex 侧**：在对话中让 Agent 调用 `catalog_snapshot`，应返回 apis / workflows 等 JSON 快照。
|
||||
|
||||
---
|
||||
|
||||
## 6. 暴露的工具（自动转发自平台）
|
||||
## 8. 排障
|
||||
|
||||
桥接启动时从 `GET /mcp/tools` 拉取列表，**无需改 `mcp_bridge.py`** 即可随平台升级获得新工具。
|
||||
| 现象 | 可能原因 | 处理 |
|
||||
|------|----------|------|
|
||||
| Codex 无工具 / 连接失败 | `uvicorn` 未启动或 URL 错误 | 确认 `/health`；检查 `~/.codex/config.toml` 中 URL 以 `/mcp` 结尾 |
|
||||
| 401 / requires API Key | 未配置或 Key 无效 | 个人中心重新生成 Key，更新 `Authorization` |
|
||||
| 内网 IP 可 curl 但 Codex 连不上 | DNS rebinding 校验 | 设置 `QIP_MCP_DISABLE_DNS_PROTECTION=true` 或配置 `QIP_MCP_ALLOWED_HOSTS` |
|
||||
| 修改工具后客户端仍是旧的 | 客户端缓存 | 重启 Codex 会话或应用；服务端重启 `uvicorn` |
|
||||
| 远程环境 MCP 失败 | 配在了本机而非 Codex 所在机器 | 改 Codex 实际运行机器上的 `~/.codex/config.toml`；从那台机器验证是否能访问 `http://10.20.30.42:8000/health` |
|
||||
| Web 正常、MCP 不行 | 只检查了 Web | MCP 走 `/mcp`，与 `/api` 独立；分别自检 |
|
||||
|
||||
### 资源管理
|
||||
|
||||
- `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`
|
||||
查看 MCP 相关日志：启动 `uvicorn` 的终端；Codex 客户端 MCP 日志。
|
||||
|
||||
---
|
||||
|
||||
## 9. 环境变量
|
||||
|
||||
## 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`。
|
||||
| 变量 | 含义 |
|
||||
|------|------|
|
||||
| `MCP_REQUIRE_API_KEY` | `true` 时所有 MCP 工具（含只读、`GET /mcp/tools`）均需 Key |
|
||||
| `QIP_MCP_DISABLE_DNS_PROTECTION` | `true` 时关闭 MCP 传输的 Host/Origin 校验 |
|
||||
| `QIP_MCP_ALLOWED_HOSTS` | 逗号分隔 Host 白名单，如 `10.20.30.42:8000,qip.corp:8000` |
|
||||
| `QIP_MCP_ALLOWED_ORIGINS` | 逗号分隔 Origin 白名单 |
|
||||
|
||||
---
|
||||
|
||||
## 8. Loki 日志（可选）
|
||||
## 10. 维护与文档索引
|
||||
|
||||
若需在管理端或 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。
|
||||
- **新增 MCP 工具**：修改 `app/main.py` 中 `MCP_TOOL_SPECS` 与 `_dispatch_mcp_tool` 分支 → 重启 `uvicorn` → 重启 MCP 客户端。
|
||||
- **AI 选型与 Recipe（Agent 必读）**：[mcp_tools_for_ai.md](./mcp_tools_for_ai.md)
|
||||
- **curl / 批量调用示例**：[mcp_quickstart.md](./mcp_quickstart.md)
|
||||
- **Codex 短约定**：项目根 [AGENTS.md](../AGENTS.md)
|
||||
|
||||
---
|
||||
|
||||
## 9. 维护建议
|
||||
## 11. 常见问题
|
||||
|
||||
- 平台新增工具时，无需改桥接，重启 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`**
|
||||
**还需要 bridge 吗？**
|
||||
不需要。`/mcp` 已是标准 MCP Server。
|
||||
|
||||
**每人都要装 Python 吗？**
|
||||
仅**运行后端的服务器**需要 Python 环境；只用 Codex 连 MCP 的同事不需要本机 Python。
|
||||
|
||||
**能和 Web 一起用吗？**
|
||||
可以。Web 走登录态 `/api/*`；AI 走 `/mcp` + API Key。
|
||||
|
||||
**脚本还能用吗？**
|
||||
可以。继续 `POST /mcp/invoke` 与 `GET /mcp/tools`，与 MCP 协议共用同一套工具实现。
|
||||
|
||||
+188
-20
@@ -1,9 +1,176 @@
|
||||
# MCP 快速接入与 AI 调用说明书
|
||||
|
||||
> **AI Agent 请优先阅读**：[mcp_tools_for_ai.md](./mcp_tools_for_ai.md)（工具决策表、鉴权、Recipe、节点约定）。
|
||||
> 本文档侧重 curl 示例与人工接入；项目根 [AGENTS.md](../AGENTS.md) 供 Codex 自动加载。
|
||||
> **Codex / 内网安装**：[mcp_install.md](./mcp_install.md)（`~/.codex/config.toml`、团队协作、排障）。
|
||||
> 本文档侧重 **HTTP curl** 与脚本调用；项目根 [AGENTS.md](../AGENTS.md) 供 Codex 自动加载。
|
||||
|
||||
本文档给 AI Agent 和开发者使用，目标是让 AI 可以直接通过本平台的 MCP 接口完成：
|
||||
## 接入方式选择
|
||||
|
||||
| 方式 | 端点 | 适用 |
|
||||
|------|------|------|
|
||||
| **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 数据创建/更新
|
||||
@@ -17,11 +184,12 @@
|
||||
|
||||
## 1. 基础信息
|
||||
|
||||
- 服务地址：`http://127.0.0.1:8000`
|
||||
- 工具发现：`GET /mcp/tools`
|
||||
- 单次调用：`POST /mcp/invoke`
|
||||
- 服务地址：`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，配置到 MCP Bridge 环境变量 `QIP_API_KEY`（兼容 `AI_TEST_API_KEY`），或在请求头使用 `Authorization: Bearer <api_key>` / `X-API-Key: <api_key>`。
|
||||
- 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` 同样校验。
|
||||
|
||||
@@ -151,7 +319,7 @@
|
||||
### 4.1 通用调用模板
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -163,7 +331,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 4.2 批量调用模板
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
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 '{
|
||||
@@ -182,7 +350,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
### 示例 A：AI 自动创建接口
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -203,7 +371,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 示例 B：AI 自动创建 Mock 数据
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "mock_upsert",
|
||||
@@ -217,7 +385,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 示例 C：AI 自动创建 Workflow（含条件分支）
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -245,7 +413,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 示例 D：AI 自动 Patch Workflow JSON
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -262,7 +430,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 示例 E：AI 执行工作流并分析结果
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "workflow_run",
|
||||
@@ -275,7 +443,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "workflow_analyze_last_run",
|
||||
@@ -286,7 +454,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
### 示例 F：AI 批量编排（创建接口 → Mock → Patch → 执行）
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
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 '{
|
||||
@@ -328,7 +496,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
### 示例 G：按目录分功能管理
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
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 '{
|
||||
@@ -362,7 +530,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke-batch \
|
||||
|
||||
```bash
|
||||
# 1) 创建草稿批跑任务
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -377,7 +545,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
# 假设返回 data.id = 3
|
||||
|
||||
# 2) 绑定要执行的工作流 ID 列表
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <sto-api-key>" \
|
||||
-d '{
|
||||
@@ -389,7 +557,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
}'
|
||||
|
||||
# 3) 执行批跑
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "workflow_batch_run",
|
||||
@@ -397,7 +565,7 @@ curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
}'
|
||||
|
||||
# 4) 查询结果（含每次 workflow_run 的 run_id）
|
||||
curl -s -X POST http://127.0.0.1:8000/mcp/invoke \
|
||||
curl -s -X POST http://10.20.30.42:8000/mcp/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tool": "workflow_batch_get",
|
||||
|
||||
+26
-15
@@ -1,6 +1,6 @@
|
||||
# MCP 工具能力说明（AI 专用）
|
||||
|
||||
> **读者**：Cursor / Codex / Claude 等通过 `quality-inspection-platform` MCP 工作的 Agent。
|
||||
> **读者**：Codex / Claude / Cursor 等通过 `quality-inspection-platform` MCP 工作的 Agent。
|
||||
> **目的**：在调用 `tools/list` 之外，提供「何时用哪个工具、按什么顺序、参数怎么填」的固定上下文。
|
||||
> **维护**：工具以 `app/main.py` 中 `MCP_TOOL_SPECS` 和平台 `GET /mcp/tools` 为准；增删工具时请同步更新本文档。
|
||||
> **重要**：某些 MCP 客户端可能缓存、裁剪或延迟刷新工具列表；不要仅凭当前客户端可见工具反向删减本文档能力。
|
||||
@@ -10,16 +10,16 @@
|
||||
## 0. Agent 必读（30 秒）
|
||||
|
||||
1. **先** `catalog_snapshot` 了解现有 apis / workflows / workflow_batches / mocks / folders / ssh_tree，避免重复创建。
|
||||
2. **写操作与执行**必须带 `sto-` API Key（`Authorization: Bearer` 或桥接环境变量 `QIP_API_KEY`，兼容 `AI_TEST_API_KEY`）。
|
||||
2. **写操作与执行**必须带 `sto-` API Key（MCP 请求头 `Authorization: Bearer` 或 `X-API-Key`；HTTP 脚本可在 body 传 `api_key`，兼容旧名 `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`。
|
||||
5. 如果当前客户端没有显示某个工具，先用 MCP `tools/list` 或 `GET /mcp/tools` 核对，再重启 MCP 客户端 / 会话。
|
||||
6. 人类可读安装见 `docs/mcp_install.md`；curl 示例见 `docs/mcp_quickstart.md`。
|
||||
|
||||
### 0.1 工具来源与客户端刷新
|
||||
|
||||
- 权威工具清单来自后端 `app/main.py` 的 `MCP_TOOL_SPECS`，平台通过 `GET /mcp/tools` 对外暴露。
|
||||
- `mcp_bridge.py` 启动后会从 `QIP_BASE_URL`（或兼容 `AI_TEST_BASE_URL`）的 `/mcp/tools` 拉取工具并转换为 MCP `tools/list`。
|
||||
- 平台内置 Streamable HTTP MCP（`GET/POST /mcp`），`tools/list` 由 `MCP_TOOL_SPECS` 提供；兼容 HTTP 网关 `GET /mcp/tools`。
|
||||
- Codex / Cursor / Claude 等客户端可能在会话启动时缓存工具列表；平台新增工具后，通常需要重启 MCP 客户端或重启会话。
|
||||
- 如果客户端只显示部分工具，不代表平台没有该能力。先用 `/mcp/tools` 或本文档核对，再决定是否降级。
|
||||
- Agent 更新本文档时，应以源码和 `/mcp/tools` 为准，不以单个客户端当前暴露的工具子集为准。
|
||||
@@ -44,14 +44,14 @@
|
||||
|
||||
### 2.1 平台地址
|
||||
|
||||
MCP Bridge 通过环境变量访问平台：
|
||||
Codex 等客户端在个人 MCP 配置中配置平台 URL 与 API Key，例如：
|
||||
|
||||
| 环境变量 | 含义 | 示例 |
|
||||
|----------|------|------|
|
||||
| `QIP_BASE_URL` | 质量检测平台后端地址（兼容 `AI_TEST_BASE_URL`） | `http://127.0.0.1:8000` |
|
||||
| `QIP_API_KEY` | `sto-` 开头的 API Key（兼容 `AI_TEST_API_KEY`） | `sto-...` |
|
||||
| 配置项 | 含义 | 示例 |
|
||||
|--------|------|------|
|
||||
| `url` | MCP 端点 | `http://10.20.30.42:8000/mcp` |
|
||||
| `http_headers.Authorization` / `headers.Authorization` | `Bearer sto-...` | `Bearer sto-xxx` |
|
||||
|
||||
Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服务；平台进程由质量检测平台项目本身或共享服务负责。
|
||||
Agent 通过 MCP 工具访问平台；平台进程由质量检测平台项目或共享内网服务负责。兼容环境变量名 `AI_TEST_API_KEY` 仅适用于旧 HTTP 脚本，MCP 客户端请用请求头传 Key。
|
||||
|
||||
### 2.2 调用鉴权
|
||||
|
||||
@@ -92,6 +92,8 @@ Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服
|
||||
|
||||
## 4. 工具清单（按分类）
|
||||
|
||||
下文参数均为各工具的 **`arguments` 对象**（MCP `tools/call` 直接传该对象）。仅在使用 HTTP 网关时，外层再包一层 `{"tool":"<名称>","arguments":{...}}`，见 [mcp_quickstart.md](./mcp_quickstart.md)。
|
||||
|
||||
### 4.1 发现与目录
|
||||
|
||||
#### `catalog_snapshot`
|
||||
@@ -247,7 +249,7 @@ Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服
|
||||
|
||||
#### `mcp_tool_upsert`
|
||||
|
||||
- **用途**：平台内「自定义 MCP 工具配置」表，**不是**本桥接工具列表本身。
|
||||
- **用途**：平台内「自定义 MCP 工具配置」表，**不是** Codex / Claude / Cursor 所见的内置 MCP 工具列表本身。
|
||||
|
||||
#### SSH 系列
|
||||
|
||||
@@ -289,6 +291,15 @@ Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服
|
||||
|
||||
## 6. 调用协议
|
||||
|
||||
### 6.1 Codex / MCP 客户端（推荐）
|
||||
|
||||
- **端点**：`http://10.20.30.42:8000/mcp`（Streamable HTTP）
|
||||
- **鉴权**：请求头 `Authorization: Bearer sto-...`（Codex 配置在个人 `config.toml` 的 `mcp_servers.<name>.http_headers`）
|
||||
- **工具发现**：MCP 方法 `tools/list`（与 `MCP_TOOL_SPECS` 一致）
|
||||
- **工具调用**：MCP 方法 `tools/call`（`name` + `arguments`）→ `content[0].text` 为 JSON 字符串，解析后字段为 `ok` / `tool` / `data` / `error`；失败时 `isError` 可能为 true
|
||||
|
||||
### 6.2 HTTP 网关（curl / CI）
|
||||
|
||||
- **发现**：`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` 时任一步失败即停
|
||||
@@ -334,7 +345,7 @@ workflow_analyze_last_run → workflow_patch_json(只改变量/单节点 data)
|
||||
|
||||
| error / 现象 | 处理 |
|
||||
|--------------|------|
|
||||
| 401 MCP requires API Key | 配置 `QIP_API_KEY`（或 `AI_TEST_API_KEY`）或请求头 Bearer |
|
||||
| 401 MCP requires API Key | Codex：个人 `config.toml` 中配置 `Authorization: Bearer sto-...`；curl：请求头或 body `api_key` |
|
||||
| workflow folder not registered | 先 `folder_ensure` workflows |
|
||||
| 仅 draft 批次可执行 | 已对 running/success 的 batch 再 run |
|
||||
| unknown mcp tool | `GET /mcp/tools` 刷新名称 |
|
||||
@@ -349,9 +360,9 @@ workflow_analyze_last_run → workflow_patch_json(只改变量/单节点 data)
|
||||
|------|------|
|
||||
| **本文** `docs/mcp_tools_for_ai.md` | **AI Agent（首选）** |
|
||||
| `docs/mcp_quickstart.md` | 人类 + curl 示例 |
|
||||
| `docs/mcp_install.md` | MCP 桥接安装 |
|
||||
| `docs/mcp_install.md` | MCP Server 安装、Codex/内网/远程环境 |
|
||||
| 项目根 `AGENTS.md` | Codex 自动加载的短指引 |
|
||||
|
||||
---
|
||||
|
||||
*文档版本：与仓库 `MCP_TOOL_SPECS` 同步（含 workflow_run_* / workflow_validate / 执行类鉴权）。*
|
||||
*文档版本：与 `MCP_TOOL_SPECS`（28 个工具）同步；接入方式为内置 Streamable HTTP `/mcp`，见 `docs/mcp_install.md`。*
|
||||
|
||||
Reference in New Issue
Block a user