python-sdk 废弃特性迁移指南2026-07-28 规范下的 Deprecation 全面解读【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdkMCPModel Context Protocol官方 Python SDKpython-sdk针对 2026-07-28 版协议规范对一批旧特性做了系统性收编Roots、服务端发起的 Sampling、协议内 Logging 被标记为 deprecatedProgress 被限定为服务端到客户端单向ping则被直接移出协议。本指南以 docs/deprecated.md 为骨架逐项说明哪些 API 已废弃、为什么废弃、迁移到哪个新写法并结合仓库源码src/mcp/shared/exceptions.py、src/mcp/client/client.py 等验证每一个行为帮你把存量代码平滑升级到新协议时代。一、2026-07-28 规范废弃了什么1.1 五件被收编的事官方文档用一张表列出了 2026-07-28 规范回收的五类能力SDK 仍完整实现它们但每一处调用现在都会触发Deprecation 警告废弃内容废弃原因替代方案Rootsctx.session.list_roots()、client.send_roots_list_changed()、传给Client(...)的list_roots_callbackSEP-2577服务端发起的 Samplingctx.session.create_message()、传给Client(...)的sampling_callbackSEP-2577 将该项能力整体标废返回InputRequiredResult让客户端重试该调用见 Multi-roundtrip 请求协议内 Loggingctx.log()、ctx.debug()、ctx.info()、ctx.warning()、ctx.error()、ctx.session.send_log_message()、client.set_logging_level()SEP-2577 将该项能力整体标废协议内没有替代品改用普通import logging输出到 stderr见 Loggingpingclient.send_ping()从协议中移除而非简单废弃2026-07-28 里没有ping方法没有替代品它只在modelegacy连接上有效客户端到服务端的 Progressclient.send_progress_notification()2026-07-28 只允许 Progress 从服务端到客户端客户端没有可发送的内容由你的服务端用ctx.report_progress()上报进度见 Progress1.2 从表里浮出来的三个结论Roots、Sampling、Logging 是一伙的它们仨被同一个提案SEP-2577一次性标废。Sampling 和 Roots 共享一个更深层的问题这两处都是服务端向客户端发请求的场景而整个服务端→客户端请求方向正是 2026-07-28 用 Multi-roundtrip 请求multi-round-trip requests取代的东西。消失的是独立的 RPC 方法sampling/createMessage、roots/list以及推送式的elicitation/create而CreateMessageRequest/ListRootsRequest/ElicitRequest这些载荷类型被保留下来嵌入到InputRequiredResult.input_requests中客户端侧仍然落到同一批回调上。ping是个异类协议没有废弃它而是直接删除。SDK 方法仍然会警告提示语写的是removed而不是deprecated在现代连接上调用会得到Method not found响应。二、废弃是提示不是禁令2.1 今天什么都不会坏上述每一个方法在协商版本为 2025-11-25 或更早的会话上都继续正常工作。客户端固定modelegacy就能拿到 2026 年之前完全一致的行为线上数据格式不变能力协商逻辑不变。变化只发生在首次运行某个废弃方法时你会看到一条可见的警告MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).2.2 为什么用UserWarning而不是DeprecationWarningMCPDeprecationWarning是UserWarning的子类不是DeprecationWarning的子类。这是有意为之Python 的默认过滤器只在代码以__main__方式直接运行时显示DeprecationWarning这正是库废弃一个东西、两年没人发现的经典路径。而这条自定义警告在任何位置都会显示无需任何-W标志。源码佐证见 src/mcp/shared/exceptions.pyclass MCPDeprecationWarning(UserWarning)的 docstring 明确写道继承UserWarning是为了默认可见让用户无需显式开启 warnings 就能发现废弃特性。2.3 提示的边界线路上没有通道提示性质止步于线路。Sampling 和 Roots 是服务端发给客户端的请求而一个 2026-07-28 会话根本没有承载这种请求的通道。在工具内部、现代连接上调用ctx.session.create_message()警告照样触发但随后的发送会以错误失败Cannot send sampling/createMessage: this transport context has no back-channel for server-initiated requests.这两个信号按顺序出现MCPDeprecationWarning在你调用方法的那一刻触发与连接类型无关错误是 SDK 随后尝试发送时返回的结果。这两条路径只有在全程运行于modelegacy连接、且客户端注册了对应回调时才能端到端走通。对应地仓库在 src/mcp/shared/exceptions.py 定义了NoBackChannelError当请求作用域的通道报告TransportContext.can_send_request为False时抛出序列化为INVALID_REQUEST错误响应——这正是文档中那段报错文案的实现源头。三、在 legacy 会话上使用pingPing是一个空请求任一方都可以发送它来确认对方仍在应答。2026-07-28 规范将其移除SEP-2575现代客户端发送的每个请求本身就证明了服务端在线而现代服务端也没有通道主动发一个 ping。两条 SDK 方法在握手时代handshake-era的会话上仍然可用。客户端侧async def main() - None: async with Client(http://localhost:8000/mcp, modelegacy) as client: await client.send_ping() # warns; returns an EmptyResult服务端侧在任意 handler 内mcp.tool() async def check_client(ctx: Context) - str: A tool that still pings the client mid-call. await ctx.session.send_ping() # no warning; an EmptyResult while the client is connected return client answered需要区分几个细节client.send_ping()每次调用都会触发MCPDeprecationWarning。在默认2026-07-28连接上服务端会以MCPError: Method not found回应。ctx.session.send_ping()不带警告。在现代连接上它会像任何其他服务端发起的请求一样因为缺少返回通道back-channel而抛出同样的错误。任何一侧都不会注册应答 ping的处理逻辑。源码层面src/mcp/client/client.py 中send_ping被deprecated(ping is removed as of 2026-07-28; the method only works under modelegacy., categoryMCPDeprecationWarning)装饰——提示语用的正是removed与文档一致而 src/mcp/client/session.py 中的底层实现只是把PingRequest通过send_request发出去本身没有任何警告装饰。四、Roots 变更通知的完整链路一个 2025 时代的客户端若声明了 roots 能力可以通过发送notifications/roots/list_changed告知服务端自己的工作目录发生了变化服务端收到后重新请求roots/list。2026-07-28 规范把这条通知连同整个推送式 roots 流程一起移除了。4.1 客户端回调声明 一个调用兑现承诺在客户端传入list_roots_callback详见 Client 回调就是在声明roots: {listChanged: true}而下面这一个调用负责兑现这个承诺async def open_folder(client: Client, uri: str, name: str) - None: The user opened another folder: expose it through the roots callback, then tell the server. workspace.append(Root(uriFileUrl(uri), namename)) await client.send_roots_list_changed()4.2 服务端底层Server接收处理函数在服务端底层Server通过构造函数参数接收这个处理函数async def roots_changed(ctx: ServerRequestContext, params: NotificationParams | None) - None: The clients roots changed: ask for the new list. roots (await ctx.session.list_roots()).roots server Server(Bookshop, on_roots_list_changedroots_changed)4.3 行为细节workspace是你的list_roots_callback返回的那个列表。client.send_roots_list_changed()会触发警告而且它需要一个modelegacy客户端在现代连接上这条通知会被静默丢弃。调用后请保持会话开启因为服务端随后的roots/list请求会经由这条会话送达。MCPServer高层封装没有针对这条通知的钩子只有底层Server的on_roots_list_changed能注册 handler该参数同样已废弃构造时会警告。通知本身不携带 payload所以 handler 通过ctx.session.list_roots()去取新列表。仓库侧的证据链完整客户端方法 src/mcp/client/client.py 的send_roots_list_changed被deprecated(The roots capability is deprecated as of 2026-07-28 (SEP-2577)., ...)装饰服务端底层构造函数在 src/mcp/server/lowlevel/server.py 对on_roots_list_changed等参数统一发出废弃提示。测试 tests/client/test_list_roots_callback.py 则端到端验证了这条链路modelegacy下工具内context.session.list_roots()能取回回调返回的ListRootsResult而不注册回调时服务端会收到MCPError其error.code INVALID_REQUEST。五、抑制警告以及把警告变成测试失败5.1 新代码里不要抑制在新代码中请直接按替代方案迁移不要为了安静而屏蔽警告。5.2 存量服务按类别过滤不过一个确实还在服务 2026 年前客户端的存量服务完全有权利拥有一份干净的日志。在第一个废弃调用运行之前过滤掉该类别即可import warnings from mcp import MCPDeprecationWarning warnings.filterwarnings(ignore, categoryMCPDeprecationWarning)这就是全部 API。没有按方法区分的开关也不该有单一类别的意义就在于一行让它静音一行把它请回来。5.3 反转过滤器白送一个回归测试把过滤器反过来用你会白得一个回归测试。在 pytest 配置的filterwarnings设置中加入error::mcp.MCPDeprecationWarning废弃调用就会从警告变成抛出异常。一个仍调用ctx.info()的名为old_log的工具将不再通过调用会以is_errorTrue和Error executing tool old_log返回而被捕获的服务端日志会点名元凶mcp.shared.exceptions.MCPDeprecationWarning: The logging capability is deprecated as of 2026-07-28 (SEP-2577).一行 pytest 配置就能让废弃调用再也无法悄悄溜回你的代码库而不让某个测试失败。六、SDK 层面的废弃帮助函数以下不是协议变更只是 SDK 使用方式有了更好的替代品。它们用同一条MCPDeprecationWarning警告且3.0 会移除旧形式。废弃内容替代做法FuncMetadata.call_fn_with_arg_validation()先FuncMetadata.validate_arguments()再FuncMetadata.call_fn()。事实上只有直接驱动FuncMetadata的代码比如自定义的Tool子类才会调用它。AuthSettings(resource_server_url...)且不传validate_token_resource显式设置它True表示服务端拒绝你的 verifier 未报告为为resource_server_url签发的 Bearer TokenFalse表示由你的 verifier 自行检查 token 的 audience见 AuthorizationToken Verifier。不设置时行为等同False3.0 将在设置了resource_server_url时把True作为默认值。ClientCredentialsOAuthProvider(...)或PrivateKeyJWTOAuthProvider(...)且不传issuer传入issuer指名签发这批凭证的授权服务器见 编写 OAuth 客户端Machine-to-machine。不传时由 MCP 服务器决定把凭证送给哪个授权服务器3.0 会把这个关键字参数变为必填。关于issuer的警告行为仓库测试 tests/client/auth/extensions/test_client_credentials.py 中pytest.warns(MCPDeprecationWarning, matchOmittingissueris deprecated)给出了精确印证。七、总结2026-07-28 规范废弃了Roots、服务端发起的Sampling和协议内Logging都来自 SEP-2577把Progress限定为服务端到客户端单向并移除了ping。替代方案一栏指明了出路Multi-roundtrip 请求 用于 Sampling 和 RootsLogging 用于日志Progress 用于进度ping则什么都不需要。废弃是提示没有线上格式变更一切在 2026 年前的会话上照常工作你会得到一条默认可见的MCPDeprecationWarning它是UserWarning因此默认开启。Sampling 和 Roots 额外需要一个 2026-07-28 会话所不具备的返回通道。在现代连接上它们会先警告、随后抛出异常。warnings.filterwarnings(ignore, categoryMCPDeprecationWarning)可以静音整个类别pytest 里的error::mcp.MCPDeprecationWarning则把它变成测试失败。SDK 层面的废弃 遵循同一规则现在警告3.0 移除旧形式。新代码不应构建在任何这些废弃 API 之上。本仓库文档的其余页面docs教授的都是当前现代API升级时可据此对照迁移。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考