web-search-mcp

Português | English

Servidor MCP autônomo que pesquisa na web, abre as páginas, lê o conteúdo e devolve um resumo com as fontes para o agente que chamou. Três tools — research_web, analyze_urls e read_url — para qualquer agente (Claude Code, LangChain, LangGraph, etc). Sem framework de agente embutido: só FastMCP.

Não é um MCP para o SearXNG. A busca é própria e tem duas fontes:

• Google via Tor, a principal. O servidor consulta o Google (pelo endpoint do Google CSE) através de quatro canais Tor, alternando as queries entre eles. Quando o Google barra um canal, a query refaz em outro na hora e o barrado troca de IP em segundo plano.

• SearXNG, a reserva. Só entra quando o Google falha por todos os caminhos — ou sempre, se você preferir, com SEARCH_BACKEND=searxng.

A stack inteira (quatro containers Tor + SearXNG) vem pronta num docker compose em search-engine/. Detalhes em De onde vêm os links.

A ideia: pesquisar num contexto isolado

A pesquisa inteira acontece fora da janela de contexto do agente principal. Ele manda uma pergunta em linguagem natural e recebe de volta um resumo curto — nunca vê o material bruto.

                     ┌─────────────────────────────────────────────┐
  agente principal   │  web-search-mcp (contexto próprio)          │
  ────────────────   │                                             │
                     │  1. gera variantes de busca (LLM)           │
  "quem foi X?"  ──► │  2. busca em paralelo (Google via Tor;      │
                     │     SearXNG de reserva)                     │
                     │  3. triagem por título/trecho (LLM) e abre  │
                     │     só as páginas escolhidas                │
                     │     + ponte quando nada lido cita o nome    │
                     │  4. monta o dossiê ....... 15-50k chars     │
                     │  5. resume com as fontes (LLM)              │
       resumo   ◄──  │                          ....... ~700 tokens│
     ~700 tokens     └─────────────────────────────────────────────┘

Sem isso, uma pesquisa séria significa despejar dezenas de milhares de tokens de HTML e texto extraído na conversa principal — material que fica lá ocupando espaço em todas as chamadas seguintes, mesmo depois de já ter sido usado. Aqui esse custo é pago num processo separado, com o LLM que você escolher, e o que atravessa é só a resposta.

Na prática:

• O contexto do agente não incha. Ele gasta ~700 tokens por pesquisa em vez dos 6k-20k tokens do material lido. Conversas longas com muitas pesquisas continuam viáveis.

• Dá para usar um modelo barato na parte cara. Quem lê 5 páginas e resume pode ser um modelo local pequeno; o agente principal, o caro, só recebe o resultado pronto.

• A resposta vem citada. O resumo traz as URLs realmente consultadas e um carimbo de data/hora, então dá para conferir a fonte em vez de confiar.

• Uma chamada resolve. O research_web já busca vários ângulos por dentro e lê em paralelo — o agente não precisa orquestrar rodadas de busca.

O analyze_urls aplica a mesma ideia a links que o usuário já tem: "resuma estes três artigos", "compare as duas propostas" — lê as páginas aqui dentro e devolve só a análise. Quando você quer o texto cru mesmo — "leia este link para mim" — é o read_url que serve, e aí o conteúdo vai inteiro para o agente, sem resumo.

Related MCP server: myscrape

De onde vêm os links: Google via Tor, SearXNG de reserva

O research_web busca no Google pelo endpoint do Google CSE (o mesmo que o widget de busca embutida usa), através de quatro canais Tor. O SearXNG continua na stack, mas como reserva.

Por quê. Um SearXNG raspa os buscadores e, no uso normal, toma CAPTCHA e limite de taxa: medido em 29/08/2026 e de novo em 10/09/2026, 13 de 15 motores suspensos. O que sobra devolve casamento de nome de marca — duas perguntas técnicas diferentes chegaram a voltar a mesma lista de homepages. No A/B de 10/09/2026 (evals/search_ab.py, 12 perguntas de assuntos sem relação entre si, mesmas variantes de busca nos dois lados):

Em carga contínua (20 pesquisas seguidas, 80 consultas) 100% saíram pelo Tor, com 5 failovers entre canais e nenhuma queda para o SearXNG; a busca subiu para p50 9,7 s. Isso foi medido com dois canais — os quatro atuais existem para repartir essa carga, e ainda não foram medidos.

Como uma query anda. Nenhum passo espera:

1. o canal da vez no rodízio;

2. barrado pelo Google → esse canal troca de circuito em segundo plano (credencial SOCKS nova + NEWNYM) e a query refaz na hora em outro canal;

3. barrado de novo → um terceiro canal (com só dois, volta ao primeiro, já com circuito novo);

4. o CSE pelo IP da própria máquina (GOOGLE_CSE_DIRECT_FALLBACK);

5. o SearXNG (SEARXNG_FALLBACK).

Quando a query chega ao SearXNG e a maioria dos motores dele está suspensa, a resposta começa com um aviso de busca degradada, dizendo ao agente que a cobertura está incompleta por causa da infraestrutura — não porque o assunto não existe — e que repetir a pesquisa não vai adiantar. Sem esse aviso o agente reformula a pergunta em loop.

Só a busca passa pelo Tor. As páginas são abertas direto, desta máquina. SEARCH_BACKEND=searxng desliga o Google e volta ao SearXNG puro — rollback é trocar a variável e reiniciar.

Ressalvas:

• Não é API documentada. Se o Google mudar o formato, o parse falha alto e a busca cai no SearXNG em vez de quebrar.

• O CX default é público e de terceiro (blackle.com, o mesmo que o motor google cse do SearXNG usa). Pode sumir; GOOGLE_CSE_CX troca sem mexer no código.

• O fallback direto não é garantido. O IP de casa também tomou 429 do CSE no dia da medição.

• Termos de uso. Consulta automatizada ao Google, ainda mais via Tor, contraria os termos do Google. Avalie antes de usar; com SEARCH_BACKEND=searxng nada disso acontece.

Medições, decisões e riscos em plans/tor.md.

Requisitos

• Python ≥ 3.13

• uv

• A stack de busca: quatro containers Tor (a fonte de links é o Google CSE, consultado por eles) e um SearXNG de reserva, com formato JSON habilitado — tudo num docker compose pronto em search-engine/. Sem os Tor a busca ainda funciona (CSE direto, depois SearXNG); SEARCH_BACKEND=searxng usa só o SearXNG

• Um servidor de LLM com API compatível com OpenAI (/v1/chat/completions e /v1/models) — ex. llama.cpp server, vLLM, ou a própria OpenAI

Infraestrutura de busca via docker compose

search-engine/ traz a stack de busca inteira, já nas portas que são o default do .env.example. Numa cópia nova do repo:

cp .env.example .env          # troque TOR_CONTROL_PASSWORD
cd search-engine
docker compose up -d --wait

A primeira subida compila a imagem Tor localmente (search-engine/tor/: Alpine com o pacote tor fixado em 0.4.9.12-r0), então demora mais e precisa de internet. Se o Alpine tirar essa versão do repositório, a compilação falha — atualize o número no Dockerfile. O --wait segura o comando até os canais Tor ficarem healthy (o bootstrap leva até ~60 s); sem ele, as pesquisas desse intervalo caem no CSE direto e no SearXNG.

Sobe:

Os containers Tor leem o mesmo .env da raiz que configura o MCP (env_file: ../.env), então a senha do ControlPort é uma só e não há como os dois lados divergirem. Sem o .env o compose falha na hora. As portas Tor só escutam em 127.0.0.1: publicar em 0.0.0.0 transformaria a máquina num proxy aberto. Dentro do container há uma segunda barreira: o torrc só aceita SOCKS vindo de faixas privadas (SocksPolicy), e o ControlPort exige a senha.

Os serviços mcp-searxng e caddy são um servidor MCP de busca de terceiros — este projeto fala com o SearXNG direto, por HTTP. Se você não os usa, pode removê-los do compose sem afetar em nada o web-search-mcp.

Antes de subir isso em qualquer lugar que não seja sua máquina, troque as senhas. Os placeholders estão versionados neste repositório e portanto são públicos:

• TOR_CONTROL_PASSWORD (no .env) — quem tiver a senha controla o tor

• SEARXNG_SECRET (em search-engine/docker-compose.yaml) — chave com que o SearXNG assina; deve ser um valor aleatório e longo, ex. openssl rand -hex 32

• o Bearer password123 do search-engine/searxng/caddy/Caddyfile — é a única autenticação na frente do mcp-searxng, cuja porta 8887 é publicada no host. Quem souber o token usa o serviço

Tudo de uma vez: start.sh

./start.sh

Cria o .env a partir do .env.example se ele não existir, lembra quais variáveis conferir (MODEL_BASE_URL, MODEL_API_KEY, TOR_CONTROL_PASSWORD, MCP_HOST/MCP_PORT) e espera um Enter. Depois confere se as portas e os nomes de container estão livres, sobe o search-engine/ e inicia o MCP em streamable-http. No fim mostra a URL para plugar o cliente (http://127.0.0.1:8765/mcp por padrão). Ctrl+C derruba tudo: o MCP e os containers (docker compose down; volumes preservados). Se o MCP cair sozinho, a stack cai junto. Argumentos extras vão para o web-search-mcp.

O LLM continua externo: se MODEL_BASE_URL não responder, o script avisa e sobe assim mesmo — read_url funciona sem ele, research_web e analyze_urls não.

Instalação

A partir do GitHub (não precisa clonar)

uvx --from git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2 web-search-mcp

Registro no Claude Code:

claude mcp add web-search \
  -e SEARXNG_URL=http://localhost:8886 \
  -e MODEL_BASE_URL=http://localhost:8200/v1 \
  -- uvx --from git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2 web-search-mcp

Instalado assim, o .env não é lido: a configuração inteira entra por -e — ver Configurando o servidor instalado. @v0.2.2 fixa essa versão. Troque por @main para sempre pegar o topo do branch, ou por qualquer outra tag ou commit.

Para deixar o comando fixo no PATH em vez de resolver a cada execução:

uv tool install git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2

A partir do clone (desenvolvimento)

uv sync
cp .env.example .env

Edite o .env: MODEL_BASE_URL do seu servidor de modelo e TOR_CONTROL_PASSWORD (os containers Tor leem este mesmo arquivo). Com a stack do search-engine/ nas portas default, SEARXNG_URL e TOR_CHANNELS já batem. O servidor sobe com os defaults se você não copiar nada, mas sem LLM em MODEL_BASE_URL o research_web e o analyze_urls não funcionam, e sem busca nenhuma no ar (Tor, CSE direto e SearXNG) o research_web não acha links — o read_url funciona sozinho.

Uso

Dois transportes, mesmas tools. A diferença é quem sobe o processo — e isso muda de onde vem a configuração.

stdio (padrão — para Claude Code e clientes locais)

uv run web-search-mcp

Na prática você não roda isso à mão: quem executa é o cliente. Registro no Claude Code apontando para o clone:

claude mcp add web-search -- uv --directory /caminho/para/web_search_mcp run web-search-mcp

Para registrar a versão instalada do GitHub, com a configuração no bloco env, ver Configurando o servidor instalado.

HTTP (compartilhar entre vários agentes)

Suba o servidor. Do clone, que lê o .env da raiz:

uv run web-search-mcp --http

Ou instalado, passando a configuração pelo ambiente:

SEARXNG_URL=http://localhost:8886 \
MODEL_BASE_URL=http://localhost:8200/v1 \
uvx --from git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2 web-search-mcp --http

Sobe em http://{MCP_HOST}:{MCP_PORT}/mcp (padrão 127.0.0.1:8765).

Com ele no ar, registre o cliente pela URL:

claude mcp add --transport http web-search http://127.0.0.1:8765/mcp

Que no .mcp.json fica:

{
  "mcpServers": {
    "web-search": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

No modo http o bloco env do cliente não tem efeito. No stdio o cliente spawna o processo, então o -e dele vira o ambiente do servidor; no http o processo é seu e já está rodando quando o cliente conecta, com o ambiente que você deu na hora de subir. Toda a configuração migra para o lado do servidor, e trocar uma variável exige reiniciá-lo — editar o .mcp.json não adianta.

Deixando rodando (systemd de usuário, sem sudo)

# ~/.config/systemd/user/web-search-mcp.service
[Unit]
Description=web-search-mcp (http)
After=network.target

[Service]
Environment=MODEL_BASE_URL=http://localhost:8200/v1
# Busca: Google CSE pelos quatro canais Tor do search-engine/, SearXNG de reserva
Environment=SEARCH_BACKEND=google_tor
Environment=TOR_CHANNELS=127.0.0.1:9060:9061,127.0.0.1:9070:9071,127.0.0.1:9080:9081,127.0.0.1:9090:9091
Environment=SEARXNG_URL=http://localhost:8886
# TOR_CONTROL_PASSWORD fica fora da unit, num arquivo só seu (chmod 600)
EnvironmentFile=%h/.config/web-search-mcp/secrets.env
ExecStart=%h/.local/bin/uvx --from git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2 web-search-mcp --http
Restart=on-failure

[Install]
WantedBy=default.target

A senha do ControlPort é a mesma do .env que os containers Tor leem. Ela não vai na unit porque systemctl --user cat/show exibem cada Environment= para quem olhar:

mkdir -p ~/.config/web-search-mcp
install -m 600 /dev/null ~/.config/web-search-mcp/secrets.env
echo 'TOR_CONTROL_PASSWORD=a-mesma-do-.env-do-search-engine' > ~/.config/web-search-mcp/secrets.env

systemctl --user daemon-reload
systemctl --user enable --now web-search-mcp

A unit não depende dos containers: o search-engine/ sobe sozinho no boot (restart: unless-stopped), e se os canais Tor ainda não estiverem no ar quando a primeira pesquisa chegar, ela cai no CSE direto e depois no SearXNG em vez de falhar. As linhas SEARCH_BACKEND e TOR_CHANNELS repetem os defaults — estão ali para ficar explícito o que mudar se os canais estiverem em outro host ou em outras portas. Rodando do clone (WorkingDirectory= apontando para ele e uv run web-search-mcp --http), o .env da raiz é lido e nenhuma dessas linhas é necessária.

Antes de expor esse endpoint além da sua máquina, note que o servidor não tem autenticação nenhuma. Com o default MCP_HOST=127.0.0.1 só processos locais alcançam, o que é seguro. Trocar para 0.0.0.0 para outra máquina consumir deixa as tools abertas a qualquer um na rede, sem credencial e servindo de proxy de scraping em cima do seu LLM. Nesse caso ponha um reverse proxy com token na frente e restrinja MCP_CORS_ALLOW_ORIGINS às origens que você usa, em vez de deixar *.

Tools

research_web(query: str, recent: bool = False, *, user_message: str) -> str

Pesquisa a pergunta na web (gera variantes de busca — sempre incluindo a pergunta em palavras-chave, com os nomes intactos —, roda em paralelo, faz uma triagem dos candidatos por título e trecho e lê só os escolhidos) e devolve um resumo em português, com carimbo de data/hora. Quando nenhuma página lida contém um nome da pergunta (nome localizado, apelido), faz uma busca curta pela palavra que anda junto com esse nome nos títulos dos resultados e lê essas páginas primeiro — é o que liga "Pai Putrefato" a "Mystic Carrion". Cada fato termina com um link markdown para a página de onde saiu, montado em código a partir da URL realmente lida — não pedido ao modelo. Marcador [n] que o modelo inventar para uma fonte que não existe é apagado, em vez de ficar apontando para o nada. No fim vai a lista numerada das URLs consultadas.

Use recent=True só quando a resposta depende do dia de hoje (clima, cotação, placar, notícia). Para fatos estáveis (história, biografia, conceitos), deixe recent=False — filtrar por data descarta as melhores fontes.

user_message (obrigatório) é a última mensagem do usuário, copiada literalmente. O agente que chama costuma traduzir ou trocar o nome que o usuário escreveu antes mesmo da primeira pesquisa ("Pai Putrefato" vira "Rotting Bride"). Quando a query perdeu um nome que está na mensagem, a pesquisa também busca pelos nomes da mensagem e usa o texto original na triagem e no resumo. Se a mensagem só repete a query, nada muda. Medido em 11/09/2026 com o agente do Open WebUI (qwen3.8:27B): resposta certa em 10 de 10 conversas, contra 6 de 10 sem o campo, com menos pesquisas por conversa. Opcional, o agente só preenchia o campo em 9 de 20 chamadas; por isso ele é obrigatório.

A mesma pergunta reescrita logo em seguida (mesmo conjunto de palavras de conteúdo, em qualquer ordem) devolve o resultado anterior em vez de buscar de novo: a tool já busca vários ângulos por dentro, e repetir só relê as mesmas páginas. Busca degradada vem com o aviso descrito em De onde vêm os links.

Agente que pesquisa em círculo trocando a pergunta a cada volta (o que escapa do cache acima) é freado por sessão: chamadas de research_web e analyze_urls que começam logo depois da anterior contam como o mesmo turno; a partir da 3ª o resultado vem com aviso para parar e pedir o nome exato ao usuário, e a 5ª não é executada.

analyze_urls(urls: list[str], request: str = "Resuma o conteúdo.") -> str

Lê de 1 a 8 URLs fornecidas e devolve só a análise pedida em linguagem natural — resumo, parecer técnico, opinião, comparação —, feita pelo LLM deste servidor. O texto das páginas não entra no contexto do agente. O orçamento de caracteres do dossiê é repartido entre as páginas, para que todas caibam juntas. A resposta lista as URLs analisadas e as que falharam.

read_url(url: str) -> str

Abre uma URL específica e devolve o conteúdo principal da página em Markdown, inteiro, sem busca nem resumo — o texto bruto volta pro agente processar. Vem com um cabeçalho Fonte desta página e um link markdown pronto, para o agente citar o que leu com endereço.

Nas duas tools que leem URLs, se o servidor redirecionar para outro endereço (ex. uma página que não existe mais caindo na home), a resposta avisa e usa a URL final. Sem esse aviso o agente lê a página errada sem saber e tenta de novo em loop. As duas bloqueiam URLs que apontam para IP privado/loopback/link-local (proteção anti-SSRF).

Prompt pesquisador

O servidor também expõe um prompt MCP com a política de uso: pesquisar antes de responder o que não se sabe com certeza, uma chamada por pergunta, responder só com base no resumo e manter os links e as datas.

Configuração

Nenhuma variável é obrigatória. Toda uma tem default no código, e o servidor sobe sem configuração alguma. Você só declara o que desviar do padrão — na prática, MODEL_BASE_URL, se o seu não estiver na porta abaixo, e TOR_CONTROL_PASSWORD, que os containers Tor exigem.

A lista completa, com o default de cada uma:

Log

Modelo (API compatível com OpenAI)

Busca (Google CSE via Tor)

O caminho de cada query está em De onde vêm os links.

SearXNG (reserva)

Usado quando o Google falhou por todos os caminhos, ou sempre, com SEARCH_BACKEND=searxng. Só o SEARXNG_MAX_RESULTS vale também para o Google.

Scraper

Research

Servidor MCP

Juiz do eval

Sobre MCP_HOST e MCP_CORS_ALLOW_ORIGINS: o servidor não tem autenticação nenhuma. Com os defaults ele só escuta em 127.0.0.1, o que restringe o acesso à sua máquina. Trocar MCP_HOST para 0.0.0.0 expõe as tools para qualquer um na rede, sem credencial — o que permite usar seu servidor como proxy de scraping e queimar seu LLM. Se precisar compartilhar na rede, ponha um reverse proxy com autenticação na frente e restrinja MCP_CORS_ALLOW_ORIGINS às origens que você de fato usa.

De onde a configuração vem

Isto não depende do transporte: a leitura acontece no import do config, antes de stdio ou http entrarem em cena. O que decide é onde o config.py está.

load_dotenv() procura o .env subindo a partir do diretório do config.py. No clone isso chega na raiz do projeto e acha o arquivo; instalado, o config.py mora no site-packages e a busca não encontra nada — nem mesmo um .env que exista no diretório de onde o servidor foi executado. Instalado, portanto, tudo entra por variável de ambiente.

De onde sai essa variável de ambiente, aí sim depende do transporte: no stdio, do bloco env do cliente (-e), que é quem spawna o processo; no http, do ambiente de quem subiu o processo — export, systemd, compose.

A precedência é variável de ambiente > .env > default, porque o load_dotenv() roda sem override. Útil no clone para testar uma variação sem editar arquivo:

MODEL_BASE_URL=http://localhost:8205/v1 uv run web-search-mcp --http

Configurando o servidor instalado

Declare no bloco env do registro:

claude mcp add web-search \
  -e SEARXNG_URL=http://localhost:8886 \
  -e MODEL_BASE_URL=http://localhost:8200/v1 \
  -e MODEL_CONTEXT_TOKENS=65536 \
  -e TZ=America/Sao_Paulo \
  -- uvx --from git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2 web-search-mcp

Note que MODEL não aparece: deixado de fora, o servidor usa o modelo já carregado no seu MODEL_BASE_URL. Passe -e MODEL=nome-do-modelo só para fixar um.

O comando acima grava isto no .mcp.json (escopo de projeto) ou no ~/.claude.json (escopo de usuário, com -s user):

{
  "mcpServers": {
    "web-search": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fabio-barboza/web_search_mcp@v0.2.2", "web-search-mcp"],
      "env": {
        "SEARXNG_URL": "http://localhost:8886",
        "MODEL_BASE_URL": "http://localhost:8200/v1"
      }
    }
  }
}

O que entra em env fica em texto puro nesse arquivo. Para SEARXNG_URL e MODEL_BASE_URL isso não tem consequência, mas se o seu provedor de LLM exigir uma MODEL_API_KEY real, ela vai parar no .mcp.json — que costuma ser versionado quando está no escopo de projeto. Nesse caso registre com claude mcp add -s user, que grava em ~/.claude.json, fora do repositório.

A busca via Tor não pede nada no bloco env se a stack do search-engine/ estiver na mesma máquina: o default de TOR_CHANNELS já aponta para os quatro canais em 127.0.0.1. O TOR_CONTROL_PASSWORD é opcional para o MCP — sem ele só o NEWNYM desliga — e, se você passar por -e, vale a mesma ressalva da MODEL_API_KEY: fica em texto puro no arquivo.

Detecção de modelo

Quando MODEL fica vazio, cada chamada de LLM consulta GET {MODEL_BASE_URL}/models para achar o modelo já carregado, em vez de forçar um específico (evita pagar reload de GPU a troco de nada). Não há cache: se outro cliente trocou o modelo no servidor, a próxima chamada já usa o novo. Funciona nativamente com routers que expõem status de load (ex. llama.cpp/llama-swap); em providers genéricos, cai no único modelo da lista ou pede pra você preencher MODEL explicitamente se houver ambiguidade.

A mesma consulta traz, nesses routers, os argumentos com que o modelo subiu: o --ctx-size dali define o orçamento do dossiê, no lugar do MODEL_CONTEXT_TOKENS.

Testes

uv run --group test pytest

Tudo determinístico — mocka rede e LLM, não precisa de SearXNG nem de modelo rodando.

Eval

uv run python -m evals.run

Roda um conjunto fixo de perguntas contra a web e o LLM reais, mede faithfulness (afirmações do resumo suportadas pelo dossiê) e relevância, e salva o resultado em evals/results/. Não é teste de CI — a web muda entre execuções — serve para comparar rodadas e pegar alucinação escancarada, não como avaliação independente (o juiz costuma ser o mesmo modelo que escreveu o resumo).

uv run python -m evals.search_ab [--load 20] [--hl pt-BR en]

A/B da fonte de links: SearXNG × Google CSE via Tor na mesma sessão, com as mesmas variantes de busca nos dois lados, seguido de uma carga contínua que mede taxa de bloqueio por canal, failovers e quedas para o CSE direto e o SearXNG. Precisa dos canais Tor e do SearXNG no ar. Foi daqui que saíram os números de De onde vêm os links.

Estrutura

src/web_search_mcp/
  server.py         # FastMCP: tools, prompt, transporte, main()
  config.py         # única fonte de configuração (lê o .env inteiro)
  llm.py            # chat completion via requests, detecção de modelo e de contexto
  tools/
    research.py     # tool: pesquisa, lê páginas, resume com fontes
    analyze.py      # tool: lê URLs fornecidas e devolve só a análise
    read_url.py     # tool: lê uma URL específica
  util/
    search_chain.py # fonte de links: Google via Tor, SearXNG de reserva
    google_cse.py   # cliente do Google CSE, com failover entre canais
    tor.py          # canais Tor: rodízio e troca de circuito
    searxng.py      # cliente do SearXNG
    scraper.py      # download (curl_cffi, impressão TLS do Chrome) + extração (anti-SSRF)
tests/              # pytest, sem rede, sem LLM
evals/              # roda contra web/LLM reais, sob demanda
search-engine/      # docker compose da busca: SearXNG + canais Tor (dependência externa)
plans/              # planos de mudança aprovados
start.sh            # sobe search-engine/ + MCP em --http; Ctrl+C derruba tudo

Layout src/ de propósito: o pacote instalado ocupa um único namespace (web_search_mcp), em vez de despejar server/config/util na raiz do site-packages e colidir com outros pacotes.