ProcureFlow MCP Server
by Running-hue
README.md
# ProcureFlow Agent
> 基于 DeepAgents / LangGraph 的多 Agent 智能采购系统，将采购分析、订单执行、ERP 数据服务、MCP 工具、长期记忆与沙箱运行整合为一条可审计的业务链路。
## 项目亮点
- **多 Agent 协作**：主 Agent 负责意图识别与任务路由，`procurement-analyst` 负责采购分析，`procurement-order` 负责订单查询与写操作；Prompt、工具、Skills 和中间件均通过 YAML/模块化配置解耦。
- **标准化业务工具**：通过 MCP 封装供应商、零部件、库存与采购订单能力，共提供 8 个工具，支持比价、库存预警、订单明细查询、采购建议与可视化报告生成。
- **Human-in-the-Loop**：创建或修改订单前，Agent 会自动解析物料、供应商与系统单价，结构化补齐缺失字段，并在最终写入前要求人工审批。
- **长链路上下文管理**：MongoDB Checkpoint 保存会话状态，长期记忆按用户隔离；结合上下文摘要、工具结果 Offloading 与 Skills 渐进式加载控制上下文开销。
- **隔离执行与恢复**：OpenSandbox 承担文件和代码执行，支持健康检查、生命周期续期、失效重建及 Skills 恢复。
- **ERP Python 化迁移**：使用 FastAPI + SQLAlchemy 重构原 Spring Boot ERP 层，保持 54 个 REST 接口路径、8 个 MCP 工具及原响应协议兼容。
## 系统架构
```mermaid
flowchart LR
UI[Vue 3 对话前端] --> CHAT[FastAPI Chat API]
CHAT --> MAIN[主 Agent\n意图识别 / 路由]
MAIN --> ANALYST[采购分析 Agent]
MAIN --> ORDER[采购订单 Agent]
ANALYST --> MCP[MCP 工具层\n8 tools]
ORDER --> HITL[字段补充 / 人工审批]
HITL --> MCP
MCP --> ERP[FastAPI ERP\n54 REST APIs]
ERP --> MYSQL[(MySQL)]
MAIN --> MONGO[(MongoDB\nCheckpoint / Store)]
ANALYST --> SANDBOX[OpenSandbox\nSkills / 文件 / 代码]
ORDER --> SANDBOX
```
## 界面展示
### 多 Agent 智能采购工作台
统一展示会话历史、流式回复、工具调用和 Agent 业务能力。
### 库存分析与可视化报告
采购分析 Agent 调用库存 MCP 工具，输出库存预警表、柱状图和采购建议。
### 订单校验与人工审批
订单 Agent 完成物料、数量、系统单价和交期校验后停在人工审批边界；未经批准不会执行写入。
## 核心流程
### 采购分析
```text
用户需求 → 主 Agent 路由 → 采购分析 Agent
→ MCP 查询 ERP 数据 → 按需加载分析 Skill
→ 沙箱生成报告/图表 → 主 Agent 汇总结论与建议
```
### 采购订单
```text
用户下单/改单 → 主 Agent 路由 → 采购订单 Agent
→ 查询物料、供应商和系统单价
→ 校验 Schema → 结构化补充缺失字段
→ Human-in-the-Loop 最终审批 → MCP 写入 ERP
```
## 项目结构
```text
procureflow-agent/
├─ src/
│ ├─ agent/ # 主 Agent、子 Agent、中间件、记忆、HITL 与沙箱后端
│ ├─ skills/ # 主 Agent、采购分析与订单扩展 Skills
│ ├─ mcp_server/ # 8 个 ERP MCP 工具
│ ├─ erp_api/ # FastAPI + SQLAlchemy ERP 服务
│ └─ api_view/ # 对话、历史记录与流式事件 API
├─ frontend/ # Vue 3 对话前端
├─ tests/ # ERP 流程、54 接口与 8 MCP 工具契约测试
├─ migrations/ # Alembic 基线迁移
├─ database/ # 已匿名化的本地演示数据
├─ demo_data/ # 采购网页抓取的最小可复现报价页面
├─ docs/ # 架构迁移与等价性说明
└─ start_web.py # ERP、MCP、Agent API、前端统一启动器
```
## 快速开始
### 1. 创建环境
推荐使用 Conda，同时管理 Python 3.11 与 Node.js 22：
```powershell
git clone https://github.com/Running-hue/procureflow-agent.git
cd procureflow-agent
conda env create -f environment.yml
conda activate procureflow-agent
Copy-Item .env.example .env
```
在 `.env` 中配置 MySQL、MongoDB、模型服务和 OpenSandbox。仓库不包含任何真实密钥。
### 2. 初始化数据库
创建空表：
```powershell
alembic upgrade head
```
或导入样例数据：
```powershell
python scripts\import_original_sql.py --yes-recreate
```
> 样例导入会重建相关表，请勿对生产数据库执行。
### 3. 启动可选报价演示页
采购分析 Skill 中的三个报价页面已包含在仓库中。OpenSandbox 运行于 Docker 时，可通过 `host.docker.internal` 访问：
```powershell
python -m http.server 5173 --directory demo_data\quote_pages
```
### 4. 启动完整服务
```powershell
python start_web.py
```
| 服务 | 地址 |
|---|---|
| Vue 前端 | `http://127.0.0.1:3000` |
| ERP OpenAPI | `http://127.0.0.1:8080/docs` |
| Agent OpenAPI | `http://127.0.0.1:8090/docs` |
| MCP | `http://127.0.0.1:8000/mcp` |
## 验证
```powershell
python -m pytest -q
ruff check src\erp_api src\mcp_server tests start_web.py scripts
cd frontend
npm ci
npm run build
```
当前自动化验证覆盖：
- 54 个 ERP REST 接口路径契约；
- 8 个 MCP 工具注册契约；
- 供应商、零部件、库存、订单事务与明细流程；
- OpenSandbox 失效恢复逻辑；
- Vue 3 生产构建。
模型、MongoDB、MySQL 和 OpenSandbox 的真实端到端对话需要本地服务与个人密钥，本仓库不伪造外部集成结果。
## 安全设计
- `.env`、本地密钥目录、日志、缓存、生成文件和前端构建产物均被 Git 忽略。
- 采购订单写操作仅由订单子 Agent 执行，并在真正调用 MCP 写工具前要求人工审批。
- 未验证的 Skills 在 OpenSandbox 中执行；用户记忆按 `user_id` 隔离持久化。
- 工具大结果自动 Offloading，上下文接近阈值时自动摘要，降低长链路失败风险。
迁移范围与接口等价性详见 [迁移报告](docs/MIGRATION_REPORT.md)，安全边界详见 [SECURITY.md](SECURITY.md)。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues