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).

MIT License Built with Rust MCP


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)

ÁreaFerramentas / Capacidades MCP
Buscaweb_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çãoextract_fields (extração estruturada primária)
Automaçãoscout_browser_automate / browser_automate (omni-ferramenta com estado), scout_agent_profile_auth, scout_browser_close
Tratamento anti-botRenderização CDP, rotação de proxies, novas tentativas cientes de bloqueio
HITLvisual_scout, `hitl_web_fetch(auth_mode="challenge"
Memóriamemory_search (histórico de pesquisa com suporte LanceDB)
Pesquisa profundadeep_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 de steps. 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 de SingletonLock com 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 CapacidadeAções do Cortex Scout
Navegação e entradanavigate, navigate_back, click, hover, type, press_key, scroll, wait_for, wait_for_selector, wait_for_locator
Localizador e verificaçãoclick_locator, type_locator, assert, assert_locator, generate_locator, verify_element_visible, verify_text_visible, verify_list_visible, verify_value
Abas e mídiatabs, resize, screenshot, snapshot, pdf_save, file_upload, fill_form, handle_dialog
Rede e mocksnetwork_tap, network_dump, network_state_set, mock_api, route_list, unroute
Estado do navegadorstorage_clear, storage_state_export, storage_state_import, storage_checkpoint, storage_rollback, cookie_*, localstorage_*, sessionstorage_*
Controle de ponteiro de baixo nívelmouse_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.

AlvoProteçãoEvidênciaNotas
LinkedInCloudflare + AuthJSON · TrechoExtração de listagens protegidas por autenticação
TicketmasterCloudflare TurnstileJSON · TrechoExtração com desafio tratado
AirbnbDataDomeJSON · TrechoGrandes conjuntos de resultados sob controles de bot
UpworkreCAPTCHAJSON · TrechoRecuperação de listagens protegidas
AmazonAWS ShieldJSON · TrechoExtração de resultados de busca
nowsecure.nlCloudflareJSONCaminho 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ão 5000; substituível via --port, PORT ou CORTEX_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ão info. No nível info, 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 objeto command+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ávelPadrãoDescrição
RUST_LOGwarnNível de log. Mantenha warn para MCP stdioinfo inunda o stderr e confunde clientes MCP
HTTP_TIMEOUT_SECS30Timeout de leitura por requisição (segundos)
HTTP_CONNECT_TIMEOUT_SECS10Timeout de conexão TCP (segundos)
OUTBOUND_LIMIT16Máximo de conexões HTTP de saída simultâneas
MAX_CONTENT_CHARS10000Máximo de caracteres retornados por página raspada
CORTEX_SCOUT_TOOL_TIMEOUT_SECSespecífico da ferramentaLimite 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 definidoSubstituiçã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_SECSespecífico da etapaTimeout 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 definidoSubstituição por etapa, por exemplo CORTEX_SCOUT_SCRAPE_STAGE_TIMEOUT_SECS_CDP_INITIAL_ATTEMPT=30

Navegador / Anti-bot

VariávelPadrãoDescrição
CHROME_EXECUTABLEdetectado automaticamenteSubstitui o caminho para o binário Chromium/Chrome/Brave
SEARCH_CDP_FALLBACKtrueRepete buscas no mecanismo de busca via CDP nativo do Chromium quando bloqueado
SEARCH_TIER2_NON_ROBOTnão definidoDefina 1 para permitir hitl_web_fetch como escalada de busca de último recurso
MAX_LINKS100Máximo de links seguidos por rastreamento de página

Busca

VariávelPadrãoDescrição
SEARCH_ENGINESgoogle,bing,duckduckgo,braveMecanismos ativos (separados por vírgula)
SEARCH_MAX_ENGINES_PER_QUERY3Máximo de mecanismos consultados por busca antes que a rotação baseada em saúde selecione o próximo conjunto
SEARCH_MAX_RESULTS_PER_ENGINE10Resultados por mecanismo antes da mesclagem/deduplicação
SEARCH_ENGINE_STAGGER_MS125Atraso entre lançamentos por mecanismo para reduzir gatilhos anti-bot de rajada
SEARCH_COMMUNITY_TRIGGER_RESULTS4Executar expansão de comunidade Reddit/HN somente quando a busca primária retornar menos que este número de resultados
SEARCH_SHARED_CACHEtrueCompartilhar resultados de busca bem-sucedidos entre processos Cortex Scout concorrentes no mesmo host
SEARCH_SHARED_CACHE_TTL_SECS300TTL para o cache de busca compartilhado entre processos
SEARCH_HOST_MIN_GAP_MSajustado por mecanismoEspaçamento mínimo entre processos para requisições a mecanismos de busca do mesmo IP de host
SEARCH_HOST_MAX_GAP_MSajustado por mecanismoEspaçamento máximo/jitter entre processos para requisições a mecanismos de busca do mesmo IP de host
SCRAPE_HOST_MIN_GAP_MS900Espaçamento mínimo entre processos para requisições de scrape ao mesmo host
SCRAPE_HOST_MAX_GAP_MS1800Espaçamento máximo/jitter entre processos para requisições de scrape ao mesmo host
CORTEX_SCOUT_HOST_GUARD_DISABLEDfalseDefina 1 somente se você quiser explicitamente desabilitar o throttling compartilhado no nível do host

Proxy

VariávelPadrãoDescrição
IP_LIST_PATHCaminho 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_PATHCaminho opcional para proxy_source.json (usado por proxy_control grab)

Memória Semântica (LanceDB)

VariávelPadrãoDescrição
LANCEDB_URICaminho do diretório para memória de pesquisa persistente. Omita para desabilitar
CORTEX_SCOUT_MEMORY_DISABLED0Defina 1 para desabilitar memória mesmo quando LANCEDB_URI estiver definido
MODEL2VEC_MODELembutidoID do modelo HuggingFace ou caminho local para embeddings (ex.: minishlab/potion-base-8M)

Pesquisa Profunda

VariávelPadrãoDescrição
DEEP_RESEARCH_ENABLED1Defina 0 para desabilitar a ferramenta deep_research em tempo de execução
OPENAI_API_KEYChave de API para síntese LLM. Omita para endpoints locais sem chave (Ollama)
OPENAI_BASE_URLhttps://api.openai.com/v1Endpoint compatível com OpenAI (OpenRouter, Ollama, LM Studio, etc.)
DEEP_RESEARCH_LLM_MODELgpt-4o-miniIdentificador do modelo (deve ser suportado pelo endpoint)
DEEP_RESEARCH_SYNTHESIS1Defina 0 para pular síntese LLM (somente busca+scrape)
DEEP_RESEARCH_HOP_TIMEOUT_SECS90Timeout de scrape por salto. Quando excedido, deep_research retorna resultados parciais em vez de travar até o chamador MCP expirar
DEEP_RESEARCH_SYNTHESIS_MAX_TOKENS1024Máximo de tokens para resposta de síntese. Use 4096+ para modelos de contexto grande
DEEP_RESEARCH_SYNTHESIS_MAX_SOURCES8Máximo de documentos-fonte alimentados à síntese LLM
DEEP_RESEARCH_SYNTHESIS_MAX_CHARS_PER_SOURCE2500Máximo de caracteres extraídos por fonte para síntese

Somente Servidor HTTP

VariávelPadrãoDescrição
CORTEX_SCOUT_PORT / PORT5000Porta de escuta para o binário do servidor HTTP (cortex-scout)

Melhores Práticas para Agentes

Fluxo operacional recomendado:

  1. Chame memory_search antes de qualquer nova execução de pesquisa — pule a busca ao vivo se a similaridade ≥ 0,60 e skip_live_fetch for true.
  2. Para descoberta de tópicos, use web_search para descoberta somente de URLs, ou web_search(include_content=true) para buscar e raspar os principais resultados em uma única ida e volta.
  3. Para URLs conhecidas, use web_fetch(mode="single") com output_format="clean_json", e defina query + strict_relevance=true para manter apenas seções relevantes.
  4. Em 403/429: chame proxy_control com action:"grab" para atualizar a lista de proxies, depois tente novamente com use_proxy:true.
  5. Para páginas com acesso autenticado: execute visual_scout quando auth_risk_score >= 0.4, depois use hitl_web_fetch(auth_mode="challenge") para muros CAPTCHA ou hitl_web_fetch(auth_mode="auth") para muros de login.
  6. Para pesquisa profunda: deep_research lida automaticamente com busca multi-salto + scrape + síntese LLM. Ajuste depth (1–3) e max_sources conforme o orçamento de custo por execução.
  7. Para automação de UI e testes E2E: use scout_browser_automate com 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, chame scout_agent_profile_auth e 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: "" em cortex-scout.json é válido e significa "sem autenticação necessária"
  • Mantenha synthesis_max_sources em 1-2
  • Mantenha synthesis_max_chars_per_source em torno de 600-1000
  • Mantenha synthesis_max_tokens em torno de 512-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:

  1. Use uma build recente (2026-03-05 ou mais nova)
  2. Evite caminhos de perfil persistentes, a menos que precise de uma sessão logada
  3. Execute fluxos HITL/perfil sequencialmente
  4. Feche todas as janelas do navegador antes de reutilizar um perfil
  5. 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:

  1. Use RUST_LOG=warn, não info.
  2. 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 de mcp.json.
  3. No Windows, não use env; use command mais um objeto env.
  4. 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.