协议版本: 2024-11-05
Model Context Protocol (MCP) 提供了一种标准化方式，让客户端向服务器暴露文件系统"根目录"。根目录定义了服务器可在文件系统内操作的边界范围，使其能够了解可访问哪些目录和文件。服务器可从支持该协议的客户端请求根目录列表，并在列表变更时接收通知。

​
用户交互模型

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

​
能力

Clients that support roots 必须 declare the roots capability during initialization: 
{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}
listChanged indicates whether the client will emit notifications when the list of roots changes.

​
协议消息

​
列出根目录

To retrieve roots, servers send a roots/list request: 请求： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}
响应： 响应： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

​
根列表更改

When roots change, clients that support listChanged 必须 send a notification: 
{
  "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"
  }
]

​
错误处理

Clients 应当 return standard JSON-RPC errors for common failure cases:
  • 客户端不支持 roots: -32601 (方法未找到)
  • 内部错误: -32603
示例错误： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

​
安全注意事项

  1. Clients 必须:
    • 仅公开具备适当权限的根目录
    • 验证所有根URI以防止路径遍历
    • 实施恰当的访问控制
    • 监控根权限可访问性
  2. Servers 应当:
    • 处理根节点（roots）不可用的情况
    • 在操作过程中遵从根目录边界限制
    • 验证所有路径是否符合提供的根目录

​
实施指导原则

  1. Clients 应当:
    • 向服务器暴露根目录前提示用户获取同意
    • 为根管理提供清晰的用户界面
    • 对外暴露前验证根目录可访问性
    • 监视根目录变化
  2. Servers 应当:
    • 使用前检查roots能力
    • 优雅处理根列表变化
    • 在操作中遵守根边界
    • 适当地缓存根信息