Deploymentcenter BotandClaude Opus 5
8b6d6a307e
MCP-ADAPTER 1.1
Werkzeuge ruft ein Modell von sich aus auf - Ressourcen und Prompts waehlt ein
MENSCH. In Claude Desktop sind das Anhang-Menue und Schraegstrich-Befehle, und
genau die fehlten.
- Vier Ressourcen: dc://roadmap (fertiger Markdown-Block),
dc://naechste-schritte, dc://projekte, dc://befunde.
- Vier Prompts: arbeit-aufnehmen, befunde-sichten, fehler-melden,
roadmap-pflegen. Ihr Wert liegt nicht in der gesparten Tipparbeit, sondern
darin, dass die Hausregeln mitkommen - erst nachsehen wer dransitzt,
Fremdmeldung nur mit Begruendung, Verworfenes nicht ohne neues Argument
wiedervorschlagen. Bisher standen die nur in Werkzeugbeschreibungen, und
die liest ein Modell erst, wenn es das Werkzeug schon gewaehlt hat.
- DC_PROJECT: worauf die Ressourcen zeigen. Werkzeuge nehmen project_slug je
Aufruf, Ressourcen haben keine Argumente.
- Ressourcen laufen durch dieselbe Fremddaten-Abgrenzung wie
Werkzeugergebnisse - sie sind eher ein Einfallstor, weil sie ungefragt im
Kontext landen.
- Einrichtung fuer claude_desktop_config.json dokumentiert.
Behoben: "initialize" spiegelte die verlangte Protokollfassung zurueck. Ein
Client, der 2025-06-18 anfragte, bekam sie bestaetigt, obwohl der Adapter
fuer 2024-11-05 geschrieben war. Jetzt wird gegen eine Liste tatsaechlich
bedienter Fassungen ausgehandelt.
Behoben: process.exit() mitten in schliessenden libuv-Handles. Unter Windows
eine Assertion und Rueckgabewert != 0 - ein sauber beendeter Server sah aus
wie ein abgestuerzter.
ZWEI BEFUNDE, DIE ERST DIE RESSOURCEN ZUTAGE FOERDERTEN
- roadmap.php?action=render lehnte fuer ein Werkbank-Token mit
"missing_project" ab. projectFilter() laesst es beim Lesen bewusst durch
(es soll die Landschaft sehen) und liefert null, also wurde der
Projektbezug "all". Betroffen war ausgerechnet der Tokentyp, den der
Adapter verlangt. Rueckfall ist jetzt das Heimatprojekt des Tokens.
- ProjectLinks::between() benutzte :a dreimal, forProject() :slug zweimal.
Bei ATTR_EMULATE_PREPARES = false unzulaessig -> HY093 und ein 500 auf
/api/bugtracker/v1/projects. Derselbe Fehler wie einst in der
Volltextsuche des Bugtrackers; ein Suchlauf ueber alle prepare()-Aufrufe
der Codebasis fand keine weitere Stelle.
WARUM BEIDE UNBEMERKT BLIEBEN
Beide Wege laufen nur mit einem Werkbank-Token (owner_type = dev_agent). Der
Testlauf hatte keines - es gibt keine API, so eines anzulegen, und in der
Produktion geschieht das von Hand. Ein Tokentyp, den kein Testfall benutzt,
ist ein Tokentyp, dessen Sonderwege niemand prueft.
testctl.php kann jetzt action=workbench_token; vier Testfaelle decken die Wege
ab, samt Gegenprobe, dass der Rueckfall aufs Heimatprojekt das Lesen ueber alle
Projekte nicht einschraenkt. 128 Faelle, alle gruen.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
136 lines
7.8 KiB
Markdown
136 lines
7.8 KiB
Markdown
# Deploymentcenter — Entwickler- und Agenten-Dokumentation
|
|
|
|
Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur-
|
|
Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.
|
|
|
|
---
|
|
|
|
## Zuerst lesen
|
|
|
|
| Dokument | Wofür |
|
|
|---|---|
|
|
| **[ROADMAP.md](./ROADMAP.md)** | **Der eine Ort für alles Geplante, Zurückgestellte und bewusst Verworfene.** Ab 2.7.0 gilt die Arbeitsteilung: Zustand im Deploymentcenter (WebUI → Roadmap, `dc_roadmap`), Begründung hier. |
|
|
| **[ROADMAP_MIGRATION.md](./ROADMAP_MIGRATION.md)** | **Eine vorhandene `ROADMAP.md` oder `TODO.md` ins Deploymentcenter überführen.** Einmalig je Projekt, sechs Schritte. Für die Agenten der angebundenen Projekte. |
|
|
| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
|
|
| **[Änderungen](../public/docs/changelog.json)** | Was sich je Fassung geändert hat und was zu tun ist. Öffentlich unter `/docs/changelog.php`, maschinenlesbar über `GET /api/updateservice/v1/changelog?since=X` |
|
|
| **[Release-Anleitung für Agenten](../public/docs/release.md)** | Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern |
|
|
| **[Linux-Testumgebung](./TESTUMGEBUNG.md)** | **Die geteilte Test-VM.** Wie ein Agent dort selbständig testet: DEV-Lizenz holen, Auslieferung prüfen, Befunde melden — mit `dc-testkit` |
|
|
| **[Testinstanz & automatisierter Testlauf](./TESTINSTANZ.md)** | **`dc-dev.mhdf.de` — die zweite Installation zum Kaputtmachen.** 128 Fälle gegen API, Rechte, Migrationen und Zugangssperre (`tests/e2e/run.py`). **`scripts/deploy.py` führt sie vor jedem Produktiv-Upload aus** und bricht bei Fehlschlägen ab (`--ohne-test` umgeht das) |
|
|
| [Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md) | Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts |
|
|
| [Agenten-Handbuch](../public/docs/bugtracker.md) | Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/` |
|
|
|
|
## Modul-Handbücher
|
|
|
|
- **[Lizenzsystem (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)** — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
|
|
- **[Watchdog (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)** — Überwachung von Anwendungen, Diensten und Infrastruktur
|
|
- **[UpdateService](./UPDATESERVICE_INTEGRATION_GUIDE.md)** — Release-Verteilung und Update-Prüfung
|
|
- **[Erstinstallation](./SETUP_INTEGRATION_GUIDE.md)** — `setup.json`, Installationskonto, `update-agent --action install`
|
|
- **[Bugtracker](./BUGTRACKER_INTEGRATION_GUIDE.md)** — Anbindung aus Anwendungen heraus
|
|
- **[Supervisor](./SUPERVISOR_INTEGRATION_GUIDE.md)** — Befunde: was ist ungewöhnlich? Läuft serverseitig auf ohnehin eingehenden Daten, **ohne Einbau in die Anwendungen**. Enthält auch den Rückbau begonnener Vorbereitungen
|
|
- **[MCP-Adapter](../mcp/README.md)** — Claude Code **und Claude Desktop** an Bugtracker, Roadmap und Supervisor anschließen — 15 Werkzeuge, 4 Ressourcen, 4 Prompts
|
|
|
|
Hintergrund zu Supervisor und MCP, inklusive der Frage, warum der Client keinen
|
|
Quelltext sieht: **[archiv/SUPERVISOR_MCP_DESIGN.md](./archiv/SUPERVISOR_MCP_DESIGN.md)**
|
|
— archiviert, die Herleitung gilt weiter, der Stand steht in der
|
|
[Roadmap](./ROADMAP.md).
|
|
|
|
---
|
|
|
|
## Modulübersicht
|
|
|
|
| Modul | Aufgabe | Endpunkte | Authentifizierung |
|
|
|---|---|---|---|
|
|
| **Bugtracker** | Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease | `/api/bugtracker/v1/report`<br>`/api/bugtracker/v1/projects`<br>`/api/bugtracker/v1/manage` | Token mit `bugtracker:*` |
|
|
| **UpdateService** | Release-Verteilung, semantischer Versionsvergleich | `/api/updateservice/v1/check`<br>`/api/updateservice/v1/publish` | Lesen offen, Publish braucht `updateservice:publish` |
|
|
| **Watchdog** | Heartbeat-Monitoring, Zustandsbewertung, Alarmierung | `/api/watchdog/v1/ping`<br>`/api/watchdog/v1/evaluate` | Token mit `watchdog:ping` |
|
|
| **Supervisor** | Befunde: was ist ungewöhnlich? Fünf Detektoren laufen serverseitig im Tick und brauchen keine Client-Änderung | `/api/supervisor/v1/observe`<br>`/api/supervisor/v1/findings`<br>`/api/supervisor/v1/catalog` | Melden `supervisor:report`, Lesen `supervisor:read`, Einstufen `supervisor:manage` |
|
|
| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache, befristete DEV-Schlüssel zur Selbstbedienung | `/api/license/v1/validate`<br>`/api/license/v1/deactivate`<br>`/api/license/v1/dev-key` | Validierung offen, Deaktivierung authentifiziert, DEV-Schlüssel `license:dev` |
|
|
| **Tokens** | Selbst-Provisionierung von Sub-Tokens | `/api/tokens/v1/provision` | Master-Token |
|
|
| **Setup** | Erstinstallation: Anmeldung, Katalog, Anwendungstoken | `/api/setup/v1/login`<br>`/api/setup/v1/catalog`<br>`/api/setup/v1/token` | Login offen, Rest `setup:*` |
|
|
| **System** | Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung | `/api/health`<br>`/api/openapi.json` | Health optional, OpenAPI offen |
|
|
|
|
---
|
|
|
|
## Schnittstelle maschinenlesbar
|
|
|
|
```
|
|
GET https://dc.mhdf.de/api/openapi.json
|
|
```
|
|
|
|
Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI
|
|
hinterlegte Textblock entfällt damit.
|
|
|
|
---
|
|
|
|
## Drosselung
|
|
|
|
Je IP und Minute. Wird die Grenze überschritten, antwortet der Endpunkt mit
|
|
`429 rate_limited` — dann das Intervall verdoppeln und später erneut versuchen,
|
|
nicht sofort wiederholen.
|
|
|
|
| Endpunkt | Grenze | Einstellbar über |
|
|
|---|---|---|
|
|
| `/api/errors/v1/report` | **300** | `bugtracker.error_rate` |
|
|
| `/api/bugtracker/v1/report` | 60 | `bugtracker.report_rate` |
|
|
| `/api/supervisor/v1/observe` | 120 | `supervisor.observe_rate` |
|
|
| `/api/license/v1/*` | 120 | fest |
|
|
| `/api/license/v1/dev-key` | 10 | fest — ein Schlüssel je Testlauf, nicht je Sekunde |
|
|
| `/api/updateservice/v1/*` | 240 | fest |
|
|
| `/api/setup/v1/login` | 10 | fest — dort werden Passwörter geprüft |
|
|
| `/api/tokens/v1/provision` | 20 | fest |
|
|
|
|
---
|
|
|
|
## Antwortformat
|
|
|
|
Alle JSON-Endpunkte antworten einheitlich:
|
|
|
|
```json
|
|
{ "status": "success", "…": "…" }
|
|
```
|
|
|
|
```json
|
|
{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }
|
|
```
|
|
|
|
Der `code` ist stabil und für Programme gedacht; die `message` richtet sich an
|
|
Menschen und kann sich ändern.
|
|
|
|
---
|
|
|
|
## Betrieb
|
|
|
|
| Aufgabe | Befehl |
|
|
|---|---|
|
|
| Deployment | `python scripts/deploy.py` |
|
|
| Migration | `php public/install_db.php` oder WebUI → System → DB-Migration |
|
|
| Evaluator (Cron, minütlich) | `curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate` |
|
|
| Zustand prüfen | `curl https://dc.mhdf.de/api/health` |
|
|
| Logs | `var/log/dc-<datum>.log` auf dem Server |
|
|
|
|
## Aufbau
|
|
|
|
```
|
|
config/ Zugangsdaten (nicht versioniert), Vorlage in config.example.php
|
|
src/ Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
|
|
Core/ Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator,
|
|
ProjectLinks (welches Projekt nutzt welches, in welcher Fassung)
|
|
Modules/ Bugtracker, License, Supervisor, UpdateService, Watchdog, Notify
|
|
public/ Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation,
|
|
testkit/dc-testkit.sh (das Werkzeug für die Linux-Test-VM)
|
|
sql/ Schema und Migrationen (fortlaufend nummeriert)
|
|
var/log/ Laufzeitprotokolle
|
|
scripts/ Deployment
|
|
mcp/ MCP-Adapter für Claude Code — eine Datei, keine Abhängigkeiten
|
|
client-dotnet/ Client-SDK: Lizenz, Update, Setup
|
|
```
|
|
|
|
Der Supervisor läuft ausschließlich hier — an den Detektoren in
|
|
`Modules/Supervisor/ServerDetectors.php`
|
|
im minütlichen Tick mit (gedrosselt auf zehn Minuten). Er arbeitet auf Daten,
|
|
die ohnehin hereinkommen — Fehlerberichte, Heartbeats, Kennzahlen — und
|
|
braucht dafür keine Änderung an den Anwendungen.
|
|
|
|
Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad
|
|
entsprechen — eine `require`-Zeile ist nicht mehr nötig.
|