Roots

Das Model Context Protocol (MCP) bietet einen standardisierten Weg für Clients, Dateisystem-“Roots” für Server bereitzustellen. Roots definieren die Grenzen, wo Server im Dateisystem operieren können, und ermöglichen es ihnen zu verstehen, auf welche Verzeichnisse und Dateien sie Zugriff haben. Server können die Liste der Roots von unterstützenden Clients anfordern und Benachrichtigungen erhalten, wenn sich diese Liste ändert.

Benutzerinteraktionsmodell

Roots in MCP werden typischerweise über Arbeitsbereich- oder Projektkonfigurationsoberflächen bereitgestellt.

Zum Beispiel könnten Implementierungen einen Arbeitsbereich-/Projektauswähler anbieten, der es Benutzern ermöglicht, Verzeichnisse und Dateien auszuwählen, auf die der Server Zugriff haben sollte. Dies kann mit automatischer Arbeitsbereichserkennung von Versionskontrollsystemen oder Projektdateien kombiniert werden.

Implementierungen sind jedoch frei, Roots über jedes Schnittstellenmuster bereitzustellen, das ihren Bedürfnissen entspricht—das Protokoll selbst schreibt kein spezifisches Benutzerinteraktionsmodell vor.

Fähigkeiten

Clients, die Roots unterstützen, MÜSSEN die roots-Fähigkeit während der Initialisierung deklarieren:

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

listChanged indicates whether the client will emit notifications when the list of roots changes.

Protocol Messages

Listing Roots

To retrieve roots, servers send a 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

When roots change, clients that support listChanged MUST send a notification:

{
  "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

A root definition includes:

• uri: Eindeutiger Bezeichner des Root. Dies MUSS in der aktuellen Spezifikation eine file://‑URI sein.
• name: Optionaler, menschenlesbarer Anzeigename.

Example roots for different use cases:

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

Clients SHOULD return standard JSON-RPC errors for common failure cases:

• Client does not support roots: -32601 (Method not found)
• Internal errors: -32603

Example error:

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

Security Considerations

1. Clients MÜSSEN:

   • Roots nur mit angemessenen Berechtigungen freigeben
   • Alle Root‑URIs validieren, um Path Traversal zu verhindern
   • Geeignete Zugriffskontrollen implementieren
   • Erreichbarkeit der Roots überwachen

2. Server SOLLEN:

   • Fälle behandeln, in denen Roots nicht mehr verfügbar sind
   • Root‑Grenzen bei Operationen respektieren
   • Alle Pfade gegen die bereitgestellten Roots validieren

Implementation Guidelines

1. Clients SOLLEN:

   • Nutzer um Zustimmung bitten, bevor Roots gegenüber Servern offengelegt werden
   • Klare Benutzeroberflächen für Root‑Verwaltung bereitstellen
   • Erreichbarkeit der Roots vor Offenlegung validieren
   • Auf Root‑Änderungen überwachen

2. Server SOLLEN:

   • Vor Nutzung auf die Roots‑Fähigkeit prüfen
   • Änderungen der Root‑Liste robust verarbeiten
   • Root‑Grenzen bei Operationen respektieren
   • Root‑Informationen angemessen cachen