TheCrawler

TheCrawler — raspador web pronto para IA com contratos de extração validados

Raspe páginas da web, execute extração estruturada com LLM ou diagnostique se URLs estão prontas para um contrato de extração embutido antes de gastar tokens de LLM. Motor de código aberto (AGPL-3.0). US$ 0,005 por página raspada com sucesso no Apify.

Comece com um teste seguro: execute uma URL pública com dryRun: true no Apify, ou clone o código-fonte atual do GitHub e execute a compilação local CLI/MCP a partir de engine/. Um pequeno pacote de prova está em examples/diagnostic-challenge, incluindo um relatório de prontidão de exemplo em examples/diagnostic-challenge/sample-report.md.

Sprint de prontidão de extração de US$ 500

Use isto quando precisar saber se um fluxo de trabalho real da web pública vale a pena automatizar antes de gastar tempo de engenharia em extração.

• Escopo: até 25 URLs públicas e um formato de saída alvo.
• Primeiro passo: envie uma verificação de adequação pública através do formulário de issue estruturado ou use o caminho privado de verificação de adequação na página do sprint.
• Pagamento: solicitado somente após o fluxo de trabalho parecer adequado, por link de pagamento único de US$ 500 ou fatura.
• Saída: um relatório de prontidão com orientação de pronto, misto, bloqueado ou ainda não vale a pena automatizar.
• Crédito: se o fluxo de trabalho continuar para configuração ou uso hospedado, os US$ 500 são creditados para essa próxima etapa.

O tópico da oferta pública é issue #1 do GitHub. O pacote de prova inclui um relatório de prontidão de exemplo mostrando o formato do relatório antes de um comprador enviar URLs.

Verificações de adequação públicas devem usar este formato:

Workflow type:
Public URLs (up to 25):
Target output shape / required fields:
Known blockers or constraints:
Timing:

Não inclua credenciais de login, URLs privadas, dados pessoais ou dados brutos de clientes em issues do GitHub.

O que torna isso diferente

• Contratos de extração validados: selecione um contrato embutido, obtenha dados normalizados mais validation.valid, campos obrigatórios e evidência de campos ausentes. Contratos atuais: real-estate-listing, product-page, docs-page.
• Extração de identidade de marca (extractBrand: true): uma chamada retorna a cor classificada do site palette, themeColor e candidatos de melhor suposição logo (JSON-LD / SVG de cabeçalho / favicons / og:image). No modo Playwright, lê cores renderizadas via getComputedStyle — funciona em SPAs onde CSS estático não consegue. Determinístico, sem LLM.
• Controles de conteúdo: onlyMainContent mais includeTags / excludeTags (permitir/negar CSS) removem navegação, rodapé, barras laterais e anúncios de texto, markdown, links e saída HTML. Compatível com Firecrawl. Alias waitFor suportado.
• Formatos HTML: extractHtml (HTML limpo, conteúdo principal) e extractRawHtml (DOM serializado completo) junto com markdown.
• Diagnósticos sem LLM: execute diagnoseMode para pontuar a prontidão da fonte, identificar bloqueadores e salvar um relatório Markdown legível para o comprador antes da extração.
• Extração com LLM: envie um JSON Schema ou use um contrato, receba dados tipados analisados. Agnóstico de endpoint — aponte para OpenAI, seu próprio llama.cpp / vLLM / LM Studio / Ollama. Você traz o LLM, sem dependência de fornecedor.
• Raspagem adaptativa: Cheerio primeiro (HTTP+parse rápido), fallback automático para Playwright quando um shell SPA é detectado. Mantém a renderização do navegador opcional em vez de obrigatória para cada página.
• Erros estruturados: enum errorType (dns | timeout | rate-limit | blocked-bot | js-required | http-4xx | http-5xx | parse | network | unknown) + booleano errorRetryable. Agentes ramificam programaticamente — sem regex em strings de erro.
• Detecção de página de desafio: respostas 200 OK com corpos de controle de acesso ou página de desafio são sinalizadas como errorType: 'blocked-bot' em vez de retornar HTML de desafio como conteúdo útil.
• Extratores prontos para uso: JSON-LD, microdados, dados de comércio (preço/SKU/avaliação), formulários com tipos de campo, 16 rastreadores de análise detectados (GA4, GTM, Meta Pixel, Hotjar, Segment, Mixpanel, etc.), hreflang, paginação, cadeia de redirecionamento. Extração de texto público semelhante a e-mail e telefone é opcional.
• Fragmentação RAG ciente de títulos: markdown fragmentado nos limites h1-h3 com sobreposição e SHA por fragmento. Alimente diretamente um banco de vetores.

Três modos

Primeira execução segura

Use dryRun: true para um teste de fumaça no Apify. O ator rastreia a página, mas não emite um evento de cobrança.

{
  "urls": ["https://example.com"],
  "extractMarkdown": true,
  "dryRun": true
}

Para a compilação local atual de MCP/CLI:

git clone https://github.com/manchittlab/TheCrawler.git
cd TheCrawler/engine
npm install
npm run build
node dist/cli.js crawl https://example.com --markdown

Raspagem simples (padrão)

{
  "urls": ["https://example.com"],
  "extractMarkdown": true,
  "rotateUserAgent": true,
  "requestRetries": 3
}

Retorna PageData rico por URL: título, descrição, idioma, URL canônica, diretivas de robots, texto completo, markdown sem boilerplate, links (com sinalizador interno/externo), imagens (com src de carregamento preguiçoso), meta tags, OG/Twitter Card, JSON-LD, microdados, dados de comércio, formulários, análise detectada, campos de texto público opcionais semelhantes a e-mail/telefone, links sociais, hreflang, paginação, cadeia de redirecionamento, cabeçalhos de resposta + tempo, além de errorType + errorRetryable estruturados em caso de falha.

Modo de extração com LLM

{
  "urls": ["https://shop.example.com/products/123"],
  "extractMode": true,
  "extractJsonSchema": {
    "type": "object",
    "properties": {
      "productName": { "type": "string" },
      "price": { "type": "number" },
      "currency": { "type": "string" },
      "inStock": { "type": "boolean" }
    },
    "required": ["productName"]
  },
  "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
  "llmModel": "gpt-4o-mini"
}

Rastreia a URL → limpa para markdown → envia (markdown + schema) para seu endpoint de chat-completions compatível com OpenAI → retorna dados tipados analisados por URL. A extração baseada em esquema usa o formato de resposta JSON Schema quando suportado, com fallbacks para endpoints que suportam apenas saída de objeto JSON ou texto. Suporta extractPrompt em linguagem natural em vez de/ao lado do esquema. O ator cobra por página como normal; o custo da chamada LLM é o que seu endpoint cobra.

Nota: o modo de extração requer um endpoint LLM acessível publicamente. URLs de LAN (por exemplo, http://192.168.x.x) não são acessíveis a partir da infraestrutura do Apify. Use OpenAI, vLLM hospedado ou exponha seu servidor local via túnel.

Defina THECRAWLER_LLM_API_KEY como uma variável de ambiente do Actor para que a chave LLM nunca apareça nas entradas de execução (visível no histórico de execução).

Modo de diagnóstico de contrato

{
  "urls": ["https://example.com/listing-1", "https://example.com/listing-2"],
  "diagnoseMode": true,
  "extractContract": "real-estate-listing",
  "diagnosticReport": true
}

Executa raspagem + pontuação de prontidão sem chamada LLM. A saída do dataset inclui por URL verdict, readyForExtraction, score, blockers, warnings e recommendedNextStep, além de um resumo do fluxo de trabalho. Quando diagnosticReport é verdadeiro, o ator salva contract-diagnostic-report no armazenamento chave-valor da execução como Markdown com um resumo de sinais de prontidão ausentes. O relatório exclui intencionalmente detalhes brutos de contato extraídos.

Modo de extração de contrato

{
  "urls": ["https://example.com/listing-1"],
  "extractMode": true,
  "extractContract": "product-page",
  "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
  "llmModel": "gpt-4o-mini"
}

Usa o esquema e prompt do contrato selecionado e, em seguida, anexa a validação do contrato ao resultado da extração. Agentes podem ramificar em validation.valid e validation.missingRequiredFields em vez de confiar em markdown solto. Contratos embutidos atualmente cobrem real-estate-listing e product-page.

Recursos de confiabilidade

Recurso	Padrão	Por quê
requestRetries	3	Falhas transitórias (5xx, rede, tempo limite) são repetidas automaticamente
requestTimeoutSecs	30	Limite de tempo por solicitação
rotateUserAgent	true	Usa strings padrão de User-Agent do navegador para compatibilidade; não substitui controles de acesso
cacheEnabled	false	LRU em memória de 5 min por (URL + sinalizadores de extração) opt-in
Detecção de página de desafio	sempre ativo	Sinaliza corpos de controle de acesso ou página de desafio como errorType: 'blocked-bot'
Raspagem adaptativa	opt-in	adaptiveCrawling: true tenta Cheerio primeiro, escala para Playwright na detecção de SPA

Pesquisa → raspagem

Resultados do Google Top-N raspados em uma chamada. Chave SerpAPI opcional para pesquisa confiável.

{ "searchQuery": "best CRM 2026", "searchLimit": 10, "extractMarkdown": true }

Sitemap → raspagem

Arquivos Sitemap.xml + sitemap-index resolvidos automaticamente.

{ "sitemapUrl": "https://example.com/sitemap.xml", "maxPages": 50 }

Extração de arquivos

URLs de PDF e DOCX são detectadas e analisadas automaticamente. Retorna texto extraído + (para PDFs) metadados, contagem de páginas.

Preços

• Modo de raspagem: US$ 0,005 por página raspada com sucesso (páginas com falha não são cobradas).
• Modo de extração / modo de diagnóstico: ainda cobrado por página raspada com sucesso. O custo do endpoint LLM é pago pelo proprietário do endpoint, não por este ator.
• Sprint de prontidão de extração: US$ 500 após confirmação de adequação para um fluxo de trabalho público: até 25 URLs públicas, um formato de saída alvo e um relatório pronto / misto / bloqueado. O pagamento é por link único ou fatura após o escopo ser confirmado. Se o fluxo de trabalho continuar para configuração ou uso hospedado, os US$ 500 são creditados para essa próxima etapa. Se outra pilha for mais adequada, o relatório diz isso.

Além da Apify Store

O código-fonte do motor de código aberto atual para esta compilação do ator está em engine/; coloque-o em seu próprio projeto Node, servidor MCP, CLI ou servidor de API REST. O pacote npm publicado é mais antigo que este código-fonte do GitHub até a próxima publicação npm, então use o caminho do código-fonte do GitHub abaixo para ferramentas atuais de contrato validado e MCP. Auto-hospedagem evita cobranças por página do Apify, enquanto sua própria infraestrutura e custos de endpoint LLM ainda se aplicam.

# Current GitHub source build
cd engine
npm install
npm run build

# CLI
node dist/cli.js crawl https://example.com --markdown
node dist/cli.js extract https://example.com --schema '{...}'

# MCP server (Cline, Claude Code, Cursor, Windsurf)
node dist/mcp.js

# REST API server
THECRAWLER_API_KEY=local_test_key node dist/server.js --port 3000
curl -H "Authorization: Bearer local_test_key" \
  "http://localhost:3000/v1/contracts?includeSchema=true"
curl -X POST "http://localhost:3000/v1/scrape" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/product","formats":["markdown","metadata","links","structuredData","commerceData"]}'
curl -X POST "http://localhost:3000/v1/diagnose" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"contractName":"product-page","urls":["https://example.com/product"],"reportMarkdown":true}'
curl -X POST "http://localhost:3000/v1/map" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","maxPages":1}'
curl -X POST "http://localhost:3000/v1/extract-contract" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"contractName":"product-page","urls":["https://example.com/product"],"llmBaseUrl":"http://localhost:1234/v1/chat/completions","llmModel":"qwen/qwen3.5-9b"}'

# Older npm package; use for plain crawl only until the next publish
npm install thecrawler
thecrawler crawl https://example.com --markdown

Para configuração do Cline a partir de um clone do GitHub, use llms-install.md. O código-fonte atual do GitHub é o caminho de revisão para contratos validados e ferramentas MCP até que o npm seja atualizado.

GitHub: https://github.com/manchittlab/TheCrawler · Licença: AGPL-3.0