qihongkun
f5143aee09
- 添加 Dockerfile、docker-compose.yml 和 Jenkins 流水线配置 - 新增 MCP 原生集成模块 (mcp_native.py) - 移除旧的 mcp_bridge.py，更新依赖和文档 - 添加部署文档 (Docker 和服务器部署指南) Co-authored-by: Cursor <cursoragent@cursor.com>
149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
# 质量检测平台（quality-inspection-platform）
|
||
|
||
仓库目录名：`quality-inspection-platform`。一个基于 `FastAPI` 的质量检测平台，提供三类能力：
|
||
|
||
- 接口定义管理
|
||
- Mock 数据管理
|
||
- Workflow 流程编排与执行
|
||
|
||
此外，平台内置 **Streamable HTTP MCP Server**（`/mcp`），供 Cursor、Claude Desktop、Codex 等客户端直接连接，无需单独桥接进程。
|
||
|
||
## 技术栈
|
||
|
||
- Python
|
||
- FastAPI
|
||
- SQLAlchemy
|
||
- Pydantic
|
||
- SQLite
|
||
- Jinja2
|
||
- HTMX
|
||
- Drawflow
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
app/
|
||
main.py FastAPI 入口、页面路由、REST API、MCP HTTP 网关
|
||
database.py SQLite engine / session / Base
|
||
models.py SQLAlchemy 模型
|
||
schemas.py Pydantic 请求与响应模型
|
||
services/engine.py Workflow 执行引擎
|
||
static/app.js 前端交互逻辑
|
||
templates/ Jinja2 页面模板
|
||
docs/
|
||
mcp_tools_for_ai.md MCP 能力说明（AI Agent 首选）
|
||
mcp_install.md MCP Server 安装说明（Cursor / HTTP）
|
||
mcp_quickstart.md MCP 调用说明（人类 / curl）
|
||
AGENTS.md Codex 等自动加载的项目 Agent 约定
|
||
app/mcp_native.py 内置 Streamable HTTP MCP（挂载于 /mcp）
|
||
start_project.command macOS 一键启动前后端（双击或终端执行）
|
||
requirements.txt Python 依赖
|
||
```
|
||
|
||
## 服务器部署
|
||
|
||
| 方式 | 文档 |
|
||
|------|------|
|
||
| **Docker Compose（推荐，尤其 CentOS 7）** | [`docs/deploy_docker.md`](./docs/deploy_docker.md) |
|
||
| 裸机 systemd + Nginx | [`docs/deploy_server.md`](./docs/deploy_server.md) |
|
||
|
||
快速启动：
|
||
|
||
```bash
|
||
cp .env.example .env # 修改密码与密钥
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
## 安装依赖
|
||
|
||
建议先进入项目目录，再安装依赖：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
如果你使用虚拟环境，也可以先激活 `.venv` 再安装。
|
||
|
||
## 启动项目
|
||
|
||
### 方式一：命令行启动后端
|
||
|
||
```bash
|
||
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
|
||
```
|
||
|
||
启动后访问：
|
||
|
||
- 首页：`http://127.0.0.1:8000/`
|
||
- API 文档：`http://127.0.0.1:8000/docs`
|
||
- MCP 协议端点：`http://127.0.0.1:8000/mcp`
|
||
- MCP 工具列表（HTTP 兼容）：`http://127.0.0.1:8000/mcp/tools`
|
||
|
||
### 方式二：在 PyCharm 里启动
|
||
|
||
推荐创建一个 `Python` Run Configuration，并使用 `Module name` 模式：
|
||
|
||
- `Module name`: `uvicorn`
|
||
- `Parameters`: `app.main:app --host 127.0.0.1 --port 8000 --reload`
|
||
- `Working directory`: 项目根目录
|
||
|
||
注意：`app.main:app` 必须放在 `uvicorn` 后面作为位置参数传入，不能写到最后。
|
||
|
||
### 方式三：macOS 快速启动（推荐）
|
||
|
||
项目根目录有 `start_project.command`，会分别打开两个 Terminal 窗口启动后端（8000）与前端（5173），就绪后自动打开浏览器。
|
||
|
||
```bash
|
||
# 在项目根目录执行（脚本会自动 pip install；前端需已 npm install）
|
||
./start_project.command
|
||
```
|
||
|
||
首次使用若前端未安装依赖：`cd frontend-admin && npm install`
|
||
|
||
也可在 Finder 中双击该文件。脚本使用相对路径，不依赖旧目录名；若你曾在桌面/程序坞放了快捷方式，请把目标路径改为：
|
||
|
||
`/Users/qihongkun/work/My_app/quality-inspection-platform/start_project.command`
|
||
|
||
## 配置 MCP 客户端（Cursor 等）
|
||
|
||
后端启动后，在 `~/.cursor/mcp.json` 中配置 URL 与 API Key（无需额外进程）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quality-inspection-platform": {
|
||
"url": "http://127.0.0.1:8000/mcp",
|
||
"headers": { "Authorization": "Bearer sto-你的API密钥" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
完整说明（含内网部署、团队协作、Remote SSH、排障）见：
|
||
|
||
- [`docs/mcp_install.md`](./docs/mcp_install.md)
|
||
|
||
AI 使用 MCP 前请阅读：
|
||
|
||
- [`docs/mcp_tools_for_ai.md`](./docs/mcp_tools_for_ai.md)
|
||
- 项目根 [`AGENTS.md`](./AGENTS.md)（Codex 会自动加载）
|
||
|
||
## 常用开发命令
|
||
|
||
```bash
|
||
rg --files
|
||
rg "workflow_run" app docs
|
||
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
|
||
python3 -m py_compile app/main.py app/services/engine.py app/mcp_native.py
|
||
```
|
||
|
||
## 当前已知情况
|
||
|
||
- 默认数据库文件是根目录下的 `ai_test.db`
|
||
- 项目当前没有现成的 `pytest`、`ruff`、`flake8` 配置
|
||
- 前端是模板 + 原生 JS 结构，改动 UI 时通常集中在：
|
||
- `app/templates/index.html`
|
||
- `app/templates/partials/*.html`
|
||
- `app/static/app.js`
|