内容
# MCPPro 智能系统
欢迎使用 **MCPPro 智能系统**，这是一个生产级别、最新的 AI 代理和文档 RAG（检索增强生成）编排平台。MCPPro 采用分层架构，分为编排器层、专门的模型上下文协议（MCP）工具层、FastAPI 文档处理管道和安全的遥测/矢量存储。
## 系统架构
MCPPro 架构由五层组成，结构如下：
```mermaid
graph TD
%% Client Layer
subgraph ClientLayer["1. 客户端层"]
Chat["网页聊天界面<br/>- 聊天界面<br/>- 流式响应<br/>- 文件/文档上传"]
Admin["管理员仪表盘<br/>- API 监控<br/>- 分析和指标<br/>- 请求日志"]
end
%% Backend 1 Layer
subgraph Backend1["2. 后端 1（编排器 - Next.js）"]
RunEndpoint["/api/run（评估）<br/>- 查询细化（最多 15 步）<br/>- 工具编排"]
ChatEndpoint["/api/chat（聊天）<br/>- 多代理协调<br/>- 上下文管理"]
AuthEndpoint["/api/auth（身份验证）<br/>- 会话管理<br/>- Supabase 身份验证"]
MCPClient["MCP 客户端管理器<br/>- 发现和管理 MCP 服务器<br/>- 动态路由工具/代理"]
Observability["可观察性层<br/>- 跟踪和性能指标<br/>- 工具执行日志"]
end
%% LLM Providers
LLM["LLM 提供商<br/>- OpenAI（GPT-4.1）<br/>- Google Gemini<br/>- Grok"]
%% Tool Layer
subgraph ToolLayer["3. 工具层（由 MCP 客户端管理器注册和执行）"]
subgraph CoreTools["核心工具"]
JS["JavaScript 运行器<br/>（沙箱执行）"]
FC["文件创建器<br/>（创建/编辑文件）"]
WS["网页搜索<br/>（搜索和检索）"]
end
subgraph MCPServers["MCP 服务器"]
BrowserMCP["浏览器 MCP 服务器<br/>（自动化和抓取）"]
RAGMCP["RAG MCP 服务器<br/>（连接到后端 2）"]
ComputerMCP["计算机 MCP 服务器<br/>（操作系统自动化）"]
end
subgraph ExternalAPIs["外部 API 和服务"]
Tavily["Tavily 网页搜索"]
GitHub["GitHub API"]
Resend["Resend 电子邮件"]
V0["v0 UI 生成器"]
end
end
%% Backend 2 Layer
subgraph Backend2["4. 后端 2（FastAPI/Python）"]
subgraph RAGPipeline["文档智能和 RAG 管道"]
DocPipe["文档管道<br/>（PDF、DOCX、PPTX、图像）"] --> OCR["OCR 引擎<br/>（Tesseract、EasyOCR）"]
OCR --> Embed["嵌入引擎<br/>（OpenAI 嵌入、BGE-M3）"]
Embed --> Retrieve["RAG 检索引擎<br/>（相似性搜索、LangChain QA）"]
Retrieve --> Context["相关上下文<br/>为代理"]
end
end
%% Data Layer
subgraph DataLayer["5. 数据层"]
Supabase["Supabase PostgreSQL<br/>- 用户和会话<br/>- 日志和分析<br/>- 设置和文件元数据"]
VectorDBs["矢量数据库<br/>- Pinecone<br/>- Qdrant<br/>- PGVector"]
end
%% Connections
Chat & Admin <-->|"HTTPS / WebSocket"| Backend1
Backend1 <--> LLM
Backend1 <--> MCPClient
Backend1 <--> Observability
MCPClient <--> CoreTools
MCPClient <--> MCPServers
MCPClient <--> ExternalAPIs
RAGMCP <--> Backend2
RAGPipeline <--> VectorDBs
Backend1 <--> Supabase
Supabase <-->|"安全连接"| VectorDBs
```
### 五层架构：
1. **客户端层**：包含 **网页聊天界面**（带有流式响应、多模型选择和文件上传）和 **管理员仪表盘**（带有请求日志、分析和服务指标）。
2. **后端 1（编排器）**：Next.js 14 API 路由（`/api/run`、`/api/chat` 和 `/api/auth`）作为入口点。**MCP 客户端管理器**在此层协调多代理交互，并决定哪个工具或代理应处理查询。
3. **工具层**：包含核心工具（如 JavaScript 执行和文件编辑）、专门的 **MCP 服务器**（如网页浏览代理和 RAG 查询代理）和外部集成（Tavily 搜索、GitHub、Resend 和 v0）。
4. **后端 2（FastAPI/Python）**：包含 **文档智能和 RAG 管道**。处理文档上传、OCR 提取（使用 Tesseract/EasyOCR）、嵌入生成（BGE-M3 或 OpenAI）和文档检索。
5. **数据层**：依赖 **Supabase PostgreSQL** 作为核心事务数据库，用于日志记录、会话、用户设置和元数据，以及 **矢量数据库**（Qdrant、Pinecone 或 PGVector）用于语义存储。
## 快速入门
### 先决条件
确保您的机器上已安装以下内容：
- **Node.js**：`18.x` 或更高版本（带有 `npm` 包管理器）
- **Python**：`3.12.x`（推荐）
- **Docker 和 Docker Compose**：用于容器化设置
- **Tesseract OCR**：用于基于图像的文档解析（可选）
## 统一本地执行（Docker Compose）
运行整个栈（Next.js 前端、FastAPI 后端和 Qdrant 矢量存储）的最简单方法是使用 Docker Compose：
```bash
# 克隆存储库并导航到根目录
cd MCPPRO-agent-main
# 在后台启动所有服务
docker compose up -d
```
启动后，请访问以下服务：
* **前端**：[http://localhost:3000](http://localhost:3000)
* **FastAPI 后端**：[http://localhost:8000](http://localhost:8000)
* **API 文档**：[http://localhost:8000/docs](http://localhost:8000/docs)
* **Qdrant 控制台**：[http://localhost:6333/dashboard](http://localhost:6333/dashboard)
## 环境变量配置
前端和后端都依赖于配置文件（`.env` 和 `.env.local`）。关键配置值包括：
| 键 | 描述 | 推荐/示例 |
| :--- | :--- | :--- |
| `ENVIRONMENT` | 部署环境 | `development` / `production` |
| `DEFAULT_VECTOR_STORE` | 目标矢量数据库 | `inmemory` / `qdrant` / `pinecone` |
| `DEFAULT_LLM_PROVIDER` | 默认 LLM 服务 | `openai` / `gemini` / `anthropic` |
| `SUPABASE_URL` | Supabase API 端点 | `https://your-project.supabase.co` |
| `SUPABASE_SERVICE_KEY` | 关系和日志存储密钥 | `your-supabase-service-key` |
| `OPENAI_API_KEY` | OpenAI 身份验证 | `sk-proj-...` |
| `GEMINI_API_KEY` | Gemini 身份验证 | `AIzaSy...` |
## CI/CD 管道
该项目使用 GitHub Actions 配置了自动 CI/CD 管道，位于 [.github/workflows/ci-cd.yml](file:///D:/Antigravity/Major-project/MCPPRO%20agent-main/.github/workflows/ci-cd.yml)。
该管道在每次推送和拉取请求到 `main`、`master` 和 `dev` 分支时运行验证步骤：
- **后端 CI**：设置 Python 3.12，通过 `uv` 安装依赖项，编译后端代码，并使用 `docker/setup-buildx-action` 和 `docker/build-push-action` 运行 dry-run Docker 构建。
- **前端 CI**：设置 Node 18，同步依赖项，验证 Next.js 构建，并运行 dry-run Docker 构建。
## RAG 评估和诊断
要验证 RAG（检索增强生成）搜索引擎的质量和延迟，请运行自动评估运行器：
```bash
cd backend
python scripts/evaluate_rag.py
```
此评估套件测试索引延迟、查询回答延迟和针对目标文档数据集的余弦相似性相关性得分。
## 生产准备就绪
对于生产部署、高可用性架构、故障转移指南和扩展检查清单，请参阅完整的 [PRODUCTION_READINESS.md](file:///D:/Antigravity/Major-project/MCPPRO%20agent-main/PRODUCTION_READINESS.md)。
