Documentación de Searchgirl

Searchgirl tiene cuatro caras servidas por el mismo binario. Esta página recorre cada una, el motor SearXNG por debajo, y el modo suite (federado).

La interfaz web

http://localhost:8089 — una portada con sugerencias, resultados por categoría (General, Noticias, Imágenes, Videos, Ciencia, IT y más), filtros de idioma/fecha/SafeSearch, respuestas directas e infoboxes, y tema claro/oscuro. Las miniaturas pasan por el proxy propio de Searchgirl (/thumb): tu navegador nunca toca los hosts de los motores.

La API REST

Endpoint	Qué hace
`GET /api/search?q=...`	Búsqueda. Parámetros: `category`, `language`, `time_range` (day/week/month/year), `safesearch` (0-2), `page`, `engines`.
`GET /api/suggest?q=...`	Autocompletado.
`POST /api/answer`	Síntesis IA con citas: `{"query": "...", "fetch_pages": true}` — 503 sin un LLM.
`POST /api/read`	URL → Markdown: `{"url": "https://..."}`.
`GET /api/engines` · `/api/categories`	Catálogo de motores/categorías.
`GET /api/config`	Versión, modo de auth, disponibilidad de LLM.
`GET /healthz`	Liveness.

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

La respuesta es una forma normalizada y estable — deduplicación por URL, puntaje, dominio, fechas ISO — independiente del JSON crudo de SearXNG.

MCP (para Claude Code, Claude Desktop o cualquier cliente MCP)

El servidor MCP corre en http://localhost:8089/mcp (transporte HTTP streamable). Herramientas:

search — metabúsqueda con category, language, time_range, max_results.
url_read — descarga una URL pública como Markdown (con protección SSRF).
answer — búsqueda + síntesis con citas [n] (solo aparece si hay un LLM configurado).

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

Si definiste SEARCHGIRL_MCP_TOKEN, agrega la cabecera:

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

¿Prefieres stdio? El mismo binario: searchgirl serve (sin -http) habla MCP por stdio — necesita alcanzar SearXNG (descomenta el mapeo 127.0.0.1:8090:8080 en el compose y exporta SEARXNG_URL=http://localhost:8090). Para el uso diario, el /mcp por HTTP es el camino recomendado.

Respuesta IA (opcional, apagada por defecto)

Con un modelo configurado, el botón de Respuesta IA aparece en la interfaz, junto con POST /api/answer y la herramienta MCP answer: busca, toma las mejores fuentes y escribe una respuesta corta citando [1][2], con la lista de fuentes al pie. Sin modelo, todo lo demás funciona sin cambios.

# Anthropic (nativo — tiene prioridad si está definido):
ANTHROPIC_API_KEY=sk-ant-...

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

SearXNG por debajo

La configuración del motor vive en searxng/settings.yml:

search.formats: [html, json] — esencial: sin json la API devuelve 403.
server.limiter: false — SearXNG no está expuesto; el límite de tasa lo pone Searchgirl.
autocomplete: duckduckgo — habilita /api/suggest.

SearXNG trae unos 200 motores activos por defecto. Para curarlos, agrega a settings.yml:

use_default_settings:
  engines:
    remove: [qwant, startpage]   # los que te sigan fallando

y docker compose restart searxng.

Auth, tokens y límite de tasa

Login local — un usuario (SEARCHGIRL_USER/SEARCHGIRL_PASS), la pantalla estándar de Escriba; todo queda protegido hasta iniciar sesión.
Tokens Bearer — SEARCHGIRL_MCP_TOKEN acepta varios tokens con nombre (claude:abc...,n8n:def...); revocar uno es quitarlo de la lista, sin rotar el resto. Los tokens se combinan tanto con el login local como con la federación — los humanos inician sesión, los agentes usan el token.
Límite de tasa — por IP en API, MCP y login (SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST). Detrás de un reverse proxy, define SEARCHGIRL_TRUSTED_PROXIES para que el límite vea la IP real del cliente vía X-Forwarded-For.

Modo suite (federado con Lockatus)

En el docker-compose.suite.yml de la Suite Escriba, Searchgirl se une en el puerto 8089 con AUTH_MODE=federado: inicio de sesión único vía Lockatus (PKCE S256, cookie HMAC), sin login local. El acceso se gobierna desde la matriz del hub (roles admin/usuario). Para un despliegue SSO en producción — registrar el cliente searchgirl, las reglas exactas de redirect_uri y la verificación — mira la sección de federación de DEPLOY.md.

Ver en GitHub