TypeScript SDK 中 Roots 根路径机制从能力声明、roots/list 应答到废弃迁移完整指南【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk导读本文围绕官方 TypeScript SDKmodelcontextprotocol/client的 Roots 能力展开你将学会如何在客户端声明roots能力、通过setRequestHandler(roots/list, …)向服务器提供file://根路径清单以及用sendRootsListChanged()通知服务器清单变更。与此同时本文会结合仓库源码说明 Roots 在协议版本 2026-07-28SEP-2577下的废弃状态与迁移路径帮助你在2025-era 连接兼容窗口内正确使用这一机制并提前规划向工具参数、资源 URI、服务器配置三条迁移路线的方案。背景Roots 是什么以及为什么需要关注废弃Roots 的协议定位在 MCP 协议中Root 是客户端交给服务器的一个file://URI用于向服务器圈定其文件操作的边界。典型场景是IDE 或工作区类客户端把当前打开的项目目录、数据目录以 Root 形式暴露给服务器服务器据此知道哪些路径是本次会话相关的从而提供更有针对性的工具、资源或提示。从 spec.types.2025-11-25.ts 的类型定义可以看出Root的结构uri: string—— 标识该根的 URI协议要求目前必须以file://开头类型注释明确说明该限制可能在协议未来版本放宽以支持其他 URI schemename?: string—— 可选的根名称用于人类可读展示也可在应用其他部分引用该根_meta?: { [key: string]: unknown }—— 协议通用元数据字段。废弃警告SEP-25772026-07-28 协议版本起 Roots 被弃用关联文档开头即给出关键警告Roots 自协议版本 2026-07-28SEP-2577起被废弃。承载根路径的请求roots/list没有任何替代品——协议修订不再提供服务器向客户端请求根路径的通道因此正确做法是把路径直接交给服务器。SDK 源码中处处可见这一废弃标记。例如 client.ts 中sendRootsListChanged()的 JSDoc/** * Notifies the server that the clients root list has changed. Requires the roots.listChanged capability. * * deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577). * Remains functional during the deprecation window (at least twelve months). * Migrate to passing paths via tool parameters, resource URIs, or configuration. */ async sendRootsListChanged() { return this.notification({ method: notifications/roots/list_changed }); }需要强调的是废弃不等于立即失效。Roots 在 2025-era 连接上至少保持 12 个月可用兼容窗口因此需要继续服务 2025-era 服务器的客户端仍然可以并且应当实现本页的 API。迁移优先废弃后的三条替代路径在实现 Roots API 之前先评估是否可以直接迁移。关联文档给出三条替代路径工具参数Tools把一次调用应当作用的路径作为工具参数传给服务器。这是最贴近每次调用上下文的方式服务器在tools/call中直接拿到路径无需额外的往返请求资源Resources把服务器拥有的位置以资源 URI 形式暴露服务器可以通过resources/list让客户端了解可用位置服务器自身配置把固定目录写进服务器自己的配置文件服务器启动即知。本文其余部分讲解的是在废弃窗口内仍需要应答 2025-era 服务器的客户端如何使用 Roots API。声明 Roots 能力capability在Client构造函数的capabilities中声明roots服务器才知道这个客户端允许我发起roots/list请求。若设置listChanged: true客户端还获准在清单变化时向服务器发送变更通知。配套示例 roots.examples.ts 中的完整写法import { Client } from modelcontextprotocol/client; const client new Client({ name: workspace-client, version: 1.0.0 }, { capabilities: { roots: { listChanged: true } } });这里有两个要点name/version参数Client构造函数的第一个参数是客户端标识名称 版本用于握手时向服务器自报家门capabilities.roots声明客户端支持 Roots 能力listChanged: true额外声明支持发送notifications/roots/list_changed通知。为什么必须先声明能力再注册处理器关联文档特别提醒必须在注册处理器之前声明能力——否则setRequestHandler(roots/list, …)会直接抛错。这一行为在 SDK 源码中有明确的强制校验。查看 client.ts 中的assertRequestHandlerCapabilitycase roots/list: { if (!this._capabilities.roots) { throw new SdkError( SdkErrorCode.CapabilityNotSupported, Client does not support roots capability (required for ${method}) ); } break; }也就是说setRequestHandler在注册时会校验客户端声明的能力。未声明capabilities.roots而尝试注册roots/list处理器会抛出CapabilityNotSupported错误。同理assertNotificationCapabilityclient.ts会在未声明roots.listChanged时拦截notifications/roots/list_changed通知的发送。应答 roots/list 请求服务器发起roots/list请求时客户端通过setRequestHandler(roots/list, …)返回{ roots }。每个uri必须以file://开头name可选。配套示例 roots.examples.tsconst roots [ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data } ]; client.setRequestHandler(roots/list, async () { return { roots }; });当已连接的服务器请求roots/list时它收到的正是处理器返回的清单[ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data } ]从类型层面看ListRootsResult的定义为roots: Root[]见 spec.types.2025-11-25.tsListRootsRequest的method字面量为roots/list见 spec.types.2025-11-25.ts。这些类型均源自协议 schema客户端与服务端共享同一套定义保证请求/响应的形状完全一致。注意Roots 是建议性边界不是访问授权关联文档特别强调Roots 是建议性的边界advisory boundaries不是访问授权。服务器依然以自身的权限访问文件系统SDK 不会在任一侧强制校验清单内容。也就是说服务器可以在 Roots 清单之外访问其他路径如果它自己的权限允许客户端给出清单不代表授予服务器访问权也不代表服务器只能访问这些路径SDK 层面没有任何对清单的强制执行逻辑。这是理解 Roots 语义的关键它更多是一种上下文提示/工作区指示而不是安全边界。任何安全假设都必须落在服务器自身的权限模型上。2026-07-28 连接上的特殊情况input_required 内嵌请求关联文档还指出一个协议演进下的细节在 2026-07-28 连接上不存在服务器到客户端的请求通道但同一个roots/list处理器依然可以生效——此时它处理的是嵌入在input_required结果中的roots/list请求详见 Protocol versions。从源码看input_required引擎确实把roots/list作为内嵌请求的一种类型处理。inputRequired.ts 中定义了内嵌结果的分派类型其中包含{ kind: roots; roots: Root[] }这一分支并根据候选对象中是否含有roots数组来判别第 239-240 行。也就是说在 2026-era 协议下客户端注册的roots/list处理器依然复用但触发它的通道从独立请求变为内嵌于input_required结果这正是 client.ts 注释中通过已注册的 elicitation/sampling/roots 处理器来履行所指的场景。通知服务器根路径清单已变更当客户端的根路径清单发生变化新增、删除或修改任何 Root时调用sendRootsListChanged()发送notifications/roots/list_changed通知。该通知依赖前面声明的listChanged: true能力——未声明则 SDK 会在发送时抛出CapabilityNotSupported。配套示例 roots.examples.tsroots.push({ uri: file:///home/user/projects/another-app, name: Another app }); await client.sendRootsListChanged();通知本身不携带任何 payload方法名即全部信息RootsListChangedNotification的params为可选见 spec.types.2025-11-25.ts。协议约定服务器收到通知后应自行重新发起roots/list请求以获取更新后的完整清单。上述示例运行后服务器再次请求roots/list会收到[ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data }, { uri: file:///home/user/projects/another-app, name: Another app } ]端到端验证示例中的内存传输 harness配套示例文件 roots.examples.ts 的下半部分提供了一个可运行的 harness用于端到端验证上述两个环节。它用modelcontextprotocol/server创建一个内存服务器通过InMemoryTransport.createLinkedPair()与客户端建立链接然后服务器调用server.listRoots()验证收到客户端roots/list处理器返回的清单对应文档引用的第一段输出服务器注册notifications/roots/list_changed通知处理器在收到通知后再次listRoots()打印更新后的清单对应文档引用的第二段输出。从源码结构看这印证了完整链路客户端声明能力 → 注册roots/list处理器 → 服务器请求 → 客户端应答 → 客户端发list_changed通知 → 服务器重新拉取。你可以用以下命令在examples/目录下实际运行它npx tsx guides/clients/roots.examples.ts该文件也参与pnpm sync:snippets --check的代码片段同步校验确保文档中的ts代码块与示例文件逐字一致。最佳实践与注意要点使用顺序关键约束构造Client时声明capabilities: { roots: { listChanged: true } }再调用setRequestHandler(roots/list, …)注册处理器需要通知变更时调用sendRootsListChanged()。顺序颠倒先注册处理器、后声明能力会因 SDK 的能力断言直接抛错。数据形状约束uri必须为合法 URI且协议要求以file://开头当前协议版本约束name可选建议提供人类可读名称便于服务器展示与引用每次roots/list应答应返回当前完整的根清单通知只起触发重新拉取的作用不含增量数据。语义边界Roots 是建议性边界SDK 不强制执行安全模型必须建立在服务器自身权限之上通知无 payload服务器收到通知后应主动重新请求roots/list。总结RecapRoots 已被 SEP-2577 废弃优先通过工具参数、资源 URI 或服务器配置传递路径2025-era 连接上至少 12 个月兼容窗口内仍可用能力声明在Client构造函数中声明capabilities: { roots: { listChanged: true } }且必须先声明再注册roots/list处理器否则 SDK 抛CapabilityNotSupported应答请求setRequestHandler(roots/list, …)返回{ roots }每个根uri以file://开头建议性边界Roots 不是访问授权SDK 不在任一侧强制执行变更通知sendRootsListChanged()通知服务器清单已变化服务器自行重新请求roots/list获取最新清单。延伸阅读工具参数迁移Tools 服务器指南资源 URI 迁移Resources 服务器指南协议版本与 2026-07-28 连接下的请求通道Protocol versions客户端完整示例代码roots.examples.ts客户端实现与能力断言源码client.tsRoots 类型定义spec.types.2025-11-25.ts【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TypeScript SDK 中 Roots 根路径机制：从能力声明、roots/list 应答到废弃迁移完整指南
TypeScript SDK 中 Roots 根路径机制从能力声明、roots/list 应答到废弃迁移完整指南【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk导读本文围绕官方 TypeScript SDKmodelcontextprotocol/client的 Roots 能力展开你将学会如何在客户端声明roots能力、通过setRequestHandler(roots/list, …)向服务器提供file://根路径清单以及用sendRootsListChanged()通知服务器清单变更。与此同时本文会结合仓库源码说明 Roots 在协议版本 2026-07-28SEP-2577下的废弃状态与迁移路径帮助你在2025-era 连接兼容窗口内正确使用这一机制并提前规划向工具参数、资源 URI、服务器配置三条迁移路线的方案。背景Roots 是什么以及为什么需要关注废弃Roots 的协议定位在 MCP 协议中Root 是客户端交给服务器的一个file://URI用于向服务器圈定其文件操作的边界。典型场景是IDE 或工作区类客户端把当前打开的项目目录、数据目录以 Root 形式暴露给服务器服务器据此知道哪些路径是本次会话相关的从而提供更有针对性的工具、资源或提示。从 spec.types.2025-11-25.ts 的类型定义可以看出Root的结构uri: string—— 标识该根的 URI协议要求目前必须以file://开头类型注释明确说明该限制可能在协议未来版本放宽以支持其他 URI schemename?: string—— 可选的根名称用于人类可读展示也可在应用其他部分引用该根_meta?: { [key: string]: unknown }—— 协议通用元数据字段。废弃警告SEP-25772026-07-28 协议版本起 Roots 被弃用关联文档开头即给出关键警告Roots 自协议版本 2026-07-28SEP-2577起被废弃。承载根路径的请求roots/list没有任何替代品——协议修订不再提供服务器向客户端请求根路径的通道因此正确做法是把路径直接交给服务器。SDK 源码中处处可见这一废弃标记。例如 client.ts 中sendRootsListChanged()的 JSDoc/** * Notifies the server that the clients root list has changed. Requires the roots.listChanged capability. * * deprecated Deprecated as of protocol version 2026-07-28 (SEP-2577). * Remains functional during the deprecation window (at least twelve months). * Migrate to passing paths via tool parameters, resource URIs, or configuration. */ async sendRootsListChanged() { return this.notification({ method: notifications/roots/list_changed }); }需要强调的是废弃不等于立即失效。Roots 在 2025-era 连接上至少保持 12 个月可用兼容窗口因此需要继续服务 2025-era 服务器的客户端仍然可以并且应当实现本页的 API。迁移优先废弃后的三条替代路径在实现 Roots API 之前先评估是否可以直接迁移。关联文档给出三条替代路径工具参数Tools把一次调用应当作用的路径作为工具参数传给服务器。这是最贴近每次调用上下文的方式服务器在tools/call中直接拿到路径无需额外的往返请求资源Resources把服务器拥有的位置以资源 URI 形式暴露服务器可以通过resources/list让客户端了解可用位置服务器自身配置把固定目录写进服务器自己的配置文件服务器启动即知。本文其余部分讲解的是在废弃窗口内仍需要应答 2025-era 服务器的客户端如何使用 Roots API。声明 Roots 能力capability在Client构造函数的capabilities中声明roots服务器才知道这个客户端允许我发起roots/list请求。若设置listChanged: true客户端还获准在清单变化时向服务器发送变更通知。配套示例 roots.examples.ts 中的完整写法import { Client } from modelcontextprotocol/client; const client new Client({ name: workspace-client, version: 1.0.0 }, { capabilities: { roots: { listChanged: true } } });这里有两个要点name/version参数Client构造函数的第一个参数是客户端标识名称 版本用于握手时向服务器自报家门capabilities.roots声明客户端支持 Roots 能力listChanged: true额外声明支持发送notifications/roots/list_changed通知。为什么必须先声明能力再注册处理器关联文档特别提醒必须在注册处理器之前声明能力——否则setRequestHandler(roots/list, …)会直接抛错。这一行为在 SDK 源码中有明确的强制校验。查看 client.ts 中的assertRequestHandlerCapabilitycase roots/list: { if (!this._capabilities.roots) { throw new SdkError( SdkErrorCode.CapabilityNotSupported, Client does not support roots capability (required for ${method}) ); } break; }也就是说setRequestHandler在注册时会校验客户端声明的能力。未声明capabilities.roots而尝试注册roots/list处理器会抛出CapabilityNotSupported错误。同理assertNotificationCapabilityclient.ts会在未声明roots.listChanged时拦截notifications/roots/list_changed通知的发送。应答 roots/list 请求服务器发起roots/list请求时客户端通过setRequestHandler(roots/list, …)返回{ roots }。每个uri必须以file://开头name可选。配套示例 roots.examples.tsconst roots [ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data } ]; client.setRequestHandler(roots/list, async () { return { roots }; });当已连接的服务器请求roots/list时它收到的正是处理器返回的清单[ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data } ]从类型层面看ListRootsResult的定义为roots: Root[]见 spec.types.2025-11-25.tsListRootsRequest的method字面量为roots/list见 spec.types.2025-11-25.ts。这些类型均源自协议 schema客户端与服务端共享同一套定义保证请求/响应的形状完全一致。注意Roots 是建议性边界不是访问授权关联文档特别强调Roots 是建议性的边界advisory boundaries不是访问授权。服务器依然以自身的权限访问文件系统SDK 不会在任一侧强制校验清单内容。也就是说服务器可以在 Roots 清单之外访问其他路径如果它自己的权限允许客户端给出清单不代表授予服务器访问权也不代表服务器只能访问这些路径SDK 层面没有任何对清单的强制执行逻辑。这是理解 Roots 语义的关键它更多是一种上下文提示/工作区指示而不是安全边界。任何安全假设都必须落在服务器自身的权限模型上。2026-07-28 连接上的特殊情况input_required 内嵌请求关联文档还指出一个协议演进下的细节在 2026-07-28 连接上不存在服务器到客户端的请求通道但同一个roots/list处理器依然可以生效——此时它处理的是嵌入在input_required结果中的roots/list请求详见 Protocol versions。从源码看input_required引擎确实把roots/list作为内嵌请求的一种类型处理。inputRequired.ts 中定义了内嵌结果的分派类型其中包含{ kind: roots; roots: Root[] }这一分支并根据候选对象中是否含有roots数组来判别第 239-240 行。也就是说在 2026-era 协议下客户端注册的roots/list处理器依然复用但触发它的通道从独立请求变为内嵌于input_required结果这正是 client.ts 注释中通过已注册的 elicitation/sampling/roots 处理器来履行所指的场景。通知服务器根路径清单已变更当客户端的根路径清单发生变化新增、删除或修改任何 Root时调用sendRootsListChanged()发送notifications/roots/list_changed通知。该通知依赖前面声明的listChanged: true能力——未声明则 SDK 会在发送时抛出CapabilityNotSupported。配套示例 roots.examples.tsroots.push({ uri: file:///home/user/projects/another-app, name: Another app }); await client.sendRootsListChanged();通知本身不携带任何 payload方法名即全部信息RootsListChangedNotification的params为可选见 spec.types.2025-11-25.ts。协议约定服务器收到通知后应自行重新发起roots/list请求以获取更新后的完整清单。上述示例运行后服务器再次请求roots/list会收到[ { uri: file:///home/user/projects/my-app, name: My App }, { uri: file:///home/user/data, name: Data }, { uri: file:///home/user/projects/another-app, name: Another app } ]端到端验证示例中的内存传输 harness配套示例文件 roots.examples.ts 的下半部分提供了一个可运行的 harness用于端到端验证上述两个环节。它用modelcontextprotocol/server创建一个内存服务器通过InMemoryTransport.createLinkedPair()与客户端建立链接然后服务器调用server.listRoots()验证收到客户端roots/list处理器返回的清单对应文档引用的第一段输出服务器注册notifications/roots/list_changed通知处理器在收到通知后再次listRoots()打印更新后的清单对应文档引用的第二段输出。从源码结构看这印证了完整链路客户端声明能力 → 注册roots/list处理器 → 服务器请求 → 客户端应答 → 客户端发list_changed通知 → 服务器重新拉取。你可以用以下命令在examples/目录下实际运行它npx tsx guides/clients/roots.examples.ts该文件也参与pnpm sync:snippets --check的代码片段同步校验确保文档中的ts代码块与示例文件逐字一致。最佳实践与注意要点使用顺序关键约束构造Client时声明capabilities: { roots: { listChanged: true } }再调用setRequestHandler(roots/list, …)注册处理器需要通知变更时调用sendRootsListChanged()。顺序颠倒先注册处理器、后声明能力会因 SDK 的能力断言直接抛错。数据形状约束uri必须为合法 URI且协议要求以file://开头当前协议版本约束name可选建议提供人类可读名称便于服务器展示与引用每次roots/list应答应返回当前完整的根清单通知只起触发重新拉取的作用不含增量数据。语义边界Roots 是建议性边界SDK 不强制执行安全模型必须建立在服务器自身权限之上通知无 payload服务器收到通知后应主动重新请求roots/list。总结RecapRoots 已被 SEP-2577 废弃优先通过工具参数、资源 URI 或服务器配置传递路径2025-era 连接上至少 12 个月兼容窗口内仍可用能力声明在Client构造函数中声明capabilities: { roots: { listChanged: true } }且必须先声明再注册roots/list处理器否则 SDK 抛CapabilityNotSupported应答请求setRequestHandler(roots/list, …)返回{ roots }每个根uri以file://开头建议性边界Roots 不是访问授权SDK 不在任一侧强制执行变更通知sendRootsListChanged()通知服务器清单已变化服务器自行重新请求roots/list获取最新清单。延伸阅读工具参数迁移Tools 服务器指南资源 URI 迁移Resources 服务器指南协议版本与 2026-07-28 连接下的请求通道Protocol versions客户端完整示例代码roots.examples.ts客户端实现与能力断言源码client.tsRoots 类型定义spec.types.2025-11-25.ts【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考