search-scrape
Scraping Stealth auto-hospedado e Busca Federada para Agentes de IA. Uma alternativa 100% privada e gratuita ao Firecrawl, Jina Reader e Tavily. Com bypass universal anti-bot + Memória de Pesquisa Semântica, configuração copiar-colar.
Documentação
CortexScout (cortex-scout) — Mecanismo de Busca e Extração Web para Agentes de IA
O CortexScout é o módulo de Pesquisa Profunda e Extração Web dentro do ecossistema Cortex-Works.
Projetado para cargas de trabalho de agentes que exigem recuperação web eficiente em tokens, tratamento confiável anti-bot e fallback opcional com Humano-no-Loop (HITL).
Visão Geral
O CortexScout fornece um único binário Rust auto-hospedável que expõe capacidades de busca, extração e automação de navegador com estado via MCP (stdio) e um servidor HTTP opcional. Os formatos de saída são estruturados e otimizados para uso downstream com LLMs.
Ele foi construído para lidar com os modos de falha práticos da recuperação web (limites de taxa, desafios de bot, páginas com muito JavaScript) através de fallbacks progressivos: recuperação nativa → renderização via Chromium CDP → Testes E2E com Estado → fluxos HITL.
Ferramentas (Catálogo de Capacidades)
| Área | Ferramentas / Capacidades MCP |
|---|---|
| Busca | web_search (descoberta de URL) ou web_search(include_content=true) (busca+conteúdo em uma única chamada) |
| Busca e Rastreamento | `web_fetch(mode="single" |
| Extração | extract_fields (extração estruturada primária) |
| Automação | scout_browser_automate / browser_automate (omni-ferramenta com estado), scout_agent_profile_auth, scout_browser_close |
| Tratamento anti-bot | Renderização CDP, rotação de proxies, novas tentativas cientes de bloqueio |
| HITL | visual_scout, `hitl_web_fetch(auth_mode="challenge" |
| Memória | memory_search (histórico de pesquisa com suporte LanceDB) |
| Pesquisa profunda | deep_research (busca multi-salto + raspagem + síntese) |
Nomes legados permanecem chamáveis como aliases de compatibilidade (web_search_json, web_fetch_batch, web_crawl, fetch_then_extract, human_auth_session). Os agentes devem preferir as ferramentas primárias unificadas acima.
Integração com o Ecossistema
Embora o CortexScout funcione como uma ferramenta autônoma hoje, ele foi projetado para integrar-se ao CortexDB e ao CortexStudio para escalonamento multi-agente, artefatos de recuperação compartilhados e governança centralizada.
🎭 O "Playwright Killer" (Automação de Navegador com Estado)
O CortexScout inclui um mecanismo de automação CDP integrado e com estado, projetado especificamente para Agentes de IA, substituindo completamente frameworks pesados como Playwright ou Cypress para fluxos de teste E2E.
- A Omni-Ferramenta Silenciosa (
scout_browser_automate): Em vez de chamar dezenas de ferramentas de navegador, os agentes passam um único array desteps. O runtime agora cobre famílias de ações estilo Playwright em uma única chamada: navegação, hover/clique/digitação/espera, ações baseadas em localizadores, asserções, abas, capturas de tela/PDF, upload de arquivos, preenchimento de formulários, política de diálogos, ações de mouse por coordenadas, simulação de rotas, captura de console/rede e CRUD de cookies/armazenamento. - Perfil de Agente Persistente: A automação roda silenciosamente em segundo plano (
--headless=new) usando um perfil isolado dedicado (~/.cortex-scout/agent_profile). Ela mantém cookies, localStorage e estado de sessão entre chamadas de ferramentas sem causar colisões deSingletonLockcom seu navegador de desktop ativo. - Mecanismo de Mock, Trace e Verificação para QA: Os agentes podem instalar mocks de rotas (
mock_api,route_list,unroute) com sobrescrita/remoção de cabeçalhos de resposta, fluxos de trace (trace_start,trace_stop,trace_export), capturar logs de console/rede, criar checkpoints do estado do navegador e executar tanto asserções baseadas em CSS quanto em localizadores, além de auxiliares de verificação estilo Playwright. - O Portal de Autenticação do Agente (
scout_agent_profile_auth): Se o agente silencioso encontrar um CAPTCHA ou um login OAuth complexo (como Google/Microsoft) em um novo domínio, esta ferramenta inicia o perfil do agente em uma janela visível. Você resolve o CAPTCHA uma vez, os cookies são salvos e o agente retorna à automação silenciosa para sempre.
Mapa de Cobertura Estilo Playwright
| Área de Capacidade | Ações do Cortex Scout |
|---|---|
| Navegação e entrada | navigate, navigate_back, click, hover, type, press_key, scroll, wait_for, wait_for_selector, wait_for_locator |
| Localizador e verificação | click_locator, type_locator, assert, assert_locator, generate_locator, verify_element_visible, verify_text_visible, verify_list_visible, verify_value |
| Abas e mídia | tabs, resize, screenshot, snapshot, pdf_save, file_upload, fill_form, handle_dialog |
| Rede e mocks | network_tap, network_dump, network_state_set, mock_api, route_list, unroute |
| Estado do navegador | storage_clear, storage_state_export, storage_state_import, storage_checkpoint, storage_rollback, cookie_*, localstorage_*, sessionstorage_* |
| Controle de ponteiro de baixo nível | mouse_click_xy, mouse_down, mouse_move_xy, mouse_drag_xy, mouse_up, mouse_wheel |
A principal compensação em relação ao MCP Playwright puro é o empacotamento, não o formato das capacidades: o Cortex Scout mantém a superfície do navegador dentro de uma única omni-ferramenta com estado, para que os agentes gastem menos turnos e menos tokens coordenando fluxos de múltiplas etapas.
Eficácia Anti-Bot e Validação
Este repositório inclui artefatos de evidência capturados que validam fluxos de extração e HITL contra alvos protegidos representativos.
| Alvo | Proteção | Evidência | Notas |
|---|---|---|---|
| Cloudflare + Auth | JSON · Trecho | Extração de listagens protegidas por autenticação | |
| Ticketmaster | Cloudflare Turnstile | JSON · Trecho | Extração com desafio tratado |
| Airbnb | DataDome | JSON · Trecho | Grandes conjuntos de resultados sob controles de bot |
| Upwork | reCAPTCHA | JSON · Trecho | Recuperação de listagens protegidas |
| Amazon | AWS Shield | JSON · Trecho | Extração de resultados de busca |
| nowsecure.nl | Cloudflare | JSON | Caminho de retorno manual validado |
Consulte proof/README.md para metodologia e saídas brutas.
Início Rápido
Opção A — Binários pré-compilados
Baixe os artefatos de lançamento mais recentes do GitHub Releases e execute um dos seguintes:
cortex-scout-mcp— servidor MCP stdio (recomendado para VS Code / Cursor / Claude Desktop)cortex-scout— servidor HTTP opcional (porta padrão5000; substituível via--port,PORTouCORTEX_SCOUT_PORT)
Verificação de saúde (servidor HTTP):
./cortex-scout --port 5000
curl http://localhost:5000/health
Opção B — Compilar a partir do código-fonte
Instale o protoc primeiro. O lance-encoding usa Protocol Buffers durante a compilação de lançamento, portanto o protoc deve estar no seu PATH.
- macOS:
brew install protobuf - Ubuntu/Debian:
sudo apt-get install -y protobuf-compiler - Fedora:
sudo dnf install -y protobuf-compiler
Compilação básica (busca, raspagem, pesquisa profunda, memória):
git clone https://github.com/cortex-works/cortex-scout.git
cd cortex-scout
cargo build --release --manifest-path mcp-server/Cargo.toml --bin cortex-scout-mcp
Isso funciona a partir da raiz do repositório porque o caminho do manifesto é explícito.
Compilação completa (inclui hitl_web_fetch / HITL com navegador visível):
cargo build --release --manifest-path mcp-server/Cargo.toml --all-features --bin cortex-scout-mcp
Se você também quiser o binário opcional do servidor HTTP, compile-o explicitamente com cargo build --release --bin cortex-scout.
Teste local de fumaça do MCP:
python3 publish/ci/smoke_mcp.py
Isso executa uma sessão JSON-RPC stdio delimitada por novas linhas contra o binário local cortex-scout-mcp e exercita as principais ferramentas públicas com exemplos de entrada seguros.
Integração MCP (VS Code / Cursor / Claude Desktop)
Adicione uma entrada de servidor à sua configuração MCP.
VS Code (mcp.json — global, ou settings.json em mcp.servers):
As variáveis de guarda de timeout rígido abaixo são obrigatórias nas configurações MCP. Elas são a barreira de segurança que impede que uma página ruim, uma inicialização de navegador travada ou uma etapa de raspagem presa mantenham toda a sessão MCP aberta indefinidamente.
// mcp.json (global): top-level key is "servers"
// settings.json (workspace): use "mcp.servers" instead
{
"servers": {
"cortex-scout": {
"type": "stdio",
"command": "env",
"args": [
"RUST_LOG=warn",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS=90",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED=120",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=45",
"CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS=12",
"CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS=4",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS=20",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK=25",
"SEARCH_ENGINES=google,bing,duckduckgo,brave",
"LANCEDB_URI=/YOUR_PATH/cortex-scout/lancedb",
"HTTP_TIMEOUT_SECS=30",
"MAX_CONTENT_CHARS=10000",
"/YOUR_PATH/cortex-scout/mcp-server/target/release/cortex-scout-mcp"
]
}
}
}
O comportamento padrão é direto/sem proxy. Adicione IP_LIST_PATH e PROXY_SOURCE_PATH somente se você quiser ferramentas de proxy disponíveis. Se você quiser proxy_control disponível sem rotear o tráfego normal por proxies, aponte IP_LIST_PATH para um arquivo ip.txt vazio e deixe os agentes popularem-no sob demanda.
Importante: Sempre use
RUST_LOG=warn, nãoinfo. No nívelinfo, o servidor emite centenas de linhas de log por requisição para o stderr, o que pode confundir clientes MCP que monitoram o stderr.
Windows: O Windows não tem o comando
env. Use o formato de objetocommand+env— consulte docs/IDE_SETUP.md.
Com pesquisa profunda (síntese via LLM usando OpenRouter / qualquer API compatível com OpenAI):
{
"servers": {
"cortex-scout": {
"type": "stdio",
"command": "env",
"args": [
"RUST_LOG=warn",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS=90",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SEARCH_STRUCTURED=120",
"CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=45",
"CORTEX_SCOUT_BROWSER_LAUNCH_TIMEOUT_SECS=12",
"CORTEX_SCOUT_BROWSER_TAB_PROBE_TIMEOUT_SECS=4",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS=20",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_RETRY_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_FORCED_CDP_ATTEMPT=25",
"CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_NATIVE_CDP_FALLBACK=25",
"SEARCH_ENGINES=google,bing,duckduckgo,brave",
"LANCEDB_URI=/YOUR_PATH/cortex-scout/lancedb",
"HTTP_TIMEOUT_SECS=30",
"MAX_CONTENT_CHARS=10000",
"OPENAI_BASE_URL=https://openrouter.ai/api/v1",
"OPENAI_API_KEY=sk-or-v1-...",
"DEEP_RESEARCH_LLM_MODEL=moonshotai/kimi-k2.5",
"DEEP_RESEARCH_ENABLED=1",
"DEEP_RESEARCH_SYNTHESIS=1",
"DEEP_RESEARCH_SYNTHESIS_MAX_TOKENS=4096",
"/YOUR_PATH/cortex-scout/mcp-server/target/release/cortex-scout-mcp"
]
}
}
}
Guia multi-IDE: docs/IDE_SETUP.md
Configuração (cortex-scout.json)
Crie cortex-scout.json no mesmo diretório do binário (ou na raiz do repositório). Todos os campos são opcionais; variáveis de ambiente atuam como fallback.
{
"deep_research": {
"enabled": true,
"llm_base_url": "http://localhost:1234/v1",
"llm_api_key": "",
"llm_model": "lfm2-2.6b",
"synthesis_enabled": true,
"synthesis_max_sources": 3,
"synthesis_max_chars_per_source": 800,
"synthesis_max_tokens": 1024
}
}
Principais Variáveis de Ambiente
Núcleo
| Variável | Padrão | Descrição |
|---|---|---|
RUST_LOG | warn | Nível de log. Mantenha warn para MCP stdio — info inunda o stderr e confunde clientes MCP |
HTTP_TIMEOUT_SECS | 30 | Timeout de leitura por requisição (segundos) |
HTTP_CONNECT_TIMEOUT_SECS | 10 | Timeout de conexão TCP (segundos) |
OUTBOUND_LIMIT | 16 | Máximo de conexões HTTP de saída simultâneas |
MAX_CONTENT_CHARS | 10000 | Máximo de caracteres retornados por página raspada |
CORTEX_SCOUT_TOOL_TIMEOUT_SECS | específico da ferramenta | Limite superior rígido para cada chamada de ferramenta MCP/HTTP. Quando excedido, o Cortex Scout cancela a ferramenta e retorna uma resposta de timeout estruturada em vez de travar |
CORTEX_SCOUT_TOOL_TIMEOUT_SECS_<TOOL> | não definido | Substituição por ferramenta, por exemplo CORTEX_SCOUT_TOOL_TIMEOUT_SECS_SCRAPE_URL=90 ou CORTEX_SCOUT_TOOL_TIMEOUT_SECS_VISUAL_SCOUT=20 |
CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS | específico da etapa | Timeout compartilhado para etapas pesadas de raspagem, como fetch CDP, raspagem nativa, redução semântica e registro de histórico |
CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_<STAGE> | não definido | Substituição por etapa, por exemplo CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=30 |
Navegador / Anti-bot
| Variável | Padrão | Descrição |
|---|---|---|
CHROME_EXECUTABLE | detectado automaticamente | Substitui o caminho para o binário Chromium/Chrome/Brave |
SEARCH_CDP_FALLBACK | true | Repete buscas no mecanismo de busca via CDP nativo do Chromium quando bloqueado |
SEARCH_TIER2_NON_ROBOT | não definido | Defina 1 para permitir hitl_web_fetch como escalada de busca de último recurso |
MAX_LINKS | 100 | Máximo de links seguidos por rastreamento de página |
Busca
| Variável | Padrão | Descrição |
|---|---|---|
SEARCH_ENGINES | google,bing,duckduckgo,brave | Mecanismos ativos (separados por vírgula) |
SEARCH_MAX_ENGINES_PER_QUERY | 3 | Máximo de mecanismos consultados por busca antes que a rotação baseada em saúde selecione o próximo conjunto |
SEARCH_MAX_RESULTS_PER_ENGINE | 10 | Resultados por mecanismo antes da mesclagem/deduplicação |
SEARCH_ENGINE_STAGGER_MS | 125 | Atraso entre lançamentos por mecanismo para reduzir gatilhos anti-bot de rajada |
SEARCH_COMMUNITY_TRIGGER_RESULTS | 4 | Executar expansão de comunidade Reddit/HN somente quando a busca primária retornar menos que este número de resultados |
SEARCH_SHARED_CACHE | true | Compartilhar resultados de busca bem-sucedidos entre processos Cortex Scout concorrentes no mesmo host |
SEARCH_SHARED_CACHE_TTL_SECS | 300 | TTL para o cache de busca compartilhado entre processos |
SEARCH_HOST_MIN_GAP_MS | ajustado por mecanismo | Espaçamento mínimo entre processos para requisições a mecanismos de busca do mesmo IP de host |
SEARCH_HOST_MAX_GAP_MS | ajustado por mecanismo | Espaçamento máximo/jitter entre processos para requisições a mecanismos de busca do mesmo IP de host |
SCRAPE_HOST_MIN_GAP_MS | 900 | Espaçamento mínimo entre processos para requisições de scrape ao mesmo host |
SCRAPE_HOST_MAX_GAP_MS | 1800 | Espaçamento máximo/jitter entre processos para requisições de scrape ao mesmo host |
CORTEX_SCOUT_HOST_GUARD_DISABLED | false | Defina 1 somente se você quiser explicitamente desabilitar o throttling compartilhado no nível do host |
Proxy
| Variável | Padrão | Descrição |
|---|---|---|
IP_LIST_PATH | — | Caminho opcional para ip.txt (um proxy por linha: http://, socks5://). Deixe não definido para desabilitar suporte a proxy completamente, ou aponte para um arquivo vazio para manter as ferramentas de proxy disponíveis, mas inativas por padrão |
PROXY_SOURCE_PATH | — | Caminho opcional para proxy_source.json (usado por proxy_control grab) |
Memória Semântica (LanceDB)
| Variável | Padrão | Descrição |
|---|---|---|
LANCEDB_URI | — | Caminho do diretório para memória de pesquisa persistente. Omita para desabilitar |
CORTEX_SCOUT_MEMORY_DISABLED | 0 | Defina 1 para desabilitar memória mesmo quando LANCEDB_URI estiver definido |
MODEL2VEC_MODEL | embutido | ID do modelo HuggingFace ou caminho local para embeddings (ex.: minishlab/potion-base-8M) |
Pesquisa Profunda
| Variável | Padrão | Descrição |
|---|---|---|
DEEP_RESEARCH_ENABLED | 1 | Defina 0 para desabilitar a ferramenta deep_research em tempo de execução |
OPENAI_API_KEY | — | Chave de API para síntese LLM. Omita para endpoints locais sem chave (Ollama) |
OPENAI_BASE_URL | https://api.openai.com/v1 | Endpoint compatível com OpenAI (OpenRouter, Ollama, LM Studio, etc.) |
DEEP_RESEARCH_LLM_MODEL | gpt-4o-mini | Identificador do modelo (deve ser suportado pelo endpoint) |
DEEP_RESEARCH_SYNTHESIS | 1 | Defina 0 para pular síntese LLM (somente busca+scrape) |
DEEP_RESEARCH_HOP_TIMEOUT_SECS | 90 | Timeout de scrape por salto. Quando excedido, deep_research retorna resultados parciais em vez de travar até o chamador MCP expirar |
DEEP_RESEARCH_SYNTHESIS_MAX_TOKENS | 1024 | Máximo de tokens para resposta de síntese. Use 4096+ para modelos de contexto grande |
DEEP_RESEARCH_SYNTHESIS_MAX_SOURCES | 8 | Máximo de documentos-fonte alimentados à síntese LLM |
DEEP_RESEARCH_SYNTHESIS_MAX_CHARS_PER_SOURCE | 2500 | Máximo de caracteres extraídos por fonte para síntese |
Somente Servidor HTTP
| Variável | Padrão | Descrição |
|---|---|---|
CORTEX_SCOUT_PORT / PORT | 5000 | Porta de escuta para o binário do servidor HTTP (cortex-scout) |
Melhores Práticas para Agentes
Fluxo operacional recomendado:
- Chame
memory_searchantes de qualquer nova execução de pesquisa — pule a busca ao vivo se a similaridade ≥ 0,60 eskip_live_fetchfortrue. - Para descoberta de tópicos, use
web_searchpara descoberta somente de URLs, ouweb_search(include_content=true)para buscar e raspar os principais resultados em uma única ida e volta. - Para URLs conhecidas, use
web_fetch(mode="single")comoutput_format="clean_json", e definaquery+strict_relevance=truepara manter apenas seções relevantes. - Em 403/429: chame
proxy_controlcomaction:"grab"para atualizar a lista de proxies, depois tente novamente comuse_proxy:true. - Para páginas com acesso autenticado: execute
visual_scoutquandoauth_risk_score >= 0.4, depois usehitl_web_fetch(auth_mode="challenge")para muros CAPTCHA ouhitl_web_fetch(auth_mode="auth")para muros de login. - Para pesquisa profunda:
deep_researchlida automaticamente com busca multi-salto + scrape + síntese LLM. Ajustedepth(1–3) emax_sourcesconforme o orçamento de custo por execução. - Para automação de UI e testes E2E: use
scout_browser_automatecom arrays de etapas para abas, asserções de localizador, capturas de tela/PDF, mocks de rota, uploads de arquivos e configuração de estado do navegador. Se bloqueado por login inicial/CAPTCHA, chamescout_agent_profile_authe depois retome a automação.
FAQ
Por que deep_research com Ollama ou qwen3.5 às vezes falha ou volta ao modo heurístico?
Alguns modelos locais com capacidade de raciocínio retornam respostas /v1/chat/completions compatíveis com OpenAI com message.reasoning preenchido, mas message.content vazio. O Cortex Scout agora tenta novamente endpoints locais Ollama por meio de /api/chat nativo com think:false quando esse padrão é detectado.
Configuração recomendada para modelos locais Ollama classe 4B:
llm_api_key: ""emcortex-scout.jsoné válido e significa "sem autenticação necessária"- Mantenha
synthesis_max_sourcesem1-2 - Mantenha
synthesis_max_chars_per_sourceem torno de600-1000 - Mantenha
synthesis_max_tokensem torno de512-768
Se você ainda vir síntese lenta ou instável, reduza synthesis_max_sources antes de aumentar os limites de tokens.
Por que vejo erros de bloqueio de perfil do Chromium?
Cada requisição headless usa um perfil temporário único, então scraping normal e pesquisa profunda são seguros contra corridas de bloqueio de perfil. Somente fluxos HITL (como hitl_web_fetch) usando um perfil de navegador real podem encontrar bloqueio se você os executar concorrentemente ou tiver Brave/Chrome aberto no mesmo perfil. Para evitar: execute chamadas HITL uma de cada vez e feche todas as janelas do navegador antes de reutilizar um perfil.
Lista de verificação:
- Use uma build recente (2026-03-05 ou mais nova)
- Evite caminhos de perfil persistentes, a menos que precise de uma sessão logada
- Execute fluxos HITL/perfil sequencialmente
- Feche todas as janelas do navegador antes de reutilizar um perfil
- Deixe o Cortex Scout usar seus próprios perfis temporários para pesquisa concorrente
Meu cliente MCP conecta, mas as ferramentas falham ou expiram imediatamente. O que devo verificar primeiro?
Verifique isto antes de qualquer outra coisa:
- Use
RUST_LOG=warn, nãoinfo. - Em macOS/Linux, em configurações estilo
env, passe o caminho do binário diretamente após as atribuições de env. Não insira"--"nos argumentos demcp.json. - No Windows, não use
env; usecommandmais um objetoenv. - Certifique-se de que o caminho do binário aponte para uma build atual.
Versionamento e Changelog
Veja CHANGELOG.md.
Licença
MIT. Veja LICENSE.