python-sdk 中的采样与根:借客户端模型、读客户端工作区,以及 2026-07-28 弃用后的正确迁移路径
python-sdk 中的采样与根:借客户端模型、读客户端工作区,以及 2026-07-28 弃用后的正确迁移路径
服务端处理器除了向客户端发起请求之外,还可以反过来向已连接的客户端索要两类东西:一是用客户端自身的模型完成一次补全(采样 Sampling),二是读取客户端的工作区文件夹列表(根 Roots)。本文基于 python-sdk 官方文档 docs/handlers/sampling-and-roots.md 及仓库源码,完整讲解 Sample(...) 与 ListRoots() 两种依赖解析标记的用法、客户端侧能力声明与回调应答,并结合 resolve.py 的实现细节说明其底层传输与错误语义。读完你将能在旧协议会话中实现"借模型写文案""让客户端指定目录"等工具,同时理解为何这两个功能已在 2026-07-28 规范中被弃用,以及新代码应当如何迁移。
兼容性前提:采样与根在 SDK 所能协商的每一个协议版本上都仍然可用,但不要在它们之上设计新功能——请先阅读下面的弃用警告。
弃用警告:2026-07-28 规范已将其标记为 deprecated
!!! warning "2026-07-28 规范中已弃用"
采样和根自 2026-07-28 起被弃用(见 SEP-2577)。它们仍然完全可用,并且至少在从规范中移除之前会保留 12 个月,但新的实现不应再以它们为基础。推荐的迁移路径是:采样改用与 LLM 提供商 API 直接集成;根改用工具参数、资源 URI 或服务器配置来传递目录。SDK 全量弃用功能清单见 docs/deprecated.md。
两个功能仍"完全可用"这一点由源码与测试共同背书:仓库中的 test_sampling_and_roots.py 在第 1 行明确写着"该页面每一条声明都对着真实 SDK 验证过",并以 legacy 与 auto 两种模式参数化跑通采样与根的完整链路(详见下文"测试即证据"一节)。也就是说,旧代码继续工作,新设计请避开。
采样(Sampling):借用客户端的模型
当工具的某个解析器(resolver)返回 Sample(...) 时,工具会收到客户端模型的补全结果。它走的是与 依赖注入(Dependencies) 中驱动 Elicit 完全相同的依赖解析机制:通过 Annotated[T, Resolve(fn)] 把解析器声明的依赖注入进工具参数。
以下为官方示例 docs_src/sampling_and_roots/tutorial001.py(对应原文档 server.py 片段):
from typing import Annotated
from mcp.server import MCPServer
from mcp.server.mcpserver import Resolve, Sample
from mcp.types import CreateMessageResult, SamplingMessage, TextContent
mcp = MCPServer("Bookshop")
def draft_blurb(title: str) -> Sample:
prompt = f"Write a one-sentence blurb for the book {title!r}."
return Sample(
[SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
max_tokens=60,
)
@mcp.tool()
async def blurb(title: str, draft: Annotated[CreateMessageResult, Resolve(draft_blurb)]) -> str:
"""Draft a blurb for a book."""
return draft.content.text if draft.content.type == "text" else "No blurb."
Sample(...) 与 sampling/createMessage 参数的对应关系
Sample(messages, max_tokens=...) 直接镜像 sampling/createMessage 的请求参数。从 resolve.py 的 Sample 类定义可以看到其完整的构造签名:
class Sample:
def __init__(
self,
messages: list[SamplingMessage],
*,
max_tokens: int,
system_prompt: str | None = None,
include_context: IncludeContext | None = None,
temperature: float | None = None,
stop_sequences: list[str] | None = None,
metadata: dict[str, Any] | None = None,
model_preferences: ModelPreferences | None = None,
tools: list[Tool] | None = None,
tool_choice: ToolChoice | None = None,
) -> None:
这些参数最终被包装进 CreateMessageRequestParams,再经 _render_request 渲染为线上的 CreateMessageRequest 发送(resolve.py)。关于注入结果,有几个要点:
- 注入类型随参数变化:默认注入的是客户端的
CreateMessageResult;一旦给Sample(...)传了tools或tool_choice,注入类型变为CreateMessageResultWithTools。这一选择由_result_type依据wants_sampling_tools(...)决定(resolve.py)。 - 必须声明能力:客户端必须声明
sampling能力;若传了tools/tool_choice则还必须声明sampling.tools。若未声明,框架不会向客户端发送它无法处理的请求,而是直接以-32021协议错误终止调用。对于没有反向通道(back-channel)的 2026 年之前的会话,由于根本没有可发送的通道,调用会以"无反向通道"的常规错误失败。能力门禁的实现见_require_capability(resolve.py),它抛出码为MISSING_REQUIRED_CLIENT_CAPABILITY的MCPError。 - 协议版本决定投递方式:在
2026-07-28协议上,请求在**多轮往返(multi-round-trip)**流程中投递(见 多轮往返请求);在2025-11-25上则是发给客户端的独立请求。代码写法两种情况下完全一致,但要注意多轮往返的硬性规则:请求必须在每一轮重试中渲染出完全一致的内容,因此只能从工具参数及其他稳定数据来构造请求。实现上,_INPUT_REQUIRED_VERSION = "2026-07-28"决定了走InputRequiredResult批处理路径还是同步反向通道路径(resolve.py),且每个问题只会被问一次,答案经由request_state在各轮之间携带(_fulfil中的状态持久化逻辑)。 - 不要动
include_context:除"none"以外的取值本身已被弃用(SEP-2596),而且几乎不会有客户端声明对应的能力,所以保持默认即可。
客户端侧:sampling_callback 应答
在线路的另一端,客户端用已有的回调来应答这类请求。采样请求由 sampling_callback 应答(async (context, params) -> CreateMessageResult),回调收到完整的 CreateMessageRequestParams(含 messages、model_preferences、max_tokens 等),由你自己的代码决定如何运行模型,SDK 只负责搬运请求。详细说明见 客户端回调。
根(Roots):这些该放在哪里?
根(roots)是客户端明确表示"服务器可以在其上操作"的文件夹集合。注意它的定位:这只是信息性的引导,不是访问控制机制——服务器被"告知"了这些目录,但这并不构成权限边界。解析器返回 ListRoots() 即可取到:
from typing import Annotated
from mcp.server import MCPServer
from mcp.server.mcpserver import ListRoots, Resolve
from mcp.types import ListRootsResult
mcp = MCPServer("Bookshop")
def workspace_roots() -> ListRoots:
return ListRoots()
@mcp.tool()
async def catalog_folder(roots: Annotated[ListRootsResult, Resolve(workspace_roots)]) -> str:
"""Pick the folder the catalog export should go to."""
if not roots.roots:
return "No workspace folders shared."
return str(roots.roots[0].uri)
上例出自 docs_src/sampling_and_roots/tutorial002.py。
关于 ListRoots,有几个要点:
- 注入内容:注入的
ListRootsResult携带一个Root列表,每个Root包含一个file://URI 和可选的显示名。测试中即以Root(uri=FileUrl("file:///workspace/catalog"), name="catalog")的形式构造客户端应答(test_sampling_and_roots.py)。 - 能力门禁与采样相同:客户端必须声明
roots能力,否则调用在发送请求之前就以-32021失败(_require_capability中的RootsCapability分支)。 - 线上形态:
ListRoots()在线上渲染为ListRootsRequest,应答校验为ListRootsResult(resolve.py)。
客户端侧则由 list_roots_callback 应答:该回调不接收任何参数,直接返回一个 ListRootsResult。sampling_callback 与 list_roots_callback 都可以改为返回 ErrorData(...) 来拒绝请求(见 客户端回调)。
能力即回调:注册回调就是声明能力
理解"注册回调 = 声明能力"这一等价关系,是理解整个链路的关键。客户端在连接时声明自己的 capabilities,你不需要手写这个对象——注册某个回调就是在声明对应能力。官方文档 docs/client/callbacks.md 给出的映射如下:
| 你传入的参数 | 客户端声明的能力 |
|---|---|
elicitation_callback= |
"elicitation": {"form": {}, "url": {}} |
sampling_callback= |
"sampling": {} |
list_roots_callback= |
"roots": {"listChanged": true} |
| 都不传 | {} |
唯一的细化项是采样的子能力:如果你的采样器能处理 tools / tool_choice 参数,需要同时传 sampling_capabilities=SamplingCapability(tools=SamplingToolsCapability()) 给 Client(...),服务器只有看到 sampling.tools 被声明后才会发送这类参数。服务器端可以通过 ctx.session.check_client_capability(...) 在发请求前主动探测(详见 客户端回调 中的示例工具)。
在 2026 时代的会话中,回调并没有死:当某个工具的 InputRequiredResult 携带 CreateMessageRequest 或 ListRootsRequest 时,Client 的自动循环会把该条目分发给你在 Client(...) 上注册的同一个 sampling_callback / list_roots_callback 并代为重试调用——这正是 多轮往返请求 所描述的新形态。
2025 世代连接上的旧接口
对于直接驱动会话(session)的代码,ctx.session.create_message(...) 和 ctx.session.list_roots() 仍然存在。它们只在存在反向通道的地方(即 2025 世代、非无状态(stateless)的连接)可用,调用时会触发弃用警告。与之相对,上面介绍的解析器标记(Sample / ListRoots)才是受支持的形态:框架会根据协商出的协议版本自动选择投递方式,且不产生弃用警告。文档原文明确指出(docs/handlers/sampling-and-roots.md),旧接口与新标记在代码中的工作方式不同,新代码应一律使用解析器标记。
测试即证据:两个示例在真实 SDK 上被验证
仓库测试 tests/docs_src/test_sampling_and_roots.py 对本文的每条关键声明都提供了可复现的验证:
test_a_sampling_dependency_receives_the_clients_completion:以legacy与auto两种模式连接tutorial001.mcp,客户端 sampler 收到提示词 "Write a one-sentence blurb for the book 'Dune'." 并返回一条补全,工具最终把补全文本作为tools/call的结果返回——证明采样依赖在两种协议世代都能工作。test_a_roots_dependency_receives_the_clients_folders:客户端list_roots_callback返回一个指向file:///workspace/catalog的根,工具读取roots.roots[0].uri并原样返回。test_an_undeclared_capability_fails_before_a_request_is_sent:不注册任何回调直接调用blurb工具,pytest.raises(MCPError)捕获到码为MISSING_REQUIRED_CLIENT_CAPABILITY的异常——正是文档所说的-32021协议错误在真实 SDK 中的表现。
整个测试文件还带有 filterwarnings("error::mcp.MCPDeprecationWarning"),说明这两条路径在测试时不会触发弃用警告——与文档"解析器标记是受支持形态、不产生警告"的表述一致。
总结
- 从解析器中返回
Sample(...)或ListRoots(),工具就会像接收其他任何依赖一样收到CreateMessageResult或ListRootsResult。 - 客户端必须声明对应的能力(
sampling、sampling.tools、roots),否则请求不会被发出,调用直接以-32021协议错误失败。 - 客户端通过
sampling_callback与list_roots_callback应答;注册回调即声明能力。 - 两个功能在
2026-07-28规范中均已被弃用:当下功能完整,但错误地用于新设计。迁移方向:用 LLM 提供商 API 取代采样,用显式参数(工具参数、资源 URI、服务器配置)取代根。
若要报告一个慢工具的进度,参见 进度(Progress)。