Roots

Documentation Index

完全なドキュメント索引を取得してください: modelcontextprotocol.io/llms.txt

さらに先へ進む前に、利用可能なすべてのページを把握するために、このファイルを使用してください。

The Model Context Protocol (MCP) は、client が filesystem の "root" を server に公開するための標準化された方法を提供します。root は、server が filesystem 内のどこで動作できるかの境界を定義し、どの directory や file にアクセスできるかを理解できるようにします。server は、対応する client に root の一覧を要求でき、その一覧が変更されたときには notification を受け取れます。

User Interaction Model

MCP における root は、通常、workspace または project の設定インターフェイスを通じて公開されます。

たとえば実装は、server がアクセスできるようにする directory や file をユーザーが選択できる workspace/project picker を提供できます。これは、version control system や project file からの自動的な workspace 検出と組み合わせることもできます。

ただし、実装は自身の要件に合う任意のインターフェイスパターンで root を公開して構いません。プロトコル自体は、特定のユーザーインタラクションモデルを義務付けていません。

Capabilities

root をサポートする client は、初期化時に roots capability を宣言しなければなりません (MUST)。

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

listChanged は、root の一覧が変更されたときに client が notification を発行するかどうかを示します。

Protocol Messages

Listing Roots

root を取得するために、server は roots/list request を送信します。

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

Response:

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

Root List Changes

root が変更されたとき、listChanged をサポートする client は notification を送信しなければなりません (MUST)。

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

Message Flow

sequenceDiagram participant Server participant Client Note over Server,Client: Discovery Server->>Client: roots/list Client-->>Server: Available roots Note over Server,Client: Changes Client--)Server: notifications/roots/list_changed Server->>Client: roots/list Client-->>Server: Updated roots

Data Types

Root

root 定義には次が含まれます。

uri: root の一意な識別子。現行の specification では、これは file:// URI でなければなりません (MUST)
name: 表示目的の、人が読める任意の名前

異なるユースケースに対する root の例:

Project Directory

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

Multiple Repositories

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

Error Handling

client は、一般的な失敗ケースに対して標準の JSON-RPC error を返すべきです (SHOULD)。

client が root をサポートしていない: -32601（Method not found）
内部 error: -32603

error の例:

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

Security Considerations

client は次を満たさなければなりません (MUST)。
- 適切な権限を持つ root だけを公開する
- path traversal を防ぐため、すべての root URI を検証する
- 適切な access control を実装する
- root の可用性を監視する
server は次を行うべきです (SHOULD)。
- root が利用不能になるケースを扱う
- 操作中は root の境界を尊重する
- 提供された root に照らして、すべての path を検証する

Implementation Guidelines

client は次を行うべきです (SHOULD)。
- root を server に公開する前に、ユーザーの同意を求める
- root 管理のための明確なユーザーインターフェイスを提供する
- 公開前に root の可用性を検証する
- root の変更を監視する
server は次を行うべきです (SHOULD)。
- 使用前に roots capability を確認する
- root 一覧の変更を適切に扱う
- 操作において root の境界を尊重する
- root 情報を適切にキャッシュする