TheCrawler

TheCrawler — raspador web listo para IA con contratos de extracción validados

Raspea páginas web, ejecuta extracción estructurada impulsada por LLM, o diagnostica si las URLs están listas para un contrato de extracción integrado antes de gastar tokens de LLM. Motor de código abierto (AGPL-3.0). $0.005 por página raspada con éxito en Apify.

Comienza con una prueba segura: ejecuta una URL pública con dryRun: true en Apify, o clona el código fuente actual de GitHub y ejecuta la compilación local de CLI/MCP desde engine/. Un pequeño paquete de demostración está en examples/diagnostic-challenge, incluyendo un informe de preparación de muestra en examples/diagnostic-challenge/sample-report.md.

Sprint de preparación de extracción de $500

Úsalo cuando necesites saber si un flujo de trabajo web público real vale la pena automatizar antes de invertir tiempo de ingeniería en extracción.

• Alcance: hasta 25 URLs públicas y una forma de salida objetivo.
• Primer paso: envía una verificación de idoneidad pública a través del formulario de incidencias estructurado o usa la ruta privada de verificación de idoneidad en la página del sprint.
• Pago: se solicita solo después de que el flujo de trabajo parezca adecuado, mediante un enlace de pago único de $500 o factura.
• Resultado: un informe de preparación con orientación de listo, mixto, bloqueado o aún-no-vale-la-pena-automatizar.
• Crédito: si el flujo de trabajo continúa hacia la configuración o el uso alojado, los $500 se acreditan hacia ese siguiente paso.

El hilo público de la oferta es GitHub issue #1. El paquete de demostración incluye un informe de preparación de muestra que muestra la forma del informe antes de que un comprador envíe URLs.

Las verificaciones de idoneidad públicas deben usar esta forma:

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

No incluyas credenciales de acceso, URLs privadas, datos personales ni datos brutos de clientes en incidencias de GitHub.

Qué lo hace diferente

• Contratos de extracción validados: selecciona un contrato integrado, obtén datos normalizados más validation.valid, campos requeridos y evidencia de campos faltantes. Contratos actuales: real-estate-listing, product-page, docs-page.
• Extracción de identidad de marca (extractBrand: true): una sola llamada devuelve el color clasificado del sitio palette, themeColor y los mejores candidatos de logo (JSON-LD / SVG de cabecera / favicons / og:image). En modo Playwright lee colores renderizados mediante getComputedStyle — funciona en SPAs donde el CSS estático no puede. Determinista, sin LLM.
• Controles de contenido: onlyMainContent más includeTags / excludeTags (permitir/denegar CSS) eliminan navegación, pie de página, barras laterales y anuncios del texto, markdown, enlaces y salida HTML. Compatible con Firecrawl. Alias waitFor soportado.
• Formatos HTML: extractHtml (HTML limpio de contenido principal) y extractRawHtml (DOM serializado completo) junto con markdown.
• Diagnósticos sin LLM: ejecuta diagnoseMode para puntuar la preparación de la fuente, identificar bloqueadores y guardar un informe Markdown legible para el comprador antes de la extracción.
• Extracción impulsada por LLM: envía un JSON Schema o usa un contrato, recibe datos tipados analizados. Agnóstico al endpoint — apunta a OpenAI, tu propio llama.cpp / vLLM / LM Studio / Ollama. Tú aportas el LLM, sin bloqueo de proveedor.
• Rastreo adaptativo: Cheerio primero (HTTP+parseo rápido), con respaldo automático a Playwright cuando se detecta un shell SPA. Mantiene el renderizado del navegador opcional en lugar de obligatorio para cada página.
• Errores estructurados: enumeración errorType (dns | timeout | rate-limit | blocked-bot | js-required | http-4xx | http-5xx | parse | network | unknown) + booleano errorRetryable. Los agentes ramifican programáticamente — sin regex sobre cadenas de error.
• Detección de páginas de desafío: las respuestas 200 OK con cuerpos de control de acceso o páginas de desafío se marcan como errorType: 'blocked-bot' en lugar de devolver HTML de desafío como contenido útil.
• Extractores listos para usar: JSON-LD, microdatos, datos comerciales (precio/SKU/valoración), formularios con tipos de campo, 16 rastreadores de analítica detectados (GA4, GTM, Meta Pixel, Hotjar, Segment, Mixpanel, etc.), hreflang, paginación, cadena de redirecciones. La extracción de texto público similar a correo electrónico y teléfono es opcional.
• Fragmentación RAG consciente de encabezados: markdown fragmentado en límites h1-h3 con solapamiento y SHA por fragmento. Aliméntalo directamente a una base de datos vectorial.

Tres modos

Primera ejecución segura

Usa dryRun: true para una prueba de humo en Apify. El actor rastrea la página pero no emite un evento de facturación.

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

Para la compilación local actual 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

Rastreo simple (predeterminado)

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

Devuelve un PageData enriquecido por URL: título, descripción, idioma, URL canónica, directivas robots, texto completo, markdown sin contenido superfluo, enlaces (con indicador interno/externo), imágenes (con src de carga diferida), metaetiquetas, OG/Twitter Card, JSON-LD, microdatos, datos comerciales, formularios, analítica detectada, campos de texto público opcionales similares a correo electrónico/teléfono, enlaces sociales, hreflang, paginación, cadena de redirecciones, encabezados de respuesta + tiempos, más errorType + errorRetryable estructurados en caso de fallo.

Modo de extracción impulsado por 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"
}

Rastrea la URL → limpia a markdown → envía (markdown + schema) a tu endpoint de chat-completions compatible con OpenAI → devuelve datos tipados analizados por URL. La extracción basada en esquema usa el formato de respuesta JSON Schema cuando es compatible, con respaldos para endpoints que solo admiten salida de objeto JSON o texto. Admite extractPrompt en lenguaje natural en lugar de/junto al esquema. El actor cobra por página como de costumbre; el costo de la llamada al LLM es lo que cobre tu endpoint.

Nota: el modo de extracción requiere un endpoint LLM accesible públicamente. Las URLs de LAN (p. ej. http://192.168.x.x) no son accesibles desde la infraestructura de Apify. Usa OpenAI, vLLM alojado, o expón tu servidor local mediante un túnel.

Establece THECRAWLER_LLM_API_KEY como variable de entorno del Actor para que la clave del LLM nunca termine en las entradas de ejecución (visibles en el historial de ejecuciones).

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
}

Ejecuta rastreo + puntuación de preparación sin llamada al LLM. La salida del dataset incluye por URL verdict, readyForExtraction, score, blockers, warnings y recommendedNextStep, más un resumen del flujo de trabajo. Cuando diagnosticReport es verdadero, el actor guarda contract-diagnostic-report en el almacén clave-valor de la ejecución como Markdown con un resumen de señales de preparación faltantes. El informe excluye intencionalmente detalles de contacto extraídos en bruto.

Modo de extracción 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 el esquema y la instrucción del contrato seleccionado, luego añade validación de contrato al resultado de extracción. Los agentes pueden ramificar en validation.valid y validation.missingRequiredFields en lugar de confiar en markdown suelto. Los contratos integrados actualmente cubren real-estate-listing y product-page.

Características de fiabilidad

Característica	Predeterminado	Por qué
requestRetries	3	Los fallos transitorios (5xx, red, tiempo de espera) se reintentan automáticamente
requestTimeoutSecs	30	Límite de tiempo por solicitud
rotateUserAgent	true	Usa cadenas de User-Agent de navegador estándar para compatibilidad; no anula los controles de acceso
cacheEnabled	false	LRU en memoria de 5 min opcional por (URL + indicadores de extracción)
Detección de páginas de desafío	siempre activa	Marca los cuerpos de control de acceso o páginas de desafío como errorType: 'blocked-bot'
Rastreo adaptativo	opcional	adaptiveCrawling: true intenta Cheerio primero, escala a Playwright al detectar SPA

Búsqueda → rastreo

Los resultados Top-N de Google se rastrean en una sola llamada. Clave SerpAPI opcional para búsqueda fiable.

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

Sitemap → rastreo

Los archivos Sitemap.xml y sitemap-index se resuelven automáticamente.

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

Extracción de archivos

Las URLs de PDF y DOCX se detectan y analizan automáticamente. Devuelve texto extraído + (para PDFs) metadatos, número de páginas.

Precios

• Modo de rastreo: $0.005 por página raspada con éxito (las páginas fallidas no se cobran).
• Modo de extracción / modo de diagnóstico: se cobra igualmente por página raspada con éxito. El costo del endpoint LLM lo paga el propietario del endpoint, no este actor.
• Sprint de preparación de extracción: $500 tras la confirmación de idoneidad para un flujo de trabajo público: hasta 25 URLs públicas, una forma de salida objetivo y un informe de listo / mixto / bloqueado. El pago es mediante enlace único o factura después de confirmar el alcance. Si el flujo de trabajo continúa hacia la configuración o el uso alojado, los $500 se acreditan hacia ese siguiente paso. Si otra pila es más adecuada, el informe lo indica.

Más allá de Apify Store

El código fuente del motor de código abierto actual para esta compilación del actor está en engine/; intégralo en tu propio proyecto Node, servidor MCP, CLI o servidor de API REST. El paquete npm publicado es más antiguo que este código fuente de GitHub hasta la próxima publicación de npm, así que usa la ruta del código fuente de GitHub a continuación para las herramientas actuales de contratos validados y MCP. El autoalojamiento evita los cargos por página de Apify, aunque tu propia infraestructura y los costos del endpoint LLM siguen aplicándose.

# 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 la configuración de Cline desde un clon de GitHub, usa llms-install.md. El código fuente actual de GitHub es la ruta de revisión para contratos validados y herramientas MCP hasta que npm se actualice.

GitHub: https://github.com/manchittlab/TheCrawler · Licencia: AGPL-3.0