search-rotation
Rotação de busca na web e extração de páginas nos níveis gratuitos de vários provedores, com um painel local para chaves, ordem dos mecanismos e status de cota.
Documentação
Um servidor MCP para busca na web e extração de páginas em vários provedores.
Criado por Robin Bially.
Rotacione entre cotas disponíveis, faça failover automaticamente quando um provedor estiver indisponível e retorne resultados consistentes ao seu assistente de IA. Um painel local permite gerenciar chaves de API, reordenar mecanismos, verificar cotas e inspecionar o histórico de requisições.
Interface real do painel, exibida em inglês com dados de demonstração ilustrativos. Chamadas e orçamentos dos provedores são exibidos separadamente; as barras de atividade oferecem detalhes por intervalo de tempo e por mecanismo.
Início rápido
npm
npx -y search-rotation --http --open
Requer Node.js 20.3+. Para MCP via stdio, configure seu cliente para executar
npx -y search-rotation sem argumentos. O servidor também está listado no
registro oficial de MCP
como io.github.robin-bially/search-rotation.
Homebrew
brew install robin-bially/tap/search-rotation
search-rotation --http --open
O Homebrew instala o runtime Node.js necessário. Para MCP via stdio, configure seu
cliente para executar search-rotation sem argumentos. Consulte o
Homebrew tap para atualizações e detalhes.
Versão fixa do GitHub
npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.4.11
Use esta opção quando quiser uma versão fixa em vez da versão atual do npm.
Adicione suas chaves de provedor no painel e conecte seu assistente usando o guia de configuração do cliente MCP para Codex, Claude, Cursor ou OpenCode.
O que você obtém
- Busca e extração: rotação independente para busca na web e extração de páginas em Markdown.
- Failover automático: ordenação ciente de cotas, períodos de espera por limite de taxa e timeouts de requisição.
- Painel local: chaves de API, ordem de mecanismos por arrastar e soltar, chamadas e erros por mecanismo, saldos de cotas separados e histórico interativo de requisições.
- Local ou remoto: MCP via stdio ou Streamable HTTP autenticado.
Provedores: Tavily · Firecrawl · Parallel · Exa · Google PSE · Jina Reader · DuckDuckGo HTML. Acesso sem chave e contabilização de cotas variam por provedor.
Ferramentas MCP
web_search · fetch_url · engine_status · open_dashboard
A aba Ferramentas MCP do painel explica cada ferramenta, seus parâmetros e exemplos de chamadas copiáveis.
Interface real do painel, exibida em inglês.
Filtros de tempo de busca
web_search aceita os seguintes argumentos:
| Parâmetro | Significado |
|---|---|
query | Texto de busca obrigatório. |
numResults | Contagem opcional de resultados, 1–20; caso contrário, a configuração do painel é aplicada. |
engine | Provedor preferido, sujeito ao suporte de filtro de tempo e disponibilidade; o failover permanece ativado. |
timeRange | day, week, month ou year: janela de data UTC começando há 1, 7, 30 ou 365 dias, até hoje. |
startDate | Limite inferior de data opcional no formato YYYY-MM-DD. |
endDate | Limite superior de data opcional no formato YYYY-MM-DD. |
Use timeRange ou datas explícitas. Limites unilaterais e datas de início e fim iguais são permitidos; datas de calendário inválidas, limites invertidos e mistura de filtros relativos e explícitos são rejeitados antes de qualquer requisição ao provedor.
{"name":"web_search","arguments":{"query":"AI inference research","timeRange":"week","numResults":5}}
{"name":"web_search","arguments":{"query":"AI inference research","startDate":"2026-08-01","endDate":"2026-08-31"}}
Janelas relativas são resolvidas uma vez por requisição em datas UTC, inclusive durante failover. Estes são filtros de data, não janelas exatas de 24 horas; month e year significam 30 e 365 dias, não aritmética de calendário. A Exa recebe o início do primeiro dia UTC e o fim do último dia UTC.
Suporte do provedor e rotação
| Provedor / acesso | Janela relativa | Dois limites de data | Um limite de data |
|---|---|---|---|
| Tavily, com ou sem chave | Sim | Sim | Sim |
| Firecrawl, com ou sem chave | Sim | Sim | Ignorado |
| Exa, API direta com chave | Sim | Sim | Sim |
| Exa, MCP hospedado sem chave | Ignorado | Ignorado | Ignorado |
| Parallel, qualquer modo de acesso | Ignorado | Ignorado | Ignorado |
| Google PSE / DuckDuckGo HTML | Ignorado | Ignorado | Ignorado |
Esta tabela descreve o suporte implementado no search-rotation, não todos os recursos upstream. A Tavily recebe start_date / end_date, a Firecrawl recebe um intervalo tbs personalizado e a Exa recebe startPublishedDate / endPublishedDate. A Firecrawl é excluída conservadoramente para datas unilaterais; os outros caminhos ignorados não têm mapeamento de data implementado.
O roteador exclui provedores incompatíveis antes das verificações de cota e rotação, inclusive quando um engine incompatível é preferido. Cada pool de provedores elegíveis tem seu próprio cursor de rotação, então misturar buscas filtradas e não filtradas não deixa provedores sem uso. Prioridades de cota existentes, períodos de espera, regras estritas de gratuidade e failover se aplicam dentro desse pool. Se nenhum provedor compatível estiver disponível, a busca falha explicitamente; ela nunca tenta novamente sem o filtro. Buscas sem argumentos de tempo mantêm acesso a todos os provedores elegíveis.
Os resultados mostram uma data de publicação quando fornecida pelo adaptador, e o histórico de requisições inclui o período solicitado. Os metadados de data do provedor podem ser estimados ou ausentes: a Tavily filtra datas de publicação ou atualização, a Exa filtra datas de publicação estimadas e a Firecrawl usa a interpretação de data do índice de busca. A inclusão exata dos limites segue o provedor; isso não é uma verificação independente da data de publicação de cada página. Consulte as referências da Tavily, Firecrawl e Exa.
Após atualizar, reconecte seu cliente MCP para carregar o novo esquema de ferramentas.
Lançamento
VERSION=0.4.10 ./scripts/release.sh --publish
O script verifica o pacote (npm ci, build, testes, npm run smoke:package), incrementa a versão, aponta os pins do documento para ela, faz commit e tag, empacota o tarball com seu checksum, cria o release no GitHub, atualiza a fórmula em robin-bially/homebrew-tap e, por fim, aguarda até que o registro npm sirva a nova versão. Sem --publish, ele apenas prepara os artefatos em .build/releases; --dry-run verifica os pré-requisitos, --draft cria um rascunho de release e --force tolera uma árvore suja. O tap é clonado temporariamente quando TAP_DIR não está definido, então um checkout limpo é suficiente.
A publicação no npm acontece em .github/workflows/publish.yml por meio de publicação confiável assim que o release do GitHub é publicado, então o script em si não precisa de credenciais npm. O workflow exige um editor confiável para search-rotation no npmjs.com que aponte para este repositório e publish.yml.
O mesmo workflow registra a versão no registro oficial de MCP a partir de server.json. Distribuição e listagens rastreia cada canal, quem o mantém atualizado e o que cada um ainda precisa.
Saiba mais
Configuração do cliente · Operações e configuração (DE) · Distribuição e listagens · Releases · CI · Licença MIT