agent-craft/m10_mcp_basics/README.md

🧩 模块说明：MCP 基础篇 - 多模态协作协议客户端实现

📌 核心知识点：MCP协议原理｜客户端封装｜工具调用｜LangChain集成｜流式输出

---

1️⃣ simple_client.py （最小化MCP客户端MVP）

实现最基础的MCP单次调用客户端，提供最小可行性实现，是学习MCP的起点。

• ✅ 掌握点：

  • MCP协议的基本调用流程
  • 异步上下文管理器的应用
  • 单次工具调用的完整生命周期
  • 资源的自动创建与清理

• 特点：

  • 代码精简，易于理解
  • 封装程度低，更接近协议本质
  • 适合学习和理解MCP的基本概念
  • 单次调用模式，无需维护长连接

💡 这是理解MCP协议最简单的入口，通过run_once方法将启动进程、握手、调用、关闭等操作封装为一次性流程。

---

2️⃣ simple_main.py （基础使用示例）

展示如何使用simple_client进行单次工具调用，是MCP应用的最简示范。

• ✅ 掌握点：

  • SimpleClient的基本实例化方法
  • 环境变量配置与传递
  • 工具参数构造与调用
  • 异步代码的基本编写方式

• 功能演示：

  • 初始化MCP客户端
  • 调用高德地图搜索功能
  • 处理并显示结果
  • 完整的单次调用生命周期

💡 从这个简单示例开始，可以直观看到MCP工具的调用过程和结果处理方式，适合初学者上手。

---

3️⃣ mcp_client.py （生产级MCP客户端）

实现完整的MCP客户端功能，支持长连接和多次工具调用，是生产环境的标准实现。

• ✅ 掌握点：

  • MCP长连接的建立与维护
  • 工具列表的动态获取
  • 多次工具调用的会话管理
  • 错误处理与异常恢复机制
  • 资源生命周期的精确控制

• 核心功能：

  • connect(): 建立与MCP服务的连接
  • list_tools(): 获取可用工具列表
  • call_tool(): 调用指定工具
  • cleanup(): 清理资源
  • 异步上下文管理器支持

💡 此客户端相比simple版本，增加了长连接复用、错误处理、多次调用等生产级特性，适合构建稳定的应用。

---

4️⃣ mcp_bridge.py （LangChain桥接适配器）

实现MCP工具到LangChain工具的自动转换，是MCP与LangChain生态集成的关键桥梁。

• ✅ 掌握点：

  • MCP工具元数据到LangChain工具的转换
  • JSON Schema到Pydantic模型的动态映射
  • 异步工具与LangChain的集成
  • 工具参数的类型安全转换

• 技术要点：

  • 自动从MCP服务获取工具定义
  • 生成符合LangChain规范的工具描述
  • 处理参数验证和类型转换
  • 管理MCP客户端的生命周期

💡 此适配器使得任何MCP服务都能无缝集成到LangChain和LangGraph工作流中，大大扩展了AI应用的能力边界。

---

5️⃣ agent_stream.py （智能体流式输出处理）

提供智能体运行过程的流式可视化输出，增强用户交互体验，是构建用户友好应用的重要组件。

• ✅ 掌握点：

  • LangGraph v2事件流处理
  • 流式文本输出的实时渲染
  • 工具调用状态的可视化展示
  • 用户交互体验优化

• 实现特性：

  • 监听并处理LangGraph事件
  • 实时显示AI生成内容
  • 展示工具调用开始和结束状态
  • 优化控制台输出格式

💡 此组件将抽象的智能体决策过程转化为可感知的输出，让用户能够实时了解AI的思考和行动。

---

6️⃣ mcp_main.py （综合应用完成体）

融合mcp_client、mcp_bridge和agent_stream三大核心组件，实现完整的MCP工具调用智能体应用。

• ✅ 掌握点：

  • 多MCP服务的批量管理与初始化
  • LangGraph工作流的构建与优化
  • LLM与工具的智能绑定
  • 条件路由逻辑实现
  • 资源的统一管理（AsyncExitStack）

• 系统架构：

  1. 插件化注入层：动态加载多个MCP服务
  2. 工具适配层：自动将MCP工具转换为LangChain格式
  3. 工作流编排层：构建基于LangGraph的智能体决策流
  4. 用户交互层：提供流式输出和友好界面

• 运行流程：

  启动应用 → 加载MCP服务 → 获取工具列表 → 构建LangGraph → 执行用户查询 → 流式展示结果
  

💡 整个模块的集大成者，展示了如何将各个组件有机结合，构建一个功能完整、架构清晰的智能体应用。

---

🔔 全局注意事项

• 学习路径建议：严格按照文档顺序学习 simple_client.py → simple_main.py → mcp_client.py → mcp_bridge.py → agent_stream.py → mcp_main.py

• 环境准备：

  • 所有示例依赖根目录 .env 中的 API 密钥配置
  • MCP服务需要Node.js环境，确保已安装并配置正确路径
  • 运行前请确保已安装必要依赖：pip install -r requirements.txt
  • 高德地图MCP服务需要 AMAP_MAPS_API_KEY 环境变量配置

---

💡 扩展建议

• 尝试集成其他MCP服务，扩展智能体的能力范围
• 实现自定义的MCP适配器，连接私有工具服务
• 探索将MCP客户端与其他AI框架（如LangChain之外的框架）集成
• 实现更复杂的工作流模式，如并行工具调用、超时控制等