152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# 🧩 模块说明：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之外的框架）集成
|
||
- 实现更复杂的工作流模式，如并行工具调用、超时控制等 |