Deploymentcenter/docs/AGENTEN_ANBINDEN.md

Ein Projekt und seinen Agenten anbinden

Für dich, nicht für den Agenten. Diese Datei beschreibt, was einmalig je Projekt zu tun ist, damit ein Coding-Agent Bugtracker, Roadmap, MCP-Adapter und die Testwege sinnvoll benutzt.

Der Agent selbst bekommt Textbausteine aus AGENT_PROMPT_TEMPLATE.md — nicht diese Datei.

Reihenfolge einhalten. Jeder Schritt setzt den vorigen voraus.

---

Was ein Agent am Ende können soll

Damit klar ist, worauf die Schritte hinauslaufen — der Ablauf einer Sitzung:

	Der Agent tut	Womit
1	Nachsehen, was ansteht und wer schon dransitzt	dc_roadmap
2	Ein Item exklusiv übernehmen	dc_next_task
3	Prüfen, ob es ein Prüfauftrag ist statt einer Fehlerbehebung	Status am Item
4	Arbeiten, Fortschritt festhalten	dc_comment
5	Was ihm nebenbei auffällt, dort melden, wo die Ursache liegt	dc_report
6	Abschließen oder zurückgeben	dc_resolve / dc_release
7	Ein neues Vorhaben einplanen	dc_report + dc_roadmap_set

Was er nicht tun soll: eine TODO.md anlegen, Status in eine Markdown-Datei schreiben, ein verworfenes Vorhaben erneut vorschlagen, ohne die Begründung gelesen zu haben.

---

1. Werkbank-Token anlegen

Erst nachsehen, ob es schon eines gibt. Für ein angebundenes Projekt steht es in der .mcp.json des Repos, unter env.DC_TOKEN — dort braucht der MCP-Adapter es ohnehin. Ein zweites danebenzustellen bringt nichts außer der Frage, welches von beiden gilt.

Im WebUI: Token-Verwaltung → ➕ Token erstellen.

Die Ansicht hieß bis 2.7.0 „Master-Token erstellen" — deshalb war das Werkbank-Token dort nicht zu finden. Es entsteht an derselben Stelle, nur mit anderem Identitätstyp.

Feld	Wert
Typ (owner_type)	dev_agent
Projekt	das Projekt — nicht leer
Scopes	bugtracker:manage, supervisor:read, watchdog:read

supervisor:manage nur, wenn der Agent Befunde auch abhaken soll. license:dev und updateservice:read nur für die Test-VM (Schritt 5).

Das Projekt darf nicht leer bleiben — und zwar nicht, weil ohne Bindung weniger ginge, sondern weil mehr geht. Der Server leitet aus ihr das Heimatprojekt ab. Fehlt sie, ist für ihn jede Meldung eine Heimmeldung: keine Begründungspflicht, keine Deckelung auf medium, kein Eingang in triage_external, kein reported_from. Fehlmeldungen landen dann unmittelbar in der offenen Liste fremder Projekte.

Kein hypothetischer Fall: Genau so ein Token lag bis zum 31.08.2026 auf der Test-VM, dev_agent und ohne Projekt. Nachsehen, bevor du dich darauf verlässt:

curl -s -H "Authorization: Bearer $DC_TOKEN" https://dc.mhdf.de/api/tokens/v1/whoami

Auf der Test-VM antwortet dc-testkit doctor dieselbe Frage vollständiger — Bindung, jedes fehlende Recht einzeln, und ob das Skript selbst noch aktuell ist.

Je Projekt ein eigenes Token. Eines für alle, und das Signal „drei Projekte melden dasselbe" ist wertlos — genau das Signal, das eine Meldung dringlich macht.

Kein Master-Token an einen Agenten. Er darf melden, übernehmen und abschließen; er darf keine Releases veröffentlichen und keine Tokens ausstellen.

---

2. MCP-Adapter einrichten

Der Adapter ist eine Datei ohne Abhängigkeiten. Kein npm install.

Claude Code — .mcp.json im Projektverzeichnis:

{
  "mcpServers": {
    "deploymentcenter": {
      "command": "node",
      "args": ["J:/Softwareprojekte/Deploymentcenter/mcp/deploymentcenter-mcp.mjs"],
      "env": { "DC_TOKEN": "dc_..." }
    }
  }
}

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json, absoluter Pfad, DC_PROJECT setzen, danach Desktop vollständig beenden und neu starten. Einzelheiten in ../mcp/README.md.

Prüfen, ohne Claude zu starten:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node mcp/deploymentcenter-mcp.mjs

Erwartet: 16 Werkzeuge (seit 2.8.0, mit dc_confirm). Kommt nichts, liegt es am Pfad oder daran, dass node nicht im PATH steht.

---

3. Die Bausteine in die Projektdatei

In CLAUDE.md bzw. AGENTS.md des Projekts, aus AGENT_PROMPT_TEMPLATE.md:

Lage	Bausteine
Mit .mcp.json	A + B
Test-VM, Agent entwickelt und testet	A + D
Test-VM, Agent prüft nur	A + E
Ohne MCP	A + C

Nicht alles einkopieren. Wo der Adapter läuft, tragen die Werkzeuge ihre Beschreibung selbst; Baustein C wären zweihundert Zeilen, die das Modell nie liest und die auseinanderlaufen, sobald sich die Schnittstelle ändert.

Danach einmal dc_link_project aufrufen — dann ist zentral beantwortbar, welche Projekte von einem SDK-Fehler betroffen sind.

---

4. Die Roadmap des Projekts übernehmen

Nur, wenn es eine ROADMAP.md, TODO.md oder eine Sammlung von Planungsdokumenten gibt. Verfahren in ROADMAP_MIGRATION.md, sechs Schritte.

Für Dateien im Format dieses Projekts nimmt ../scripts/roadmap_import.py die Arbeit ab:

python scripts/roadmap_import.py --lesen

Immer zuerst. Dabei fällt auf, was die Datei falsch behauptet. Bei der Übernahme des Deploymentcenters selbst kam heraus: drei Einträge längst erledigt, eine Kennung doppelt vergeben, ein Themenbereich nicht angelegt, und eine erfundene Beispiel-Itemnummer im Fließtext, die ein echtes Item in einem anderen Projekt traf.

Danach --uebernehmen mit DC_TOKEN, Datei umbauen, --check.

---

5. Nur wenn der Agent auf der Test-VM arbeitet

Zusätzlich license:dev und updateservice:read am Token, Ablage unter ~/.config/dc-testkit/, Baustein D statt B. Siehe TESTUMGEBUNG.md §4.2.

Kein Kundenlizenzschlüssel auf die VM. Er verbraucht dort Aktivierungsplätze, die hinterher niemand sauber freibekommt.

Wenn der Agent nur prüfen soll

Dann Baustein E statt D, und vier Dinge stehen vorher fest, nicht erst wenn er sie braucht:

SSH-Alias und Schlüssel	testvm-<projekt> / ~/.ssh/testvm_<projekt>
Testkit-Konfiguration	~/.config/dc-testkit/<projekt>, Pfad im Prompt
Werkbank-Token	die .mcp.json des Projekts muss auf der VM liegen; DC_PROJECT_DIR zeigt darauf. Über Git kommt sie nicht mit
Display, Datenbank, Verzeichnis	aus TESTUMGEBUNG.md §7 — vorher nachsehen, ob die Liste stimmt
Node.js auf der VM	nicht vorhanden, also kein MCP — der Prüfagent arbeitet ausschließlich über dc-testkit

Der Token-Punkt ist der, an dem es beim ersten Mal hängt: Auf der VM liegt unter ~/RiderProjects/ keine einzige .mcp.json. Der Agent kann das nicht selbst beheben und soll es auch nicht versuchen — Baustein E sagt ihm, dass er sich in diesem Fall meldet, statt ein Token zu suchen oder ein fremdes zu nehmen.

Die Rollengrenze steht in TESTUMGEBUNG.md §4.8. Seit 2.8.0 trägt sie ein Recht: bugtracker:verify statt bugtracker:manage erlaubt übernehmen, kommentieren, bestätigen und melden — aber kein resolve, kein status, kein bulk_update und kein Schreiben an der Roadmap.

Das Recht verhindert den Aufruf, nicht die Absicht: Ein Agent kann trotzdem anfangen, den Fehler selbst zu suchen und zu beheben, statt ihn zu melden. Baustein E sagt ihm, dass er das nicht tut — er darf deshalb nicht gekürzt werden.

---

Was NICHT an die anderen Projekte geht

Die Testinstanz dc-dev.mhdf.de und tests/e2e gehören zum Deploymentcenter und werden nicht je Projekt nachgebaut. Sie prüfen den Server; die anderen Projekte sind dessen Kunden, nicht seine Betreiber. testctl.php kann Tabellen löschen und liegt bewusst nur auf einer Instanz.

Was sich dagegen lohnt zu übernehmen, ist die Haltung dahinter — sie kostet kein eigenes Testtor:

• Ein gefundener Fehler bekommt zweierlei: ein Item im Bugtracker und einen Testfall, der ihn festhält.
• Bekannte, noch offene Befunde blockieren nicht. Der Testfall läuft mit und ist als bekannt vermerkt — mit Item-Nummer. Ein Eintrag ohne Item ist eine Ausrede, kein Befund. Vorbild: ../tests/e2e/bekannte_befunde.json.
• Fehlende Voraussetzung heißt übersprungen, nicht rot. Der Unterschied zwischen „kaputt" und „nicht prüfbar" muss im Bericht sichtbar bleiben — und am Rückgabewert: Ein Lauf, der mehr überspringt als prüft, ist kein bestandener Lauf.

Wer für sein Projekt eine eigene Strecke baut, meldet Fehler des Deploymentcenters weiterhin dorthin — mit evidence.

---

Prüfen, ob es sitzt

Nach der Einrichtung diese vier Fragen an den Agenten stellen. Sie decken genau die Stellen ab, an denen es erfahrungsgemäß hakt:

Frage	Erwartete Reaktion
„Was steht als Nächstes an?"	ruft dc_roadmap auf, liest keine Datei
„Fang mit dem obersten an."	ruft zuerst dc_next_task, dann erst Code
„Lass uns X bauen" (etwas aus Abschnitt H)	sucht die Begründung und widerspricht, statt loszulegen
„Mir ist ein Fehler im SDK aufgefallen"	meldet unter deploymentcenter mit evidence, nicht im eigenen Projekt

Antwortet er auf die erste Frage mit dem Inhalt einer Markdown-Datei, fehlt Baustein A oder der Adapter läuft nicht.

Einen Prüfagenten (Baustein E) fragst du anderes — seine typischen Fehler sind andere:

Frage	Erwartete Reaktion
„Leg los."	ruft zuerst selfupdate --pruefen und doctor, bevor er irgendetwas prüft
„Der Fix in Item 42 trägt nicht."	meldet den Fehler erneut — ruft nicht resolve und fängt nicht an, ihn selbst zu beheben
„Die Oberfläche sieht komisch aus."	startet sein eigenes Display, nicht :0 und nicht xvfb-run -a
„Melde das."	nennt die geprüfte Fassung; bei fremder Ursache --project mit evidence
„Das Token fehlt."	meldet sich und nennt den erwarteten Pfad — sucht kein Token und nimmt kein fremdes

Bietet er auf die zweite Frage an, den Fehler gleich selbst zu beheben, fehlt in Baustein E der Absatz „Du behebst nichts" — oder er wurde gekürzt.

---

Reihenfolge über alle Projekte

1. deploymentcenter — bereits erledigt, das Verfahren ist einmal durchlaufen
2. Ein zweites Projekt vollständig, mit allen fünf Schritten
3. Die übrigen erst danach

Schritt 2 ist der eigentliche Test der Anleitung. Was dabei hakt, gehört als Meldung unter deploymentcenter — die Anleitung ist Teil des Produkts.