协议修订: 2025-06-18
模型上下文协议 (MCP) 提供了一种标准化的方式，让客户端能够向服务器暴露文件系统的“根目录”(roots)。根目录定义了服务器可以在文件系统中操作的边界，使其能够理解自己有权访问哪些目录和文件。服务器可以向支持的客户端请求根目录列表，并在该列表发生变化时接收通知。

​
用户交互模型

MCP 中的根目录通常通过工作区或项目配置界面来暴露。 例如，实现可以提供一个工作区/项目选择器，允许用户选择服务器应有权访问的目录和文件。这可以与从版本控制系统或项目文件中自动检测工作区的功能相结合。 然而，实现可以自由地通过任何适合其需求的界面模式来暴露根目录——协议本身并未强制要求任何特定的用户交互模型。

​
功能

支持根目录的客户端**必须**在初始化期间声明 roots 能力。 
{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}
listChanged 指示当根目录列表发生变化时，客户端是否会发出通知。

​
协议消息

​
列出根目录

要检索根目录，服务器发送一个 roots/list 请求： 请求：
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}
响应 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

​
根目录列表变更

当根目录发生变化时，支持 listChanged 的客户端**必须**发送一个通知。 
{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

​
消息流

​
数据类型

​
根目录

一个根目录定义包括：
  • uri：根目录的唯一标识符。在当前规范中，这**必须**是一个 file:// URI。
  • name：可选的、供显示使用的人类可读名称。
不同用例的根目录示例

​
项目目录

{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}

​
多个代码仓库

[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]

​
错误处理

对于常见的失败情况，客户端**应该**返回标准的 JSON-RPC 错误。
  • 客户端不支持根目录：-32601 (Method not found)
  • 内部错误：-32603
错误示例 
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

​
安全注意事项

  1. 客户端**必须**
    • 仅暴露具有适当权限的根目录
    • 验证所有根目录 URI 以防止路径遍历
    • 实施适当的访问控制
    • 监控根目录的可访问性
  2. 服务器**应该**
    • 处理根目录变得不可用的情况
    • 在操作过程中尊重根目录边界
    • 根据提供的根目录验证所有路径

​
实施指南

  1. 客户端**应该**
    • 在向服务器暴露根目录前，提示用户征求同意
    • 为根目录管理提供清晰的用户界面
    • 在暴露前验证根目录的可访问性
    • 监控根目录的变化
  2. 服务器**应该**
    • 在使用前检查根目录能力
    • 优雅地处理根目录列表的变化
    • 在操作中尊重根目录边界
    • 适当地缓存根目录信息