mcp-agent
Haohao-end/mcp-agent加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你问 AI 助手："深圳今天天气怎么样？"它一本正经地回答："深圳今天晴朗，温度适宜。"然而此刻深圳正在下暴雨。这个场景几乎每个用过 AI 助手的用户都遇到过——大模型的知识是有时间截止点的，它不知道今天发生了什么，更无法替你查天气、搜文档、调用外部工具。
MCP Agent Orchestrator 正是为了解决这个尴尬而生的。这个来自个人开发者的 Python 项目，将 Model Context Protocol（MCP） 协议落了地，让大模型可以真正调用外部工具、访问实时数据，而不只是待在"知识茧房"里输出文本。
2024 年底，Anthropic 正式发布了 Model Context Protocol（MCP） 开源协议。它的核心目标是解决一个长期困扰 AI 应用开发者的痛点：每个工具都要单独适配，导致 AI 与外部系统的集成成本极高。
想象一下：你要让 AI 能查天气，就要写一套天气 API 适配；让 AI 能搜文档，又要写另一套；让 AI 能读数据库，再写一套。这些适配代码散落在各个项目中，难以复用，成了 AI 应用开发中的"重复造轮子"重灾区。
MCP 协议的出现，就是要成为 AI 领域的"USB-C"——提供统一的标准接口，让任何 AI 模型可以通过同一套协议连接任何外部工具。就像 USB-C 让手机、笔记本、充电器互相兼容一样，MCP 让大模型与各种外部系统"即插即用"。
这个项目并非单一功能的工具，而是一个 MCP 协议的 Python 实现框架，提供了多个可独立使用的服务端示例，展示了 MCP 在不同场景下的应用潜力。
Weather 服务端演示了 MCP 最基础也是最核心的能力：让大模型调用外部 REST API 并处理返回结果。
项目使用 FastMCP 框架（来自 MCP 官方 Python SDK）定义工具函数，通过 @mcp.tool() 装饰器将 get_weather() 注册为可被 LLM 调用的工具。服务端接收城市参数后，异步请求 WeatherAPI 并将结果标准化返回。整个通信基于 StdIO（标准输入/输出），这是 MCP 推荐的本地进程间通信方式，具有低延迟、高可靠性的特点。
关键代码逻辑：
get_weather() 获取实时数据这个模式的优势在于：工具的定义和执行是解耦的。Server 可以是任意语言实现的独立进程，只要遵循 MCP 协议就能与 Client 通信。
项目提供了两种 RAG（检索增强生成）实现路径：
路径 A：LangChain RAG（mcp_rag_langchain）
使用 LangChain 作为核心框架，构建完整的 RAG 流程：
PyPDFLoader 和 TextLoader 读取RecursiveCharacterTextSplitter 按语义切分路径 B：GraphRAG（mcp_rag_agent_graphrag）
这是一个更进阶的版本，集成了 Microsoft GraphRAG 技术。GraphRAG 是 2024 年微软开源的知识图谱增强检索方案，与传统 RAG 相比，它能更好地理解实体之间的语义关系，尤其适合处理复杂的多跳问题。
GraphRAG 版本使用了 LanceDB 作为向量存储，并内置了完整的实体抽取、社区检测和关系图谱构建流程。
项目的架构遵循 MCP 协议的核心理念：标准化的通信层 + 灵活的工具实现。
Client 层负责：管理与 Server 的 StdIO 连接生命周期；将 Server 的工具 schema 自动转换为 OpenAI function calling 格式；维护多轮对话状态，管理工具调用的循环逻辑。
Server 层则专注于具体工具的实现细节，完全不感知 Client 如何使用这些工具。这种分层设计使得同一个 Server 可以同时被多个不同架构的 Client 调用。
[LLM (OpenAI Compatible)]
↓
[MCP Client] ← AsyncExitStack 管理会话生命周期
↓ (StdIO)
[MCP Server] ← 可独立替换的工具实现
├── Weather Server (FastMCP + httpx)
├── RAG LangChain Server (LangChain + ChromaDB)
└── RAG GraphRAG Server (GraphRAG + LanceDB)
坦诚地说，这个项目在部署便利性上还有较大提升空间。项目没有提供 Dockerfile 或 docker-compose.yml，也没有预构建的安装脚本，所有依赖都需要手动安装。
部署步骤大约需要 15-30 分钟：
mcp、fastmcp、openai、langchain、chromadb、httpx 等.env 文件，填入 API Key、模型地址等python server.py（Weather）或 python rag_server.py（RAG）python client.py 或 python rag_agent.py硬件要求不高：CPU 2 核以上、4GB 内存即可，无需 GPU。操作系统支持 Linux/macOS/Windows。
这个项目虽然展示了 MCP 协议的强大潜力，但也存在一些需要正视的问题：
1. 缺乏开箱即用体验
没有 Dockerfile 意味着初次部署需要手动解决依赖冲突。以 LangChain 生态的版本兼容性著称，项目使用的 langchain_community 等包的版本管理可能需要一些耐心。
2. 许可证问题 项目没有声明任何开源许可证。在 GitHub 上没有 License 文件意味着默认适用最严格的著作权保护——虽然代码可以浏览，但不确定是否可以自由使用、修改和分发。这一点需要特别关注。
3. 演示性质的代码 Weather API 的 Key 是硬编码为空字符串的，README 中的示例配置也不够完整。这些更像是"概念验证"（Proof of Concept），距离生产级应用还有距离。
4. GraphRAG 的资源消耗 GraphRAG 版本包含 LanceDB 的持久化数据和完整的图谱构建流程，在没有示例数据的情况下，冷启动的初始化过程可能比较耗时。
2024-2025 年是 MCP 协议生态快速扩张的年份。Anthropic 之后，Google、OpenAI 等主要 AI 厂商陆续宣布支持 MCP 协议，越来越多的工具开始提供原生 MCP Server 实现。
MCP Agent Orchestrator 虽然只是一个个人项目，但它验证了 MCP 协议在 Python 生态中的可行性，展示了将 LangChain、GraphRAG 等主流框架与 MCP 协议结合的思路。这种组合意味着：现有的 RAG 系统、知识图谱工具，都可以低成本地改造成 MCP Server，被任何支持 MCP 的 AI 应用调用。
从增长数据看，项目获得了 75 颗 Stars，月增长趋势分 1.03（基本持平），虽然体量不大，但在 MCP 这个新兴赛道上已经算是不错的起步。
如果你想体验这个项目，建议从 Weather Server 开始：
# 1. 克隆项目
git clone https://github.com/Haohao-end/mcp-agent
cd mcp-agent
# 2. 创建虚拟环境
python -m venv venv && source venv/bin/activate
# 3. 安装依赖
pip install mcp fastmcp openai langchain langchain-community langchain-openai chromadb httpx python-dotenv
# 4. 配置环境变量
echo 'API_KEY=your_key' >> .env
echo 'BASE_URL=https://api.openai.com/v1' >> .env
# 5. 启动天气服务
python server.py &
# 6. 启动客户端
python client.py
整体来看，这个项目是一个有价值的 MCP 协议学习样本，展示了客户端-服务端架构、工具调用流程和 RAG 集成的完整实现。虽然距离生产级应用还有差距，但对于想了解 MCP 协议如何落地的开发者而言，是一个值得研究的对标案例。