Documentation de Searchgirl

Searchgirl a quatre visages servis par le même binaire. Cette page parcourt chacun d’eux, le moteur SearXNG en dessous, et le mode suite (fédéré).

L’interface web

http://localhost:8089 — un accueil avec suggestions, des résultats par catégorie (Général, Actualités, Images, Vidéos, Science, IT et plus), des filtres langue/date/SafeSearch, des réponses directes et des infoboxes, et un thème clair/sombre. Les miniatures passent par le proxy propre à Searchgirl (/thumb) : votre navigateur ne touche jamais les hôtes des moteurs.

L’API REST

Endpoint	Ce qu’il fait
`GET /api/search?q=...`	Recherche. Paramètres : `category`, `language`, `time_range` (day/week/month/year), `safesearch` (0-2), `page`, `engines`.
`GET /api/suggest?q=...`	Autocomplétion.
`POST /api/answer`	Synthèse IA avec citations : `{"query": "...", "fetch_pages": true}` — 503 sans LLM.
`POST /api/read`	URL → Markdown : `{"url": "https://..."}`.
`GET /api/engines` · `/api/categories`	Catalogue des moteurs/catégories.
`GET /api/config`	Version, mode d’authentification, disponibilité du LLM.
`GET /healthz`	Liveness.

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

La réponse est une forme normalisée et stable — déduplication par URL, score, domaine, dates ISO — indépendante du JSON brut de SearXNG.

MCP (pour Claude Code, Claude Desktop ou tout client MCP)

Le serveur MCP tourne sur http://localhost:8089/mcp (transport HTTP streamable). Outils :

search — métarecherche avec category, language, time_range, max_results.
url_read — récupère une URL publique en Markdown (avec une protection SSRF).
answer — recherche + synthèse avec citations [n] (n’apparaît que si un LLM est configuré).

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

Si vous définissez SEARCHGIRL_MCP_TOKEN, ajoutez l’en-tête :

claude mcp add --transport http searchgirl https://votre-domaine/mcp \
  --header "Authorization: Bearer <votre jeton>"

Vous préférez stdio ? Le même binaire : searchgirl serve (sans -http) parle MCP via stdio — il doit pouvoir atteindre SearXNG (décommentez le mapping 127.0.0.1:8090:8080 dans le compose et exportez SEARXNG_URL=http://localhost:8090). Pour l’usage quotidien, le /mcp HTTP est la voie recommandée.

Réponse IA (optionnelle, désactivée par défaut)

Avec un modèle configuré, le bouton Réponse IA apparaît dans l’interface, ainsi que POST /api/answer et l’outil MCP answer : elle cherche, prend les meilleures sources et rédige une réponse courte citant [1][2], avec la liste des sources en pied de page. Sans modèle, tout le reste fonctionne à l’identique.

# Anthropic (natif — prioritaire s'il est défini) :
ANTHROPIC_API_KEY=sk-ant-...

# ou tout endpoint compatible OpenAI — Ollama local, OpenRouter, DeepSeek :
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-or-...

SearXNG sous le capot

La configuration du moteur vit dans searxng/settings.yml :

search.formats: [html, json] — essentiel : sans json, l’API renvoie 403.
server.limiter: false — SearXNG n’est pas exposé ; c’est Searchgirl qui assure la limitation de débit.
autocomplete: duckduckgo — active /api/suggest.

SearXNG est livré avec environ 200 moteurs actifs par défaut. Pour les trier, ajoutez à settings.yml :

use_default_settings:
  engines:
    remove: [qwant, startpage]   # ceux qui n'arrêtent pas d'échouer chez vous

et docker compose restart searxng.

Authentification, jetons et limitation de débit

Connexion locale — un utilisateur (SEARCHGIRL_USER/SEARCHGIRL_PASS), l’écran Escriba standard ; tout est verrouillé jusqu’à la connexion.
Jetons Bearer — SEARCHGIRL_MCP_TOKEN accepte plusieurs jetons nommés (claude:abc...,n8n:def...) ; en révoquer un revient à le retirer de la liste, sans faire tourner les autres. Les jetons se combinent avec la connexion locale comme avec la fédération — les humains se connectent, les agents utilisent le jeton.
Limitation de débit — par IP sur l’API, le MCP et la connexion (SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST). Derrière un reverse proxy, définissez SEARCHGIRL_TRUSTED_PROXIES pour que la limite voie l’IP réelle du client via X-Forwarded-For.

Mode suite (fédéré avec Lockatus)

Dans le docker-compose.suite.yml de la Suite Escriba, Searchgirl rejoint l’ensemble sur le port 8089 avec AUTH_MODE=federado : authentification unique via Lockatus (PKCE S256, cookie HMAC), sans connexion locale. L’accès se gouverne depuis la matrice du hub (rôles admin/usuario). Pour un déploiement SSO en production — enregistrer le client searchgirl, les règles exactes de redirect_uri et la vérification — voir la section fédération de DEPLOY.md.

Voir sur GitHub