# Werkzeugarchitektur ab 24. August 2026

## Ziel

Athena darf nicht für jede neue Website oder jede neue Verwaltungsaufgabe ein
neues Werkzeug benötigen. Die Plattform stellt deshalb breite Grundfähigkeiten
bereit und ergänzt sie nur dort durch Fach-MCPs, wo eine strukturierte API einen
echten Vorteil bietet.

## Die drei Ebenen

1. **Breites Web:** OpenWebUI hält `search_web` und `fetch_url` in allen
   normalen Profilen verfügbar. MakerWorld, eBay, Herstellerseiten oder eine
   morgen neu entstehende Website benötigen keine Selector-Änderung. Für
   Hermes, Pi und andere MCP-Clients liegt derselbe allgemeine Einsatzzweck über
   den unveränderten TinySearch-Upstream-MCP auf VPN-Port 8203 bereit.
2. **Breiter Operator:** Der Athena Operator enthält neben strukturierten
   Plattformaktionen ein ausgabebegrenztes allgemeines Terminal. Es deckt
   Docker, Compose, Dateien, Git, HTTP/API, Modellarbeit und SSH zu
   konfigurierten Zielsystemen ab. Eine kleine serverseitige Sperre verhindert
   ausschließlich Strombefehle und Änderungen an Athenas SSH, LAN, WireGuard,
   Firewall, Boot, Kernel, Mounts und Partitionen, weil Athena physisch nicht
   erreichbar ist.
3. **Fach-MCPs:** Home Assistant, MUA/Unraid, ARR, Navidrome und GitHub bleiben
   erhalten. Sie liefern kurze strukturierte Ergebnisse und domänenspezifische
   Schreibabläufe. Sie sind der bevorzugte Weg, aber keine Schranke: Fehlt eine
   Spezialoperation, darf der Operator die Aufgabe allgemein erledigen.

OpenWebUI ist Oberfläche und Komfortschicht. Der Auto Tool Selector hält Web
bereit und hängt anhand der Anfrage passende Fachkataloge an. Er verweigert
keine Fähigkeit und erfordert keine Site-spezifischen Regeln. Alle zentralen
MCPs sind über feste WireGuard-Ports auch für Hermes und Pi erreichbar.

## Agentische Grenzen

- maximal 48 interne Werkzeugrunden
- maximal 40 tatsächlich ausgeführte Einzelaufrufe
- maximal 12 Aufrufe desselben Werkzeugnamens
- identischer Werkzeugname mit identischen Argumenten darf einmal wiederholt
  werden; der dritte identische Aufruf wird unterdrückt
- ein unterdrückter Parallelaufruf beendet nicht mehr die gesamte Recherche,
  solange im selben Stapel noch sinnvolle Aufrufe vorhanden sind
- bei ausgeschöpftem Budget folgt zwingend eine werkzeugfreie, sichtbare
  Schlussantwort aus den bereits erhobenen Befunden
- Werkzeugausgaben bleiben kurz: 12.000 Zeichen je Ergebnis und 64.000 Zeichen
  über den Verlauf. Die Begrenzung sitzt in OpenWebUIs interner
  Fortsetzungsschleife und greift daher auch auf Resultate, die erst nach dem
  ersten Modellschritt entstehen.

Damit stoppt die Plattform bewiesene Schleifen, nicht normale lange Recherche.
Die früheren Grenzen von zwölf Gesamtaufrufen und vier Aufrufen je Werkzeug
waren für Qwen3.8-Agentenaufgaben zu klein.

## Webwege

| Client | Standardweg |
|---|---|
| OpenWebUI | native `search_web` und `fetch_url`, immer verfügbar |
| Hermes/Pi/andere MCP-Clients | `http://192.168.1.212:8203/mcp` (TinySearch; laufender Alt-Gateway zusätzlich 8211 bis zum nächsten geplanten WireGuard-Neustart) |
| Spezial-/Rollbackbedarf | historischer `mcp-web` nur mit Compose-Profil `legacy-web` |

TinySearch stellt die vier Upstream-Werkzeuge `search`, `scrape_urls`,
`research` und `get_current_datetime` bereit. Die frühere selbstgeschriebene
Web-Fassade wird nicht mehr standardmäßig gestartet und liegt nur für Rollback
im Repository.

## Sicherheitsgrenze

Über die WireGuard-Adresse sind die Dienste normal nutzbar. Auf der physischen
Universitätsadresse bleiben UI, Router und MCP-Ports geschlossen. Die
Terminal-Sperre schützt ausschließlich die entfernte Erreichbarkeit; sie ist
kein allgemeiner Funktions- oder Internetfilter.

## Abnahme

Nach Änderungen müssen mindestens folgende Prüfungen erfolgreich sein:

1. `python3 dev/test_openwebui_filters.py`
2. `python3 dev/test_athena_operator.py`
3. `docker compose -f compose.yaml config -q`
4. `docker compose -f platform/mcp/compose.yaml config -q`
5. `dev/verify_mcp_catalogs.sh`
6. Browserlauf mit einer unbekannten öffentlichen Website, GitHub plus
   Laufzeitprüfung sowie einer mehrstufigen Home-/Unraid-Aufgabe

Produktive Abnahme am 24. August 2026:

- MakerWorld ohne Site-Adapter: 12 Werkzeugaufrufe, verifizierter Treffer mit
  Downloadzahl und Direktlink, sichtbare Antwort nach 102,5 Sekunden
- GitHub + Unraid + Athena: 12 gezielte Repository-Leseaufrufe plus
  Laufzeitprüfung; vorhandenen Deemix-Backendcontainer korrekt wiederverwendet
- Home Assistant YAML: drei auskommentierte Automatisierungen gefunden, ohne
  vollständige Zustandsliste und mit sichtbarer Abschlussantwort nach 88,0 Sekunden
- absichtlicher Großausgabetest: 2.169 Home-Assistant-Zustände in einem
  Werkzeugresultat; durch V7 intern verdichtet und nach 30,9 Sekunden korrekt
  mit ausschließlich Anzahl und Testsatz beantwortet