Upgrade local web gateway with structured YouTube support

platform/web-search/README.md

@@ -1,23 +1,46 @@
-# Lokale Websuche
+# Professionelles lokales Web-Gateway
 
-SearXNG übernimmt die Metasuche. TinySearch normalisiert, crawlt und rankt die
-Ergebnisse lokal. Nur die Web-MCP-Fassade wird dem Modell angeboten; die
-generischen TinySearch-Werkzeuge bleiben intern.
+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. `docker compose up -d` ausführen.
-5. TinySearch bleibt ausschließlich über `127.0.0.1:8000` erreichbar.
+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` ist die kompakte, für kleinere Modelle optimierte Fassade.
-Sie bietet nur `web_search`, `web_compare`, `web_shop` und `web_research` an
-und verwendet für GitHub und Hugging Face zusätzlich strukturierte APIs.
+`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
 
@@ -28,3 +51,20 @@ und verwendet für GitHub und Hugging Face zusätzlich strukturierte APIs.
 - 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.