> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 根目录

<div id="enable-section-numbers" />

<Info>**协议修订版本**: 2025-06-18</Info>

模型上下文协议（MCP）为客户端向服务器暴露文件系统“根目录”提供了标准化方式。根目录定义了服务器在文件系统中可操作的边界，使其能够了解可以访问的目录和文件。服务器可以从支持该功能的客户端请求根目录列表，并在该列表发生变化时接收通知。

## 用户交互模型

在 MCP 中，根目录通常通过工作区或项目配置界面暴露给服务器。

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

但是，实现可以通过任何适合其需求的界面模式暴露根目录——协议本身不强制要求任何特定的用户交互模型。

## 功能

支持根目录的客户端必须在[初始化](/specification/2025-06-18/basic/lifecycle#initialization)期间声明 `roots` 能力：

```json theme={null}
{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}
```

`listChanged` 表示当根目录列表发生变化时，客户端是否会发出通知。

## 协议消息

### 列出根目录

要获取根目录列表，服务器发送一个 `roots/list` 请求：

**请求：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}
```

**响应：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}
```

### 根目录列表变化

当根目录发生变化时，支持 `listChanged` 的客户端必须发送通知：

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}
```

## 消息流程

```mermaid theme={null}
sequenceDiagram
    participant Server
    participant Client

    Note over Server,Client: 发现阶段
    Server->>Client: roots/list
    Client-->>Server: 可用的根目录

    Note over Server,Client: 变更通知
    Client--)Server: notifications/roots/list_changed
    Server->>Client: roots/list
    Client-->>Server: 更新后的根目录
```

## 数据类型

### 根目录（Root）

一个根目录定义包括：

* `uri`：根目录的唯一标识符。在当前规范中，这**必须**是一个 `file://` URI。
* `name`：可选的、用于显示的可读名称。

不同使用场景下的根目录示例：

#### 项目目录

```json theme={null}
{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}
```

#### 多个仓库

```json theme={null}
[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]
```

## 错误处理

客户端应在常见失败情况下返回标准的 JSON-RPC 错误码：

* 客户端不支持根目录：`-32601`（方法未找到）
* 内部错误：`-32603`

示例错误：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "不支持根目录",
    "data": {
      "reason": "客户端不具备根目录能力"
    }
  }
}
```

## 安全考虑

1. 客户端 **必须**：
   * 仅暴露具有适当权限的根目录
   * 验证所有根目录 URI 以防止路径穿越
   * 实施适当的访问控制
   * 监控根目录的可访问性

2. 服务器 **应该**：
   * 处理根目录变得不可用的情况
   * 在操作期间尊重根目录边界
   * 针对提供的根目录验证所有路径

## 实现指南

1. 客户端 **应该**：
   * 在向服务器暴露根目录前提示用户确认
   * 提供清晰的用户界面用于管理根目录
   * 在暴露根目录前验证其可访问性
   * 监控根目录的变化

2. 服务器 **应该**：
   * 在使用前检查客户端是否支持根目录能力
   * 优雅地处理根目录列表变化
   * 在操作中尊重根目录边界
   * 合理缓存根目录信息