Roots
协议修订版本：2025-06-18
Model Context Protocol (MCP) 为客户端向服务器公开文件系统"根目录"提供了标准化的方式。根目录定义了服务器可以在文件系统中操作的边界，使它们能够了解它们可以访问哪些目录和文件。服务器可以从支持的客户端请求根目录列表，并在该列表发生变化时接收通知。
1. 用户交互模型
MCP 中的根目录通常通过工作区或项目配置界面公开。
例如，实现可以提供一个工作区/项目选择器，允许用户选择服务器应该访问的目录和文件。这可以与版本控制系统或项目文件的自动工作区检测相结合。
但是，实现可以自由地通过任何适合其需求的界面模式公开根目录——协议本身不要求任何特定的用户交互模型。
2. 能力声明
支持根目录的客户端必须在初始化期间声明 roots 能力：
json
{
"capabilities": {
"roots": {
"listChanged": true
}
}
}listChanged 表示客户端是否会在根目录列表发生变化时发出通知。
3. 协议消息
3.1 列出根目录
要检索根目录，服务器发送 roots/list 请求：
请求：
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "roots/list"
}响应：
json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"roots": [
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}
]
}
}3.2 根目录列表变更
当根目录发生变化时，支持 listChanged 的客户端必须发送通知：
json
{
"jsonrpc": "2.0",
"method": "notifications/roots/list_changed"
}4. 消息流程
5. 数据类型
5.1 Root
根目录定义包括：
uri：根目录的唯一标识符。在当前规范中，这必须是file://URI。name：可选的人类可读名称，用于显示目的。
不同用例的根目录示例：
项目目录
json
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}多个仓库
json
[
{
"uri": "file:///home/user/repos/frontend",
"name": "Frontend Repository"
},
{
"uri": "file:///home/user/repos/backend",
"name": "Backend Repository"
}
]6. 错误处理
客户端应该为常见的失败情况返回标准的 JSON-RPC 错误：
- 客户端不支持根目录：
-32601（方法未找到） - 内部错误：
-32603
错误示例：
json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Roots not supported",
"data": {
"reason": "Client does not have roots capability"
}
}
}7. 安全考虑
7.1 客户端要求
客户端必须：
- 仅公开具有适当权限的根目录
- 验证所有根目录 URI 以防止路径遍历
- 实施适当的访问控制
- 监控根目录的可访问性
7.2 服务器建议
服务器应该：
- 处理根目录变得不可用的情况
- 在操作期间尊重根目录边界
- 针对提供的根目录验证所有路径
8. 实现指南
8.1 客户端指南
客户端应该：
- 在向服务器公开根目录之前提示用户同意
- 为根目录管理提供清晰的用户界面
- 在公开之前验证根目录的可访问性
- 监控根目录变化
8.2 服务器指南
服务器应该：
- 在使用之前检查根目录能力
- 优雅地处理根目录列表变化
- 在操作中尊重根目录边界
- 适当地缓存根目录信息