基于 LangGraph 和模型上下文协议（MCP）构建的通用助手

模型上下文协议（MCP） 是一种开放协议，能够实现大语言模型应用与外部数据源和工具之间的无缝集成。无论您是在构建一个 AI 驱动的 IDE、增强聊天界面，还是创建自定义的 AI 工作流，MCP 都提供了一种标准化的方式来连接 LLM 与其所需的上下文。您可以将 MCP 看作是 AI 应用程序中的 USB-C 接口。就像 USB-C 提供了一种标准化方式来连接您的设备与各种外设和配件一样，MCP 也为 AI 模型连接不同的数据源和工具提供了标准化途径。

LangGraph 是一个旨在使语言模型无缝集成到复杂工作流和应用程序中的框架。它强调模块化和灵活性。工作流以图的形式表示，节点对应于动作、工具或模型查询，而边则定义了它们之间的信息流动。LangGraph 提供了一种结构化但又动态的任务执行方式，非常适合用于编写涉及自然语言理解、自动化和决策制定的 AI 应用程序。

在 这篇早期文章 中，我们扩展了 LangGraph 的检索代理模板，以开发并部署一个 AI 解决方案。

在这个项目中，我们将 LangGraph 与 MCP 结合起来，构建我们自己的通用助手。对于我们的通用助手，我们采用了多智能体模式，如下所示：

助手接收用户消息，并决定使用哪个智能体。该智能体节点会决定使用哪个工具，然后在 MCP 服务器上调用该工具。由于我们所有的智能体都基于 MCP，因此只需一个 MCP-智能体节点即可完成基于 LLM 的编排工作，而另一个单独的节点则足以与 MCP 服务器协作以调用其工具。

开发环境搭建

1. 创建并激活虚拟环境

   git clone https://github.com/esxr/langgraph-mcp.git
   cd langgraph-mcp
   python3 -m venv .venv
   source .venv/bin/activate
   

2. 安装 LangGraph CLI

   pip install -U "langgraph-cli[inmem]"
   

   注意：“inmem”额外组件用于在开发模式下运行 LangGraph API 服务器（无需安装 Docker）。

3. 安装依赖项

   pip install -e .
   

4. 配置环境变量

   cp env.example .env
   

   将您的 OPENAI_API_KEY、GITHUB_PERSONAL_ACCESS_TOKEN 等添加到 .env 文件中。

   注意：我们已添加对 Milvus Lite Retriever 的支持（支持基于文件的 URI）。Milvus Lite 在 Windows 上无法运行。对于 Windows 用户，您可能需要使用 Milvus Server（通过 Docker 很容易启动），并将 MILVUS_DB 配置更改为基于服务器的 URI。您还可以扩展 retriever.py，以添加您选择的向量数据库的检索器！

实现细节

我们的实现主要分为三个部分：

1. 构建路由节点
2. 助手节点
3. 通用 MCP 包装器

构建路由节点

用于构建路由节点的图在 build_router_graph.py 中实现。它利用我们的 mcp_wrapper.py，根据每个 MCP 服务器提供的工具、提示和资源收集路由信息，并将这些路由信息按每个服务器索引存储在向量数据库中。

助手节点

助手节点的图在 assistant_graph.py 中实现。以下动画借助示例描述了各个节点的作用以及控制流的传递过程：

通用 MCP 包装器

mcp_wrapper.py 使用策略模式，通过一个抽象基类 (MCPSessionFunction) 定义了一个用于在 MCP 服务器上执行各种操作的通用接口。该模式包括：

1. 抽象接口：
   • MCPSessionFunction 定义了一个异步 __call__ 方法，作为所有会话函数的契约。
2. 具体实现：
   • RoutingDescription 类实现了根据工具、提示和资源获取路由信息的功能。
   • GetTools 类实现了从 MCP 服务器获取工具，并将其转换为 LangGraph 可消费的格式。
   • RunTool 类实现了在 MCP 服务器上调用工具并返回其输出的功能。
3. 处理函数：
   • apply 充当统一的执行者。它：
   • 使用 mcp 库中的 stdio_client 初始化会话。
   • 通过 await fn(server_name, session) 将实际操作委托给提供的 MCPSessionFunction 实例。
4. 可扩展性：
   • 可以通过继承 MCPSessionFunction 来添加新的操作，而无需修改核心处理逻辑。例如，我们可以使用这种模式来添加获取工具和执行工具的支持。

演示！

这里有一个端到端的视频！

https://github.com/user-attachments/assets/cf5b9932-33a0-4627-98ca-022979bfb2e7

langgraph-mcp 快速上手指南

langgraph-mcp 是一个结合 LangGraph 工作流引擎与 模型上下文协议 (MCP) 的通用 AI 助手框架。它允许你通过标准化的 MCP 接口连接外部数据源和工具，并利用 LangGraph 的多 Agent 架构自动路由用户请求、选择合适工具并执行任务。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux 或 macOS（推荐）。
  • 注意: 项目默认集成的 Milvus Lite 向量数据库不支持 Windows。Windows 用户需使用 Docker 部署 Milvus Server 并修改配置，或直接在 Linux/macOS/WSL2 环境下开发。
• Python: 版本 3.10 或更高。
• Git: 用于克隆代码仓库。
• API Keys:
  • OPENAI_API_KEY: 用于驱动 LLM。
  • GITHUB_PERSONAL_ACCESS_TOKEN (可选): 如果需要使用 GitHub 相关的 MCP 工具。

安装步骤

按照以下步骤完成本地开发环境的搭建：

1. 克隆项目并创建虚拟环境

   git clone https://github.com/esxr/langgraph-mcp.git
   cd langgraph-mcp
   python3 -m venv .venv
   source .venv/bin/activate
   

2. 安装 LangGraph CLI 安装带有 inmem 扩展的 CLI，以便在不依赖 Docker 的情况下以开发模式运行 LangGraph API 服务器。

   pip install -U "langgraph-cli[inmem]"
   

   国内加速提示: 如果下载缓慢，可指定国内镜像源： pip install -U "langgraph-cli[inmem]" -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装项目依赖

   pip install -e .
   

   国内加速提示: pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 配置环境变量 复制示例配置文件并填入你的密钥。

   cp env.example .env
   

   编辑 .env 文件，添加必要的凭证：

   OPENAI_API_KEY=sk-your-openai-key
   GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your-github-token
   # 如果使用远程 Milvus 服务器，在此处修改 MILVUS_DB 配置
   

基本使用

本项目核心包含三个部分：路由器 (Router)、助手 (Assistant) 和 MCP 通用封装。启动后，系统会自动根据 MCP 服务器提供的工具、资源和提示词构建路由索引，并根据用户输入自动调度 Agent。

启动开发服务器

在项目根目录下，使用 LangGraph CLI 启动服务：

langgraph dev

启动成功后，终端会显示本地 API 地址（通常为 http://localhost:2024）以及交互式 Playground 的地址。

调用示例

你可以直接向助手发送自然语言指令，系统会自动判断需要调用哪个 MCP 服务器的工具。

场景示例：假设你配置了支持 GitHub 和文件检索的 MCP 服务器。

1. 打开浏览器访问 LangGraph Playground UI（由 langgraph dev 命令输出）。
2. 在输入框中输入：

   帮我查找仓库中关于 authentication 的最新文档，并总结其主要内容。
   

3. 执行流程：
   • Router 分析意图，识别出需要“搜索文档”和“读取文件”的能力。
   • Assistant 调度对应的 MCP Agent。
   • MCP Wrapper 通过 stdio 连接到配置的 MCP 服务器，执行具体的 list_resources 或 run_tool 操作。
   • 最终返回整合后的回答。

自定义扩展

若要添加新的向量数据库检索器或自定义 MCP 操作，可修改以下核心文件：

• 路由逻辑: src/langgraph_mcp/build_router_graph.py
• 助手工作流: src/langgraph_mcp/assistant_graph.py
• MCP 策略模式实现: src/langgraph_mcp/mcp_wrapper.py (继承 MCPSessionFunction 即可扩展新功能)