第一部分. 具有 MCP 工具执行的实时 LangGraph Agent

本项目演示了一种解耦的实时 Agent 架构，该架构将 LangGraph Agent 连接到由自定义 MCP（模块化命令协议）服务器提供的远程工具。该架构支持灵活且可扩展的多 Agent 系统，其中每个工具都可以独立托管（通过 SSE 或 STDIO），从而提供模块化和可云部署的执行。

• 解耦架构： 设计了一个模块化系统，其中基于 LangGraph 的 Agent 编排 LLM 工作流程，同时通过 SSE 和 STDIO 传输将工具执行委托给远程 MCP 服务器。
• 高级异步编程： 利用 Python 的 async/await 进行非阻塞 I/O，确保多个工具的并发执行和可扩展的实时通信。
• MCP & LangGraph 集成： 展示了将模块化命令协议 (MCP) 与 LangGraph 和 LangChain 集成的深厚专业知识，从而能够无缝转换和调用分布式工具。
• 灵活的多服务器连接： 设计了一个 MultiServerMCPClient，支持与各种工具服务器的 1:1 绑定，突出了系统集成不同环境（本地、云、容器化）的能力。
• 强大的 Agent 到工具通信： 实现了详细的客户端会话、握手协议和动态工具发现，确保 Agent 和 MCP 服务器之间可靠的执行和交互。
• 前瞻性的互操作性： 为 Agent2Agent 协议奠定了基础，旨在创建一个 AI Agent 可以共享能力、协调行动并安全交换上下文和数据的生态系统。

---

🚀 项目目的

本项目旨在：

• 将 基于 LLM 的 Agent 编排 (LangGraph) 与 工具执行（通过 MCP 服务器）解耦。
• 使用 MCP 协议实现 实时、多服务器 和 语言无关 的工具集成。
• 展示如何：
  • 启动与 LangChain 兼容的 MCP 工具服务器（例如，math_server.py、weather_server.py）
  • 将它们与 LangGraph ReAct Agent 集成
  • 使用 async/await 编程来实现 Agent 和工具服务器之间的非阻塞 I/O

---

📦 项目结构

.
├── servers/
│   ├── math_server.py         # 基于 STDIO 的 MCP 工具服务器
│   └── weather_server.py      # 基于 SSE 的 MCP 工具服务器
├── client/
│   ├── multiserver_client.py  # 使用 MultiServer MCP 客户端的 LangGraph Agent
│   └── stdio_client.py        # 使用 STDIO 传输的 LangGraph Agent

---

🔧 技术栈

• 🧠 LangGraph: ReAct Agent 编排
• 🔗 LangChain: LLM 管道和工具抽象
• 🧰 MCP (模块化命令协议):
  • FastMCP – 基于 FastAPI 的服务器抽象
  • ClientSession, StdioServerParameters, MultiServerMCPClient
• 🌐 SSE & STDIO: 传输协议
• 🔁 AsyncIO: 异步并发
• ☁️ OpenAI: 后端 LLM（通过 langchain_openai）
• 🧪 dotenv: API 密钥管理

---

📜 源代码分解

1. math_server.py 和 weather_server.py

使用 FastMCP 的工具服务器：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> str:
    return "Cold in Chicago"

if __name__ == "__main__":
    mcp.run(transport="sse")

✅ 亮点：

• 每个服务器通过 @mcp.tool() 定义一个异步工具
• 服务器与传输无关：可以通过 SSE 或 STDIO 运行
• 专为模块化部署而设计：本地、云、容器化

2. multiserver_client.py

同时与多个 MCP 服务器通信的 Agent：

async with MultiServerMCPClient({
    "math": {"command": "python", "args": ["math_server.py"]},
    "weather": {"url": "http://localhost:8000/sse", "transport": "sse"}
}) as client:
    agent = create_react_agent(llm, client.get_tools())
    result = await agent.ainvoke({"message":"what's 1+1?"})

✅ 亮点：

• MultiServerMCPClient 支持与多个服务器的 1:1 绑定
• 所有工具调用都是异步的，并通过适当的传输进行流式传输
• 工具自动转换为与 LangChain 兼容的格式

3. stdio_client.py

Agent 使用原始 ClientSession 连接到一个 STDIO MCP 服务器：

async with stdio_client(StdioServerParameters(...)) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await load_mcp_tools(session)
        agent = create_react_agent(llm, tools)
        result = await agent.invoke({"messages": [HumanMessage(content="What's 1+1?")]})

✅ 亮点：

• ClientSession.initialize() 设置符合 MCP 规范的握手
• 工具通过 session.list_tools() 和 load_mcp_tools() 动态发现
• 显示对 I/O 流的低级控制

🔄 LangGraph 和 MCP 如何交互

Agent 流程：

1. Agent 创建，使用来自 MCP 客户端的工具
2. Agent 接收 用户查询
3. Agent 识别所需的工具
4. MCP 客户端将 工具调用请求 发送到远程服务器
5. 远程服务器执行工具，将结果发回
6. Agent 使用结果并返回最终响应

架构图：

+----------------+         +----------------------+        +------------------------+
| LangGraph App  |<------->| MultiServerMCPClient |<-----> |   Remote MCP Servers   |
| (ReAct Agent)  |         |  (Tool Wrapper Layer)|        | (math_server, weather) |
+----------------+         +----------------------+        +------------------------+
                                 |                                ^
                                 |                                |
                                 +--------------------------------+
                                       Async I/O (SSE or STDIO)

---

🧠 异步使用和优势

整个系统使用 async/await 来：

• 避免在等待工具响应时阻塞
• 允许并发执行多个工具
• 实现 可扩展的 实时工具编排

所有 I/O – 无论是基于网络的 (SSE) 还是基于管道的 (STDIO) – 都是 异步 处理的，从而最大限度地提高响应能力和吞吐量。

---

✅ 优点

• 模块化和可扩展： 工具服务器可以独立扩展
• 语言无关： MCP 规范支持 Python、Node.js、Dockerized 服务
• 实时执行： SSE 和 STDIO 传输支持实时交互
• LangChain 兼容： 完全支持 LangChain 和 LangGraph 工作流程

---

⚠️ 挑战

• 工具发现延迟： 初始握手会增加轻微的开销
• 传输复杂性： 管理多种传输类型（SSE 与 STDIO）可能并非易事
• 错误处理： 必须优雅地处理工具服务器故障或超时
• 部署策略： 在生产中需要编排层（例如 Docker Compose、K8s）

---

🔮 未来方向

• 具有 StdioServerParameters + 容器支持的 Dockerized 工具服务器
• 用于安全服务器访问的 身份验证层
• 可观察性： 用于工具使用的日志、跟踪和实时仪表板
• LangGraph 并行节点： 并行子图中运行多个 MCP 调用
• 多模态工具： 扩展 MCP 工具以支持图像/音频输入

---

🧩 相关概念

• MCP： 用于定义和调用模块化工具的协议
• LangGraph： 受状态机启发的 Agent 推理框架
• ReAct： 用于结构化决策的推理和行动范例
• LangChain 工具： 将外部函数/API 转换为 LLM 可调用的工具

---

📌 结论

本项目展示了 LLM 应用程序开发中清晰的关注点分离：

• LangGraph 专注于 Agent 逻辑和编排
• MCP 服务器 处理实际的任务执行
• 异步客户端 将两者连接起来，提供实时通信

这是一个面向未来的架构，用于构建具有模块化、可观察和可维护组件的企业级 LLM 应用程序。

✨ Agent2Agent 协议

AI Agent 通常隔离在特定的应用程序或平台中，它们缺乏通用的方式来与其他供应商构建的或使用不同框架的 Agent 进行通信、共享信息或协调行动。A2A 定义了 Agent 发现能力的标准方式，Agent 可以宣传其功能，以便其他 Agent 知道它们可以做什么。Agent 可以分配和跟踪任务，包括复杂的长期任务，交换状态更新和结果。Agent 可以安全地交换包含上下文指令或数据的消息。Agent 可以根据用户界面功能就呈现信息的最佳格式（文本、图像）达成一致。我们的目标是创建一个可互操作的生态系统，其中 AI Agent 可以跨不同的企业应用程序无缝地协同工作。

---

第二部分. MCP-AI-Infra-Real-Time-Agent

开发了一种基于 MCP 的 AI 基础设施，该基础设施支持实时工具执行、结构化知识检索以及用于 Claude 和 Cursor 等 AI 客户端的动态 Agent 交互。

• 设计并实现了一个基于 MCP 的 AI 系统，该系统支持实时工具执行、结构化知识检索以及用于 Claude 和 Cursor 等 AI 客户端的 Agent 工作流程。
• 开发了一个 MCP 服务器-客户端架构，以促进无缝的 LLM 交互，公开工具（get_forecast、get_alerts）、资源（API 响应、文件内容）和提示（结构化任务模板）。
• 设计了一个动态工具执行框架，允许 AI 模型在用户批准的情况下调用外部 API 服务，从而改进 AI 辅助决策和自动化。
• 将 MCP 与 LangGraph 驱动的检索增强生成 (RAG) 工作流程集成，优化上下文文档检索和结构化响应生成。
• 通过设计一个 MCP 协议（其中 AI 组件充当客户端和服务器），实现了可组合的 AI Agent，从而支持多层 Agent 交互和模块化可扩展性。
• 通过利用 MCP 协议作为通用 AI 接口，增强了系统的互操作性，从而允许跨不同主机环境的即插即用 AI 功能。
• 构建了一个自我演进的工具注册表 API，支持动态能力发现和运行时工具注册，从而支持自适应 AI 工作流程和不断发展的 Agent 系统。
• 通过缓存和并行请求处理优化了 AI 工具执行，从而提高了 MCP 服务器响应时间和 LLM 推理效率。
• 利用 Anthropic 的 MCP Inspector 进行交互式调试和测试，从而改进 AI Agent 行为和工具执行管道。
• 开发了一个可扩展的框架，支持未来在 MCP 生态系统中集成其他 AI 驱动的实用程序、自动化 Agent 和外部 API 服务。

项目概述

MCP-Servers 项目专注于实现和扩展 MCP（模型控制协议）服务器，该服务器促进 Claude 和 Cursor 等 AI 系统的实时、基于文档的响应。目标是集成一个 MCP 客户端-服务器架构，该架构使 AI 模型能够动态地访问结构化知识并调用特定工具。

核心目标

1. MCP 客户端-服务器集成

• 实现一个连接到 AI 客户端（如 Claude 3.7 Sonnet Desktop 和 Cursor）的 MCP 服务器。
• 使用现有的 MCP 框架（例如，mcpdoc）以避免重新发明核心功能。

2. 扩展 MCP 服务器功能

• 为 MCP 服务器开发 自定义工具，特别是用于获取外部数据（如天气预报和警报）。
• 将这些功能公开为 MCP 工具 (get_forecast, get_alerts)，使其可供 AI 客户端使用。

3. 增强 AI 工具执行

• 使 AI 模型能够通过在用户批准的情况下调用工具来与 MCP 服务器交互。
• 确保正确处理资源（例如，API 响应、文件内容）和提示（用于结构化任务的预写模板）。

---

MCP 架构和工作流程

1. MCP 作为通用 AI 接口

• MCP 充当 互操作性层，允许外部 AI 应用程序（Claude、Cursor 等）与结构化数据源和可执行函数交互。
• 它遵循 类似 USB-C 的架构，其中 MCP 服务器充当可以连接到各种 AI 系统的外部插件。

2. MCP 客户端-服务器角色

MCP 客户端（嵌入在 AI 主机（如 Claude 或 Cursor）中）

• 请求工具、查询资源和处理提示。
• 充当 AI 系统和 MCP 服务器之间的桥梁。

MCP 服务器（在本地实现）

• 公开工具（例如，天气 API），以便 AI 客户端动态调用。
• 提供资源（例如，API 响应、数据库查询）。
• 处理提示 以启用结构化用户交互。

---

主要特性和未来增强

• Agent 可组合性： 该架构允许 多层 Agent 交互，其中 AI Agent 可以同时充当 MCP 客户端和服务器。这使得模块化、专门的 Agent 能够处理不同的任务。
• 通过注册表 API 实现自我演进的 AI： 未来的迭代可以支持 动态工具发现，其中 AI 客户端可以实时注册和发现新的 MCP 功能。
• 开发和调试支持： 利用 Anthropic 的 MCP Inspector 来测试和调试 MCP 交互，而无需完全部署。

---

结论

本项目构建了一个 MCP 驱动的 AI 基础设施，该基础设施将 AI 模型与实时结构化知识连接起来，通过自定义工具执行扩展其功能，并增强 Agent 可组合性。目标是创建一个 自适应的、类似插件的 AI 系统，该系统可以集成到多个主机中，同时通过工具注册和运行时发现动态演进。

附录

• 不要重新发明轮子

MCP 就像 USB-C，MCP 服务器就像可以与 AI (Claude Desktop) 或云应用程序连接的外部设备。我们可以编写一次功能，并插入到许多 MCP 主机中。MCP 客户端位于 MCP 主机内部，通过 MCP 协议与 MCP 服务器进行 1:1 交互。MCP 客户端调用工具、查询资源、插入提示；MCP 服务器公开工具（模型控制：检索、数据库更新、发送）、资源（应用程序控制：数据库记录、API）、提示（用户控制：文档）。

MCP + 容器化

使用 UV 初始化项目，使用 UV 创建虚拟环境，安装依赖项（MCP [CLI]），使用 Cursor 索引官方 MCP 文档，使用 Cursor 规则更新项目

Vibe 编码

• @server.py 从 @MCP 实现一个简单的 MCP 服务器。使用 Python SDK @MCP Python SDK，服务器应该公开一个名为 terminal tool 的工具，该工具将允许用户运行终端命令，使其简单
• 帮助我在我的 mcp 服务器 @MCP 中公开一个资源，再次使用 @MCP Python SDK 来编写代码。我想公开我 Desktop 目录下的 mcpreadme.md。

致谢

MCP 速成课程：一天内完成模型上下文协议