TheCrawler

TheCrawler — 検証済みの抽出コントラクトを備えた、AI 対応ウェブスクレイパー

ウェブページをスクレイピングしたり、LLM を活用した構造化抽出を実行したり、LLM のトークンを消費する前に、URL が組み込みの抽出コントラクトに対応しているかを診断したりできます。オープンソースのエンジン（AGPL-3.0）です。Apify では、スクレイピングに成功したページ 1 件につき $0.005 です。

まずは安全なテストをお試しください。Apify で dryRun: true を指定して公開 URL を 1 件実行するか、現在の GitHub ソースをクローンし、engine/ からローカルの CLI/MCP ビルドを実行してください。小規模な検証パックは examples/diagnostic-challenge にあり、examples/diagnostic-challenge/sample-report.md では準備状況レポートのサンプルをご覧いただけます。

$500 の抽出準備状況スプリント

抽出のためにエンジニアリングの時間を費やす前に、実際の公開ウェブのワークフローを 1 つ自動化する価値があるかどうかを確認する場合にご利用ください。

• 対象範囲：公開 URL を最大 25 件、出力形式を 1 種類。
• 最初のステップ：構造化された課題フォームから公開の適合性チェックを送るか、スプリントページの非公開の適合性チェック方法をご利用ください。
• お支払い：ワークフローが適合しそうだと確認できた後にのみ、1 回限りの $500 の支払いリンクまたは請求書でお支払いいただきます。
• 成果物：準備完了、一部準備完了、ブロック中、自動化はまだ見送るべき、のいずれかを案内する準備状況レポート。
• クレジット：ワークフローがセットアップまたはホスト型の利用に進む場合、$500 は次のステップの費用に充当されます。

公開オファーのスレッドはGitHub issue #1です。検証パックには準備状況レポートのサンプルが含まれており、依頼者が URL を送る前にレポートの形式を確認できます。

公開の適合性チェックには、次の形式をご利用ください。

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

GitHub の課題には、ログイン認証情報、非公開 URL、個人データ、生の顧客データを含めないでください。

ここが違います

• 検証済みの抽出コントラクト：組み込みのコントラクトを選択すると、正規化されたデータに加え、validation.valid、必須フィールド、欠落フィールドの根拠を取得できます。現在のコントラクトは、real-estate-listing、product-page、docs-page です。
• ブランドアイデンティティの抽出（extractBrand: true）：1回の呼び出しで、サイトのランキング付きカラーpalette、themeColor、および最適と推定されるlogo候補（JSON-LD／ヘッダーのSVG／ファビコン／og:image）を返します。Playwright モードでは、getComputedStyleを使ってレンダリング後の色を読み取ります。静的CSSでは対応できないSPAでも動作します。決定論的で、LLMは不要です。
• コンテンツ制御：onlyMainContentに加え、includeTags／excludeTags（CSSによる許可／拒否）を指定すると、テキスト、Markdown、リンク、HTMLの出力からナビゲーション、フッター、サイドバー、広告を除外できます。Firecrawl互換です。waitForエイリアスにも対応しています。
• HTML形式：Markdownとともに、extractHtml（クリーンアップ済みのメインコンテンツHTML）とextractRawHtml（シリアライズされたDOM全体）を取得できます。
• LLM不要の診断：diagnoseModeを実行すると、ソースの抽出準備状況をスコア化し、障害要因を特定して、抽出前に購入者が読みやすいMarkdownレポートを保存できます。
• LLMを活用した抽出：JSON Schemaを送信するか、コントラクトを使用すると、解析済みの型付きデータが返されます。エンドポイントを選ばず、OpenAI、自前のllama.cpp／vLLM／LM Studio／Ollamaを指定できます。LLMはご自身で用意するため、ベンダーロックインはありません。
• 適応型クローリング：まずCheerio（高速なHTTP＋解析）を使い、SPAのシェルを検出すると自動的にPlaywrightへ切り替えます。すべてのページでブラウザーによるレンダリングを必須にせず、必要に応じて利用できます。
• 構造化されたエラー：errorType列挙型（dns | timeout | rate-limit | blocked-bot | js-required | http-4xx | http-5xx | parse | network | unknown）とerrorRetryableブール値を提供します。エージェントはエラーメッセージ文字列に対する正規表現を使わず、プログラムから分岐できます。
• チャレンジページの検出：アクセス制御やチャレンジページの本文を含む200 OKレスポンスは、有用なコンテンツとしてチャレンジHTMLを返すのではなく、errorType: 'blocked-bot'として通知されます。
• すぐに使える抽出機能：JSON-LD、microdata、コマースデータ（価格／SKU／評価）、フィールドタイプ付きフォーム、検出された16種類の分析トラッカー（GA4、GTM、Meta Pixel、Hotjar、Segment、Mixpanelなど）、hreflang、ページネーション、リダイレクトチェーンに対応しています。メールアドレス形式および電話番号形式の公開テキスト抽出は、オプトイン方式です。
• 見出しを考慮したRAGチャンク分割：Markdownをh1～h3の境界でオーバーラップ付きでチャンク分割し、各チャンクにSHAを付与します。そのままベクトルDBに取り込めます。

3つのモード

安全な初回実行

dryRun: trueを指定して、Apifyのスモークテストを実行します。アクターはページをクロールしますが、課金イベントは発生しません。

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

現在のローカル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

通常のクロール（デフォルト）

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

URLごとに、豊富な情報を含むPageDataを返します。タイトル、説明、言語、canonical URL、robotsディレクティブ、全文、定型部分を除去したMarkdown、リンク（内部／外部の区別付き）、画像（遅延読み込みのsrc付き）、メタタグ、OG／Twitter Card、JSON-LD、microdata、コマースデータ、フォーム、検出された分析トラッカー、オプションのメールアドレス形式／電話番号形式の公開テキストフィールド、ソーシャルリンク、hreflang、ページネーション、リダイレクトチェーン、レスポンスヘッダーと所要時間が含まれます。失敗時は、構造化されたerrorTypeとerrorRetryableも返します。

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"
}

URLをクロールし、Markdownにクリーンアップしてから、(markdown + schema)をOpenAI互換のチャット補完エンドポイントに送信し、URLごとに解析済みの型付きデータを返します。スキーマベースの抽出では、対応している場合はJSON Schemaのレスポンス形式を使用し、JSONオブジェクトまたはテキスト出力のみをサポートするエンドポイントではフォールバックを使用します。スキーマの代わりに、またはスキーマと併せて、自然言語のextractPromptも指定できます。アクターの課金は通常どおりページ単位で行われます。LLM呼び出しの費用は、指定したエンドポイントの料金によります。

注：抽出モードには、パブリックから到達可能なLLMエンドポイントが必要です。LANのURL（例：http://192.168.x.x）はApifyのインフラから到達できません。OpenAI、ホスト型vLLM、またはトンネル経由で公開したローカルサーバーを使用してください。

実行履歴に表示される実行入力にLLMキーが含まれないよう、アクターの環境変数としてTHECRAWLER_LLM_API_KEYを設定してください。

Contract diagnostic mode

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

LLM を呼び出さずに、クロールと準備状況のスコアリングを実行します。データセットの出力には、URL ごとの verdict、readyForExtraction、score、blockers、warnings、recommendedNextStep と、ワークフローの概要が含まれます。diagnosticReport が true の場合、アクターは実行時のキーバリューストアに、準備状況シグナルの不足をまとめた Markdown 形式の contract-diagnostic-report を保存します。このレポートには、抽出した連絡先の詳細情報は意図的に含めません。

Contract extract mode

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

選択したコントラクトのスキーマとプロンプトを使用し、抽出結果にコントラクト検証を追加します。エージェントは、曖昧な Markdown を信頼するのではなく、validation.valid と validation.missingRequiredFields に基づいて処理を分岐できます。現在、組み込みコントラクトは real-estate-listing と product-page に対応しています。

信頼性機能

機能	デフォルト	理由
requestRetries	3	一時的な障害（5xx、ネットワーク、タイムアウト）を自動的に再試行します
requestTimeoutSecs	30	リクエストごとの時間を制限します
rotateUserAgent	true	互換性のために標準的なブラウザーの User-Agent 文字列を使用します。アクセス制御は上書きしません
cacheEnabled	false	（URL + 抽出フラグ）ごとに、5 分間のメモリ内 LRU キャッシュをオプトインで使用します
チャレンジページの検出	常時有効	アクセス制御またはチャレンジページの本文を errorType: 'blocked-bot' として通知します
適応型クロール	オプトイン	adaptiveCrawling: true を指定すると、まず Cheerio を試し、SPA を検出した場合は Playwright に切り替えます

検索 → スクレイピング

Google の上位 N 件の検索結果を、1 回の呼び出しでクロールします。安定した検索には、オプションで SerpAPI キーを使用できます。

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

サイトマップ → スクレイピング

Sitemap.xml とサイトマップインデックスファイルを自動的に解決します。

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

ファイルの抽出

PDF および DOCX の URL を自動検出して解析します。抽出したテキストと、PDF の場合はメタデータおよびページ数を返します。

料金

• クロールモード：スクレイピングに成功したページ 1 件につき $0.005 です（失敗したページは課金されません）。
• 抽出モード／診断モード：スクレイピングに成功したページごとに引き続き課金されます。LLM エンドポイントの費用は、このアクターではなくエンドポイントの所有者が負担します。
• 抽出準備スプリント：1 つの公開ワークフローについて、適合性の確認後に $500 です。対象は公開 URL 25 件まで、出力形式 1 種類、そして ready／mixed／blocked のレポートです。対象範囲の確認後、単発リンクまたは請求書でお支払いいただきます。ワークフローがセットアップまたはホスト型の利用に進む場合、$500 は次のステップの費用に充当されます。別のスタックのほうが適している場合は、レポートにその旨を記載します。

Apify Store 以外での利用

このアクターのビルドに使用されている現在のオープンソースエンジンのソースコードは engine/ にあります。独自の Node プロジェクト、MCP サーバー、CLI、または REST API サーバーに組み込めます。次回の npm 公開までは、公開されている npm パッケージより GitHub のソースコードのほうが新しいため、現在検証済みのコントラクトと MCP ツールを利用するには、以下の GitHub ソースコードの手順を使用してください。セルフホストすれば Apify のページごとの料金を回避できますが、独自のインフラストラクチャと LLM エンドポイントの費用は引き続き発生します。

# 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

GitHub クローンから Cline をセットアップするには、llms-install.md を使用してください。npm が更新されるまでは、検証済みのコントラクトと MCP ツールの確認に現在の GitHub ソースを使用してください。

GitHub：https://github.com/manchittlab/TheCrawler · ライセンス：AGPL-3.0