MCP Python SDK 采样与根目录(Sampling & Roots):让服务端借用客户端模型与工作区文件夹
MCP Python SDK 采样与根目录(Sampling & Roots):让服务端借用客户端模型与工作区文件夹
导读
在 Model Context Protocol(MCP)的服务端开发中,工具(tool)有时需要两类客户端侧资源:一是客户端自身大模型生成的补全结果(sampling,采样),二是客户端共享出来的工作区文件夹(roots,根目录)。本文以 python-sdk 官方文档为主线,结合仓库源码与测试用例,系统讲解如何通过 Sample(...) 与 ListRoots() 这两个解析器标记在工具参数中注入这两类数据,以及能力声明、协议版本差异、弃用现状与推荐的迁移路径。读完本文,你将掌握在 MCP 服务端中安全、正确地借用客户端模型与读取客户端根目录的完整方案,并能理解其底层在 2026-07-28 与 2025-11-25 两代协议下的不同投递机制。
先说结论:两个功能都已被弃用
在深入代码之前,必须先明确本文两个主题的现状。根据官方文档(docs/handlers/sampling-and-roots.md)中的警示框:
- 采样(sampling)与根目录(roots)自 2026-07-28 版本的规范起被标记为弃用(deprecated,见 SEP-2577)。
- 它们在至少 12 个月内仍完全可用、不会被移除,但新实现不应再围绕它们进行设计。
- 官方建议的迁移方案:
- 采样 → 直接与你的 LLM 提供方 API 集成;
- 根目录 → 通过工具参数、资源 URI 或服务端配置来传递目录。
SDK 全量的弃用功能清单见 docs/deprecated.md。
尽管已弃用,这两个功能在 SDK 支持的所有协议版本上仍然正常工作。理解它们的实现机制,既有助于读懂存量代码,也能帮你做出正确的迁移决策。
解析器标记:Resolve(...) 依赖注入体系
采样与根目录不是普通的工具调用,它们走的是 python-sdk 的解析器依赖注入机制。在 docs/handlers/dependencies.md 中介绍了完整背景:工具参数可以用 Annotated[T, Resolve(fn)] 标注,SDK 会在工具体执行前调用 fn(称为解析器,resolver),并将其返回值作为参数注入。
解析器可以返回三类"请求标记"(request marker),由框架代为向对端发起请求:
| 标记 | 请求内容 | 注入的结果类型 |
|---|---|---|
Elicit(message, Model) |
向用户提问(elicitation) | 回答的模型实例 |
Sample(...) |
请求客户端用其模型生成补全(sampling/createMessage) |
CreateMessageResult |
ListRoots() |
请求客户端列出根目录(roots/list) |
ListRootsResult |
从源码注释(src/mcp/server/mcpserver/resolve.py)可以看到:Elicit 有 accept/decline/cancel 三态结果,而 Sample 和 ListRoots 没有拒绝分支——消费方直接标注结果类型即可。解析器之间还可以形成 DAG 依赖图,彼此通过 Resolve(...) 互相引用,框架在注册工具时就完成图分析,坏图(如循环依赖、无法分类的参数)会在启动时抛出 InvalidSignature,而不是在调用中途才失败。
采样(Sampling):借用客户端的模型
一个完整的示例
官方文档给出的示例(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."
这个例子的执行流程:
- 客户端调用
blurb工具,传入title; - SDK 发现
draft参数带Resolve(draft_blurb)标记,先运行解析器draft_blurb; - 解析器返回
Sample(...),SDK 据此向客户端发起sampling/createMessage请求; - 客户端用自己的模型完成补全,返回
CreateMessageResult; - SDK 把结果注入到
draft参数中,工具体像使用普通依赖一样读取draft.content.text。
注意,解析器 draft_blurb(title) 的 title 参数是按名称匹配工具自身的 title 参数,这与 Elicit 场景的解析器规则完全一致。
Sample 构造参数详解
从源码(src/mcp/server/mcpserver/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:
| 参数 | 说明 | 注意点 |
|---|---|---|
messages |
发送给客户端模型的对话消息列表,元素为 SamplingMessage(role + content) |
必填;content 常用 TextContent(type="text", text=...) |
max_tokens |
生成的最大 token 数 | 必填 |
system_prompt |
可选的系统提示词 | 可选 |
include_context |
上下文包含范围 | 不要设置,见下文警告 |
temperature |
采样温度 | 可选 |
stop_sequences |
停止序列列表 | 可选 |
metadata |
透传给 LLM 提供方的元数据 | 可选 |
model_preferences |
模型选择偏好 | 可选 |
tools |
采样过程中允许 LLM 使用的工具列表 | 传了就需要客户端声明 sampling.tools 能力 |
tool_choice |
工具使用行为的控制 | 同上 |
构造器内部会把这些参数打包成 CreateMessageRequestParams,并调用 validate_tool_use_result_messages(messages) 校验消息结构(含 tool_use/tool_result 时的消息合法性)。
注入的结果类型
- 默认情况下,注入的是客户端的
CreateMessageResult; - 一旦你在
Sample中传了tools或tool_choice,注入类型自动变为CreateMessageResultWithTools(可承载数组形式的内容)。
源码中这一决策体现在 _result_type() 函数(src/mcp/server/mcpserver/resolve.py):它根据 wants_sampling_tools(...) 判断选择哪个结果模型用于响应校验。
能力声明与 -32021 门控
客户端必须预先声明 sampling 能力,否则服务端不会发送请求,而是直接以 -32021 协议错误让调用失败。对应的错误常量是 MISSING_REQUIRED_CLIENT_CAPABILITY(见 src/mcp/server/mcpserver/resolve.py 中的 _require_capability 实现):
- 传了
tools/tool_choice→ 要求客户端声明sampling.tools; - 未传 → 要求声明
sampling。
这一"先检查再发送"的门控逻辑也被测试用例明确验证(tests/docs_src/test_sampling_and_roots.py):当客户端未声明 sampling 能力时调用 blurb,会抛出 code 为 MISSING_REQUIRED_CLIENT_CAPABILITY 的 MCPError,请求根本不会被发出。
另外,对于没有反向通道(back-channel)的 2026 年之前会话,由于根本没有通道可发,会以常规的"无反向通道"错误失败(NoBackChannelError,见 src/mcp/server/session.py 的文档说明)。
两代协议下的投递差异
同一份代码,在两种协议版本下投递方式不同(resolve.py 中的 _INPUT_REQUIRED_VERSION 固定为 "2026-07-28"):
- 2026-07-28 及以后:采样请求被封装进**多轮往返(multi-round-trip)**流程,即服务器在
tools/call中返回InputRequiredResult,客户端应答后重试调用(详见 docs/handlers/multi-round-trip.md)。采样结果会搭乘request_state在后续每一轮中携带。 - 2025-11-25 及以前:采样是调用中途发出的独立服务端到客户端请求,通过反向通道同步完成。
无论哪种方式,代码写法完全相同。但要注意多轮往返的硬性规则:请求必须在每一轮重试中渲染得完全一致——因此 Sample(...) 只能由工具的参数和其他稳定数据构造,不能掺入每次调用都变化的值(如时间戳、随机 ID),否则客户端返回的答案会被判定为与问题不匹配而反复重新询问。框架会用问题渲染内容的 SHA-256 摘要来钉住答案(见 _request_digest,resolve.py),问题一变,旧答案即失效。
include_context 千万别碰
Sample 的 include_context 参数必须留空或设为 "none"。任何非 "none" 的值本身就已被弃用(SEP-2596),而且它要求客户端声明一个几乎没有任何客户端会声明的 sampling.context 能力。从 session.py 的 create_message 文档(src/mcp/server/session.py)也能看到同样的告诫:只有客户端具备 sampling.context 能力时才应设为 "thisServer" 或 "allServers"。
根目录(Roots):工作区文件夹该放哪
什么是 Roots
Roots 是客户端告诉服务端"你可以在这些文件夹上操作"的工作区目录列表。文档强调:这仅是参考性指引(informational guidance),绝不是访问控制机制——客户端说"可以"不代表服务端应该放松自己的路径安全校验,服务端仍然需要自行约束文件访问范围。
完整示例
官方文档的示例(docs_src/sampling_and_roots/tutorial002.py):
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)
流程与采样完全对称:
- 解析器
workspace_roots返回ListRoots()标记; - SDK 向客户端发起
roots/list请求; - 客户端通过
list_roots_callback返回ListRootsResult; - 结果注入
roots参数,工具体读取roots.roots[0].uri等字段。
注入结果的结构
注入的 ListRootsResult 包含一个 Root 列表,每个 Root 由两部分组成:
uri:file://协议的 URI,标识一个工作区文件夹;name(可选):显示名称。
测试用例展示了客户端的构造方式(tests/docs_src/test_sampling_and_roots.py):ListRootsResult(roots=[Root(uri=FileUrl("file:///workspace/catalog"), name="catalog")]),随后服务端工具的返回值即 file:///workspace/catalog。
能力门控
与采样相同:客户端必须声明 roots 能力,否则调用以 -32021(MISSING_REQUIRED_CLIENT_CAPABILITY)失败,而不是真的发送请求。实现见 src/mcp/server/mcpserver/resolve.py:检查 capabilities.roots is not None,未声明则抛出携带 requiredCapabilities 负载的 MCPError。
客户端的另一半:回调
协议的每一端都有对应实现。在客户端一侧,采样与根目录请求由两个回调应答:
sampling_callback:应答sampling/createMessage请求;list_roots_callback:应答roots/list请求。
它们在 src/mcp/client/client.py 中作为 Client 构造参数暴露,并在会话初始化时传入(src/mcp/client/session.py)。SDK 还提供了默认实现 _default_sampling_callback 与 _default_list_roots_callback(src/mcp/client/session.py),当用户未提供自定义回调时使用;在请求分发处(src/mcp/client/session.py),收到的对应请求会被路由到这两个回调上。
客户端回调的详细文档见 docs/client/callbacks.md。测试中给出的回调形态:
async def sampler(context: ClientRequestContext, params: CreateMessageRequestParams) -> CreateMessageResult:
# ... 调用自己的 LLM,返回 CreateMessageResult
return CreateMessageResult(role="assistant", content=TextContent(type="text", text="..."), model="m")
async def client_roots(context: ClientRequestContext) -> ListRootsResult:
return ListRootsResult(roots=[Root(uri=FileUrl("file:///workspace/catalog"), name="catalog")])
注意:当 Sample 请求中带有 tools 或 tool_choice 时,回调的返回类型应相应使用 CreateMessageResultWithTools(采样工具子能力 sampling.tools 也需一并声明)。
2025 时代的直接调用:ctx.session.create_message(...) 与 ctx.session.list_roots()
对于直接驱动会话的旧式代码,SDK 仍然保留了两个底层方法:
ctx.session.create_message(...):发送sampling/createMessage请求(src/mcp/server/session.py);ctx.session.list_roots():发送roots/list请求(src/mcp/server/session.py)。
但要注意它们的适用边界:
- 只在存在反向通道的连接上可用(2025 时代、非无状态连接);无反向通道时会抛
NoBackChannelError; - 调用会触发弃用警告(源码中两者都带有
@deprecated("... deprecated as of 2026-07-28 (SEP-2577) ...", category=MCPDeprecationWarning)装饰器); - 上面介绍的
Sample(...)/ListRoots()解析器标记才是受支持的正规形态:框架会根据协商出的协议版本自动选择投递方式,且不会发出警告。
也就是说,新代码请一律使用解析器标记,而不是直接调用 session 方法。
源码级原理补充:请求如何被渲染与校验
为了让文章具备可验证性,这里把 src/mcp/server/mcpserver/resolve.py 中与采样/根目录相关的内部机制串起来:
- 标记判定(
_is_marker,第 651-652 行):解析器返回值是Elicit、Sample、ListRoots之一时进入_fulfil流程; - 能力检查(
_require_capability,第 673-708 行):Sample检查sampling/sampling.tools,ListRoots检查roots,未声明即抛-32021; - 请求渲染(
_render_request,第 711-718 行):Sample渲染为CreateMessageRequest(params=marker.params),ListRoots渲染为ListRootsRequest(); - 结果校验模型选择(
_result_type,第 721-731 行):按是否携带tools/tool_choice选择CreateMessageResult或CreateMessageResultWithTools,ListRoots固定为ListRootsResult; - 多轮往返状态(
_Resolution/_restore_outcome等,第 426-458、806-830 行):2026-07-28 下,结果记录进request_state并在后续轮次恢复,恢复时还会校验问题摘要与结果合法性,失败则重新询问。
测试用例 tests/docs_src/test_sampling_and_roots.py 则以 legacy 与 auto 两种模式参数化运行,分别覆盖 2025 时代与自动协商协议的投递路径,并在开头声明"本页面所有论断均对照真实 SDK 验证"——包括:
test_a_sampling_dependency_receives_the_clients_completion:采样依赖收到客户端补全,且提示词精确为"Write a one-sentence blurb for the book 'Dune'.";test_a_roots_dependency_receives_the_clients_folders:根目录依赖收到客户端的文件夹列表;test_an_undeclared_capability_fails_before_a_request_is_sent:未声明能力时以-32021在发请求前失败。
总结
- 在解析器中返回
Sample(...)或ListRoots(),工具就能像接收普通依赖一样收到CreateMessageResult(或CreateMessageResultWithTools)与ListRootsResult; - 客户端必须声明对应能力(
sampling/sampling.tools/roots),否则调用以-32021失败,请求根本不会发出; - 两个功能在 2026-07-28 均已弃用:现在完全可用,但对新设计不合适——优先用提供方 API 替代采样,用显式参数替代根目录;
- 同一份代码在 2026-07-28(多轮往返,结果搭乘
request_state)与 2025-11-25(独立请求)下行为一致,但Sample必须由稳定数据构造,保证各轮渲染一致; - 旧式直接调用
ctx.session.create_message(...)/ctx.session.list_roots()仅限存在反向通道的连接,且会触发弃用警告,新代码应改用解析器标记。
相关阅读: