AI-Profile-Router/docs/PLATFORM_CONTEXT_MCP.md

# 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, Git-Schlüssel oder Secrets. Sein Netzzugang ist
auf feste, versionierte Erreichbarkeitsprüfungen aus dem Diensteverzeichnis
beschränkt; Modellparameter können keine freie Adresse vorgeben.

## Werkzeuge

| Werkzeug | Wirkung |
|---|---|
| `athena_get_overview` | kurze Architektur und Quellenhierarchie |
| `athena_get_current_state` | begrenzter aktueller Snapshot ohne Nutzdaten |
| `athena_get_external_services` | vorhandene externe Dienste plus feste, bounded Erreichbarkeitsprüfung |
| `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.

Das zusätzliche Diensteverzeichnis unter `config/service-catalog.json` enthält
nur bekannte interne Namen, Adressen, Ports, Zuständigkeiten und Zwecke, keine
Zugangsdaten. `athena_get_external_services` prüft ausschließlich diese festen
Einträge. Es ist kein Portscanner, liest keine Antwortinhalte und akzeptiert
keine URL oder Adresse aus dem Modell. Für Details bleibt anschließend das im
Katalog genannte Fachwerkzeug zuständig.

## 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
`ssh://git@192.168.1.2:33/michael/AI-Profile-Router.git`, Branch `main`, im
Working Tree `/data/mike-ai-operator/repository`. 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 besitzt der Athena Operator
den autorisierten, strukturierten Arbeitsweg. Ein Modell darf weder im eigenen
Sandbox-Container einen weiteren Clone anlegen noch einen SSH-Schlüssel
anfordern oder kopieren.

Der verbindliche Ablauf für dauerhafte Änderungen lautet:

1. `athena_operator_prepare` und nach separater Benutzerfreigabe
   `athena_operator_execute` mit `file_update`; dies schreibt dieselben
   ausgewählten Dateien driftgeschützt in den kanonischen Working Tree und die
   ausgerollte Kopie.
2. Prüfungen über die Operation `run_checks` ausführen.
3. Nur betroffene Dienste über `compose_deploy` ausrollen.
4. Ausschließlich die ausdrücklich angegebenen geänderten Pfade mit
   `git_publish` committen und pushen. Fremde Dirty-Worktree-Dateien bleiben
   unberührt.
5. Mit `recovery` einen neuen Recovery-Koffer erzeugen und prüfen.

Das allgemeine Terminal ist weder Ersatz für diesen Ablauf noch ein Weg zu
Git-Schlüsseln. `/data/mike-ai-operator/repository` muss aus der
Modellsandbox nicht direkt erreichbar sein; der rootseitige Executor besitzt
den notwendigen Zugriff.

Eine angewandte Dokumentationspflege ist erst vollständig abgeschlossen, wenn
die dafür vorgesehenen Athena-Operator-Operationen 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.