mcp-for-beginners 实战：在 Python 中运行 MCP Sampling 采样示例——环境搭建、客户端回调与协议迁移指南

教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载本文基于 mcp-for-beginners 开源课程03-GettingStarted/14-sampling章节的 Python 解决方案完整讲解如何从零创建虚拟环境、安装mcp[cli]与openai依赖、运行client.py触发一次端到端的 Sampling 采样流程并结合仓库源码剖析客户端采样回调、服务端采样请求的实现细节最后给出 Sampling 在 MCP2026-07-28规范下已弃用的迁移建议。读完本文你将能独立运行该示例、读懂采样相关的源码并理解 MCP Sampling 的完整工作方式。一、示例背景Sampling 是什么MCP Sampling 是 MCP 协议中的一个高级特性它允许MCP 服务器在自身不具备调用 LLM 能力时向客户端发起采样请求由客户端调用其管理的 LLM例如 GitHub Copilot 背后的模型或任意 OpenAI 兼容端点并把生成结果返回给服务器。这样服务器工具可以把写摘要、写描述这类需要大模型能力的任务外包给客户端完成。在本仓库中03-GettingStarted/14-sampling/目录就是围绕这一特性设计的课程章节课程正文讲解了 Sampling 的概念、sampling/createMessage的 JSON-RPC 请求/响应格式与客户端配置方式solution/python/则给出了一份完整的 Python 解决方案——一个电商产品描述生成器服务端暴露create_product工具通过 Sampling 请求让客户端的 LLM 生成产品描述客户端源码则负责与真实 LLM默认 Azure OpenAI 部署gpt-5.1对接。[!WARNING] Sampling 在 MCP2026-07-28规范中已被标记为弃用Deprecated课程保留该章节仅用于兼容旧版本实现。新的服务器应直接集成 LLM 提供商的 API。详见 2026-07-28 规范变更说明。二、运行前准备创建虚拟环境并安装依赖解决方案的运行说明文档德文版英文原版见 solution/python/README.md给出了 4 个标准步骤。以下逐一展开。-0- 创建虚拟环境推荐但并非必须先安装uv这款快速 Python 包管理器。即便不使用uv也可以直接使用 Python 内置的venv模块创建虚拟环境python -m venv venv该命令会在当前目录生成一个venv/文件夹其中包含一套独立的 Python 解释器与包目录避免污染全局环境。-1- 激活虚拟环境文档给出的命令是 Windows 风格写法venv\Scripts\activate如果你在 Linux/macOS 下运行应改用 POSIX 写法仓库内 code/python/README.md 即采用此形式source ./venv/bin/activate激活成功后命令行提示符通常会出现(venv)前缀后续的pip安装与python运行都会落在该虚拟环境内。小提示如果安装了uv可以直接用uv run client运行示例由uv自动管理虚拟环境与依赖这也是 client.py 文件头部注释推荐的运行方式。-2- 安装依赖pip install mcp[cli] openai这条命令安装两类依赖与源码的 import 一一对应mcp[cli]官方 Python MCP SDKFastMCP 及其客户端 API[cli]额外安装 CLI 调试工具。客户端源码中from mcp import ClientSession, StdioServerParameters, types、服务端源码中from mcp.server.fastmcp import Context, FastMCP均来自该包openaiOpenAI 官方 Python SDK用于在客户端采样回调中调用真实 LLM见 client.py 中的from openai import OpenAI。三、运行示例并解读预期输出-3- 运行客户端python client.pyclient.py是采样流程的驱动端它通过 stdio 拉起server.py子进程、完成 MCP 握手初始化然后依次调用服务端的create_product与get_products两个工具。运行后你会看到类似如下的输出[02/18/26 13:16:34] INFO Processing request of type ListToolsRequest server.py:720 result: {id: 1, name: paprika, description: **Product Description: Paprika - The Vibrant Red Wonder**\n\nElevate your culinary creations with our premium paprika, the jewel of spices that bursts with color, flavor, and nutrition. Harvested from the finest red, juicy peppers, our paprika is meticulously ground to preserve its rich, vibrant hue and aromatic essence, making it an essential ingredient in any kitchen.\n\nEach sprinkle of our paprika adds a delightful warmth and a subtle sweetness to a variety of dishes, from savory stews to vibrant salads and mouthwatering marinades. Its radiant red color not only enhances the visual appeal of your meals but also signifies the freshness and quality of the peppers used. \n\nRich in antioxidants and packed with vitamins, paprika not only tantalizes your taste buds but also contributes to a healthy lifestyle. Whether youre a professional chef or a home cook, this versatile spice will inspire your creativity and add a beautiful, flavorful touch to everything you whip up.\n\nDiscover the magic of our red, juicy paprika—a spice that transforms ordinary dishes into}这段输出包含两类信息值得分别解读INFO Processing request of type ListToolsRequest server.py:720这是 MCP Python SDK 内部安装在虚拟环境 site-packages 中的mcp包而非仓库内的服务端文件在握手阶段处理tools/list请求时打印的协议日志说明客户端与服务端的连接与工具发现已经成功完成。result: {...}这是session.call_tool(create_product, arguments{product_name: paprika, keywords: red, juicy, vegetable})的返回结果见 client.py。返回的 JSON 中包含id、name和description三个字段其中description就是由客户端 LLM 通过 Sampling 生成的英文产品描述——这正是本示例要演示的核心能力。四、源码级拆解一次完整的采样是如何完成的理解了运行方式后我们来看仓库源码如何实现这条链路。整个流程涉及两个文件客户端 client.py 与 服务端 server.py。4.1 客户端通过 stdio 连接服务端客户端首先以子进程方式启动服务端建立 stdio 传输server_params StdioServerParameters( commandpython, # Using python to run the server args[server.py] )见 client.py。随后通过stdio_client打开通道并用显式传入的采样回调创建会话async with ClientSession(read, write, sampling_callbackhandle_sampling_message) as session: await session.initialize()见 client.py。这里的sampling_callback是关键它告诉 MCP SDK当服务端发起采样请求时由这个函数代为调用 LLM 并返回结果。4.2 客户端实现采样回调采样回调是客户端的核心其签名接收 MCP 协议中的CreateMessageRequestParams并返回CreateMessageResultasync def handle_sampling_message( context: RequestContext[ClientSession, None], params: types.CreateMessageRequestParams ) - types.CreateMessageResult: print(fSampling request: {params.messages}) message params.messages[0].content.text response await call_llm(message, Youre a helpful assistant, keep to the topic, dont make things up too much but definitely create a compelling product description) return types.CreateMessageResult( roleassistant, contenttypes.TextContent(typetext, textresponse), modelos.getenv(AZURE_OPENAI_DEPLOYMENT, gpt-5.1), stopReasonendTurn, )见 client.py。回调做了三件事从params.messages中取出服务端构造的提示文本messages[0].content.text调用call_llm将提示发送给真实 LLM把 LLM 的回复包装成CreateMessageResult带上roleassistant、model与stopReasonendTurn返回给服务端。4.3 客户端通过环境变量对接 Azure OpenAIcall_llm使用 OpenAI SDK 连接 Azure OpenAI 兼容端点async def call_llm(prompt: str, system_prompt: str) - str: client OpenAI( base_urlf{os.environ[AZURE_OPENAI_ENDPOINT].rstrip(/)}/openai/v1/, api_keyos.environ[AZURE_OPENAI_API_KEY], ) response client.chat.completions.create( messages[ {role: system, content: system_prompt}, {role: user, content: prompt}, ], modelos.getenv(AZURE_OPENAI_DEPLOYMENT, gpt-5.1), max_completion_tokens200, ) return response.choices[0].message.content见 client.py。因此运行前需要配置以下环境变量环境变量是否必填说明AZURE_OPENAI_ENDPOINT必填Azure OpenAI 服务端点代码会自动拼接/openai/v1/路径AZURE_OPENAI_API_KEY必填Azure OpenAI 访问密钥AZURE_OPENAI_DEPLOYMENT可选使用的模型部署名缺省为gpt-5.14.4 服务端工具内发起采样请求服务端 server.py 定义了Product数据模型id、name、description和create_product工具。工具函数的第一个特殊之处是携带ctx: Context[ServerSession, None]参数——这正是 FastMCP 提供会话访问的入口mcp.tool() async def create_product(product_name: str, keywords: str, ctx: Context[ServerSession, None]) - str: Create a product and generate a product description using LLM sampling. product Product(nameproduct_name, description) prompt fCreate a product description about {product_name} described by as {keywords} result await ctx.session.create_message( messages[ SamplingMessage( roleuser, contentTextContent(typetext, textprompt), ) ], max_tokens100, ) product.description result.content.text products.append(product) return json.dumps({ id: product.id, name: product.name, description: product.description })见 server.py。要点如下ctx.session.create_message(...)会向客户端发送一条sampling/createMessage请求并挂起等待客户端返回采样结果SamplingMessage(roleuser, contentTextContent(typetext, textprompt))构造了消息内容其中prompt就是把product_name与keywords组织成的描述指令max_tokens100是对输出长度的建议值result.content.text拿到客户端 LLM 生成的描述后填入product.description并追加到内存列表products最后以 JSON 字符串返回完整产品。对照前文运行输出即可验证client.py调用create_product(paprika, red, juicy, vegetable)后服务端通过采样拿到了一段以 Product Description: Paprika - The Vibrant Red Wonder 开头的长文本描述这正是采样回调中 LLM 的真实生成结果。五、Sampling 协议细节请求、响应与消息类型上面的源码调用了ctx.session.create_message它在协议层的形态与字段语义课程正文14-sampling/README.md有详细说明这里一并整理。5.1 sampling/createMessage 请求服务端发往客户端的采样请求在 JSON-RPC 层面形如{ jsonrpc: 2.0, id: 1, method: sampling/createMessage, params: { messages: [ { role: user, content: { type: text, text: Create a blog post summary of the following blog post: BLOG POST } } ], modelPreferences: { hints: [ { name: gpt-5.1 } ], intelligencePriority: 0.8, speedPriority: 0.5 }, systemPrompt: You are a helpful assistant., maxTokens: 100 } }各字段含义messages发给 LLM 的对话消息列表content.text是服务端构造的任务指令modelPreferences对模型选择的建议而非强制要求客户端/用户可以采纳或更换模型。其中hints给出倾向的模型名如gpt-5.1intelligencePriority与speedPriority取值 01表达对智力与速度的权衡偏好systemPrompt常规系统提示词用于设定 LLM 的角色个性与行为准则maxTokens建议的生成 token 上限。5.2 采样响应客户端调用 LLM 并等待回复后构造如下响应返回给服务端{ jsonrpc: 2.0, id: 1, result: { role: assistant, content: { type: text, text: Heres your abstract ABSTRACT }, model: gpt-5.1, stopReason: endTurn } }关键点响应中的model可能不同于请求中的hints建议——因为modelPreferences只是推荐客户端可能根据可用部署实际情况选择其他模型。stopReason常见取值包括endTurn正常结束、stopSequence命中停止序列、maxTokens达到 token 上限等详见 mcp-sampling 高级主题。5.3 多模态消息类型采样消息不只限于文本协议还支持图片与音频{ type: text, text: The message content }{ type: image, data: base64-encoded-image-data, mimeType: image/jpeg }{ type: audio, data: base64-encoded-audio-data, mimeType: audio/wav }图片与音频内容以 base64 编码的data字段携带并附上mimeType说明媒体格式。5.4 客户端能力声明客户端若想支持采样需要在能力声明中启用该特性{ capabilities: { sampling: {} } }该声明会在客户端与服务端初始化握手时被读取如果只构建服务器则无需关心此配置。在 Python SDK 中能力声明对应的落地方式就是上文的ClientSession(read, write, sampling_callbackhandle_sampling_message)——传入回调即等价于启用了sampling能力。六、替代运行方式独立启动服务端并用 VS Code 测试除了通过client.py走 stdio 子进程方式运行仓库还保留了两种服务端启动方式便于用 VS Code / GitHub Copilot 在图形界面里体验采样弹窗确认流程Streamable HTTP 方式直接运行python server.py见 code/python/server.py使用mcp.run(transportstreamable-http)然后在 VS Code 的mcp.json中注册servers: { blog-server: { type: http, url: http://localhost:8000/mcp } }SSE 方式server.py文件末尾还挂载了 Starlette 应用app Starlette(routes[Mount(/, appmcp.sse_app())])可用uvicorn server:app --port 8000启动参见 code/python/README.md 的 legacy 说明。在 VS Code 中首次测试时Copilot 会先弹出一个采样授权对话框允许/拒绝 Sampling 动作确认后再弹出常规的工具调用确认框最终在聊天面板中同时展示渲染后的结果与原始 JSON。你还可以在扩展面板中选中已安装服务器点击齿轮图标进入 Configure Model Access限制 Copilot 执行采样时可用的模型并通过 Show Sampling requests 查看近期采样请求记录。七、重要提示Sampling 已在 MCP 2026-07-28 中弃用课程的 14-sampling/README.md 与核心概念章节 mcp-2026-07-28.md 均明确标注Sampling 在 MCP2026-07-28规范中已被标记为弃用。Sampling 保留在2026-07-28规范中仅为兼容旧版本最早可能被移除的时间点是 2027 年 7 月 28 日之后发布的首个规范修订版官方给出的替代方案是新服务器应直接集成 LLM 提供商 API如直接在服务端调用 OpenAI / Azure OpenAI SDK不再通过客户端中转本课程章节及示例刻意使用实现2025-11-25协议的 SDK API仅作为 legacy 兼容与迁移参考运行前请留意 SDK 版本与协议修订的对应关系。也就是说本文的示例适合你理解 MCP Sampling 的历史工作机制、阅读旧代码或做迁移评估如果是全新项目请直接走服务端直连 LLM 提供商的现代路线。八、关键要点总结运行三步走python -m venv venv→ 激活虚拟环境 →pip install mcp[cli] openai然后python client.py即可跑通采样示例运行前需配置AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEYAZURE_OPENAI_DEPLOYMENT可选默认gpt-5.1。两端分工服务端通过ctx.session.create_message()发起sampling/createMessage并等待客户端通过ClientSession(..., sampling_callback...)注册回调在回调中调用真实 LLM 并返回CreateMessageResult。协议要点modelPreferences是建议而非强制客户端可自主选模型消息支持 text/image/audio 三种内容类型客户端需声明capabilities: {sampling: {}}。迁移方向Sampling 已在2026-07-28弃用新实现请直接在服务器侧集成 LLM 提供商 API。相关资源Sampling 课程正文含完整代码与 VS Code 测试步骤Python 解决方案英文原版运行说明Python 解决方案客户端源码Python 解决方案服务端源码练习代码服务端与运行说明Sampling 参数与安全实践高级主题MCP 2026-07-28 规范变更弃用特性与迁移指引赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载相关推荐MCP Sampling 采样机制实战在 mcp-for-beginners 中运行 Python 示例并掌握服务器委托客户端调用 LLM的完整流程MCP Sampling 采样机制实战在 mcp for beginners 中运行 Python 示例并掌握服务器委托客户端调用 LLM的完整流程 本文教程文档人工智能MCP Python SDK 采样Sampling实战服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移MCP Python SDK 采样Sampling实战服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移 导读 本文围绕官方 Python S人工智能MCP 服务MCP Clientsmcp-for-beginners 实战在 Python 中运行带 LLM 的 MCP 客户端03-llm-client 示例详解mcp for beginners 实战在 Python 中运行带 LLM 的 MCP 客户端03 llm client 示例详解 本文围绕 mcp fo教程文档人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考