Documentazione di Searchgirl

Searchgirl ha quattro volti serviti dallo stesso binario. Questa pagina li percorre uno per uno, insieme al motore SearXNG sottostante e alla modalità suite (federata).

L’interfaccia web

http://localhost:8089 — una home con suggerimenti, risultati per categoria (Generale, Notizie, Immagini, Video, Scienza, IT e altre), filtri per lingua/data/SafeSearch, risposte dirette e infobox, e un tema chiaro/scuro. Le miniature passano attraverso il proxy proprio di Searchgirl (/thumb): il tuo browser non tocca mai gli host dei motori.

L’API REST

Endpoint	Cosa fa
`GET /api/search?q=...`	Ricerca. Parametri: `category`, `language`, `time_range` (day/week/month/year), `safesearch` (0-2), `page`, `engines`.
`GET /api/suggest?q=...`	Completamento automatico.
`POST /api/answer`	Sintesi IA con citazioni: `{"query": "...", "fetch_pages": true}` — 503 senza un LLM.
`POST /api/read`	URL → Markdown: `{"url": "https://..."}`.
`GET /api/engines` · `/api/categories`	Catalogo di motori/categorie.
`GET /api/config`	Versione, modalità di autenticazione, disponibilità dell’LLM.
`GET /healthz`	Liveness.

curl "http://localhost:8089/api/search?q=searxng&category=news&time_range=week"

La risposta è una forma normalizzata e stabile — deduplicazione per URL, punteggio, dominio, date ISO — indipendente dal JSON grezzo di SearXNG.

MCP (per Claude Code, Claude Desktop o qualsiasi client MCP)

Il server MCP gira su http://localhost:8089/mcp (trasporto HTTP streamable). Strumenti:

search — metaricerca con category, language, time_range, max_results.
url_read — recupera un URL pubblico come Markdown (con protezione SSRF).
answer — ricerca + sintesi con citazioni [n] (compare solo se è configurato un LLM).

# Claude Code:
claude mcp add --transport http searchgirl http://localhost:8089/mcp

Se imposti SEARCHGIRL_MCP_TOKEN, aggiungi l’header:

claude mcp add --transport http searchgirl https://tuo-dominio/mcp \
  --header "Authorization: Bearer <il tuo token>"

Preferisci stdio? Lo stesso binario: searchgirl serve (senza -http) parla MCP via stdio — deve poter raggiungere SearXNG (decommenta la mappatura 127.0.0.1:8090:8080 nel compose ed esporta SEARXNG_URL=http://localhost:8090). Per l’uso quotidiano, l’/mcp via HTTP è la strada consigliata.

Risposta IA (opzionale, disattivata per impostazione predefinita)

Con un modello configurato, nell’interfaccia compare il pulsante Risposta IA, insieme a POST /api/answer e allo strumento MCP answer: cerca, prende le fonti migliori e scrive una risposta breve citando [1][2], con l’elenco delle fonti in fondo. Senza un modello, tutto il resto funziona invariato.

# Anthropic (nativo — ha priorità se impostato):
ANTHROPIC_API_KEY=sk-ant-...

# oppure qualsiasi endpoint compatibile OpenAI — Ollama locale, OpenRouter, DeepSeek:
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-or-...

SearXNG sotto il cofano

La configurazione del motore vive in searxng/settings.yml:

search.formats: [html, json] — essenziale: senza json l’API restituisce 403.
server.limiter: false — SearXNG non è esposto; la limitazione di frequenza la fornisce Searchgirl.
autocomplete: duckduckgo — abilita /api/suggest.

SearXNG arriva con circa 200 motori attivi per impostazione predefinita. Per curarli, aggiungi a settings.yml:

use_default_settings:
  engines:
    remove: [qwant, startpage]   # quelli che continuano a fallirti

e docker compose restart searxng.

Autenticazione, token e limitazione di frequenza

Login locale — un utente (SEARCHGIRL_USER/SEARCHGIRL_PASS), la schermata standard di Escriba; tutto resta protetto fino all’accesso.
Token Bearer — SEARCHGIRL_MCP_TOKEN accetta diversi token con nome (claude:abc...,n8n:def...); revocarne uno significa toglierlo dall’elenco, senza ruotare gli altri. I token si combinano sia con il login locale sia con la federazione — gli umani accedono, gli agenti usano il token.
Limitazione di frequenza — per IP su API, MCP e login (SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST). Dietro un reverse proxy, imposta SEARCHGIRL_TRUSTED_PROXIES così il limite vede l’IP reale del client via X-Forwarded-For.

Modalità suite (federata con Lockatus)

Nel docker-compose.suite.yml della Suite Escriba, Searchgirl si unisce sulla porta 8089 con AUTH_MODE=federado: single sign-on via Lockatus (PKCE S256, cookie HMAC), senza login locale. L’accesso è governato dalla matrice dell’hub (ruoli admin/usuario). Per un deployment SSO in produzione — registrare il client searchgirl, le regole esatte per la redirect_uri e la verifica — vedi la sezione sulla federazione di DEPLOY.md.

Vedi su GitHub