Documentação do Searchgirl

O Searchgirl tem quatro faces servidas pelo mesmo binário. Esta página percorre cada uma delas, o motor SearXNG por baixo, e o modo suíte (federado).

A interface web

http://localhost:8089 — uma home com sugestões, resultados por categoria (Geral, Notícias, Imagens, Vídeos, Ciência, TI e mais), filtros de idioma/data/SafeSearch, respostas diretas e infoboxes, e um tema claro/escuro. As miniaturas passam pelo proxy próprio do Searchgirl (/thumb): seu navegador nunca toca os hosts dos motores.

A API REST

Endpoint	O que faz
GET /api/search?q=...	Busca. Parâmetros: category, language, time_range (day/week/month/year), safesearch (0-2), page, engines.
GET /api/suggest?q=...	Autocompletar.
POST /api/answer	Síntese de IA com citações: {"query": "...", "fetch_pages": true} — 503 sem um LLM.
POST /api/read	URL → Markdown: {"url": "https://..."}.
GET /api/engines · /api/categories	Catálogo de motores/categorias.
GET /api/config	Versão, modo de autenticação, disponibilidade de LLM.
GET /healthz	Liveness.

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

A resposta é um formato normalizado e estável — dedup por URL, score, domínio, datas ISO — independente do JSON cru do SearXNG.

MCP (para o Claude Code, o Claude Desktop ou qualquer cliente MCP)

O servidor MCP roda em http://localhost:8089/mcp (transporte HTTP streamable). Ferramentas:

• search — metabusca com category, language, time_range, max_results.
• url_read — busca uma URL pública como Markdown (com proteção contra SSRF).
• answer — busca + síntese com citações [n] (só aparece se um LLM estiver configurado).

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

Se você definiu SEARCHGIRL_MCP_TOKEN, adicione o header:

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

Prefere stdio? O mesmo binário: searchgirl serve (sem -http) fala MCP via stdio — ele precisa alcançar o SearXNG (descomente o mapeamento 127.0.0.1:8090:8080 no compose e exporte SEARXNG_URL=http://localhost:8090). Para o dia a dia, o /mcp via HTTP é o caminho recomendado.

Resposta de IA (opcional, desativada por padrão)

Com um modelo configurado, o botão Resposta de IA aparece na interface, junto com o POST /api/answer e a ferramenta MCP answer: ele busca, pega as melhores fontes e escreve uma resposta curta citando [1][2], com a lista de fontes no rodapé. Sem um modelo, todo o resto funciona sem mudanças.

# Anthropic (nativo — tem prioridade se definido):
ANTHROPIC_API_KEY=sk-ant-...

# ou qualquer endpoint compatível com OpenAI — Ollama local, OpenRouter, DeepSeek:
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-or-...

O SearXNG por baixo do capô

A configuração do motor vive em searxng/settings.yml:

• search.formats: [html, json] — essencial: sem json a API retorna 403.
• server.limiter: false — o SearXNG não é exposto; o Searchgirl fornece o rate limiting.
• autocomplete: duckduckgo — habilita o /api/suggest.

O SearXNG vem com cerca de 200 motores ativos por padrão. Para curá-los, adicione ao settings.yml:

use_default_settings:
  engines:
    remove: [qwant, startpage]   # os que vivem falhando para você

e docker compose restart searxng.

Autenticação, tokens e rate limiting

• Login local — um usuário (SEARCHGIRL_USER/SEARCHGIRL_PASS), a tela padrão do Escriba; tudo fica bloqueado até o login.
• Tokens Bearer — SEARCHGIRL_MCP_TOKEN aceita vários tokens nomeados (claude:abc...,n8n:def...); revogar um é removê-lo da lista, sem rotacionar os demais. Os tokens se combinam tanto com o login local quanto com a federação — humanos fazem login, agentes usam o token.
• Rate limiting — por IP em API, MCP e login (SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST). Atrás de um reverse proxy, defina SEARCHGIRL_TRUSTED_PROXIES para que o limite veja o IP real do cliente via X-Forwarded-For.

Modo suíte (federado com o Lockatus)

No docker-compose.suite.yml da Suíte Escriba, o Searchgirl entra na porta 8089 com AUTH_MODE=federado: single sign-on via Lockatus (PKCE S256, cookie HMAC), sem login local. O acesso é governado pela matriz do hub (papéis admin/usuario). Para um deployment SSO em produção — registrar o cliente searchgirl, as regras exatas de redirect_uri e a verificação — veja a seção de federação do DEPLOY.md.

Nota

O detalhe completo — cada variável de ambiente, deployment painel por painel, tabelas de troubleshooting e o modelo de segurança — vive no README e no DEPLOY.md do repositório.

Ver no GitHub