Der MCP-Dienst

AWR stellt seinen Arbeits-Ledger über MCP (Model Context Protocol) bereit, das Standardprotokoll, mit dem ein Agent-Host — etwa ein Coding-Assistent oder ein Desktop-KI-Client — Tools entdecken und aufrufen kann. Der MCP-Dienst ist die Art, wie dein Agent Projektstatus liest, Kontext kompiliert, Nachweise aufzeichnet und Arbeit voranbringt, ohne selbst zur CLI zu wechseln. Es gibt zwei Arten, ihn zu betreiben:

• stdio — ein lokaler Prozess, den dein Client direkt startet, ein Projekt pro Prozess. Das ist die klassische Einrichtung und bleibt verfügbar.
• Gemeinsames HTTP — ein einzelner Streamable-HTTP-Endpunkt, der mehrere Projekte und mehrere unabhängige Clients bedient. Sowohl das npm- als auch das PyPI-Paket enthalten diese Fähigkeit.

Dieser Artikel konzentriert sich auf den gemeinsamen HTTP-Dienst, den du betreibst, wenn mehr als eine Person oder ein Agent dieselben Projekte braucht. Was Agents mit diesen Tools tun, sobald sie verbunden sind, steht unter Agents. Das menschliche Gegenstück derselben Operationen steht unter Die AWR-CLI.

Wie der gemeinsame Dienst funktioniert

Du initialisierst jedes Projekt auf dem Server mit awr init und registrierst dann seinen kanonischen absoluten Stamm zusammen mit der project_id, die zurückgegeben wird von:

awr --json status

AWR verifiziert diese Identität beim Start und bei jeder Anfrage. Quelldateien und die .awr-Datenbank jedes Projekts bleiben getrennt — der Dienst klont keine Repositories, mountet keine Client-Dateisysteme und mergt keine Projekt-Ledger. Clients brauchen Netzwerkzugang zum Dienst, nicht eine lokale AWR-Ausführbare, und Projektdateien müssen auf dem Server lesbar sein: Ein Pfad auf einem Client-Laptop wird nicht per Fernzugriff lesbar. Es gibt kein gemeinsames „aktuelles Projekt" — jedes Projekt-Tool nimmt ein explizites project-Argument, und es gibt kein Tool zum Öffnen eines beliebigen Serverpfads.

Den Dienst konfigurieren

Erstelle eine TOML-Datei im Besitz des Betreibers außerhalb des öffentlichen Repositorys:

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

Jeder Client-Eintrag nennt eine Umgebungsvariable, die seine Bearer-Zugangsdaten enthält. Verwende unterschiedliche, zufällig generierte Zugangsdaten von mindestens 32 Zeichen. Ein write-Grant schließt Lesezugriff ein; ein read-Grant kann Projekte nicht verändern. Halte Client-IDs über die Rotation von Zugangsdaten hinweg stabil — Konversations- und Anfragebindungen hängen an der Client-ID, und deren Änderung erzeugt einen eigenen Geltungsbereich. Konfigurationsänderungen werden erst nach einem Neustart des Dienstes wirksam.

Den Dienst betreiben

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

Jede HTTP-Anfrage ist authentifiziert. Der eingebaute Mechanismus ist statische Bearer-Authentifizierung — kein OAuth-Autorisierungsserver und kein Enterprise-Identitätsanbieter. Für Fernzugriff terminiere HTTPS an einer authentifizierten Deployment-Grenze und beschränke direkten Zugriff auf das Backend. Zusätzliche Zugriffskontrollen:

• Origins werden abgelehnt, sofern sie nicht ausdrücklich in allowed_origins aufgeführt sind; native Clients lassen den Origin-Header normalerweise weg.
• Das SDK prüft allowed_hosts, mit Loopback-Hosts als Standard, wenn keine konfiguriert sind.
• Der Dienst validiert Origin, implementiert aber keinen Browser-CORS-Preflight — ein Browser-Frontend braucht also ein passendes Gateway.

Auf Unix stoppen SIGTERM und Ctrl-C die Annahme von Anfragen kontrolliert und lassen aktive HTTP-Arbeit auslaufen. Das Trennen eines Clients oder ein Neustart des Dienstes beendet niemals eine AWR-Arbeitssession — Protokollverbindungen und persistente Sessions sind getrennte Identitäten. AWR installiert keinen System-Daemon — nutze den Prozess-Supervisor deines Deployments für Start und Neustart. Für lokale Einzel-Client-Nutzung bleibt der stdio-Befehl:

awr-mcp --project /absolute/project

Einen Client verbinden

Konfiguriere jeden MCP-Client für Streamable HTTP mit derselben Dienst-URL unter dem Pfad /mcp, plus eigene Bearer-Zugangsdaten in einem Authorization: Bearer …-Header, der über den Zugangsdaten-Mechanismus dieses Clients bereitgestellt wird. Rufe nach dem Verbinden awr_projects_list auf, um die Projekt-Keys zu entdecken, für die deine Zugangsdaten berechtigt sind. Jedes Projekt-Tool verlangt dann project:

{"project": "billing", "work": "INVOICE-001"}

Die Tools

Der gemeinsame HTTP-Dienst stellt insgesamt 21 Tools bereit (20 über stdio, wo das Projektlisten-Tool fehlt). Sie fallen in drei Gruppen.

Arbeits- und Kontext-Tools

Diese spiegeln die alltäglichen CLI-Aktionen:

Session- und Fortsetzungs-Tools

Sessions binden eine Konversation an eine Arbeitseinheit. Gib einen stabilen conversation-Bezeichner von deinem Host an — keinen HTTP-Verbindungsbezeichner. Derselbe Konversations-String unter einem anderen Projekt oder Client ist eine separate Bindung.

Eine ausstehende Wartefrage blockiert Arbeitsübergänge und Resume, bis der Host eine Antwort aufzeichnet. Die Antwort hebt diese Blockade auf, ändert aber weder den Arbeitsstatus noch plant sie den nächsten Turn des Hosts — dein Host untersucht die Session, kompiliert frischen Kontext und entscheidet, ob er fortsetzt oder einen Nachfolger erstellt.

Schreibvorgänge, Revisionen und unsichere Ergebnisse

Jeder gemeinsame HTTP-Schreibvorgang erfordert zwei Dinge:

• eine client-generierte, stabile request_id (bis zu 256 Bytes),
• die zuletzt beobachtete expected_revision.

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

Das exakte Wiederholen derselben Request-ID und Argumente gibt das aufgezeichnete Ergebnis zurück, ohne die Aktion erneut auszuführen — ein erneuter Versuch nach einem Timeout ist also sicher. Geänderte Argumente erfordern eine neue ID. Speichere die zurückgegebene project_revision für deinen nächsten Schreibvorgang, und berechne die nächste Revision niemals durch Addieren von eins: Das Request-Journal und die Domänenoperation verbrauchen beide Revisionen.

Nach einem Timeout oder Verbindungsabbruch rufe awr_operation_get mit demselben Projekt und derselben Request-ID auf. Eine unvollendete Anfrage meldet write_outcome: unknown; ein unterbrochener Schreibvorgang kann bereits committet sein — schließe daher niemals aus einem geschlossenen HTTP-Antwortstream auf einen Fehlschlag. awr_operation_recover kann ein committetes Ergebnis nur dann aufzeichnen, wenn ein eindeutiges terminales Ereignis an die Anfrage gebunden ist — es ruft das ursprüngliche Tool niemals erneut auf. Lesevorgänge können parallel laufen; Schreibvorgänge werden pro Projekt serialisiert, und verschiedene Projekte haben unabhängige Sperren. Ein veralteter Schreibvorgang liefert einen Konflikt — lies den aktuellen Zustand und überdenke es, bevor du es erneut versuchst.

Workstream-Lesevorgänge (in Entwicklung)

Die Entwicklungsquelle ergänzt eine Registry mit version = 2, die Clients schreibgeschützten Zugriff auf ausdrücklich aufgeführte, unveränderliche Workstreams für Projekte gewährt, die den YAML-Workstream-Ledger verwenden. Diese sind Berechtigungen im Besitz des Betreibers: Projektweite read/write-Grants allein autorisieren keinen isolierten Workstream.

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

Autorisierte Clients nutzen das nur im gemeinsamen Dienst verfügbare Tool awr_workstream und beginnen mit action: "capabilities" und action: "list", um zu entdecken, was sie lesen dürfen. Sei dir der aktuellen Grenzen bewusst: Diese Erweiterung gewährt nur Lesevorgänge — keine Mutationen, Inhaltsdatei-Lesevorgänge oder Team-PostgreSQL-Operationen — und Projekte, die sie aktivieren, lehnen die Legacy-Tools des gemeinsamen Dienstes ab, einschließlich aller Schreibvorgänge, bis eine autorisierte Implementierung verfügbar ist. Aktivierung und Reindizierung sind in dieser Phase lokale Betreiberaktionen.

Wie es weitergeht

• Agents — wie ein Agent Sessions, Claims und Checkpoints über diese Tools nutzt.
• Die AWR-CLI — dieselben Domänenoperationen von der Kommandozeile, für Betreiber und Debugging.
• Fehlerbehebung — Revisionskonflikte, veraltete Quellen und Wiederherstellung.