規範
規範（2024-11-05）
客戶端功能
根目錄

根目錄

協議版本: 2024-11-05

模型上下文協議（MCP）為客戶端向服務器公開文件系統"根目錄"提供了標準化方式。根目錄定義了服務器可以在文件系統中操作的邊界，使它們瞭解可以訪問哪些目錄和文件。服務器可以從支持的客戶端請求根目錄列表，並在該列表更改時接收通知。

用戶交互模型

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": "我的項目"
      }
    ]
  }
}

根目錄列表變更

當根目錄變更時，支持 listChanged 的客戶端必須發送通知：

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

消息流程 

  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: 更新的根目錄

數據類型

根目錄

根目錄定義包括：

  • uri：根目錄的唯一標識符。在當前規範中，這必須是 file:// URI。
  • name：可選的人類可讀名稱，用於顯示目的。

不同用例的根目錄示例：

項目目錄 

{
  "uri": "file:///home/user/projects/myproject",
  "name": "我的項目"
}

多個倉庫 

[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "前端倉庫"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "後端倉庫"
  }
]

錯誤處理

客戶端應該為常見的失敗情況返回標準 JSON-RPC 錯誤：

  • 客戶端不支持根目錄：-32601（方法未找到）
  • 內部錯誤：-32603

錯誤示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "不支持根目錄",
    "data": {
      "reason": "客戶端沒有根目錄能力"
    }
  }
}

安全考慮

  1. 客戶端必須：

    • 只公開具有適當權限的根目錄
    • 驗證所有根目錄 URI 以防止路徑遍歷
    • 實現適當的訪問控制
    • 監控根目錄可訪問性

  2. 服務器應該：

    • 處理根目錄變得不可用的情況
    • 在操作期間尊重根目錄邊界
    • 根據提供的根目錄驗證所有路徑

實現指南

  1. 客戶端應該：

    • 在向服務器公開根目錄之前提示用戶同意
    • 為根目錄管理提供清晰的用戶界面
    • 在公開之前驗證根目錄可訪問性
    • 監控根目錄變更

  2. 服務器應該：

    • 在使用前檢查根目錄能力
    • 優雅地處理根目錄列表變更
    • 在操作中尊重根目錄邊界
    • 適當緩存根目錄信息
採樣