MCP aggregator manager

MCP Aggregator Manager

一个基于MCP (Model Context Protocol) 协议的高性能聚合管理器，支持多源服务聚合、智能搜索和动态工具调用。

🚀 功能特性

• 多源聚合: 支持同时连接和管理多个MCP服务
• 智能搜索: 基于向量嵌入的语义搜索，支持自然语言查询
• 动态调用: 实时发现和调用可用的MCP工具
• 实时通信: 基于ASGI和SSE的实时客户端-服务器通信
• 向量化存储: 使用Qwen3-Embedding-0.6B模型生成高质量向量嵌入
• Web界面: React + TypeScript构建的现代化管理界面

🏗️ 架构设计

Browser [Web前端] |HTTP/REST| API [FastAPI/ASGI服务器]
Client [MCP客户端] |SSE/JSON-RPC| API
API  Aggregator [聚合逻辑]
Aggregator  ClientMgr [客户端管理器]
Aggregator  VectorDB [向量数据库管理器]
Ingestor [服务摄取器] --> EmbedModel [Qwen3嵌入模型]

核心组件

• ClientManager: 管理和维护MCP客户端连接池
• MCPAggregator: 核心聚合逻辑，处理搜索和工具调用
• Service Ingestor: 自动发现、连接和摄取MCP服务
• Vector DB Manager: 向量存储和检索管理
• AI服务层: 基于Qwen3模型的向量化服务

工作流程

1. 摄取 (Ingest): 发现并连接可用的MCP服务
2. 向量化 (Embed): 提取工具描述并生成向量嵌入
3. 搜索 (Search): 基于语义相似度搜索匹配的工具
4. 调用 (Invoke): 动态加载并执行选定的工具

🛠️ 技术栈

后端

• Python 3.8+
• FastAPI: 现代化Web API框架
• ASGI: 异步服务器网关接口
• SQLite + sqlite-vec: 轻量级向量数据库
• Tortoise ORM: 异步ORM框架
• Sentence Transformers: 向量化模型支持

前端

• React 18: 用户界面库
• TypeScript: 类型安全的JavaScript
• Vite: 现代化构建工具
• ESLint: 代码质量检查

AI模型

• Qwen3-Embedding-0.6B: 阿里巴巴千问嵌入模型

📦 安装和配置

环境要求

• Python 3.8+
• Node.js 16+
• npm 或 yarn

后端安装

# 进入后端目录
cd mcp_aggregator_manager

# 安装Python依赖
pip install -r requirements.txt

# 确保Qwen3模型已下载到 models/ 目录
# models/
# └── Qwen3-Embedding-0.6B/

前端安装

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 开发模式启动
npm run dev

配置说明

1. 模型配置: Qwen3嵌入模型会自动检测本地路径（models/Qwen3-Embedding-0.6B/）
2. 数据库: SQLite数据库会自动创建在项目根目录
3. 端口配置: 默认API服务运行在8000端口，前端运行在5173端口

🚀 快速开始

启动服务

# 启动后端API服务
python -m src.mcp_aggregator.server

# 启动前端开发服务器 (在另一个终端)
cd frontend && npm run dev

访问应用

• Web界面: http://localhost:5173
• API文档: http://localhost:8000/docs
• WebSocket连接: ws://localhost:8000/ws

基本使用

1. 添加MCP服务: 在Web界面中输入MCP服务连接信息
2. 自动摄取: 系统自动发现和索引可用的工具
3. 智能搜索: 使用自然语言描述需求，系统自动匹配相关工具
4. 动态调用: 实时执行匹配的工具并返回结果

📖 API文档

主要端点

• GET /: 服务状态检查
• POST /search: 搜索MCP工具
• POST /execute: 执行MCP工具调用
• GET /services: 获取已注册的服务列表
• POST /register: 注册新的MCP服务

WebSocket事件

• connect: 建立连接
• search: 实时搜索请求
• execute: 实时工具执行
• response: 服务响应

🔧 开发

项目结构

mcp_aggregator_manager/
├── src/
│   └── mcp_aggregator/
│       ├── __init__.py
│       ├── server.py          # FastAPI服务器
│       ├── aggregator.py      # 核心聚合逻辑
│       ├── ingestor.py        # 服务摄取器
│       ├── database.py        # 数据库管理
│       └── services/
│           └── ai_service.py  # AI向量化服务
├── frontend/                  # React前端
├── models/                    # AI模型存储
├── docs/                      # 项目文档
└── requirements.txt           # Python依赖

开发模式

# 后端热重载启动
uvicorn src.mcp_aggregator.server:create_app --reload --host 0.0.0.0 --port 8000

# 前端开发服务器
cd frontend && npm run dev

代码规范

• Python: 遵循PEP 8规范
• TypeScript: 使用ESLint和Prettier
• 类型提示: 所有Python函数都需要类型注解

🤝 贡献指南

1. Fork本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开Pull Request

📄 许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情

🆘 常见问题

Q: Qwen3模型下载失败怎么办？ A: 确保网络连接正常，或手动下载模型到 models/Qwen3-Embedding-0.6B/ 目录

Q: 如何添加新的MCP服务？ A: 通过Web界面的"注册服务"功能，或直接调用 /register API端点

Q: 搜索结果不准确怎么办？ A: 检查工具描述的质量，或调整向量相似度阈值

Q: 如何监控服务状态？ A: 查看 GET /services 端点，或在Web界面中查看服务状态面板

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 提交Issue
• 发送邮件
• 加入我们的讨论群

MCP Aggregator Manager - 让MCP服务聚合变得简单高效 🚀