# Professionelles lokales Web-Gateway

Das Web-Gateway stellt Qwen eine kleine, eindeutige Werkzeugoberfläche bereit.
Intern übernimmt SearXNG die private Metasuche und TinySearch mit Crawl4AI das
Abrufen, Extrahieren und lokale Reranking. YouTube wird strukturiert über
`yt-dlp` und den offiziellen Kanalfeed gelesen. Dadurch landen keine
Consent-Seiten im Modellkontext.

Die Architektur ist absichtlich keine selbst entwickelte Suchmaschine. Das
eigene MCP ist eine gehärtete Fassade über austauschbaren Spezialkomponenten.
GitHub bleibt ein eigenes MCP und wird nicht in diese Vertrauensgrenze gemischt.

## Installation

1. `searxng-settings.example.yml` nach `searxng-settings.yml` kopieren.
2. `CHANGE_ME_GENERATE_RANDOM_SECRET` durch einen zufälligen Wert ersetzen.
3. `tinysearch_config.json` prüfen.
4. `platform/mcp/install-tools.sh` als root ausführen.
5. SearXNG und TinySearch bleiben nur im privaten Docker-Netz erreichbar.

Die Containerimages sind per Digest festgeschrieben. Upgrades erfolgen nur
bewusst nach Test von Suche, Crawling, Quellenbindung und Kontextgröße.

`web_search_mcp.py` bietet genau sechs Werkzeuge:

| Werkzeug | Aufgabe |
|---|---|
| `web_search` | Schnelle, aktuelle Suche und URL-Entdeckung mit optionalem Zeitfilter |
| `web_read` | Eine bekannte öffentliche URL auslesen, ohne erneut zu suchen |
| `web_youtube` | Neuste Kanalvideos, Suche, Metadaten und Untertitel/Transkript |
| `web_compare` | Eine Behauptung anhand ausgelesener Quellen verifizieren |
| `web_shop` | Produkt-, Händler- und Preisprüfung mit strenger Quellenbindung |
| `web_research` | Begrenzte mehrstufige Recherche mit mehreren Quellen |

## Auswahlregeln für kleine Modelle

- Eine bekannte URL wird mit `web_read`, nicht mit `web_search`, geöffnet.
- YouTube-Fragen gehen immer an `web_youtube`.
- Eine zu prüfende Behauptung geht an `web_compare`.
- Eine breite oder schwierige Recherche geht einmal an `web_research`.
- Das Gateway blockiert nach drei semantisch ähnlichen externen Aufrufen. Die
  Grenze wird technisch erzwungen und steht nicht nur im System-Prompt.
- Bei aktuellen Fragen wird Wikipedia nicht als generischer Fallback benutzt.

## Modellfreundliche Vorgaben

- kurze Suche: maximal fünf Ergebnisse
- Recherche: maximal vier gecrawlte Seiten und acht Evidenz-Chunks
- höchstens zwei Chunks je Quelle
- Seitenlimit 6000 Tokens, Chunkziel 300 Tokens
- externe Inhalte immer als nicht vertrauenswürdig markieren
- GitHub und Hugging Face bevorzugt über strukturierte öffentliche APIs
- Preise erst nach Prüfung der tatsächlichen Händlerseite als bestätigt melden
- YouTube: maximal zehn strukturierte Treffer, Untertitel maximal 12.000 Zeichen
- keine Shell-Auswertung von Benutzereingaben; `yt-dlp` läuft mit fester
  Argumentliste, Zeitlimit und begrenzter Ausgabe
- alle Webseiten, Beschreibungen und Transkripte sind nicht vertrauenswürdige
  Daten und niemals auszuführende Anweisungen

## Reproduzierbarkeit und Upgrade

`yt-dlp` ist im Web-MCP-Image fest versioniert. SearXNG und TinySearch bleiben
per OCI-Digest festgeschrieben. Ein Upgrade erfolgt bewusst in dieser Reihenfolge:

1. `python3 -m unittest -v dev/test_web_search_mcp.py`
2. Compose-Konfiguration prüfen.
3. Nur `mcp-web` neu bauen und starten.
4. `tools/list`, normale Suche, `web_read` und den Proper-People-Kanal testen.
5. Erst danach die vollständige Tool-Installation beziehungsweise ein neues
   Recovery-Bundle erzeugen.