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':
                    break
                print(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 Key
        self.openai_api_key = os.getenv("OPENAI_API_KEY") 
        # 读取 BASE YRL
        self.base_url = os.getenv("BASE_URL")
        # 读取 model
        self.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 API
            response = 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.content
        except 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':
                    break
                
                response = await self.process_query(query)  # 发送用户输入到 OpenAI API
                print(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 AsyncExitStack

from openai import OpenAI  
from dotenv import load_dotenv

from 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 Key
        self.base_url = os.getenv("BASE_URL")  # 读取 BASE YRL
        self.model = os.getenv("MODEL")  # 读取 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) # 创建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.tools
        print("\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 response
        response = 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.name
            tool_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 response
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
            )
            return response.choices[0].message.content
            
        return content.message.content
    
    #多轮对话
    async def chat_loop(self):
        """运行交互式聊天循环"""
        print("\n🤖 MCP 客户端已启动！输入 'quit' 退出")

        while True:
            try:
                query = input("\n你: ").strip()
                if query.lower() == 'quit':
                    break
                
                response = await self.process_query(query)  # 发送用户输入到 OpenAI API
                print(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 sys
    asyncio.run(main())

3.2 测试运行

uv run client.py server.py