werkbaum/docs/rfc/001-mcp-server.md

RFC 001 — MCP-Server: Werkbaum für KI-Agenten außerhalb des Editors

Status	Abgestimmt (drei Runden am 2026-09-02, Entscheidungen in §11 und D93) — nichts gebaut
Plan-Knoten	#ai.mcp in docs/examples/werkbaum.werkbaum
Entscheidung	D93 in docs/DECISIONS.md
Berührt	Backend (de.werkbaum.integration.mcp, Security, Build), frontend/src/* (headless-Module: eine Verschiebung, drei neue Dateien), tools/pull-doc, README, .mcp.json
Berührt nicht	Notation (SPEC), llms.md, frontend/src/app.js im Verhalten, Deploy-Skripte außer einer Umgebungszeile
Neue Technologie	keine — die JVM bleibt die einzige Laufzeit (§6, Runde 3)

1. Zusammenfassung

Werkbaum bekommt einen MCP-Server (Model Context Protocol) im Backend: Unter /api/v1/mcp bietet die Spring-Boot-Anwendung KI-Agenten außerhalb des Editors — Claude Code, OpenCode, Codex, IDE-Agenten, gehostete Agenten — einen Werkbaum-Plan als Ressource (Text) und als Werkzeuge (Baum, Warnungen, günstigster Pfad, Knoten-Verben, Schreiben) an, über Streamable HTTP mit einem Bearer-Token.

Das Backend parst nicht selbst: Es führt die headless-Module des Frontends (parser.js, model.js, live.js und drei neue) unverändert in der JVM aus — per GraalJS, gebündelt beim Bauen. Damit bleibt D14 gewahrt (genau ein Parser), und ein Agent bekommt wörtlich dieselben Warnungen, effektiven Status und Stationen, die das Diagramm zeigt.

Zwei Arten von Plänen, ein Satz Werkzeuge: Server-Dokumente bearbeiten die Tools direkt — als Zeilen-Diff gegen Basisversion und Prüfsumme (D76), Konflikte werden abgelehnt, jede Änderung steht in der Historie mit dem Namen des Agenten. Lokale .werkbaum-Dateien liest und schreibt der Agent mit seinen eigenen Werkzeugen und reicht den Text an dieselben Tools — zur Analyse, zur Prüfung und für die Knoten-Verben, die dann Text zurückgeben. Es gibt keinen lokalen Prozess und keine neue Laufzeit: kein Node-Paket, nichts zu installieren beim Entwickler, nur eine URL und ein Token in der Host-Konfiguration.

Zwei Leitplanken: keine beschädigte Notation und kein [^] von einem Agenten — auf Server-Dokumenten als Sperre, auf Text als Prüfergebnis. Der Git-Spiegel eines geteilten Plans ist das vorhandene tools/pull-doc --git-commit (D88), das künftig nennt, wer welche Version geändert hat — vom Cron oder vom Agenten selbst aufgerufen.

Das ist die Gegenrichtung zu #ai.dialog: Dort käme ein Modell in den Editor, hier geht der Plan zu Agenten, die schon irgendwo laufen. Beides teilt sich den Boden (llms.md, D43) und dieselben Module — die drei neuen Dateien in frontend/src sind genau die, die #ai.dialog später auch braucht.

2. Motivation

Die Beweggründe, wie sie in Runde 3 benannt wurden (§11): Ein oder mehrere Entwickler arbeiten parallel an geteilten Werkbaum-Plänen und setzen dabei agentische KI ein — vor allem, um einen Plan im Dialog zu erstellen und den Feature-Fortschritt zu tracken. Der Agent läuft meist lokal beim Entwickler (OpenCode, Claude Code, Codex); später soll ein Agent auch in das Werkbaum-Frontend kommen (#ai.dialog). Die Pläne liegen beides: als Datei neben dem Code und als geteiltes Server-Dokument.

Heute kann ein Agent damit dreierlei tun — und alles davon nur halb:

1. Eine .werkbaum-Datei lesen und schreiben. Das geht mit Claude Code bereits, llms.md erklärt die Notation (D43). Aber der Agent muss die Semantik selbst nachrechnen: Ist der Plan warnungsfrei? Welcher Knoten ist effektiv wie weit (§4)? Was ist die nächste Station auf dem günstigsten Pfad (§9)? Für all das gibt es im Frontend geprüfte Funktionen — der Agent bekommt sie nicht zu sehen und rät. Beim Größen-Konflikt (D62) oder der Closure-Rechnung (D42) ist Raten nachweislich falsch.
2. Ein Server-Dokument (?live=) anfassen. Nur per curl gegen die REST-API — mit Volltext-PUT, also ohne das Zeilen-Diff-Protokoll (D76). Ein Agent, der so schreibt, überschreibt, was ein Mensch in der Zwischenzeit getippt hat; genau der Verlust, gegen den D89 vier Netze gespannt hat.
3. Den Plan im Editor ändern lassen — #ai.dialog ist eine Idee ohne Entwurf.

MCP ist inzwischen die Verkehrssprache dafür: Claude Code, OpenCode, Codex, Claude Desktop, IDE-Agenten und die Anthropic-API selbst (MCP-Connector) sprechen es. Ein Server, der Werkbaum darüber anbietet, macht Punkt 1 und 2 richtig — für alle diese Hosts, nicht nur für einen.

3. Ziele und Nicht-Ziele

Ziele

• Ein Agent kann einen Plan lesen (Server-Dokument per Ressource; eine Datei liest er selbst) und den Notationsleitfaden dazu bekommen.
• Ein Agent kann einen Plan befragen, ohne die SPEC nachzuimplementieren: Baum mit allem, was das Diagramm weiß; Warnungen; günstigster Pfad samt Stationen und Personen-Last — für einen Text wie für ein Dokument.
• Ein Agent kann einen Plan ändern, ohne fremde Arbeit zu überschreiben; jede Änderung an einem Dokument ist als Agenten-Änderung erkennbar.
• Kein zweiter Parser, keine zweite Semantik (D14). Keine neue Laufzeit (D93-Nachtrag, CLAUDE.md).
• Kein Geheimnis läuft durch den Server, das er nicht braucht.

Nicht-Ziele (Abgrenzung — wird nicht gebaut, siehe §9)

• Kein LLM im Server. Der Server ruft kein Modell auf und kennt keinen API-Schlüssel. Das Modell sitzt im Host; #ai.key bleibt ein eigener Knoten.
• Keine neue Notation. Nichts an SPEC oder llms.md ändert sich.
• Kein lokaler Prozess. Kein Node-Paket, kein stdio-Server, kein Jar-Aufruf beim Entwickler (§6).
• Kein Taiga über MCP in der ersten Fassung (§9).
• Keine Rechteverwaltung — ein Token je Installation; das Dokument-Zugriffsmodell (unerratbare UUID, D76) bleibt.
• Kein Ersatz für #ai.dialog und kein Chat im Editor.

4. Begriffe (soweit hier nötig)

MCP trennt Hosts (die Anwendung mit dem Modell) von Servern (Prozesse oder Endpunkte, die Fähigkeiten anbieten). Ein Server bietet drei Dinge an:

• Resources — lesbare Inhalte mit URI, vom Host in den Kontext geholt („zeig mir den Plan“).
• Tools — aufrufbare Funktionen mit JSON-Schema, die das Modell selbst wählt („prüfe den Plan“, „setze den Status“).
• Prompts — vorgefertigte Anweisungen, die der Nutzer auswählt („zerlege diesen Knoten“).

Transporte: stdio (der Host startet den Server als Kindprozess) und Streamable HTTP (ein Netzwerk-Endpunkt; hat 2025 das ältere SSE-Verfahren abgelöst). MCP verlangt keine bestimmte Sprache — es gibt offizielle SDKs für TypeScript, Python, Kotlin, Java, C#; Werkbaum nimmt den Spring-AI-Starter für Java (§11). Die Protokollrevision trägt das SDK; dieses RFC legt keine fest.

5. Vorschlag

5.1 Architektur

 Host beim Entwickler                          Werkbaum-Backend (Spring Boot, JDK 21)
 (Claude Code, OpenCode, Codex, …)             ┌───────────────────────────────────────┐
 ┌──────────────┐  Streamable HTTP + Bearer    │ /api/v1/mcp                           │
 │  Modell      │◄────────────────────────────►│  de.werkbaum.integration.mcp          │
 │  + Werkzeuge │  (Apache reicht /api/ durch) │   ├─ resources  (Guide, Dokumente)    │
 │  + eigene    │                              │   ├─ tools      (inspect, check,      │
 │    Datei-    │                              │   │              write, verbs)        │
 │    Zugriffe  │                              │   └─ WerkbaumCore: GraalJS-Kontext    │
 └──────────────┘                              │        führt werkbaum-core.mjs aus —  │
        │ liest/schreibt                       │        das Bündel aus frontend/src:   │
        ▼ .werkbaum-Dateien selbst             │        parser · model · live ·        │
   Repo des Entwicklers                        │        inspect · guard · edit         │
   (Git-Spiegel: tools/pull-doc)               │  DocumentService / LiveEditingService │
                                               └───────────────────────────────────────┘

Es gibt einen Dienst und ein Artefakt: das Backend-Jar. Neu darin sind ein Paket, ein Bearer-Filter und ein gebündeltes JS-Modul als Ressource. Alles Entscheidbare kommt aus frontend/src; Kotlin ist Transport, Zugang, Ablage und die Brücke in die JVM.

5.2 Zwei Formen je Werkzeug: Text und Dokument

Weil es keinen lokalen Prozess gibt, unterscheidet der Server nicht nach Ablage, sondern nach Eingabeform. Jedes Werkzeug nimmt entweder text (der Agent hat die Datei selbst gelesen) oder document (die UUID eines Dokuments dieses Backends):

Form	Lesen	Ergebnis eines Schreib-Werkzeugs	Leitplanken (§5.5)
text	der Agent liefert den Text mit	der neue Text samt Prüfergebnis — der Agent schreibt ihn selbst in die Datei	Prüfergebnis: findings mit blocking: true/false; der Text wird trotzdem zurückgegeben
document	DocumentService	der neue Stand (version, checksum) — geschrieben per PATCH /content-Weg (D76)	Sperre: blockierende Befunde ⇒ nicht geschrieben

document ist eine UUID, keine URL: Der Server fasst nur seine eigenen Dokumente an. Fremde Backends gibt es für ihn nicht — das nimmt die SSRF-Frage aus dem Entwurf, bevor sie gestellt ist, und ein Agent, der mit zwei Werkbaum-Servern arbeitet, konfiguriert zwei MCP-Server.

Der ?live=-Link, den Menschen weitergeben, enthält die UUID; ein Agent bekommt sie vom Menschen oder aus der Ressourcen-Liste (§5.3).

5.3 Resources

URI	Inhalt	MIME
werkbaum://guide	llms.md — der Notationsleitfaden (D43)	text/markdown
werkbaum://doc/<uuid>	Notationstext des Dokuments; version und checksum als Metadaten	text/plain

Die Ressourcen-Liste nennt die Dokumente dieses Backends mit Titel und UUID — für den Agenten, der fragt „welche Pläne gibt es hier?“. Das ist dieselbe Auskunft wie GET /documents, die heute hinter dem Master-Passwort steht (D76-Nachtrag 6), und sie steht hier hinter dem Bearer-Token (§5.6): Wer das Token hat, ist Entwickler dieser Installation, nicht ein Fremder mit einer erratenen Adresse. Das Master-Passwort selbst geht nie über MCP.

Resources sind bewusst nur der Text: Er ist das führende Format (D14), und ein Agent, der ihn im Kontext hat, kann mit llms.md schon alles lesen. Die Semantik kommt aus den Tools.

5.4 Tools

Wenige Verben, sprechend benannt; jedes nimmt text oder document (§5.2), die Dokument-Form beim Schreiben zusätzlich base ({version, checksum} vom letzten Lesen — Pflicht):

Tool	Eingabe	Ausgabe	Nutzt
werkbaum_read	document	Text, version, checksum, Zeilenzahl	DocumentService
werkbaum_inspect	text|document, optional id (Teilbaum), include: [tree, warnings, path]	JSON: Baum je Knoten mit id, label, line, gate, optional, status, effectiveStatus, size, assumedSize, tags, deps, desc, taigaSlug, ticketRef; Warnungen als {type, line, …} plus englischer Klartext; Pfad als nötige Knoten, Stationen in Dokumentreihenfolge, assigneeLoads, overloadedAssignee, exact (D42)	parse, effectiveStatus, computeCheapPlan, assigneeLoads, taigaSlugs, warningText; inspect.js
werkbaum_check	text|document, optional against (Vorher-Text)	findings: Warnungs-Delta und Leitplanken-Befunde mit blocking — das, was ein Schreib-Werkzeug prüfen würde, als Auskunft. Für Agenten, die eine Datei gleich selbst schreiben	guard.js
werkbaum_set_status	…, id, status (Code der §4-Tabelle)	Text-Form: neuer Text + findings; Dokument-Form: neuer Stand + findings	setStatusBox (parser.js)
werkbaum_apply_ops	…, ops[] (insert/replace/delete mit index, count, lines — dasselbe Schema wie LineOperation der API)	wie oben	applyOps (live.js)
werkbaum_write	…, newText (Volltext)	wie oben; Dokument-Form: Diff per computeOps	computeOps (live.js)
werkbaum_add_node	…, parent (ID), line (Knotenzeile ohne Einrückung), optional after (Geschwister-ID)	wie oben	addNodeLine (edit.js)
werkbaum_move_node	…, id, parent, optional after	wie oben; Teilbaum samt Beschreibungs- und Fortsetzungszeilen wandert mit, Einrückung wird angepasst	moveSubtree (edit.js)
werkbaum_set_size	…, id, size (XS…XXL oder null)	wie oben	setSizeToken (edit.js)
werkbaum_remove_node	…, id, discard: true|false	wie oben — discard setzt [-] (§4), false löscht den Teilbaum samt Blöcken	setStatusBox bzw. removeSubtree (edit.js)

Die Knoten-Verben (Runde 1, §11) sind Bequemlichkeit für das Modell: apply_ops könnte jedes davon ausdrücken, aber ein Agent, der Zeilenindizes ausrechnet, verrechnet sich — ein Verb mit ID ist die robustere Schnittstelle. Damit dabei keine zweite Stelle mit Zeilenformat-Wissen entsteht, liegen die Text→Text-Regeln als frontend/src/edit.js neben setStatusBox/setFoldMark (parser.js) und appendToken (taiga.js) — headless, getestet, und für #ai.dialog schon da (§7.1). Kotlin verdrahtet sie nur.

Warnungen tragen Typ und Text. Der Typ (sizeConflict, unknownDep, …) ist für den Agenten das Verlässliche; der englische Text kommt dazu, weil das Modell ihn ohne Nachschlagen versteht. Die Texte sind die Editor-Texte (warningText, D33-Nachtrag) in Englisch — nicht nacherzählt (§7.1).

5.5 Leitplanken

Auf jedem Schreib-Werkzeug, vor dem Schreiben (Dokument) bzw. als Befund (Text):

1. Keine beschädigte Notation. Der Ergebnis-Text wird geparst; trägt er Struktur-Warnungen, die der Ausgangstext nicht hatte — mixedGate, unknownStatus, descStray, duplicateId —, ist das blockierend: Ein Dokument wird nicht geschrieben, die Antwort nennt sie; ein Text kommt mit blocking: true zurück. Das sind die Warnungen, bei denen der Parser eine Zeile anders liest, als sie gemeint war. Schalter allowWarnings: true je Aufruf erlaubt es ausdrücklich. Inhaltliche Widersprüche — sizeConflict, assigneeOverload, xorConflict, unknownDep, unknownDesc — werden geschrieben und gemeldet: Ein Agent arbeitet in Zwischenschritten (das Ziel einer Abhängigkeit entsteht oft erst im nächsten Zug), und im Diagramm sieht ein Mensch sie als bernsteinfarbene Marke — wie bei einer eigenen Änderung (Runde 1; die strengere Fassung war der Vorschlag). Verschwindende Warnungen sind immer erlaubt, jede Antwort trägt das Warnungs-Delta.
2. Kein [^] von einem Agenten. in Produktion ist die Aussage eines Deploys (D30), nicht die eines Modells. Blockierend wie oben; Schalter allowProd: true je Aufruf — ausdrücklich, nie still.
3. Konflikt ist ein Fehler, keine Entscheidung. Bei veralteter base (Dokument) kommt der aktuelle Text mit zurück; der Agent — und im Zweifel der Mensch hinter ihm — entscheidet. Der Server rebased nichts über das hinaus, was der LiveEditingService ohnehin tut (D76: nicht überlappende Ops verschiebt er; das bleibt). Für Dateien gilt dasselbe auf der Seite des Agenten: Er hat den Text gelesen und schreibt ihn selbst — werkbaum_check mit against sagt ihm vorher, ob sein Ergebnis Befunde hat.

Der Preis der Text-Form ist benannt und war Teil der Entscheidung (Runde 3): Bei Dateien ist die Leitplanke Auskunft, keine Sperre. Ein Agent, der blocking: true ignoriert und die Datei trotzdem schreibt, hat den Fehler dann wenigstens im Transkript stehen — und der nächste inspect meldet ihn wieder.

5.6 Zugang und Identität

Zugang: ein statisches Bearer-Token je Installation (WERKBAUM_MCP_TOKEN, in der Umgebungsdatei des Dienstes wie das Master-Passwort, D77), geprüft von einem Spring-Security-Filter für /api/v1/mcp/**; ohne Token 401. Hosts geben es als Header mit (Claude Code: claude mcp add --transport http werkbaum <url> --header "Authorization: Bearer …"; der API-MCP-Connector: authorization_token). Das Token reist über HTTPS in der Host-Konfiguration, nie im Transkript. OAuth 2.1, das die MCP-Spezifikation für HTTP vorsieht, kommt, sobald es einen Identity Provider gibt — die Taiga-Instanz wechselt auf OIDC (D91-Nachtrag 1), das wäre der naheliegende Anker; ohne einen Authorization Server wäre OAuth ein Bau weit über den Anlass hinaus (Runde 2). Ohne konfiguriertes Token ist der Endpunkt gesperrt, nicht offen — dieselbe Voreinstellung wie beim Master-Passwort (D76-Nachtrag 6), und GET /info meldet mcp: false.

Identität: Jeder Schreibvorgang an ein Dokument geht mit clientId mcp-<sitzung> (laufende seq je Sitzung, D76-Nachtrag 7) und einem displayName, der den Host nennt — den Namen aus dem MCP-Handshake (clientInfo.name, etwa „Claude Code“), Rückfall „Agent“ (Runde 1). In jedem offenen Editor steht damit „geändert von: Claude Code“ (D86); der Name bleibt eine Behauptung, kein Nachweis — wie beim Anzeigenamen eines Menschen. Das Token ist zugleich die Schicht, über die später das Owner-Passwort (#col.live.owner) kommt: je Dokument eine Zuordnung in der Umgebung des Dienstes, nie als Tool-Parameter.

5.7 Geteiltes Dokument und Git — beides zugleich

Ein Agent soll auf dem geteilten Dokument arbeiten (dort sitzen die Menschen, dort greift das Konfliktprotokoll), und derselbe Plan soll unter Git-Kontrolle stehen (Diff, Blame, Review, ein Netz außerhalb des Servers — D89). Die Antwort ist eine Richtung: Der Server ist die Quelle, Git ist das Archiv.

Der Weg dafür existiert: tools/pull-doc --git-commit (D88, #col.git.pull) holt ein Server-Dokument in ein Worktree und committet es datiert, nur bei Änderung. Zwei Aufrufer:

• Der Cron auf dem Server-Host oder beim Entwickler — archiviert alle Änderungen, egal von wem.
• Der Agent selbst, nach seinem Schreibvorgang: Er läuft lokal beim Entwickler und hat eine Shell; pull-doc --git-commit --with-history <uuid> <datei> ist ein Befehl wie jeder andere. Ohne lokalen MCP-Prozess (Runde 3) ist das der Weg, den Spiegel sofort nach der eigenen Änderung zu ziehen; der Cron fängt den Rest. Das Prompt werkbaum/decompose (§5.8) endet mit genau diesem Hinweis.

Wer steht im Commit? Ein Spiegel-Commit enthält den ganzen Serverstand — die Zeilen des Agenten und alles, was Menschen seit dem letzten Commit geändert haben. Die Form der Urheber-Angabe entscheidet, ob git blame später lügt:

Form	Aussage	Preis
a) git commit --author="Claude Code <…>"	Der Agent ist Git-Autor — blame schreibt ihm jede Zeile darin zu, auch die, die Anna getippt hat	Falsche Blame-Auskunft; Git verlangt eine E-Mail-Adresse, die es nicht gibt
b) Co-Authored-By:-Trailer	Die Repo-Konvention für Claude-Commits: „hat beigetragen“, ohne Autor zu sein	Braucht ebenfalls Name <email>; für Menschen aus der Server-Historie gibt es nur den Anzeigenamen
c) Freitext im Betreff (… (Version 8, via Claude Code))	Lesbar im git log --oneline	Nicht maschinenlesbar; nennt nur den Auslöser
d) Historie im Rumpf + eigene Trailer	Der Rumpf listet aus GET /history, wer welche Version seit dem letzten Spiegel-Commit geändert hat („v7 Anna · v8 Claude Code“); je Beteiligtem Werkbaum-Changed-By: <Anzeigename>, dazu Werkbaum-Version: 8	Ein zweiter GET je Commit; eigene Trailer statt der GitHub-Konvention

Entschieden (Runde 2): d, mit c im Betreff. Git-Autor bleibt, wer den Prozess betreibt (buchstäblich richtig — er hat committet), die Beteiligten stehen mit Namen im Rumpf, maschinenlesbar per git interpret-trailers, und Werkbaum-Version: gibt pull-doc beim nächsten Lauf die Untergrenze für „seit dem letzten Commit“. Der Cron-Commit wird damit im selben Zug ehrlicher. Der Schalter (--with-history) kommt ins Skript (D77-Nachtrag). Die Anzeigenamen bleiben Behauptungen (D86) — deshalb „Changed-By“, nicht „Author“.

5.8 Prompts (optional, Phase 5)

Zwei vorgefertigte Anweisungen, die ein Host dem Nutzer anbietet:

• werkbaum/review — „Prüfe diesen Plan: Warnungen, Größen, fehlende Zerlegung ab M, unklare Zuständigkeiten“ (nutzt inspect, schreibt nichts).
• werkbaum/decompose — „Zerlege Knoten #id in Teilpakete mit Größen“ (endet in den Verben, mit den Leitplanken; bei einem Dokument mit dem Hinweis auf pull-doc).

Beides sind Texte, keine Logik; sie leben im Backend-Paket und nicht in llms.md (das bleibt Notation, D43).

5.9 Konfiguration

Serverseitig (Umgebungsdatei des Dienstes, D77):

• WERKBAUM_MCP_TOKEN — das Bearer-Token; fehlt es, ist der Endpunkt gesperrt.
• Kein weiterer Schalter: Es gibt keine Dateiwurzeln (kein Dateizugriff), keinen Spiegel (§5.7 läuft beim Aufrufer), keine Fremdserver (§5.2).

Beim Entwickler: die URL und das Token in der Host-Konfiguration. Im Repository liegt eine .mcp.json, die auf ${WERKBAUM_MCP_URL} und ${WERKBAUM_MCP_TOKEN} aus der Umgebung zeigt — damit Claude Code hier den Server von selbst hat, gegen die stabile Instanz oder gegen ein lokal gestartetes Backend (./gradlew bootRun; der Entwickler-Rechner hat das JDK ohnehin). Der Plan docs/examples/werkbaum.werkbaum ist damit das erste Dokument, an dem der Server benutzt wird (Dogfooding, D27).

5.10 Die JVM führt die JS-Module aus

Der Kern der Entscheidung (Runden 2 und 3): Das Backend braucht die Werkbaum-Logik, darf sie nicht nachbauen (D14) und soll keine zweite Laufzeit neben sich haben. Also führt es die Module selbst aus — dieselbe Technik, die der Plan für das IDE-Plugin vorsieht (#idea.drift.js: „den einen JS-Parser im IDE laufen lassen“).

• GraalJS (org.graalvm.polyglot:polyglot + js-community) läuft auf dem Stock-OpenJDK 21 der Zielumgebung (D77) im Interpreter-Modus — ohne Graal-Compiler langsamer, aber ein Plan hat Dutzende Kilobyte, keine Megabyte; zu messen, nicht anzunehmen.
• Gebündelt beim Bauen: Gradle ruft das vorhandene Frontend-Tooling (esbuild, das Vite mitbringt) und bündelt frontend/src/inspect.js samt allem, was es importiert, zu einem ES-Modul werkbaum-core.mjs in den Jar-Ressourcen. So braucht GraalJS keine Import-Auflösung und kein virtuelles Dateisystem; Node bleibt, was es ist — Build-Werkzeug, nie Laufzeit. Der Build bricht, wenn das Bündel fehlt: dieselbe Zusage wie bei der OpenAPI-Generierung.
• Was in der JVM anders ist: crypto.subtle (die Prüfsumme in live.js) gibt es in GraalJS nicht — die Prüfsumme rechnet Kotlin (MessageDigest), checksum() wird dort nicht aufgerufen; alles übrige (TextEncoder, Map, Set, Unicode-Regex) ist ECMAScript und vorhanden. Ein Polyglot-Context ist nicht nebenläufig: ein kleiner Pool von Kontexten mit gecachter Source, je Aufruf einer — die Kosten je Kontext (Speicher, Aufbauzeit) sind Teil des Spikes.
• Der Spike vor Phase 1 misst: Laufen parser.js, model.js, live.js, inspect.js, guard.js, edit.js als Bündel in GraalJS und liefern für den mitgelieferten Plan dieselben Zahlen wie Vitest (231 Knoten, 0 Warnungen, Stationen)? Was kostet ein Kontext an RSS auf der Zielumgebung (D76-Nachtrag 3: rund 300 MB frei)? Reicht der Apache den SSE-Strom langer Werkzeugaufrufe ungepuffert durch (Long Polling ist gemessen, D76-Nachtrag 2 — ein Strom nicht)? Die Ergebnisse gehören als Nachtrag zu D93. Fällt der Spike durch, ist die Antwort nicht Node, sondern eine neue Frage an den Entwickler (CLAUDE.md-Regel).

6. Alternativen

A — Kotlin-Server mit eigenem Parser

Pro: keine JS-Ausführung in der JVM. Contra: genau die zweite Grammatik, die D14 verbietet — und die Drift-Frage, die #idea.drift für das IDE-Plugin schon stellt. Verworfen (#ai.mcp.kotlin als [-]).

B — Node-Paket, das die Frontend-Module importiert (Entwurf der Runden 1–2)

Pro: ein Parser; stdio ist der Transport, den alle lokalen Hosts können; Dateien und Git-Spiegel direkt am Prozess. Contra: Node.js würde Laufzeit — beim Entwickler als Paket, auf dem Server als zweiter Dienst. Bisher ist Node im Repo Build-Werkzeug. Runde 3 hat das als das erkannt, was es ist: die Einführung einer Technologie, eine Dimension schwerer als eine Abhängigkeit (CLAUDE.md, D93-Nachtrag). Und die Beweggründe brauchten es nicht: Der Text darf zum eigenen Server. Verworfen (#ai.mcp.node als [-]); die Tool-Schicht, die dafür geplant war, wandert unverändert nach frontend/src.

C — Das Backend-Jar als lokaler stdio-Server (java -jar … --mcp-stdio)

Pro: keine neue Laufzeit, Dateien und Spiegel lokal. Contra: verlangt ein JDK beim Entwickler und startet in Sekunden; und sobald der Text ohnehin zum Server darf, ist der lokale Prozess ohne Anlass. Nicht gewählt, bleibt als Rückfall benannt, falls die Text-Form sich als unpraktisch erweist — sie kostete dann keinen Technologie-Wechsel.

D — Nur im Backend, Text-Form für Dateien (gewählt)

Pro: eine Laufzeit, ein Artefakt, ein Deployment; die vorhandene Zugangsschicht; nichts zu installieren beim Entwickler; die Module bleiben einmal vorhanden. Contra: Netz auch für lokale Dateien; die Leitplanken sind dort Auskunft statt Sperre; der GraalJS-Spike steht vor allem anderen. Gewählt (Runde 3).

E — Nichts bauen: Agenten lesen llms.md und editieren Dateien

Pro: funktioniert heute mit Claude Code. Contra: keine Semantik, keine Server-Dokumente außer per curl, Schreiben ohne Konfliktschutz — der Ausgangszustand aus §2. Bleibt als Rückfall bestehen — der Server ersetzt llms.md nicht.

F — OpenAPI der REST-API den Agenten geben

Contra: dieselbe Semantik-Lücke wie E, und die Prüfsumme müsste das Modell selbst rechnen. Verworfen.

G — #ai.dialog zuerst (Modell im Editor)

Nicht konkurrierend — D liefert die Module, die G später braucht.

7. Impact auf den bestehenden Code

7.1 frontend/src/ — eine Verschiebung, drei neue Dateien

Datei	Was	Warum
app.js → neu i18n.js	Das I18N-Objekt (ab app.js:3287) in ein headless-Modul verschieben; app.js importiert es.	Der Server braucht warningText(w, t) mit englischem t. Eine Kopie im Backend wäre die Drift, vor der D33-Nachtrag warnt. Reine Verschiebung; der Vite-Bundle bleibt gleich.
neu inspect.js	Baum → JSON (id, label, line, status, effectiveStatus, assumedSize, …), Warnungen → {type, line, text}, Pfad → Stationen und Lasten. Das Einstiegsmodul des Bündels.	Die Sicht für Agenten — und für #ai.dialog. Headless, Vitest-getestet gegen SPEC §10 und den mitgelieferten Plan.
neu guard.js	Leitplanken (§5.5): Warnungs-Delta nach Klasse (strukturell/inhaltlich), [^]-Befund; Text → findings.	Eine Stelle, die weiß, was blockiert.
neu edit.js	Text→Text-Regeln der Knoten-Verben: addNodeLine, moveSubtree, setSizeToken, removeSubtree — zeilenweise, zeichengenau, mit Fortsetzungs- und Beschreibungszeilen (§1), Kommentare bleiben stehen.	Die eine Stelle für „Zeile eines Knotens umbauen“; bewusst nicht in parser.js (Sammelbecken).
parser.js, model.js, live.js, taiga.js, warnings.js, render.js	unverändert	Alles Nötige ist exportiert; render.js ist headless bis zum Aufruf (esc).

Die drei neuen Dateien sind reine ES-Module ohne Browser- und ohne Node-APIs — die Bedingung dafür, dass sie in GraalJS laufen, und ohnehin die Hausregel (D54-Nachtrag 3).

7.2 Backend

Ort	Was
build.gradle.kts	Abhängigkeiten spring-ai-starter-mcp-server-webmvc und org.graalvm.polyglot:polyglot + js-community (Runde 3, Rückfrage gestellt und beantwortet — die Boot-4-Verträglichkeit des Starters ist beim Bauen zu prüfen; fällt sie durch, das MCP-Java-SDK direkt mit seinem WebMVC-Transport). Eine Gradle-Task bundleWerkbaumCore, die per npx esbuild --bundle --format=esm aus frontend/src/inspect.js die Ressource werkbaum-core.mjs erzeugt; processResources hängt davon ab.
neu de.werkbaum.integration.mcp	WerkbaumCore (GraalJS-Kontext-Pool, gecachte Source, Aufrufe inspect/check/edit als Kotlin-Funktionen mit JSON hinein und heraus), McpServerConfiguration (Resources, Tools, Prompts am Starter registriert), McpTools (die Verben aus §5.4, je mit Text- und Dokument-Form; Dokument-Form über DocumentService/LiveEditingService — derselbe Weg wie PATCH /content, mit Prüfsumme aus MessageDigest).
api/SecurityConfiguration.kt	Bearer-Filter für /api/v1/mcp/** gegen werkbaum.mcp.token; ohne Wert denyAll (D76-Nachtrag 6).
api/DocumentsController.kt (getInfo)	mcp: true/false
openapi/api.yaml	ServiceInfo.mcp; der MCP-Endpunkt selbst steht nicht in der OpenAPI — er spricht JSON-RPC, nicht REST, und der Starter trägt seinen Vertrag selbst (dieselbe Grenze wie beim Long-Polling-Endpunkt, D76-Nachtrag 5: was der Generator nicht ausdrücken kann, bleibt draußen — hier ohne Verlust, denn die Tool-Schemata prüft das SDK)
application.yaml	werkbaum.mcp.token: ${WERKBAUM_MCP_TOKEN:}
scripts/deploy-backend.sh	zieht WERKBAUM_MCP_TOKEN aus der .env idempotent in die Server-Umgebung — dieselbe Zeile wie für TAIGA_API_URL (D91-Nachtrag 4)
scripts/prod.htaccess	unverändert — /api/ ist proxied; der SSE-Strom ist zu messen (§5.10)
Tests	WerkbaumCoreTest (Bündel läuft, dieselben Zahlen wie Vitest), Cucumber-Szenarien über einen MCP-Client gegen den laufenden Kontext (Token fehlt ⇒ 401; set_status auf Dokument mit veralteter base ⇒ Konflikt; [^] ⇒ abgelehnt; sizeConflict ⇒ geschrieben und gemeldet)

Perspektivisch berührt: #col.live.owner — das Owner-Passwort kommt über die Umgebung des Dienstes (§5.6), die Endpunkte sind so zu schneiden, dass die Prüfung dazukommt, ohne die Signatur zu brechen (backend/CLAUDE.md).

7.3 Übriges

Ort	Änderung
tools/pull-doc	--with-history (§5.7): holt GET /history, listet im Rumpf, wer welche Version seit dem letzten Spiegel-Commit geändert hat, setzt die Trailer Werkbaum-Changed-By: und Werkbaum-Version:; der Schalter kommt ins Skript, nicht in den Aufrufer (D77-Nachtrag)
.mcp.json (Repo-Wurzel)	HTTP-Server-Eintrag mit URL und Token aus der Umgebung (Dogfooding)
README.md / README.de.md	Abschnitt „Für KI-Agenten: der MCP-Server“ — URL, Token, die zwei Formen, die Leitplanken, pull-doc
frontend/public/llms.txt	ein Link auf den Endpunkt (Wegweiser, D43-Nachtrag 2); llms.md unverändert
docs/CHANGELOG.md	je Phase eine Zeile
tools/remote	unverändert — es ist derselbe Dienst
frontend/package.json	keine neue Abhängigkeit: esbuild bringt Vite mit

8. Sicherheit

• Plan-Text ist Fremddaten. Beschreibungen (----Teil) können Anweisungen enthalten („ignoriere die Leitplanken“). Der Server führt nichts aus, was im Text steht — GraalJS läuft ohne Host-Zugriff (kein HostAccess, kein Dateisystem, kein Netz im Kontext); der Text ist Eingabe einer reinen Funktion. Resources sind als Inhalt deklariert, nie als Anweisung. Der Host trägt die Prompt-Injection-Frage — der Server macht sie nur nicht schlimmer.
• Kein Geheimnis im Transkript. Master-Passwort und Taiga-Token gehen nie über MCP; das Bearer-Token steht in der Host-Konfiguration. Ein späteres Owner-Passwort kommt als Umgebungsvariable (§5.6).
• Kein Dateizugriff, keine Fremdserver. Der Server liest keine Pfade und ruft keine URLs — document ist eine UUID des eigenen Backends (§5.2). Die einzige Netzverbindung des MCP-Endpunkts ist der Aufrufer.
• Rechenkosten gedeckelt: Textgröße je Aufruf begrenzt (dasselbe Limit wie PATCH /content, D76), Kontext-Pool begrenzt, ein Werkzeugaufruf mit Timeout — ein hängender Kontext wird verworfen, nicht wiederverwendet.
• Schreiben nur mit base auf Dokumenten; kein Volltext-PUT. Was der Editor an Netzen hat (Konflikt-Band, Rettungs-Sicherung, D89), hat der Agent in Form des zurückgelieferten aktuellen Textes.

9. Abgrenzung — was ausdrücklich nicht gebaut wird

Nicht gebaut	Warum	Wo es hingehört
Modellaufrufe, API-Schlüssel, Provider-Wahl	Der Host hat das Modell; ein Server mit eigenem Schlüssel wäre #ai.key unter falschem Namen	#ai.key, #ai.dialog
Ein lokaler MCP-Prozess (Node-Paket oder Jar-Modus)	Neue Laufzeit bzw. ohne Anlass, sobald der Text zum Server darf (Runde 3)	#ai.mcp.node ([-]); Jar-Modus als benannter Rückfall (§6 C)
Dateizugriff des Servers	kein Nutzer-Dateisystem am Dienst; ein Pfad über HTTP wäre die Einladung, die §8 verbietet	der Agent liest und schreibt selbst
Fremde Backends per URL	SSRF; ein Server, ein Dokumentenbestand	zwei MCP-Server konfigurieren
Taiga-Tools (Ticket anlegen, Status schreiben)	Braucht das Taiga-Token — das lebt im Browser (D91) und dürfte nicht durch ein Transkript; außerdem eine eigene Entscheidung, ob ein Modell Tickets anlegen darf	eigener Nachtrag: über den vorhandenen Proxy, Token aus der Umgebung
Anlegen/Löschen/Umbenennen von Dokumenten	Verwaltung; wartet auf #col.live.owner	nach dem Owner-Passwort
Falten (fold/unfold) als Verb	Faltmarken sind Darstellung für Menschen (§9); ein Agent liest den ganzen Text	—
Änderungsfeed / Long Polling über MCP	Ein Agent arbeitet in Zügen; read vor jedem Schreiben genügt	—
Git als Quelle (Server folgt dem Repo)	Umkehrung von §5.7; Konfliktmarker mitten in der Notation	#col.git.pr, #col.git.auto
OAuth 2.1	kein Identity Provider; Bearer-Token bis dahin	#ai.mcp.auth, wenn ein IdP da ist
Ein Kotlin-Parser	D14	#ai.mcp.kotlin ([-])

10. Umsetzungsreihenfolge

Jede Phase ist für sich abgeschlossen und bekommt ihre CHANGELOG-Zeile; Plan-Knoten gehen beim Mergen auf [x].

0. Spike (#ai.mcp.spike): GraalJS-Bündel läuft in der JVM, dieselben Zahlen wie Vitest für den mitgelieferten Plan; Speicher je Kontext auf der Zielumgebung gemessen (RSS vorher/nachher, wie in D77); SSE durch den Apache mit einem absichtlich langen Werkzeugaufruf gemessen (wie D76-Nachtrag 2). Ergebnis als D93-Nachtrag. Erst danach wird gebaut.
1. Lesen und befragen (#ai.mcp.core, #ai.mcp.read, #ai.mcp.inspect, #ai.mcp.auth): i18n.js, inspect.js, das Bündel im Jar, WerkbaumCore, Bearer-Filter, Resources, read, inspect, check in beiden Formen. Nachweis: Claude Code liest über die .mcp.json den mitgelieferten Plan und bekommt 231 Knoten, 0 Warnungen, dieselben Stationen wie der Editor; ohne Token 401.
2. Schreiben (#ai.mcp.write, #ai.mcp.guard): guard.js, die drei Basis-Schreib-Werkzeuge in beiden Formen. Nachweis gegen das lokale Backend mit offenem Editor: Agenten-Änderung erscheint mit „Claude Code“ in der Historie; veraltete base ⇒ Fehler mit aktuellem Text, nichts überschrieben; [^] abgelehnt; mixedGate abgelehnt, sizeConflict geschrieben und gemeldet; Text-Form liefert blocking: true und trotzdem den Text.
3. Knoten-Verben (#ai.mcp.verbs): edit.js mit Tests (Gegenprobe per Mutation wie bei setFoldMark), dann die vier Verben. Nachweis: move_node nimmt Beschreibungsblock und Fortsetzungszeilen mit und lässt den Rest zeichengenau stehen.
4. Spiegel (#ai.mcp.mirror): pull-doc --with-history. Nachweis in einem Wegwerf-Worktree: ein Agenten-Zug ergibt genau einen Commit mit Serverstand, Beteiligten im Rumpf und beiden Trailern; ein unveränderter Zug keinen.
5. Prompts (§5.8).

11. Entscheidungen

Drei Multiple-Choice-Runden am 2026-09-02, jede Frage mit der Option „zunächst offen halten“ — keine wurde gewählt.

Runde 1

Frage	Entschieden	Anmerkung
Strenge der Warnungs-Leitplanke (§5.5)	Nur Struktur-Warnungen blockieren	Vorgeschlagen war die strenge Fassung; der Nutzer hat die Zwischenschritte eines Agenten höher gewichtet
displayName (§5.6)	Host-Name aus dem Handshake	Rückfall „Agent“
Geteiltes Dokument und Git (§5.7)	Beides: Server ist Quelle, Git Archiv über pull-doc	Nutzer-Idee, mitten in der Ausarbeitung
Schreib-Tools (§5.4)	Zusätzlich Knoten-Verben	Regeln in frontend/src/edit.js
Verteilung	Nur aus dem Repo	.mcp.json; npm-Frage entfällt mit Runde 3 ohnehin
SDK-Abhängigkeit für das Node-Paket	Ja	überholt durch Runde 3 (kein Node-Paket)
Ort der Baum-Serialisierung	im MCP-Paket	überholt: es gibt kein Paket; sie liegt als frontend/src/inspect.js — dort, wo #ai.dialog sie braucht

Runde 2 (Nutzer: Architektur-Entscheidungen jetzt diskutieren)

Frage	Entschieden	Anmerkung
Urheber im Spiegel-Commit (§5.7)	Historie im Rumpf + Trailer	Werkbaum-Changed-By:, Werkbaum-Version:; Git-Autor bleibt der Betreiber
HTTP: Ort	Im Backend, das die JS-Module per GraalJS ausführt	Die Frage „Kotlin kann das nicht?“ hat den Entwurf korrigiert: MCP braucht kein Node, nur der Parser erzwang es
HTTP: Zugang (§5.6)	Statisches Bearer-Token	OAuth 2.1 erst mit einem IdP
HTTP: Umfang	Nur Dokumente	kein Dateizugriff, kein Spiegel am Dienst

Runde 3 (Nutzer: neue Technologien sind eine Dimension schwerer als Abhängigkeiten; erst die Beweggründe, dann die Entscheidung)

Beweggrund	Antwort
Für wen?	Entwickler, die parallel an geteilten Plänen arbeiten und agentische KI einsetzen — Pläne im Dialog erstellen, Fortschritt tracken; der Agent läuft meist lokal (OpenCode, Claude Code, Codex); später ein Agent im Frontend
Welche Pläne?	Beides: .werkbaum-Dateien im Repo und geteilte Server-Dokumente
Darf der Text eines lokalen Plans zur Analyse an den eigenen Server?	Ja
Startzeit eines lokalen Prozesses?	Egal

Entscheidung	Entschieden	Anmerkung
Node als Laufzeit?	Nein — nur im Backend, Text-Form für Dateien (§5.2)	Alternative C (Jar als stdio) als Rückfall benannt
Backend-Abhängigkeiten	GraalJS + Spring-AI-Starter (spring-ai-starter-mcp-server-webmvc)	Boot-4-Verträglichkeit beim Spike prüfen; Rückfall das MCP-Java-SDK direkt

Weiterhin offen — Messungen und Kleinigkeiten, die sich erst beim Bauen stellen: der Spike (§5.10, Phase 0) mit seinen drei Messungen; die Prompts (§5.8).

12. Revisionsgeschichte

• Runde 1 — Node-Paket mcp/ mit stdio, Dateien und Server-Dokumente als Ablagen; SDK, Leitplanken, Verben, Spiegel entschieden.
• Runde 2 — Urheber im Commit; Streamable HTTP im Backend per GraalJS statt als zweiter Node-Dienst — der Entwurf hatte angenommen, MCP erzwinge Node.
• Runde 3 — Der Nutzer benennt Node als neue Technologie, nicht als Abhängigkeit (CLAUDE.md-Regel, D93-Nachtrag). Aus den Beweggründen folgt: kein lokaler Prozess, alles im Backend, Text-Form für Dateien. Das Node-Paket ist verworfen; seine Tool-Schicht lebt als frontend/src/inspect.js, guard.js, edit.js weiter — unverändert im Zuschnitt, nur ohne eigenes Paket.