质量检测平台（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

目录结构

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
裸机 systemd + Nginx	docs/deploy_server.md

快速启动：

cp .env.example .env   # 修改密码与密钥
docker compose build
docker compose up -d

安装依赖

建议先进入项目目录，再安装依赖：

pip install -r requirements.txt

如果你使用虚拟环境，也可以先激活 .venv 再安装。

启动项目

方式一：命令行启动后端

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），就绪后自动打开浏览器。

# 在项目根目录执行（脚本会自动 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（无需额外进程）：

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

完整说明（含内网部署、团队协作、Remote SSH、排障）见：

• docs/mcp_install.md

AI 使用 MCP 前请阅读：

• docs/mcp_tools_for_ai.md
• 项目根 AGENTS.md（Codex 会自动加载）

常用开发命令

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