Add self-maintaining Athena platform context MCP

2026-08-23 17:31:05 +02:00
parent 64d36ad838
commit 3dbb66037d
22 changed files with 1071 additions and 9 deletions
@@ -0,0 +1,106 @@
+# Athena Platform Context MCP
+
+Stand: 23. August 2026
+
+## Zweck
+
+`mike-ai-mcp-platform-context` gibt jedem MCP-fähigen Client dasselbe
+versionierte Wissen über Athena und MikeAI. Dadurch kann in Open WebUI zwischen
+Fast, Medium, Large und Ultra gewechselt werden, ohne den vollständigen
+Operator-Kontext in jeden Prompt zu kopieren.
+
+Der MCP ist zugleich das kontrollierte Pflegefenster für seine eigene
+Dokumentation. Er ist **kein** allgemeiner Athena-Administrator und erhält
+weder Docker-Socket noch Shell, Netzwerkzugang, Git-Schlüssel oder Secrets.
+
+## Werkzeuge
+
+| Werkzeug | Wirkung |
+|---|---|
+| `athena_get_overview` | kurze Architektur und Quellenhierarchie |
+| `athena_get_current_state` | begrenzter aktueller Snapshot ohne Nutzdaten |
+| `athena_search_knowledge` | Suche in Dokumentation und versionierten Quellen |
+| `athena_read_source` | begrenzter Ausschnitt einer ausgewählten Textdatei |
+| `athena_get_change_workflow` | verbindlicher Ablauf je Änderungstyp |
+| `athena_prepare_documentation_update` | erzeugt nur eine prüfbare Vorschau |
+| `athena_apply_documentation_update` | schreibt nach Freigabe ausschließlich `docs/*.md` |
+| `athena_get_maintenance_status` | zeigt offene Git-/Recovery-Schulden |
+| `athena_close_maintenance_record` | schließt Schulden erst nach geprüftem Git-Deploy und neuerem Recovery-Koffer |
+
+## Aktueller Zustand ohne Docker-Socket
+
+`mike-ai-platform-context-snapshot.timer` startet jede Minute einen kurzen,
+fest programmierten Host-Snapshot. Er erfasst ausschließlich:
+
+- Hostname, Debian-/Kernel-Version und Uptime
+- grobe RAM- und Dateisystembelegung
+- GPU-Name, UUID, VRAM-Belegung und Treiberversion
+- Name, Image und Status der laufenden `mike-ai-*`-Container
+- aktives Inferenzprofil
+- installierten Quellcommit, Hash des Dokumentationsbaums und Status des
+  Recovery-Koffers
+
+Nicht erfasst werden Logs, Prompts, Chats, Toolinhalte, Container-Umgebungen,
+Dateiinhalte außerhalb der versionierten Dokumentation oder Secretwerte. Der
+Container liest nur die erzeugte JSON-Datei. Ein Snapshot älter als drei
+Minuten gilt als veraltet.
+
+## Dokumentationspflege
+
+Die Pflege ist absichtlich zweistufig:
+
+1. Qwen prüft Laufzeit und Quellen und ruft
+   `athena_prepare_documentation_update` auf.
+2. Das Werkzeug speichert einen Vorschlag unter
+   `/data/mike-ai-platform-context/pending` und liefert ID, Hashes und die
+   genaue Freigabezeichenfolge zurück. Noch wurde nichts geändert.
+3. Qwen zeigt den Vorschlag dem Benutzer und beendet die autonome Werkzeugkette.
+4. Erst nach ausdrücklicher Freigabe darf
+   `athena_apply_documentation_update` mit `APPLY <proposal-id>` aufgerufen
+   werden.
+5. Vorherige Dateien werden unter
+   `/data/mike-ai-platform-context/backups` gesichert, neue Inhalte atomar
+   geschrieben und unter `applied` protokolliert.
+
+Der Server akzeptiert nur einfache Markdown-Dateien direkt unter `docs/`.
+Code, Compose, Profile, Installer, Netzwerke, Services, Git und Secrets können
+über diesen Schreibweg nicht verändert werden.
+
+## Git und Recovery
+
+Die kanonische Quelle ist der private Gitea-Stand
+`git@192.168.1.2:michael/AI-Profile-Router.git`, Branch `main`. Das
+Installationsverzeichnis `/opt/mike-ai/stack` ist eine ausgerollte Kopie und
+kein Git-Working-Tree; `.mike-ai-source-commit` benennt den ausgerollten
+Commit. Der offizielle GitHub-MCP ist read-only und kann dieses private
+Gitea-Repository weder ändern noch pushen. Dafür ist ein getrennt
+autorisiertes Git-Werkzeug beziehungsweise ein administrativer Git-Workflow
+notwendig.
+
+Eine angewandte Dokumentationspflege ist erst vollständig abgeschlossen, wenn
+getrennte, dafür autorisierte Werkzeuge Folgendes bestätigt haben:
+
+1. dieselbe Änderung ist im privaten Quellrepository geprüft, committed und
+   gepusht;
+2. der Commit wurde nach Athena ausgerollt und `.mike-ai-source-commit` stimmt;
+3. ein neues verschlüsseltes Recovery-Bundle und ein neues
+   `/data/mike-ai-recovery-kit` wurden erzeugt und geprüft.
+
+Der Context MCP meldet diese Punkte nach jeder Anwendung ausdrücklich als
+offen. Er darf sie nicht selbst als erledigt markieren. Lokale Vorschläge,
+Backups und Dokumentations-Overlays werden im verschlüsselten Recovery-Bundle
+mitgesichert, sodass ungepushte Dokumentationspflege bei einem SSD-Ausfall
+nicht vollständig verloren geht. Das ersetzt keinen Git-Commit.
+
+## Verwendung in Open WebUI
+
+Das Werkzeug `Athena Plattformwissen` wird nur bei Arbeiten an Athena/MikeAI
+aktiviert. Ein geeigneter Startauftrag lautet:
+
+> Nutze zuerst das Athena-Plattformwissen. Prüfe den aktuellen Zustand und die
+> relevanten Quellen. Plane danach die gewünschte Änderung mit Rückweg. Nimm
+> keine risikoreiche Aktion und keine Dokumentationsanwendung ohne meine
+> ausdrückliche Freigabe vor.
+
+Das funktioniert unabhängig vom gewählten Textprofil. Für normale Gespräche
+bleibt der MCP deaktiviert und verbraucht damit keinen Werkzeugkontext.