fix(tools): harden OpenWebUI tool workflows

2026-08-24 00:40:32 +02:00
1 parent bfb990a4fd
commit e24839bfe1
@@ -29,7 +29,7 @@ Heimnetz / VPN-Clients
        |    +-- Piper-TTS (CPU, automatischer Fallback)
        +-- internes MCP-Netz
             +-- Web-MCP + SearXNG + TinySearch/Crawl4AI + YouTube-Adapter
-             +-- offizieller GitHub-MCP (vier read-only Werkzeuge)
+             +-- offizieller GitHub-MCP (drei kleine read-only Werkzeuge)
             +-- Home-Assistant-MCP-Relay
             +-- ARR-MCP
             +-- Unraid-MCP
@@ -61,7 +61,7 @@ Alle Profile verwenden dasselbe selbst gebaute llama.cpp-Image. Separate,
 normalerweise gestoppte Containerdefinitionen halten Parameter wie Kontext,
 MTP und CPU-Offload reproduzierbar. Ein Wechsel stoppt das alte Profil und
 startet genau einen bereits angelegten Container. Dadurch lassen sich Profile
-einzeln verändern oder duplizieren, ohne vier Modelle parallel im VRAM zu
+einzeln verändern oder duplizieren, ohne mehrere Modelle parallel im VRAM zu
 halten.

 | Profil | Ausgangswert | Zweck |
@@ -158,9 +158,9 @@ weitere MCP-Clients ──────┴── mcp-gateway (später) ── das

 | Container | Werkzeugbereich | Standardrecht |
 |---|---|---|
-| `web-mcp` | Websuche, Seitenabruf, YouTube/Transkripte, Hugging Face und öffentliche Quellen | nur lesen; begrenzte Aufrufschleifen |
+| `web-mcp` | manuell zugeschaltete Spezialabfragen für YouTube und Hugging Face | nur lesen; begrenzte Aufrufschleifen |
 | `platform-context-mcp` | Architektur, Quellen, Snapshot und Docs-Pflege | kein Docker-Socket; Docs nur Preview/Approval |
-| `github-mcp-read` | Repositorysuche, Baum, Dateiinhalt und Code-Suche | vier Tools, strikt nur lesen |
+| `github-mcp-read` | Repositorysuche, gezielte Datei- und Code-Suche | drei Tools, strikt nur lesen |
 | `home-assistant-mcp-read` | Entities, Bereiche, Historie, Diagnose | nur lesen |
 | `home-assistant-mcp-write` | kontrollierte HA-Änderungen | Preview/Approval |
 | `arr-mcp-read` | Sonarr/Radarr-Status und Releasesuche | nur lesen |
@@ -11,7 +11,7 @@
 | Home-Assistant-MCP | HA-Endpunkt plus lokaler Relay | eigener optionaler Container | optional |
 | ARR-MCP | `arr-mcp` 1.0.1 plus dokumentierter Sonarr-Patch | eigener optionaler Container | optional |
 | Navidrome-MCP | Blakeem/Navidrome-MCP 2.2.0, Image per OCI-Digest | eigener optionaler Container ohne mpv | optional |
-| GitHub-MCP | offizieller `github/github-mcp-server` 1.10.1, vier read-only Werkzeuge | eigener optionaler Container hinter Streamable-HTTP-Brücke | optional |
+| GitHub-MCP | offizieller `github/github-mcp-server` 1.10.1, drei begrenzte read-only Werkzeuge | eigener optionaler Container hinter Streamable-HTTP-Brücke | optional |
 | Platform Context MCP | Athena-/MikeAI-Wissen, begrenzter Laufzeitsnapshot und kontrollierte Dokumentationspflege | eigener Container ohne Docker-Socket, Shell, Egress oder Secrets | Kern |
 | Athena Operator MCP | Entwicklung und vollständiger Betrieb der KI-Plattform mit gebundenen Freigaben | unprivilegierte MCP-Fassade plus rootseitiger strukturierter Executor; keine freie Shell | Kern |
 | Operator-Kontext | `docs/QWEN_OPERATOR_CONTEXT.md` plus `config/operator-system-prompt.txt` | versionierte Selbstbeschreibung und Sicherheitsregeln für Qwen | Kern |
@@ -167,15 +167,17 @@ Aktuell existieren funktionale Adapter für:
 - Websuche
 - Home Assistant
 - Sonarr/Radarr
- GitHub Repository read-only (offizieller Server, vier Werkzeuge)
+- GitHub Repository read-only (offizieller Server, drei begrenzte Werkzeuge)
 - Navidrome-Bibliothek und Last.fm-Empfehlungen
 - Unraid read-only
 - eigener Unraid-Administrationsserver

 OpenWebUI bindet diese Kataloge nicht pauschal an jedes Modellprofil. Der
 lokale `MikeAI Auto Tool Selector` ergänzt anhand der jüngsten Nutzernachricht
-höchstens zwei passende MCP-Verbindungen pro Anfrage. Dadurch bleiben normale
-Chats schemafrei und kurze Profile verlieren keinen unnötigen Kontext. MUA
+höchstens zwei passende Fach-MCP-Verbindungen pro Anfrage. Allgemeine
+Webrecherche erfolgt über Open WebUIs native `search_web`/`fetch_url`-Werkzeuge;
+`web-local` ist nur noch manuell für Spezialfälle verfügbar. Dadurch bleiben
+Fachkataloge klein und kurze Profile verlieren keinen unnötigen Kontext. MUA
 mit erweiterten Verwaltungsrechten bleibt von der Automatik ausgeschlossen;
 eine automatisch bereitgestellte Verbindung erteilt niemals Schreibrechte
 oder eine Änderungsfreigabe.
@@ -186,8 +188,8 @@ nutzen denselben MUA-Endpunkt. Der frühere GraphQL-basierte Unraid-MCP wurde
 entfernt und gehört weder zum Start noch zum Recovery.

 Der GitHub-Container läuft produktiv. Token-Datei, interner
-Streamable-HTTP-Handshake, fehlende Host-Portfreigabe und exakt vier
-read-only Werkzeuge wurden am 23. August 2026 verifiziert.
+Streamable-HTTP-Handshake, fehlende Host-Portfreigabe und exakt drei
+read-only Werkzeuge wurden am 24. August 2026 verifiziert.
 Die Transportbrücke verwendet den OpenWebUI-kompatiblen `mcp-proxy` 0.12.0 im
 stateless Betrieb. Supergateway wurde nach reproduzierbaren HTTP-400-Fehlern
 bei `notifications/initialized` aus diesem Pfad entfernt.
@@ -55,10 +55,13 @@ laufen, sondern alle fachlichen Funktionen geprüft wurden.
 - [ ] rohe `qwen-*`-Routermodelle sind ausgeblendet
 - [ ] Medium ist die gespeicherte Standardauswahl
 - [ ] Filter und Quick Actions sind allen fünf Presets zugeordnet
- [ ] Auto Tool Selector wählt bei harmlosen Testfragen Web, GitHub, Home
+- [ ] native OpenWebUI-Websuche funktioniert ohne `web-local`; Auto Tool Selector wählt GitHub, Home
      Assistant, ARR, Navidrome, Unraid read-only, Athena-Plattformwissen und
      den Athena Operator korrekt
 - [ ] normale Unterhaltung erhält kein MCP; MUA wird niemals automatisch gewählt
+- [ ] eine synthetische CSV wird lokal ausgewertet; kein Webwerkzeug erhält Dateidaten
+- [ ] ein rekursiver GitHub-Komplettbaum ist nicht als Werkzeug verfügbar
+- [ ] der zweite identische Werkzeugaufruf wird gestoppt und eine Abschlussantwort erzeugt

 - [ ] SearXNG und TinySearch gesund
 - [ ] Websuche liefert kompakte, quellengebundene Ergebnisse
@@ -70,11 +73,14 @@ laufen, sondern alle fachlichen Funktionen geprüft wurden.
 - [ ] vier ähnliche erfolglose Suchvarianten werden serverseitig gestoppt
 - [ ] GitHub- und Hugging-Face-Routing geprüft
 - [ ] Home Assistant read-only Diagnose geprüft
+- [ ] Home-Assistant-MCP löst `ha.casaderoll.de` im Container auf die private
+      `HOME_LAN_PROXY_IP` auf und `tools/list` antwortet über WireGuard
 - [ ] ARR read-only Suche geprüft
 - [ ] Navidrome-MCP gesund; 38 beziehungsweise mit Last.fm 45 Werkzeuge
 - [ ] Navidrome-Schemas vollständig llama.cpp-kompatibel
 - [ ] Navidrome ist nicht pauschal an jedes Modellprofil gebunden
- [ ] offizieller GitHub-MCP gesund; exakt vier read-only Repository-Werkzeuge
+- [ ] offizieller GitHub-MCP gesund; exakt drei read-only Repository-Werkzeuge
+- [ ] `dev/verify_mcp_catalogs.sh` endet mit `MCP_CATALOG_SUITE_OK`
 - [ ] GitHub-Token liegt nur in `/etc/mike-ai/github-mcp.env` (0600), nicht in OpenWebUI
 - [ ] Unraid read-only Diagnose geprüft
 - [ ] schreibende Werkzeuge standardmäßig nicht geladen; automatische Auswahl
@@ -6,10 +6,13 @@ 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`

+`get_repository_tree` ist absichtlich nicht freigeschaltet: rekursive Bäume
+können bei Monorepositories den kompletten Werkzeugkontext belegen. Der sichere
+Weg ist eine gezielte Codesuche und anschließend das Lesen einzelner Dateien.
+
 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.
@@ -123,14 +123,14 @@ gestopptes VPN-Gateway lässt KI-Container nicht ins Internet; jeder Profilwechs
 startet exakt einen llama-Container; Text, Tool Call, Bild und Sprachausgabe funktionieren.

 Nach dem ersten Anlegen des OpenWebUI-Administrators werden Filter, Quick
-Actions und die vier Arbeitsbereichsmodelle reproduzierbar eingespielt:
+Actions und die fünf Arbeitsbereichsmodelle reproduzierbar eingespielt:

 ```bash
 sudo /opt/mike-ai/stack/platform/openwebui/install-filters.sh
 sudo /opt/mike-ai/stack/platform/openwebui/install-models.sh
 ```

-Danach sind nur die vier benannten MikeAI-Presets sichtbar; die rohen
+Danach sind nur die fünf benannten MikeAI-Presets sichtbar; die rohen
 Router-Aliase sind ausgeblendet und Medium ist die Standardauswahl. Beide
 Skripte sichern die OpenWebUI-Datenbank vor jeder Änderung. Der Modellinstaller
 synchronisiert außerdem OpenWebUIs persistente OpenAI-kompatible Verbindung mit
@@ -11,7 +11,7 @@ Reihenfolge ist absichtlich festgelegt:
   überschreibt den Standard mit Low, Medium oder High.
 3. `MikeAI Auto Tool Selector`, Priorität 25: betrachtet ausschließlich die
   jüngste Nutzernachricht und stellt pro Anfrage höchstens zwei passende MCPs
-   bereit. Er erkennt Web, GitHub, Home Assistant, Sonarr/Radarr, Navidrome,
+   bereit. Er erkennt GitHub, Home Assistant, Sonarr/Radarr, Navidrome,
   Unraid-Diagnose und Athena-Plattformwissen. Manuell gewählte Werkzeuge
   bleiben erhalten. MUA mit erweiterten Verwaltungsrechten wird nie
   automatisch zugeschaltet. Die Auswahl eines MCP ist ausdrücklich keine
@@ -75,7 +75,8 @@ das jeweilige MCP, Bestätigungsregeln und die manuelle MUA-Auswahl begrenzt.
 Alle fünf Modelle erhalten außerdem dieselbe Evidenzregel: Aussagen über
 aktuelle externe oder Systemzustände benötigen im aktuellen Turn einen
 erfolgreichen Aufruf des zuständigen Fachwerkzeugs. Task-Verwaltung zählt nicht
-als Datenquelle. Fehlt das Werkzeug oder schlägt es fehl, muss das Modell die
+als Datenquelle und wird für einzelne Fragen, Nachschlageaufgaben, Diagnosen
+oder Dateiauswertungen nicht verwendet. Fehlt das Werkzeug oder schlägt es fehl, muss das Modell die
 fehlende Verifikation offen nennen, statt Werte oder Diagnosen zu erfinden.

 Bei mehreren Administratoren muss der gewünschte Eigentümer explizit über
@@ -93,6 +94,35 @@ abgeschnitten. Sind allein die ausgewählten Schemas zu groß, wird der
 Werkzeugzugriff nur für diesen Schritt deaktiviert und das Modell erhält eine
 eindeutige Abschlussanweisung.

+Allgemeine Webrecherche läuft nativ über Open WebUIs `search_web` und
+`fetch_url`; der frühere Web-MCP ist nur noch ein manuell gewähltes
+Spezialwerkzeug. Pro Antwort sind global höchstens zwölf Werkzeugrunden erlaubt.
+Der Stability Guard stoppt den zweiten identischen Aufruf, begrenzt ein Resultat
+auf 10.000 und alle Resultate zusammen auf 36.000 Zeichen.
+`install-filters.sh` setzt die schlüssellose DuckDuckGo-Suche dabei
+reproduzierbar aktiv (fünf Treffer, maximal drei parallele Abrufe).
+
+CSV-, TSV-, Excel- und ODS-Dateien werden ausschließlich lokal verarbeitet.
+Die Profile aktivieren dafür den eingebauten Python-Code-Interpreter und die
+nativen Dateizugriffswerkzeuge. Tabellen werden nicht als Knowledge/RAG-Text
+behandelt; Web- und Web-MCP-Werkzeuge sind für private Tabellendaten gesperrt.
+
+Der Home-Assistant-Relay behält `https://ha.casaderoll.de` als TLS- und
+Hostnamen, löst ihn innerhalb des Containers aber über `extra_hosts` auf den
+privaten Reverse Proxy `${HOME_LAN_PROXY_IP:-192.168.1.2}` auf. Damit fließt der
+MCP-Verkehr über WireGuard ins Heimnetz und nicht über die öffentliche
+Fritzbox-Adresse. Bei einer abweichenden Heimserver-IP wird nur
+`HOME_LAN_PROXY_IP` in `/etc/mike-ai/stack.env` angepasst.
+
+Nach Installation, Update oder Recovery prüft der rein lesende Katalog-TÜV
+alle laufenden MCPs auf Handshake, Werkzeuganzahl, Schema-Größe, ungültige
+Regex-Muster und verbotene GitHub-Komplettbäume. Er ruft dabei kein fachliches
+Werkzeug auf und liest keine Chats oder Secrets:
+
+```bash
+sudo /opt/mike-ai/stack/dev/verify_mcp_catalogs.sh
+```
+
 Die rotierende, inhaltsfreie Metrikdatei liegt im persistenten
 OpenWebUI-Volume unter `mike-ai-request-metrics.jsonl` (maximal 5 MiB plus eine
 Rotation). Sie darf für Benchmarks ausgewertet werden, ohne Chats auszulesen.
@@ -104,13 +104,15 @@ sind ausdrücklich nicht Teil der Architektur. Standard ist read-only; jede
 Schreibaktion benötigt eine konkrete Vorschau, eine daran gebundene Freigabe
 und eine anschließende Verifikation.

-Der offizielle GitHub-MCP bietet nur vier Werkzeuge:
+Der offizielle GitHub-MCP bietet nur drei Werkzeuge:

 - Repository suchen
- Repositorybaum lesen
 - Dateiinhalt lesen
 - Code suchen

+Rekursive Komplettbäume sind absichtlich ausgeschlossen, weil sie bei großen
+Repositories den gesamten Modellkontext verdrängen können.
+
 Andere GitHub-Werkzeuge sowie Schreibzugriffe sind serverseitig deaktiviert.

 Für Entwicklung und Betrieb der KI-Plattform existiert ein zentraler Athena
@@ -234,8 +234,8 @@ Netzzugriff. Kein MCP-Port wird am Host veröffentlicht.
 |---|---|---|
 | Athena-Plattform | Architektur, Quellen, Laufzeitsnapshot, Dokumentationspflege | Lesen; Markdown nur Preview/Approval |
 | Athena Operator | vollständige Entwicklung und Betrieb der KI-Plattform | Lesen direkt; Änderungen nur Preview/Ticket/Approval |
-| Web | öffentliche Recherche über SearXNG/TinySearch/Crawl4AI sowie strukturierte YouTube-Kanal-, Video- und Transkriptabfragen | read-only; höchstens drei verwandte Aufrufe |
-| GitHub | Repositorysuche, Baum, Dateiinhalt, Code-Suche | strikt read-only, vier Tools |
+| Web | allgemeine Recherche nativ über Open WebUI; Spezialserver für YouTube und Hugging Face nur bei Bedarf | read-only; höchstens drei verwandte Aufrufe |
+| GitHub | Repositorysuche, gezielte Datei- und Code-Suche | strikt read-only, drei Tools |
 | Home Assistant | Zustände, Historie, Diagnose, begrenzte YAML-Abläufe | Lesen; Schreiben nur Preview/Approval |
 | ARR | Sonarr/Radarr, Indexersuche, kontrollierte Grabs | Lesen; Schreiben nur Preview/Approval |
 | Navidrome | Bibliothek, Empfehlungen, Playlists/Favoriten | eigener Benutzer; gezielt aktivieren |
@@ -271,11 +271,15 @@ reinen stdio-zu-Streamable-HTTP-Brücke. Aktiv sind ausschließlich:

 ```text
 search_repositories
-get_repository_tree
 get_file_contents
 search_code
 ```

+Ein rekursiver Komplettbaum ist absichtlich nicht verfügbar. Nutze zunächst
+`search_code` und lies danach nur die wirklich benötigten Dateien mit
+`get_file_contents`; so darf ein Monorepository nicht den Antwortkontext
+verdrängen.
+
 Der GitHub-Token liegt nur in `/etc/mike-ai/github-mcp.env` und nie in Open
 WebUI, Git oder einem Prompt. Für Quellcode, README, API-Routen und
 Repositorystruktur ist GitHub das richtige Werkzeug; die allgemeine Websuche
@@ -316,7 +320,7 @@ Nur-Lesen zurückkehren. Der Modus darf niemals stillschweigend erweitert werden
   Leseaufruf, verweigerter Schreibaufruf, Fehlerfall, Antwortgröße und
   Toolschleife.
 10. OpenWebUI-Verbindung versioniert installieren. Große Fachwerkzeuge nicht
-    automatisch an alle Profile hängen; vier kleine, eindeutige Lesetools sind
+    automatisch an alle Profile hängen; drei kleine, eindeutige GitHub-Lesetools sind
    eine bewusst dokumentierte Ausnahme.
 11. Recovery-, Komponenten-, Sicherheits- und Betriebsdokumentation ergänzen,
    Secret verschlüsselt sichern, Commit und Push durchführen.
@@ -0,0 +1,69 @@
+# Werkzeug-Zuverlässigkeit – Umbau vom 24. August 2026
+
+## Anlass
+
+Mehrere reale Aufgaben scheiterten nicht am Qwen-Modell, sondern an der
+Werkzeugschicht: öffentliche Suchen lieferten leere oder veraltete Resultate,
+ein rekursiver GitHub-Baum verdrängte die Antwort aus dem Kontext, eine private
+Bank-CSV wurde als Knowledge-Quelle statt als Tabelle behandelt und ein nicht
+erreichbarer Home-Assistant-Endpunkt provozierte Wiederholungen. Das System
+benötigte deshalb kleinere, klarere Werkzeuge und harte Abbruchgrenzen.
+
+## Verbindliche Lösung
+
+1. Allgemeine öffentliche Recherche verwendet Open WebUIs native
+   `search_web`- und `fetch_url`-Werkzeuge. Der eigene Web-MCP bleibt nur als
+   manuell zugeschalteter Spezialadapter für YouTube und Hugging Face.
+2. Der offizielle GitHub-MCP bietet genau drei read-only Werkzeuge:
+   `search_repositories`, `search_code` und `get_file_contents`. Rekursive
+   Komplettbäume sind ausgeschlossen.
+3. Private CSV-/Excel-Dateien werden ausschließlich mit dem lokalen
+   Code-Interpreter und pandas/openpyxl ausgewertet. Web, MCP und Knowledge/RAG
+   erhalten keine Dateiinhalte oder daraus abgeleitete Suchbegriffe. Der Filter
+   leert dafür die MCP-Auswahl und deaktiviert `features.web_search`; im
+   installierten OpenWebUI-Code läuft der Filter nachweislich vor der
+   Webwerkzeug-Injektion.
+4. Pro Antwort sind höchstens zwölf Werkzeugrunden erlaubt. Der zweite
+   identische Aufruf wird gestoppt. Ein einzelnes Resultat ist auf 10.000, alle
+   Resultate zusammen auf 36.000 Zeichen begrenzt.
+5. Der Home-Assistant-MCP behält den TLS-Namen `ha.casaderoll.de`, routet ihn
+   im Container aber auf `HOME_LAN_PROXY_IP` im Heimnetz. Dadurch funktioniert
+   er auch vom Außenstandort über WireGuard.
+6. Task-Management ist keine Faktenquelle und wird nicht für einzelne Fragen,
+   Nachschlageaufgaben oder Dateianalysen verwendet.
+
+## Abnahme
+
+- OpenWebUI-Filtertests: 28
+- Web-MCP-Tests: 9
+- Athena-Operator-Sicherheitstests: 11
+- Platform-Context-Test: bestanden
+- MCP-Katalog-TÜV: Handshake, Toolanzahl, Schema-Größe, Regex-Muster und
+  verbotene Tools; keinerlei fachliche Toolaufrufe
+- Gesamttest des Routers: Profile, Streaming, Tools, Bild, Sprache und
+  Fehlerwiederherstellung
+
+Der wiederholbare MCP-Test lautet:
+
+```bash
+sudo /opt/mike-ai/stack/dev/verify_mcp_catalogs.sh
+```
+
+Er muss mit `MCP_CATALOG_SUITE_OK` enden.
+
+## Noch manuell zu prüfen
+
+Ein echter Browsertest mit einer bewusst synthetischen CSV benötigt eine
+angemeldete OpenWebUI-Sitzung. Nach Login wird eine harmlose Beispieltabelle
+hochgeladen und geprüft, dass die Antwort sichtbare Summen enthält und in der
+Werkzeuganzeige ausschließlich lokale Datei-/Codewerkzeuge erscheinen. Für
+diesen Test dürfen niemals echte Bankdaten verwendet werden.
+
+## Rollback
+
+Vor dem Live-Umbau liegt die Quell- und Konfigurationssicherung unter
+`/data/mike-ai-recovery/pre-tooling-upgrade-20260823-235527`. OpenWebUIs
+Datenbank wurde zusätzlich unmittelbar vor Filter- und Modellinstallation
+gesichert. Ein Rollback betrifft ausschließlich Werkzeug-/OpenWebUI-Dateien;
+Netzwerk, SSH, WireGuard, Kernel, GPU-Treiber und Bootkonfiguration wurden nicht
+verändert.