Python MCP SDK 的采样(Sampling)与 Roots 依赖注入:借用客户端模型与工作区目录的完整实践指南
Python MCP SDK 的采样(Sampling)与 Roots 依赖注入:借用客户端模型与工作区目录的完整实践指南
导读
docs/handlers/sampling-and-roots.md(西班牙语译文位于 i18n/es/pages/handlers/sampling-and-roots.md)讲解的是 Python MCP SDK 中两个特殊的解析器请求标记:Sample(...)(采样)——让服务端工具借用连接客户端的 LLM 完成一次补全;以及 ListRoots()(根目录)——向客户端索取其工作区文件夹列表。二者都是服务端在 tools/call 处理过程中向客户端发起的请求,通过与 Elicit 相同的依赖注入机制注入到工具参数中。读完本文你将掌握:如何在 MCPServer 工具中声明这两个依赖、能力协商(capability)门控如何工作、-32021 协议错误何时触发、客户端侧 sampling_callback / list_roots_callback 如何应答,以及它们在 2026-07-28 协议版本下的弃用现状与推荐的迁移路径。
背景:两种"借"自客户端的能力
一个 handler(处理器)可以向已连接的客户端再索取两样东西:
- 采样(Sampling):用客户端自己的模型完成一次补全——服务端不持有任何 LLM 密钥,模型调用发生在客户端一侧;
- Roots(根目录):客户端声明的工作区文件夹列表——服务端据此知道"可以在哪些目录上操作"。
SDK 目前在所有协商到的协议版本上(2025-11-25 与 2026-07-28)都完整支持二者,但 2026-07-28 规范已将其标记为弃用,新实现不应再基于它们构建。在动手设计之前,必须先理解下面的警告。
弃用警告:2026-07-28 规范(SEP-2577)
!!! warning "被 2026-07-28 规范弃用"
采样和 roots 自 2026-07-28 起被弃用(SEP-2577。
要点拆解:
- 弃用 ≠ 移除:
docs/deprecated.md明确写道"Nothing breaks today"——今天没有任何东西会坏掉。针对协商为2025-11-25或更早的会话,所有方法照常工作,线上(wire)格式与能力协商均无变化; - 可见警告:每次调用弃用 API 时都会产生一条
MCPDeprecationWarning。它继承自UserWarning而非DeprecationWarning,因此默认即显示,无需任何-W标志; - 采样与 roots 共有的更深层问题:它们是"服务端向客户端发请求"的通道。整个这一方向正是 2026-07-28 用 多轮往返请求(Multi-round-trip requests) 取代的对象——真正消失的是独立的 RPC 方法(
sampling/createMessage、roots/list),而CreateMessageRequest/ListRootsRequest载荷类型本身得以存活,被内嵌在InputRequiredResult.input_requests中,在客户端侧命中同样的回调。
采样:借用客户端的模型
一个解析器(resolver)返回 Sample(...),工具即可通过与运行 Elicit 完全相同的依赖注入机制(见 Dependencies)拿到模型的补全结果。完整示例来自 docs_src/sampling_and_roots/tutorial001.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(...) 的参数与注入值
Sample(messages, max_tokens=...)镜像了sampling/createMessage的参数。从源码 src/mcp/server/mcpserver/resolve.py 可以看到其完整签名:除messages与必填的max_tokens外,还支持system_prompt、include_context、temperature、stop_sequences、metadata、model_preferences,以及tools/tool_choice;- 注入值类型:默认注入的是客户端的
CreateMessageResult;一旦传入tools或tool_choice,注入值就变为CreateMessageResultWithTools(由_result_type在 resolve.py 中根据wants_sampling_tools(...)判定); Sample没有 decline/cancel 分支,消费方直接注解结果类型即可,与Elicit的 accept/decline/cancel 三分支不同。
能力门控:客户端必须声明 sampling
客户端必须已经声明 sampling 能力(若你传了 tools 或 tool_choice,则必须是 sampling.tools)。如果客户端未声明:
- 调用会以
-32021协议错误失败(MISSING_REQUIRED_CLIENT_CAPABILITY,定义于 src/mcp-types/mcp_types/jsonrpc.py),而不是发出一个客户端无法处理的请求; - 能力校验由
_require_capability完成(resolve.py),它读取context.client_capabilities并抛出携带requiredCapabilities载荷的MCPError; - 一个 2026 年之前、没有回送通道(back-channel)的会话,则会以它惯常的"无回送通道"错误失败——因为根本没有任何通道可供发送。
该行为有测试直接背书:tests/docs_src/test_sampling_and_roots.py 中 test_an_undeclared_capability_fails_before_a_request_is_sent 在未传 sampling_callback 时断言 MCPError 的 code == MISSING_REQUIRED_CLIENT_CAPABILITY。
协议版本决定投递方式
- 在
2026-07-28:请求被放入多轮往返流程(InputRequiredResult)中投递,客户端通过sampling_callback应答后由Client自动重试同一tools/call; - 在
2025-11-25:它是发给客户端的独立请求(standalone server-to-client request); - 代码在两种情况下完全相同,但必须牢记多轮往返的规则:请求必须在每一轮重试中渲染得完全一致,因此只能从工具参数和其他稳定数据来构建它。
request_state中记录的结果通过"精确渲染摘要"(_request_digest的 SHA-256 摘要,见 resolve.py)与问题绑定,措辞一变旧答案即失效、服务端会重新提问。
别碰 include_context
保持 include_context 原样(即 None 或 "none"):除 "none" 之外的值本身也已被弃用(SEP-2596),并且需要一种几乎没有客户端会声明的能力。
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)
ListRootsResult 与 Root 的结构
注入的 ListRootsResult 携带一个 Root 对象列表。Root 的字段定义于 src/mcp-types/mcp_types/_types.py:
uri: FileUrl——标识根目录的 URI,目前必须以file://开头(协议注释明确说明这一限制未来可能放宽以允许其他 URI scheme);name: str | None——可选的人类可读显示名,用于展示或在应用其他部分引用;meta——可选的_meta字段。
客户端回调示例见 docs_src/client_callbacks/tutorial004.py:
async def handle_list_roots(context: ClientRequestContext) -> ListRootsResult:
return ListRootsResult(roots=[Root(uri=FileUrl("file:///home/ada/notebooks"), name="notebooks")])
同样的门控条件
与采样完全一致:若客户端未声明 roots 能力,调用以 -32021 失败,而不是发出请求。测试 tests/docs_src/test_sampling_and_roots.py 同时以 mode="legacy" 和 mode="auto" 两种模式验证了 workspace_roots 能取回客户端文件夹。
线路的另一端:客户端回调
在线路的另一侧,客户端用已有的一对回调应答这两个请求:sampling_callback 和 list_roots_callback,详见 Client callbacks。二者的签名:
async def handle_sampling(
context: ClientRequestContext,
params: CreateMessageRequestParams,
) -> CreateMessageResult:
return CreateMessageResult(
role="assistant",
content=TextContent(type="text", text="The answer is 42."),
model="my-llm",
)
async def handle_list_roots(context: ClientRequestContext) -> ListRootsResult:
return ListRootsResult(roots=[Root(uri=FileUrl("file:///home/ada/notebooks"), name="notebooks")])
- 采样回调接收完整的
CreateMessageRequestParams(messages、model_preferences、max_tokens)并返回CreateMessageResult。模型由你自己运行,SDK 只负责搬运请求; - roots 回调不接收任何参数,直接返回
ListRootsResult; - 两者都可以改为返回
ErrorData(...)来拒绝请求。
注册回调即声明能力
在 Client(...) 中传入回调就等同于声明能力——你不需要手写 capabilities 对象:
| 你传入 | 客户端声明 |
|---|---|
sampling_callback= |
"sampling": {} |
list_roots_callback= |
"roots": {"listChanged": true} |
| 都不传 | {} |
唯一的细分规则:当你的采样器要处理 tools / tool_choice 参数时,需在 sampling_callback 旁同时传入 sampling_capabilities=SamplingCapability(tools=SamplingToolsCapability())——服务端必须看到 sampling.tools 被声明,才敢发送它们。
服务端可以在发起请求前用 ctx.session.check_client_capability(...) 主动探测客户端声明了什么(见 docs/client/callbacks.md 中的能力表与 tutorial003.py 示例)。
2026 时代回调并未死亡
在 2026-07-28 会话上,回调并非失效,而是换了一种投喂方式:当工具返回携带 CreateMessageRequest 或 ListRootsRequest 的 InputRequiredResult 时,Client 的自动循环会把对应条目分发给同一个 sampling_callback / list_roots_callback 并替你重试该调用。同一组回调同时服务于两个时代。
在 2025 时代的连接上
ctx.session.create_message(...) 与 ctx.session.list_roots() 仍然存在,供直接驱动会话的代码使用:
- 它们只在存在回送通道的地方(即 2025 时代、非无状态(non-stateless)的连接)才能工作;
- 调用它们会触发
MCPDeprecationWarning; - 更糟的是在现代化连接上:警告照发,然后发送失败——"Cannot send 'sampling/createMessage': this transport context has no back-channel for server-initiated requests."(见 docs/deprecated.md)。
上面介绍的解析器标记(Sample(...) / ListRoots())才是受支持的形态:它们根据协商出的协议版本自动选择投递方式(_uses_input_required 在 resolve.py 中以 2026-07-28 为分界),且不产生任何警告。
迁移建议:不用它们时怎么办
- 采样 → 直接集成你的 LLM 提供方 API。需要客户端模型的现代服务端,应通过多轮往返载体(
InputRequiredResult)提出请求;不需要的,直接在服务端调用模型提供方即可; - Roots → 用普通工具参数、资源 URI,或服务端配置来传递目录路径(
docs/deprecated.md的替换列同样指向 Multi-round-trip requests); - 弃用是"建议性"的:
warnings.filterwarnings("ignore", category=MCPDeprecationWarning)可整类静默(仅当你的服务端确实要服务 pre-2026 客户端时才值得);反过来在 pytest 配置里加"error::mcp.MCPDeprecationWarning",弃用调用就会变成测试失败,防止它们悄悄溜回代码库。
小结
- 在解析器中返回
Sample(...)或ListRoots(),工具就会像接收任何其他依赖一样收到CreateMessageResult或ListRootsResult; - 客户端必须声明匹配的能力,否则调用以
-32021失败,而不是发出请求; - 两项功能均在
2026-07-28弃用:现阶段完全可用,但对新设计是错误的。优先选择提供方 API 而非采样,优先选择显式参数而非 roots; - 想要报告慢工具的进度,见 Progress。