day26-MCP基础

MCP快速入门实战

一、MCP技术体系介绍

MCP，全称是Model Context Protocol，模型上下文协议，由Claude母公司Anthropic于2024年11月正式提出。

MCP解决的最大痛点，就是Agent开发中调用外部工具的技术门槛过高的问题。

我们都知道，能调用外部工具，是大模型进化为智能体Agent的关键，如果不能使用外部工具，大模型就只能是个简单的聊天机器人，甚至连查询天气都做不到。因此Function calling的思路，就是创建一个外部函数（function）作为中介，一边传递大模型的请求，另一边调用外部工具，最终让大模型能够间接的调用外部工具。

Function calling是个非常不错的技术设计，自诞生以来，一直被业内奉为圭臬。但唯一的问题就是，编写这个外部函数的工作量太大了，一个简单的外部函数往往就得上百行代码。

而MCP的目标，就是能在Agent开发过程中，让大模型更加便捷的调用外部工具。MCP把大模型运行环境称作 MCP Client，也就是MCP客户端，同时，把外部函数运行环境称作MCP Server，也就是MCP服务器。

二、MCP客户端Client开发流程

1. uv工具入门使用指南

1.1 uv入门介绍

MCP开发要求借助uv进行虚拟环境创建和依赖管理。uv 是一个Python 依赖管理工具，类似于 pip 和 conda，但它更快、更高效，并且可以更好地管理 Python 虚拟环境和依赖项。它的核心目标是替代 pip，提供更好的性能和更低的管理开销。

uv 的特点：

1. 速度更快：相比 pip，uv 性能更优。
2. 兼容 pip：支持 requirements.txt 依赖管理。
3. 替代 venv：提供 uv venv 进行虚拟环境管理，比 venv 更轻量。
4. 跨平台：支持 Windows、macOS 和 Linux。

1.2 uv安装流程

使用 pip 安装（适用于已安装 pip 的系统）

最好先升级下pip：python -m pip install --upgrade pip

pip install uv==0.7.14如果该版本不存在就不指定版本：pip install uv

1.3 uv的基本用法介绍

安装 uv 后，你可以像 pip 一样使用它，但它的语法更简洁，速度也更快。注意，以下为使用语法示例，不用实际运行。

• 创建虚拟环境

  uv venv 虚拟环境名字

• 激活虚拟环境

  source myenv/bin/activate       # Linux/macOS
  虚拟环境名字\Scripts\activate     # Windows
  

• 安装 Python 依赖

  uv pip install xxx

• 运行python项目

  uv run python xxx.py

为什么MCP更推荐使用uv进行环境管理？

MCP 依赖的 Python 环境可能包含多个模块，uv可以提供更高效的管理方式，并且可以避免 pip 的一些依赖冲突问题。此外，uv 的包管理速度远超 pip，这对于 MCP 这样频繁管理依赖的项目来说是一个很大的优势。

2.MCP极简客户端搭建流程

接下来我们尝试先构建一个 MCP 客户端，确保基本逻辑可用，然后再逐步搭建 MCP 服务器进行联调，这样可以分阶段排查问题，避免一上来就涉及太多复杂性。

2.1 创建 MCP 客户端项目

# 创建项目目录
uv init mcp-client
cd mcp-client

文件/文件夹	作用
.git/	Git 版本控制目录
.venv/	虚拟环境
.gitignore	Git 忽略规则
.python-version	Python版本声明
main.py	主程序入口
pyproject.toml	项目配置文件
README.md	项目说明文档

2.2 创建MCP客户端虚拟环境

# 创建虚拟环境
uv venv# 激活虚拟环境
source .venv/bin/activate #mac/linux
.venv\Scripts\activate #windows

这里需要注意的是，相比pip，uv会自动识别当前项目主目录并创建虚拟环境。然后即可通过add方法在虚拟环境中安装相关的库。首先安装MCP SDK：

MCP SDK 是一个开发工具包，帮助开发者快速构建符合 MCP 标准的客户端或服务器，实现 AI 模型与外部工具的安全高效连接，支持动态适配工具参数变化并减少重复开发。

# 安装 MCP SDK
uv add mcp

uv使用国内源

set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple && uv add xxx

编写项目源码

接下来在主目录下创建/src/pro_name作为代码主目录，在其内部创建server和client脚本文件。

2.3 编写基础 MCP 客户端

然后在当前项目主目录中**创建 client.py **

type nul > client.py #windows
touch client.py #mac/linux

然后写入如下通用client的代码：

#Python 内置的异步编程库，让 MCP 可以非阻塞地执行任务（比如聊天、查询）。
import asyncio
#用于管理 MCP 客户端会话（但目前我们先不连接 MCP 服务器）。
from mcp import ClientSession 
#自动管理资源，确保程序退出时正确关闭 MCP 连接。
from contextlib import AsyncExitStack#定义 MCPClient 类
class MCPClient:def __init__(self):"""初始化 MCP 客户端"""self.session = None #存储与 MCP 服务器的会话对象.暂时不连接 MCP 服务器，后续可以修改来真正连接。#创建资源管理器,管理 MCP 客户端的资源，确保程序退出时可以正确释放资源。self.exit_stack = AsyncExitStack()#模拟连接 MCP 服务器,这是一个异步方法，目前只是打印一条消息，表示客户端已初始化但未真正连接到服务器。在实际应用中，这里会调用 ClientSession 来建立与真实 MCP 服务器的连接。async def connect_to_mock_server(self):"""模拟 MCP 服务器的连接（暂不连接真实服务器）"""print("✅ MCP 客户端已初始化，但未连接到服务器")#多轮对话：这是客户端的核心功能，允许用户通过命令行与 AI 模型交互。async def chat_loop(self):"""运行交互式聊天循环"""print("\nMCP 客户端已启动！输入 'quit' 退出")while True:try:query = input("\nQuery: ").strip()if query.lower() == 'quit':breakprint(f"\n🤖 [Mock Response] 你说的是：{query}")except Exception as e:print(f"\n⚠️ 发生错误: {str(e)}")#清理资源：关闭所有通过 AsyncExitStack 管理的异步资源（比如会话、文件句柄等），确保程序退出时不会留下未释放的资源和正确关闭 MCP 连接（尽管目前没有真正的连接）。async def cleanup(self):"""清理资源"""await self.exit_stack.aclose()#主函数：创建 MCPClient 实例。
async def main():#创建一个 MCP 客户端实例。client = MCPClient()try:#初始化 MCP 客户端（暂不连接服务器）。await client.connect_to_mock_server()#启动交互式聊天。await client.chat_loop()finally:#确保 不管程序是否异常退出，都会正确释放资源。await client.cleanup()if __name__ == "__main__":#运行整体程序asyncio.run(main())

MCP中一个基础的客户端代码结构总结如下：

代码部分	作用
MCPClient.__init__()	初始化 MCP 客户端
connect_to_mock_server()	模拟 MCP 服务器连接
chat_loop()	提供交互式聊天界面
cleanup()	释放资源
main()	启动客户端
asyncio.run(main())	运行程序

2.5 运行 MCP 客户端

然后尝试运行这个极简的MCP客户端：

uv run client.py

3. MCP客户端接入DeepSeek在线模型

接下来尝试在客户端中接入OpenAI和DeepSeek等在线模型进行对话。需要注意的是，由于OpenAI和DeepSeek调用方法几乎完全一样，因此这套服务器client代码可以同时适用于GPT模型和DeepSeek模型。

3.1 新增依赖

为了支持调用在线模型，以及在环境变量中读取API-KEY等信息，需要先安装如下依赖：

uv add mcp openai python-dotenv

uv使用国内源

set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple && uv add xxx

3.2 创建.env文件

创建.env文件，并写入大模型的API-Key，以及base url地址和模型名称等。

type nul > .env #windows touch .env #mac/linux

BASE_URL=https://api.deepseek.com
MODEL=deepseek-chat      
OPENAI_API_KEY="DeepSeek API-Key"

3.3 修改client.py代码

接下来修改客户端代码：

import asyncio
import os
from openai import OpenAI
from dotenv import load_dotenv
from contextlib import AsyncExitStack# 自动加载 .env 文件，避免在代码中直接暴露 API Key。
load_dotenv()class MCPClient:def __init__(self):"""初始化 MCP 客户端"""self.exit_stack = AsyncExitStack()# 读取 OpenAI API Keyself.openai_api_key = os.getenv("OPENAI_API_KEY") # 读取 BASE YRLself.base_url = os.getenv("BASE_URL")# 读取 modelself.model = os.getenv("MODEL")  if not self.openai_api_key:raise ValueError("❌ 未找到 OpenAI API Key，请在 .env 文件中设置 OPENAI_API_KEY")self.client = OpenAI(api_key=self.openai_api_key, base_url=self.base_url) #发送用户输入到大模型async def process_query(self, query: str) -> str:"""调用 OpenAI API 处理用户查询"""messages = [{"role": "system", "content": "你是一个智能助手，帮助用户回答问题。"},{"role": "user", "content": query}]try:# 调用 OpenAI APIresponse = await asyncio.get_event_loop().run_in_executor(None,lambda: self.client.chat.completions.create(model=self.model,messages=messages))return response.choices[0].message.contentexcept Exception as e:return f"⚠️ 调用 OpenAI API 时出错: {str(e)}"async def chat_loop(self):"""运行交互式聊天循环"""print("\n🤖 MCP 客户端已启动！输入 'quit' 退出")while True:try:query = input("\n你: ").strip()if query.lower() == 'quit':breakresponse = await self.process_query(query)  # 发送用户输入到 OpenAI APIprint(f"\n🤖 OpenAI: {response}")except Exception as e:print(f"\n⚠️ 发生错误: {str(e)}")async def cleanup(self):"""清理资源"""await self.exit_stack.aclose()async def main():client = MCPClient()try:await client.chat_loop()finally:await client.cleanup()if __name__ == "__main__":asyncio.run(main())

3.4 运行client.py

然后即可输入如下命令开始运行对话客户端：

uv run client.py

三、MCP天气查询服务器server与使用

1. MCP服务器通讯机制

Model Context Protocol（MCP）是一种 开源的协议，根据 MCP 的规范，当前支持3种传输方式。我们首先学习使用---标准输入输出（stdio）。

在 Model Context Protocol（MCP）中，标准输入输出（stdio）模式是一种用于本地通信的传输方式。在这种模式下，MCP 客户端会将服务器程序作为子进程启动，双方通过标准输入（stdin）和标准输出（stdout）进行数据交换。这种方式适用于客户端和服务器在同一台机器上运行的场景，确保了高效、低延迟的通信。

具体而言，客户端通过标准输入发送请求，服务器通过标准输出返回响应。这种直接的数据传输方式减少了网络延迟和传输开销，适合需要快速响应的本地应用。

相比之下，MCP 还支持基于 HTTP 和服务器推送事件（SSE）的传输方式，适用于客户端和服务器位于不同物理位置的场景。在这种模式下，客户端和服务器通过 HTTP 协议进行通信，利用 SSE 实现服务器向客户端的实时数据推送。

总的来说，stdio 模式提供了一种简单、高效的本地通信方式，适用于客户端和服务器在同一环境下运行的情况。而对于分布式或远程部署的场景，基于 HTTP 和 SSE 的传输方式则更为合适。

接下来我们尝试一个入门级的示例，那就是创建一个天气查询的服务器。通过使用OpenWeather API，创建一个能够实时查询天气的服务器（server），并使用stdio方式进行通信。

2. 天气查询服务器Server创建流程

2.1 服务器依赖安装

由于我们需要使用http请求来查询天气，因此需要在当前虚拟环境中添加如下依赖

uv add mcp httpx

2.2 服务器代码编写

接下来尝试创建服务器代码，此时MCP基本执行流程如下：

对应server服务器代码如下：

import json
import httpx
from typing import Any
from mcp.server.fastmcp import FastMCP# 初始化 MCP 服务器,服务器名称可以自定义
mcp = FastMCP("WeatherServer")# OpenWeather API 配置
OPENWEATHER_API_BASE = "https://api.openweathermap.org/data/2.5/weather"
API_KEY = "1657ffb8acb84f583d07a3377462bf8b"  # 请替换为你自己的 OpenWeather API Key
#请求载体身份标识，可以自定义
USER_AGENT = "weather-app/1.0"#异步获取天气数据
async def fetch_weather(city: str) -> dict[str, Any] | None:"""从 OpenWeather API 获取天气信息。:param city: 城市名称（需使用英文，如 Beijing）:return: 天气数据字典；若出错返回包含 error 信息的字典"""#定义请求参数params = {"q": city,"appid": API_KEY,"units": "metric","lang": "zh_cn"}#定义请求头headers = {"User-Agent": USER_AGENT}#发送异步 GET 请求到 OpenWeather API。async with httpx.AsyncClient() as client:try:response = await client.get(OPENWEATHER_API_BASE, params=params, headers=headers, timeout=30.0)#用于自动化处理 HTTP 请求的错误状态码。当服务器返回的HTTP状态码不属于2xx（成功范围）时，该方法会抛出一个HTTPError异常。response.raise_for_status()return response.json()  # 返回字典类型except httpx.HTTPStatusError as e:return {"error": f"HTTP 错误: {e.response.status_code}"}except Exception as e:return {"error": f"请求失败: {str(e)}"}#格式化天气数据
def format_weather(data: dict[str, Any] | str) -> str:"""将天气数据格式化为易读文本。:param data: 天气数据（可以是字典或 JSON 字符串）:return: 格式化后的天气信息字符串"""# 如果传入的是字符串，则先转换为字典if isinstance(data, str):try:data = json.loads(data)except Exception as e:return f"无法解析天气数据: {e}"# 如果数据中包含错误信息，直接返回错误提示if "error" in data:return f"⚠️ {data['error']}"# 提取数据时做容错处理city = data.get("name", "未知")country = data.get("sys", {}).get("country", "未知")temp = data.get("main", {}).get("temp", "N/A")humidity = data.get("main", {}).get("humidity", "N/A")wind_speed = data.get("wind", {}).get("speed", "N/A")# weather 可能为空列表，因此用 [0] 前先提供默认字典weather_list = data.get("weather", [{}])description = weather_list[0].get("description", "未知")return (f"🌍 {city}, {country}\n"f"🌡 温度: {temp}°C\n"f"💧 湿度: {humidity}%\n"f"🌬 风速: {wind_speed} m/s\n"f"🌤 天气: {description}\n")#定义MCP工具函数
@mcp.tool()
async def query_weather(city: str) -> str:"""输入指定城市的英文名称，返回今日天气查询结果。:param city: 城市名称（需使用英文）:return: 格式化后的天气信息"""data = await fetch_weather(city)return format_weather(data)if __name__ == "__main__":# 以标准 I/O 方式运行 MCP 服务器mcp.run(transport='stdio')

上述代码有两个注意事项，

1. query_weather函数的函数说明至关重要，相当于是此后客户端对函数进行识别的基本依据，因此需要谨慎编写；
2. 当指定 transport='stdio' 运行 MCP 服务器时，客户端必须在启动时同时启动当前这个脚本，否则无法顺利通信。这是因为 stdio 模式是一种本地进程间通信方式，它需要服务器作为子进程运行，并通过标准输入输出（stdin/stdout）进行数据交换。

当我们编写完服务器后，并不能直接调用这个服务器，而是需要创建一个对应的能够进行stdio的客户端，才能顺利进行通信。

3. 天气查询客户端client创建流程

3.1 代码编写

创建.env文件，并写入大模型的API-Key，以及base url地址和模型名称等。

type nul > .env #windows touch .env #mac/linux

BASE_URL=https://api.deepseek.com
MODEL=deepseek-chat      
OPENAI_API_KEY="DeepSeek API-Key"

import asyncio
import os
import json
from typing import Optional
from contextlib import AsyncExitStackfrom openai import OpenAI  
from dotenv import load_dotenvfrom mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client# 加载 .env 文件，确保 API Key 受到保护
load_dotenv()class MCPClient:def __init__(self):"""初始化 MCP 客户端"""self.exit_stack = AsyncExitStack()self.openai_api_key = os.getenv("OPENAI_API_KEY")  # 读取 OpenAI API Keyself.base_url = os.getenv("BASE_URL")  # 读取 BASE YRLself.model = os.getenv("MODEL")  # 读取 modelif not self.openai_api_key:raise ValueError("❌ 未找到 OpenAI API Key，请在 .env 文件中设置 OPENAI_API_KEY")self.client = OpenAI(api_key=self.openai_api_key, base_url=self.base_url) # 创建OpenAI client#用于保存 MCP 的客户端会话，默认是 None，稍后通过 connect_to_server 进行连接。self.session: Optional[ClientSession] = None#连接指定server端，参数为server端文件路径async def connect_to_server(self, server_script_path: str):#判断服务器脚本是 Python 还是 Node.js，选择对应的运行命令。is_python = server_script_path.endswith('.py')is_js = server_script_path.endswith('.js')if not (is_python or is_js):raise ValueError("服务器脚本必须是 .py 或 .js 文件")command = "python" if is_python else "node"#告诉 MCP 客户端如何启动服务器。server_params = StdioServerParameters(command=command,args=[server_script_path],env=None)# 启动服务器进程，并建立 标准 I/O 通信管道stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))#拿到读写流。self.stdio, self.write = stdio_transport#创建 MCP 客户端会话，与服务器交互。self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))#发送初始化消息给服务器，等待服务器就绪。await self.session.initialize()# 向 MCP 服务器请求所有已注册的工具（用 @mcp.tool() 标记）。response = await self.session.list_tools()tools = response.toolsprint("\n已连接到服务器，支持以下工具:", [tool.name for tool in tools])     #使用大模型处理查询并调用可用的 MCP 工具 (Function Calling)async def process_query(self, query: str) -> str:#收到用户输入后，先把它组装进一个 messages 列表，目前只包含用户信息（{"role": "user", "content": query}）。messages = [{"role": "user", "content": query}]# 向 MCP 服务器请求所有已注册的工具（用 @mcp.tool() 标记）。response = await self.session.list_tools()#获取服务器上的工具，再转换成 available_tools 的格式。方便后面发给模型，告诉它：可以调用这些工具。available_tools = [{"type": "function","function": {"name": tool.name,"description": tool.description,"input_schema": tool.inputSchema}} for tool in response.tools]# print(available_tools)#模型调用first responseresponse = self.client.chat.completions.create(model=self.model,            messages=messages,tools=available_tools     )# 处理返回的内容content = response.choices[0]if content.finish_reason == "tool_calls":print("即将调用外部工具进行天气查询......................")# 如何是需要使用工具，就解析工具tool_call = content.message.tool_calls[0]tool_name = tool_call.function.nametool_args = json.loads(tool_call.function.arguments)# 执行工具（手动调用外部工具函数）result = await self.session.call_tool(tool_name, tool_args)print(f"\n\n[Calling tool {tool_name} with args {tool_args}]\n\n")# 将模型返回的调用哪个工具数据和工具执行完成后的数据都存入messages中messages.append(content.message.model_dump())messages.append({"role": "tool","content": result.content[0].text,"tool_call_id": tool_call.id,})# 将上面的结果再返回给大模型用于生产最终的结果#second responseresponse = self.client.chat.completions.create(model=self.model,messages=messages,)return response.choices[0].message.contentreturn content.message.content#多轮对话async def chat_loop(self):"""运行交互式聊天循环"""print("\n🤖 MCP 客户端已启动！输入 'quit' 退出")while True:try:query = input("\n你: ").strip()if query.lower() == 'quit':breakresponse = await self.process_query(query)  # 发送用户输入到 OpenAI APIprint(f"\n🤖 OpenAI: {response}")except Exception as e:print(f"\n⚠️ 发生错误: {str(e)}")#清理资源async def cleanup(self):"""清理资源"""await self.exit_stack.aclose()async def main():client = MCPClient()try:await client.connect_to_server(sys.argv[1])await client.chat_loop()finally:await client.cleanup()if __name__ == "__main__":import sysasyncio.run(main())

3.2 测试运行

uv run client.py server.py