根目录

模型上下文协议（MCP）为客户端向服务器公开文件系统“根目录”提供了一种标准方式。 根目录用于告知服务器客户端认为相关的目录和文件，使服务器能够据此聚焦其操作。 它们属于信息性指引，而不是访问控制机制。协议不会强制服务器停留在根目录范围内。 服务器可以向支持此功能的客户端请求根目录列表。

用户交互模型

MCP 中的根目录通常通过工作区或项目配置界面公开。

例如，实现可以提供工作区/项目选择器，让用户选择服务器应有权访问的目录和文件。 这也可以与版本控制系统或项目文件提供的工作区自动检测结合使用。

不过，实现可以自由采用符合自身需求的任何界面模式来公开根目录；协议本身不规定 具体的用户交互模型。

能力

支持根目录的客户端 MUST 在每个请求的 _meta.io.modelcontextprotocol/clientCapabilities 中声明 roots 能力：

{
  "_meta": {
    "io.modelcontextprotocol/clientCapabilities": {
      "roots": {}
    }
  }
}

协议消息

列出根目录

为了在处理客户端请求期间获取根目录，服务器发送一个包含 roots/list 请求的 InputRequiredResult：

输入请求（在 InputRequiredResult.inputRequests 中传递）：

{
  "method": "roots/list"
}

客户端结果（在重试请求的 inputResponses 中返回）：

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

消息流

  sequenceDiagram
    participant Server
    participant Client

    Note over Server,Client: Initial Request
    Client->>Server: tools/call(id: 1)
    Server-->>Client: InputRequiredResult(roots/list)
    Client->>Server: tools/call(id: 2, inputResponses{key: roots} + requestState)

数据类型

Root

根目录定义包括：

• uri：根目录的唯一标识符。在当前规范中，它 MUST 是一个 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"
  }
]

错误处理

如果发生错误，客户端无需携带错误消息重放初始调用，因为采用 InputRequiredResult 模式时，服务器并未等待响应。

安全注意事项

1. 客户端 MUST：

   • 仅公开具有适当权限的根目录
   • 验证所有根目录 URI，防止路径遍历
   • 实施适当的访问控制
   • 监控根目录的可访问性

2. 服务器 SHOULD：

   • 处理根目录变得不可用的情况
   • 在操作期间遵守根目录边界
   • 根据提供的根目录验证所有路径

实现指南

1. 客户端 SHOULD：

   • 在向服务器公开根目录前征得用户同意
   • 提供清晰的根目录管理界面
   • 在公开前验证根目录的可访问性
   • 监控根目录变化

2. 服务器 SHOULD：

   • 使用前检查根目录能力
   • 在操作中遵守根目录边界
   • 适当地缓存根目录信息