Document controlled GitHub MCP write mode

2026-08-23 18:20:01 +02:00
parent 2347073f3f
commit 288dc62e7e
5 changed files with 146 additions and 0 deletions
@@ -0,0 +1,78 @@
+# GitHub MCP: sicherer Lese- und Wartungsmodus
+
+## Normalbetrieb
+
+Athena startet den offiziellen GitHub MCP grundsätzlich im Nur-Lesen-Modus.
+Sichtbar sind exakt:
+
+- `search_repositories`
+- `get_repository_tree`
+- `get_file_contents`
+- `search_code`
+
+Der Token liegt ausschließlich in `/etc/mike-ai/github-mcp.env` (Modus 0600).
+Er steht weder in Open WebUI noch in Git, der Dokumentation oder dem Platform
+Context MCP. Der Container besitzt keinen Host-Port.
+
+Status anzeigen:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh status
+```
+
+## Bewusster Wartungstermin mit Schreibzugriff
+
+Wenn Dateien in einem eigenen Repository geändert werden sollen, aktiviert der
+Administrator den begrenzten Wartungsmodus:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh maintenance --confirm
+```
+
+Zusätzlich zu den Lesewerkzeugen werden nur diese Operationen angeboten:
+
+- Branches auflisten und einen neuen Branch anlegen
+- eine oder mehrere Dateien committen
+- einen Pull Request anlegen
+
+Absichtlich fehlen Löschen, Mergen, Repository-Erstellung, Workflow-Ausführung,
+Issue-Veränderungen und administrative Werkzeuge. Trotzdem ist dies echter
+Schreibzugriff. Vor jeder Änderung muss das Modell den aktuellen Dateiinhalt
+lesen, auf einem neuen Branch arbeiten und Ziel, Dateien und Wirkung nennen.
+
+Nach der Arbeit sofort zurückschalten:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh read
+```
+
+Beide Umschaltungen starten nur den GitHub-MCP-Container neu und danach kurz
+das Open-WebUI-Backend, damit dessen Werkzeugcache sicher zum aktiven Modus
+passt. LLM-Profile, Router, VPN und andere MCPs werden nicht neu gestartet.
+
+## Token-Rechte
+
+Die serverseitige Werkzeugliste ersetzt keine saubere Tokenbegrenzung. Für den
+Normalbetrieb ist ein nur lesender Fine-grained PAT ideal. Ein Token, der auch
+schreiben darf, sollte nur Zugriff auf ausdrücklich ausgewählte Repositories und
+den geringsten benötigten `Contents`-Umfang erhalten. Geschützte Hauptbranches
+und verpflichtende Pull Requests bilden die zweite Schutzschicht.
+
+Nach Tokenwechsel oder Rechteänderung:
+
+```bash
+sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh read
+```
+
+## Fehlerbehebung
+
+`Failed to connect to MCP server 'github-local'` war am 23. August 2026 kein
+Tokenfehler. Supergateway beantwortete den regulären MCP-Handshake von Open
+WebUI fehlerhaft. Produktiv wird deshalb der offizielle GitHub MCP 1.10.1 über
+`mcp-proxy` 0.12.0 bereitgestellt. Der Pfad wurde mit Open WebUIs eigenem
+Python-MCP-Client und einer echten öffentlichen Repositorysuche geprüft.
+
+Der Normalmodus ist Teil des Installationsskripts. Skript, Compose-Override und
+diese Anleitung liegen im Git-Repository und werden vom Recovery-Koffer
+mitgeführt. Das Platform Context MCP kann diese Anleitung lesen, erhält aber
+weder Token noch die Fähigkeit, den Modus selbst unbemerkt umzuschalten.