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通信模式的配置与运行
|
||||||
|
|
||||||
- 特点：
|
- 功能：
|
||||||
- 代码精简，易于理解
|
- 创建名为"WeatherService"的MCP服务器
|
||||||
- 封装程度低，更接近协议本质
|
- 提供`get_weather`工具，模拟查询指定城市天气
|
||||||
- 适合学习和理解MCP的基本概念
|
- 支持异步调用，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工具的调用过程和结果处理方式，适合初学者上手。
|
> 💡 这种模式适合构建可远程访问的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`
|
`1.`（stdio_server） → `2.`（streamable_http_server）
|
||||||
|
- 两个文件均实现了相同的天气查询服务，仅通信方式不同
|
||||||
- **环境准备**：
|
- Stdio模式下，服务器启动后无输出，需通过MCP客户端连接
|
||||||
- 所有示例依赖根目录 `.env` 中的 API 密钥配置
|
- HTTP模式下，服务器启动后会监听指定端口，可通过网络访问
|
||||||
- MCP服务需要Node.js环境，确保已安装并配置正确路径
|
|
||||||
- 运行前请确保已安装必要依赖：`pip install -r requirements.txt`
|
|
||||||
- 高德地图MCP服务需要 `AMAP_MAPS_API_KEY` 环境变量配置
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 💡 **扩展建议**
|
### 💡 **扩展建议**
|
||||||
- 尝试集成其他MCP服务，扩展智能体的能力范围
|
- 尝试添加更多工具函数，扩展服务能力
|
||||||
- 实现自定义的MCP适配器，连接私有工具服务
|
- 集成真实的天气API，替代模拟数据
|
||||||
- 探索将MCP客户端与其他AI框架（如LangChain之外的框架）集成
|
- 探索FastMCP的其他配置选项和功能
|
||||||
- 实现更复杂的工作流模式，如并行工具调用、超时控制等
|
- 结合m11_mcp_advanced中的客户端实现，构建完整的MCP应用
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
from mcp.server.fastmcp import FastMCP
|
||||||
|
|
||||||
|
# 初始化服务
|
||||||
|
# WeatherService 是服务的名字
|
||||||
|
mcp = FastMCP("WeatherService")
|
||||||
|
|
||||||
|
# 业务逻辑工具
|
||||||
|
@mcp.tool()
|
||||||
|
async def get_weather(city:str):
|
||||||
|
"""
|
||||||
|
查询指定城市的实时天气。
|
||||||
|
如果是此时此刻的天气请求，调用此工具。
|
||||||
|
"""
|
||||||
|
# 模拟真实的网络请求(你可以换成自己的天气API)
|
||||||
|
# 在MCP中，工具函数可以是async的，FastMCP会自动处理
|
||||||
|
return f"{city}的天气是:晴，气温25℃，风力3级"
|
||||||
|
|
||||||
|
|
||||||
|
# 启动入口
|
||||||
|
if __name__ == '__main__':
|
||||||
|
# 默认运行方式:Stdio(标准输入输出)
|
||||||
|
# 这种模式下，程序启动后会“挂起”等待指令，不会有任何打印输出。
|
||||||
|
mcp.run()
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
from mcp.server.fastmcp import FastMCP
|
||||||
|
|
||||||
|
|
||||||
|
# 创建服务实例，指定监听地址和端口
|
||||||
|
mcp = FastMCP("WeatherService",host="0.0.0.0",port=8001)
|
||||||
|
|
||||||
|
# 业务逻辑工具
|
||||||
|
@mcp.tool()
|
||||||
|
async def get_weather(city:str):
|
||||||
|
"""
|
||||||
|
查询指定城市的实时天气。
|
||||||
|
如果是此时此刻的天气请求，调用此工具。
|
||||||
|
"""
|
||||||
|
# 模拟真实的网络请求(你可以换成自己的天气API)
|
||||||
|
# 在MCP中，工具函数可以是async的，FastMCP会自动处理
|
||||||
|
return f"{city}的天气是:晴，气温25℃，风力3级"
|
||||||
|
|
||||||
|
|
||||||
|
# 启动入口
|
||||||
|
if __name__ == '__main__':
|
||||||
|
# 运行方式:Streamable HTTP
|
||||||
|
# 这会自动启动 uvicorn 服务器，支持远程调用
|
||||||
|
mcp.run("streamable-http")
|
||||||
+9
-7
@@ -1,16 +1,18 @@
|
|||||||
huggingface_hub==1.1.7
|
httpx==0.28.1
|
||||||
langchain==1.1.0
|
huggingface_hub==1.2.1
|
||||||
|
langchain==1.1.3
|
||||||
langchain_chroma==1.0.0
|
langchain_chroma==1.0.0
|
||||||
langchain_classic==1.0.0
|
langchain_classic==1.0.0
|
||||||
langchain_community==0.4.1
|
langchain_community==0.4.1
|
||||||
langchain_core==1.1.0
|
langchain_core==1.1.3
|
||||||
langchain_huggingface==1.1.0
|
langchain_huggingface==1.1.0
|
||||||
langchain_openai==1.1.0
|
langchain_mcp_adapters==0.2.1
|
||||||
|
langchain_openai==1.1.1
|
||||||
langchain_text_splitters==1.0.0
|
langchain_text_splitters==1.0.0
|
||||||
langgraph==1.0.4
|
langgraph==1.0.4
|
||||||
langsmith==0.4.53
|
langsmith==0.4.58
|
||||||
mcp==1.23.1
|
mcp==1.23.3
|
||||||
openai==2.8.1
|
openai==2.9.0
|
||||||
pydantic==2.12.5
|
pydantic==2.12.5
|
||||||
python-dotenv==1.2.1
|
python-dotenv==1.2.1
|
||||||
Requests==2.32.5
|
Requests==2.32.5
|
||||||
|
|||||||
Reference in New Issue
Block a user