diff --git a/m10_mcp_basics/README.md b/m10_mcp_basics/README.md index c79e32e..ff40380 100644 --- a/m10_mcp_basics/README.md +++ b/m10_mcp_basics/README.md @@ -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之外的框架）集成 -- 实现更复杂的工作流模式，如并行工具调用、超时控制等 \ No newline at end of file +- 尝试添加更多工具函数，扩展服务能力 +- 集成真实的天气API，替代模拟数据 +- 探索FastMCP的其他配置选项和功能 +- 结合m11_mcp_advanced中的客户端实现，构建完整的MCP应用 \ No newline at end of file diff --git a/m10_mcp_basics/stdio_server.py b/m10_mcp_basics/stdio_server.py new file mode 100644 index 0000000..38e1e2e --- /dev/null +++ b/m10_mcp_basics/stdio_server.py @@ -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() \ No newline at end of file diff --git a/m10_mcp_basics/streamable_http_server.py b/m10_mcp_basics/streamable_http_server.py new file mode 100644 index 0000000..5ce1a89 --- /dev/null +++ b/m10_mcp_basics/streamable_http_server.py @@ -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") \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 4fedcc5..c913197 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,16 +1,18 @@ -huggingface_hub==1.1.7 -langchain==1.1.0 +httpx==0.28.1 +huggingface_hub==1.2.1 +langchain==1.1.3 langchain_chroma==1.0.0 langchain_classic==1.0.0 langchain_community==0.4.1 -langchain_core==1.1.0 +langchain_core==1.1.3 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 langgraph==1.0.4 -langsmith==0.4.53 -mcp==1.23.1 -openai==2.8.1 +langsmith==0.4.58 +mcp==1.23.3 +openai==2.9.0 pydantic==2.12.5 python-dotenv==1.2.1 Requests==2.32.5