人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载在 Model Context Protocol 中请求的方向通常是“客户端 → 服务器”。但服务器端 handler 也有两种向客户端反向索取的途径sampling采样即借用客户端自己的 LLM 生成一次 completion以及roots根目录即读取客户端声明的工作区目录列表。本文基于python-sdk仓库中 sampling-and-roots 文档 及其源码实现完整讲解这两项能力的使用方式、能力协商门禁、跨协议版本的传输差异以及它们当前所处的弃用状态与迁移路径。读完本文你将掌握如何用Sample(...)与ListRoots()两类 resolver 标记从客户端取回数据并理解在2026-07-28与2025-11-25两代协议下这些请求分别如何送达。两项能力的定位与弃用警告一个 handler 可以向已连接的客户端额外索取两类东西sampling让客户端用它自己的模型生成一段补全completion服务器拿到结果继续执行roots获取客户端允许服务器操作的工作区文件夹列表。这两项能力在 SDK 能协商的所有协议版本上仍然可用但在设计新方案之前必须先读这条警告⚠️ 已被2026-07-28规范弃用Sampling 与 roots 自2026-07-28起被标记为弃用对应 SEP-2577。从 docs/deprecated.md 可以看到2026-07-28规范共退役了五类能力其中 roots、服务器发起的 sampling 与协议级 logging 同属 SEP-2577 一个提案。文档特别指出 sampling 与 roots 的深层问题它们是服务器向客户端发请求的方向而整个“服务器向客户端反向调用”的方向正是2026-07-28用多轮往返请求multi-round-trip 取代的东西。被移除的是独立的 RPC 方法sampling/createMessage、roots/list而CreateMessageRequest/ListRootsRequest这些载荷类型得以保留只是改乘InputRequiredResult.input_requests这班车在客户端一侧仍然命中同一个回调。Sampling借用客户端的模型用Sample(...)声明一次采样请求Sampling 通过依赖注入机制实现你在工具参数上用Annotated[...]包一层Resolve(fn)resolver 函数返回Sample(...)标记SDK 会代你向客户端发起sampling/createMessage请求并把结果注入为工具参数。这与执行Elicit见 Dependencies的机制完全相同。完整示例来自 docs_src/sampling_and_roots/tutorial001.pyfrom 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 fWrite a one-sentence blurb for the book {title!r}. return Sample( [SamplingMessage(roleuser, contentTextContent(typetext, textprompt))], max_tokens60, ) 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(messages, max_tokens...)的参数镜像sampling/createMessage的请求参数。被注入的值是客户端的CreateMessageResult如果请求里传了tools或tool_choice注入类型会变为CreateMessageResultWithTools。Resolve(draft_blurb)声明这是一个resolverSDK 在调用工具主体之前运行draft_blurb其返回值这里是Sample标记被框架消费CreateMessageResult则作为draft参数注入。与Elicit的 accept/decline/cancel 三态结果不同Sample没有拒绝分支消费方直接标注结果类型即可。Sample的完整参数面从 src/mcp/server/mcpserver/resolve.py 的类定义可以看到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必填且会经过validate_tool_use_result_messages校验max_tokens为必填关键字参数model_preferences用于表达模型偏好如 hint、成本/延迟优先级传入tools/tool_choice后框架会要求客户端声明sampling.tools子能力见下文门禁并把结果校验为CreateMessageResultWithTools。能力门禁未声明 capability 时以-32021拒绝客户端必须已声明sampling能力若请求携带tools或tool_choice则必须声明sampling.tools。若未声明SDK不会发送一个客户端无法处理的请求而是直接以协议错误-32021missing required client capability拒绝调用。从 src/mcp/server/mcpserver/resolve.py 的_require_capability实现可以看到这个门禁的判定逻辑对于Sample框架检查capabilities.sampling当请求带tools/tool_choicewants_sampling_tools为真时还要求sampling.tools非空否则构造携带required_capabilities载荷的MCPError抛出。-32021正是MISSING_REQUIRED_CLIENT_CAPABILITY错误码其使用在 src/mcp/server/mcpserver/server.py 的扩展门禁中也有印证。另外对于没有反向通道back-channel的2026 之前会话采样请求无路可发会以常规的“无反向通道”错误失败。两代协议下的投递方式同一条Sample请求SDK 会根据协商出的协议版本选择投递方式由 resolve.py 的_uses_input_required判断2026-07-28及以后请求被装入**多轮往返multi-round-trip**流程 —— 服务器返回InputRequiredResult客户端回调应答后用input_responses/request_state重试tools/call。详细机制见 Multi-round-trip requests。2025-11-25及更早请求是发给客户端的独立sampling/createMessage请求走反向通道。两种情况下代码完全一致但必须遵守多轮往返的铁律请求必须在每一轮 retry 中渲染得完全一致因此只能由工具参数和其他稳定数据构造绝不能掺入每次运行都变化的量时间戳、随机 ID 等——否则每一轮记录的结果都会“看起来过期”服务器会反复重问直到客户端轮次上限终止调用。include_context不要再动include_context保持默认none即可任何非none的取值本身也已弃用SEP-2596而且需要一种几乎没有客户端会声明的能力。不要在新代码中使用。Roots文件应该放哪里Roots 是客户端告知服务器“可以在此目录上操作”的文件夹集合。需要强调的是roots 只是信息性指引informational guidance不是访问控制机制。resolver 返回ListRoots()标记即可发起roots/list请求。完整示例来自 docs_src/sampling_and_roots/tutorial002.pyfrom 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每个Root是一个file://URI 加上可选的显示名称name。门禁与 sampling 相同客户端未声明roots能力时调用以-32021失败而不是发出请求。在 resolve.py 中ListRoots分支检查capabilities.roots是否为None缺失则抛出同样的MCPError。在 resolve.py 中ListRoots类本身是一个极简的哨兵标记其文档注释说明了用途resolver 对客户端 roots 的请求框架注入ListRootsResult。请求经_render_request渲染为ListRootsRequest()在2025-11-25时代作为独立roots/list请求发出在2026-07-28时代则装入InputRequiredResult。连接的另一端客户端回调在连接的另一端客户端用已有的回调应答这两类请求sampling_callback与list_roots_callback详见 Client callbacks。回调签名示例来自 docs_src/client_callbacks/tutorial004.pyfrom pydantic import FileUrl from mcp.client import ClientRequestContext from mcp.types import CreateMessageRequestParams, CreateMessageResult, ListRootsResult, Root, TextContent async def handle_sampling( context: ClientRequestContext, params: CreateMessageRequestParams, ) - CreateMessageResult: return CreateMessageResult( roleassistant, contentTextContent(typetext, textThe answer is 42.), modelmy-llm, ) async def handle_list_roots(context: ClientRequestContext) - ListRootsResult: return ListRootsResult(roots[Root(uriFileUrl(file:///home/ada/notebooks), namenotebooks)])sampling 回调接收完整的CreateMessageRequestParamsmessages、model_preferences、max_tokens返回CreateMessageResult。真正调用模型的是你SDK 只负责搬运请求与结果。roots 回调不接收参数直接返回ListRootsResult。两者也都可以返回ErrorData(...)表示拒绝。把这些回调传给Client(...)的方式与elicitation_callback完全一致。值得注意的是docs/client/callbacks.md 指出注册回调本身就是能力声明——传入sampling_callback客户端就声明sampling: {}传入list_roots_callback则声明roots: {listChanged: true}。若你处理tools/tool_choice参数还需额外传sampling_capabilitiesSamplingCapability(toolsSamplingToolsCapability())让服务器能看到sampling.tools已声明。而在2026-07-28会话中这两个回调并非“死去”当InputRequiredResult携带CreateMessageRequest或ListRootsRequest时Client的自动重试循环会把它们分发给同一个sampling_callback或list_roots_callback。一套回调同时服务两代协议相关逻辑可见 src/mcp/client/session.py 中回调的分发路径。但如果你没有注册对应回调SDK 的默认回调会替客户端用错误拒绝导致整个call_tool抛出MCPError。2025 时代连接上的旧 APIctx.session.create_message(...)和ctx.session.list_roots()仍然存在供直接驱动会话的代码使用。它们有两个限制只能在存在反向通道的地方工作即 2025 时代、非 stateless 的连接在2026-07-28会话上没有承载这类服务器→客户端请求的通道调用会先触发MCPDeprecationWarning随后发送失败并抛出“no back-channel”错误调用会触发弃用警告。而上面介绍的resolver 标记Sample(...)/ListRoots()才是受支持的形式框架根据协商出的版本自动选择投递方式2026-07-28走InputRequiredResult2025-11-25走独立请求且不产生弃用警告。迁移建议新代码应该怎么做2026-07-28已弃用这两项能力SEP-2577官方建议的迁移方向能力弃用原因新方案Sampling服务器发起服务器→客户端反向请求方向被淘汰服务器直接集成 LLM 提供商 API或在2026-07-28会话中通过InputRequiredResult携带CreateMessageRequest让客户端回调Roots同上且 roots 本就不是访问控制用普通工具参数、资源 URI 或服务器配置传递目录路径关键认知弃用是“建议性”的见 docs/deprecated.md。今天什么都不会坏——针对任何协商为2025-11-25或更早的会话上述方法全部照常工作客户端钉住modelegacy即可获得完全的前 2026 行为。变化在于每次调用都会出现一条默认可见的MCPDeprecationWarning它继承自UserWarning而非DeprecationWarning无需任何-W标志就会显示。想在新项目中彻底绕开这些能力推荐做法是让工具直接调用你的 LLM 提供商 SDK把目录作为显式工具参数或资源 URI 传入而不是依赖 sampling 与 roots。回顾从 resolver 返回Sample(...)或ListRoots()工具像接收任何其他依赖一样拿到CreateMessageResult或ListRootsResult。客户端必须声明对应能力否则调用以-32021协议错误失败而不是发出请求。两项能力在2026-07-28已弃用目前完全可用但对新设计而言是错误选择。优先用提供商 API 替代 sampling用显式参数替代 roots。若要向客户端报告慢速工具的进度请参考 Progress进度上报 页面。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐Python MCP SDK 的采样Sampling与 Roots 依赖注入借用客户端模型与工作区目录的完整实践指南Python MCP SDK 的采样Sampling与 Roots 依赖注入借用客户端模型与工作区目录的完整实践指南 导读 docs/handlers/s人工智能MCP 服务MCP ClientsPython SDK 的 Sampling 与 Roots在处理器中借用客户端模型与工作目录的完整指南Python SDK 的 Sampling 与 Roots在处理器中借用客户端模型与工作目录的完整指南 采样Sampling与根目录Roots是 Mo人工智能MCP 服务MCP Clientspython-sdk 处理器指南通过 Sample 与 ListRoots 借调客户端模型与工作区根目录python sdk 处理器指南通过 Sample 与 ListRoots 借调客户端模型与工作区根目录 导读 在处理函数handler中工具tool人工智能MCP 服务MCP Clients上一篇深入解析jsondiffpatch项目的Delta格式下一篇CubeFS项目代码贡献完全指南从入门到精通的技术规范创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考