feat(module10): update code files and environment dependencies
This commit is contained in:
Annyfee
+35
-126
@@ -1,152 +1,61 @@
|
||||
# 🧩 模块说明：MCP 基础篇 - 多模态协作协议客户端实现
|
||||
# 🧩 模块说明：MCP 基础篇 - 构建多模态协作协议服务器
|
||||
|
||||
> 📌 核心知识点：MCP协议原理｜客户端封装｜工具调用｜LangChain集成｜流式输出
|
||||
> 📌 核心知识点：MCP协议原理｜FastMCP框架使用｜Stdio通信｜Streamable HTTP服务｜工具定义与注册
|
||||
|
||||
---
|
||||
|
||||
### 1️⃣ `simple_client.py` （最小化MCP客户端MVP）
|
||||
### 1. `stdio_server.py` （标准输入输出MCP服务器）
|
||||
|
||||
实现最基础的MCP单次调用客户端，提供最小可行性实现，是学习MCP的起点。
|
||||
实现基于标准输入输出的MCP服务器，支持本地进程间通信。
|
||||
|
||||
- ✅ 掌握点：
|
||||
- MCP协议的基本调用流程
|
||||
- 异步上下文管理器的应用
|
||||
- 单次工具调用的完整生命周期
|
||||
- 资源的自动创建与清理
|
||||
- 使用FastMCP创建MCP服务实例
|
||||
- 定义和注册工具函数
|
||||
- 异步工具函数的实现方式
|
||||
- Stdio通信模式的配置与运行
|
||||
|
||||
- 特点：
|
||||
- 代码精简，易于理解
|
||||
- 封装程度低，更接近协议本质
|
||||
- 适合学习和理解MCP的基本概念
|
||||
- 单次调用模式，无需维护长连接
|
||||
- 功能：
|
||||
- 创建名为"WeatherService"的MCP服务器
|
||||
- 提供`get_weather`工具，模拟查询指定城市天气
|
||||
- 支持异步调用，FastMCP自动处理协程
|
||||
- 采用标准输入输出作为通信通道
|
||||
|
||||
> 💡 这是理解MCP协议最简单的入口，通过`run_once`方法将启动进程、握手、调用、关闭等操作封装为一次性流程。
|
||||
> 💡 这种模式适合本地进程间通信，程序启动后会等待客户端指令，无默认输出。
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ `simple_main.py` （基础使用示例）
|
||||
### 2. `streamable_http_server.py` （HTTP协议MCP服务器）
|
||||
|
||||
展示如何使用`simple_client`进行单次工具调用，是MCP应用的最简示范。
|
||||
实现基于HTTP协议的MCP服务器，支持远程网络调用。
|
||||
|
||||
- ✅ 掌握点：
|
||||
- SimpleClient的基本实例化方法
|
||||
- 环境变量配置与传递
|
||||
- 工具参数构造与调用
|
||||
- 异步代码的基本编写方式
|
||||
- FastMCP服务器的网络配置
|
||||
- HTTP通信模式的实现
|
||||
- 监听地址和端口的设置
|
||||
- Streamable HTTP运行模式的使用
|
||||
|
||||
- 功能演示：
|
||||
- 初始化MCP客户端
|
||||
- 调用高德地图搜索功能
|
||||
- 处理并显示结果
|
||||
- 完整的单次调用生命周期
|
||||
- 功能：
|
||||
- 创建名为"WeatherService"的网络MCP服务器
|
||||
- 配置监听地址(0.0.0.0)和端口(8001)
|
||||
- 提供与stdio_server相同的`get_weather`工具
|
||||
- 自动启动uvicorn服务器，支持远程调用
|
||||
|
||||
> 💡 从这个简单示例开始，可以直观看到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 → 执行用户查询 → 流式展示结果
|
||||
```
|
||||
|
||||
> 💡 整个模块的集大成者，展示了如何将各个组件有机结合，构建一个功能完整、架构清晰的智能体应用。
|
||||
> 💡 这种模式适合构建可远程访问的MCP服务，便于分布式系统集成。
|
||||
|
||||
---
|
||||
|
||||
### 🔔 全局注意事项
|
||||
|
||||
- **学习路径建议**：严格按照文档顺序学习
|
||||
`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` 环境变量配置
|
||||
- **学习路径建议**：
|
||||
`1.`（stdio_server） → `2.`（streamable_http_server）
|
||||
- 两个文件均实现了相同的天气查询服务，仅通信方式不同
|
||||
- Stdio模式下，服务器启动后无输出，需通过MCP客户端连接
|
||||
- HTTP模式下，服务器启动后会监听指定端口，可通过网络访问
|
||||
|
||||
---
|
||||
|
||||
### 💡 **扩展建议**
|
||||
- 尝试集成其他MCP服务，扩展智能体的能力范围
|
||||
- 实现自定义的MCP适配器，连接私有工具服务
|
||||
- 探索将MCP客户端与其他AI框架（如LangChain之外的框架）集成
|
||||
- 实现更复杂的工作流模式，如并行工具调用、超时控制等
|
||||
- 尝试添加更多工具函数，扩展服务能力
|
||||
- 集成真实的天气API，替代模拟数据
|
||||
- 探索FastMCP的其他配置选项和功能
|
||||
- 结合m11_mcp_advanced中的客户端实现，构建完整的MCP应用
|
||||
Reference in New Issue
Block a user