1. 什么是根？ #

根（Roots）定义了 MCP 服务器在文件系统中的操作边界。客户端向服务器暴露「可访问的目录」，服务器据此知道能读写哪些路径。

协议版本：2025-11-25

2. 本章你将学到 #

• 根的作用与用户交互方式
• 能力声明与协议消息
• 根的数据结构（URI、name）
• 错误处理、安全与实现建议

3. 典型场景 #

用户用 VS Code 打开项目 ~/projects/myapp，并连接文件系统 MCP 服务器。VS Code（客户端）将 file:///home/user/projects/myapp 作为根暴露给服务器，服务器只能在该目录及其子目录内读写文件。

4. 能力 #

客户端必须在初始化时声明 roots 能力：

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

5. 协议消息 #

5.1 列出根（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"
      }
    ]
  }
}

5.2 根列表变更通知 #

当根列表变化时（如用户切换工作区），客户端发送：

{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

服务器收到后应重新调用 roots/list 获取更新后的列表。

6. 流程示意 #

7. 数据结构 #

每个根包含：

示例：单项目

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

示例：多仓库

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

8. 错误处理 #

示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": { "reason": "Client does not have roots capability" }
  }
}

9. 安全与实现 #

9.1 客户端 #

9.2 服务器 #