mcpField
C
crawler

crawler

github.com/gn00678465データ・データベース1130 回インストール33 週間前に更新
リポジトリ

crawler について

Crawler は、ウェブページのテキストが必要なワークフロー向けに、URL を整形済み Markdown に変換するスクレイピングスキルです。Firecrawl、Jina Reader、Scrapling の順に試し、取得内容を検証してから返します。

主な機能

  1. 01ウェブページを Markdown に変換
  2. 023 種類のスクレイパーを順に試行
  3. 03特定ドメインで方式をスキップ
  4. 04内容の検証とエラーページ検出
  5. 05結果をファイルに保存

活用シーン

  1. 01後続処理向けにページ本文を抽出
  2. 02ドキュメントページを Markdown で保存
  3. 03失敗時に別のスクレイパーを試行

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/gn00678465/crawler-skill --skill crawler

インストール後、Claude Code で/crawlerを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
evals.json
scripts/
crawl.py
pyproject.toml
uv.lock
scripts/src/
domain_router.py
firecrawl_scraper.py
jina_reader.py
scrapling_scraper.py
tests/
test_crawl.py

詳細

クローラースキル

堅牢な3段階フォールバックチェーンを使用して、あらゆるURLを整形済みのMarkdownに変換します。

クイックスタート

uv run scripts/crawl.py --url https://example.com --output reports/example.md

Markdownは--outputで指定したファイルに保存されます。進行状況とエラーはstderrに出力されます。成功時の終了コードは0、すべてのスクレイパーが失敗した場合は1です。

仕組み

スクリプトは各段階を順番に試し、最初に成功した結果を返します。

段階モジュール要件
1Firecrawl (firecrawl_scraper.py)環境変数FIRECRAWL_API_KEY（任意。未設定の場合はフォールバックします）
2Jina Reader (jina_reader.py)不要 — 無料で、キーは必要ありません
3Scrapling (scrapling_scraper.py)ローカルのヘッドレスブラウザー（pip経由で自動インストール）

ファイル構成

crawler-skill/
├── SKILL.md            ← this file
├── scripts/
│   ├── crawl.py               ← main CLI entry point (PEP 723 inline deps)
│   └── src/
│       ├── domain_router.py       ← URL-to-tier routing rules
│       ├── firecrawl_scraper.py   ← Tier 1: Firecrawl API
│       ├── jina_reader.py         ← Tier 2: Jina r.jina.ai proxy
│       └── scrapling_scraper.py   ← Tier 3: local headless scraper
└── tests/
    └── test_crawl.py          ← 70 pytest tests (all passing)

使用例

# Basic fetch — tries Firecrawl, falls back to Jina, then Scrapling
# Always prefer using --output to avoid terminal encoding issues
uv run scripts/crawl.py --url https://docs.python.org/3/ --output reports/python_docs.md

# If no --output is provided, markdown goes to stdout (not recommended on Windows)
uv run scripts/crawl.py --url https://example.com

# With a Firecrawl API key for best results
FIRECRAWL_API_KEY=fc-... uv run scripts/crawl.py --url https://example.com --output reports/example.md

URLの要件

受け付けるURLはhttp://とhttps://のみです。それ以外のスキーム （ftp://、file://、javascript:、スキームのないパスなど）を渡すと、終了コード1で終了し、 明確なエラーを出力します。スクレイピングは試行されません。

レポートの保存

ユーザーからクロールしたコンテンツや要約をファイルに保存するよう求められた場合は、必ず--output引数を使用し、プロジェクトルートのreports/ディレクトリにファイルを保存してください（例：{project_root}/reports）。ディレクトリが存在しない場合、スクリプトが作成します。

例： 「result.mdに保存して」と頼まれた場合は、次のように実行します。 uv run scripts/crawl.py --url <URL> --output reports/result.md

セルフホストのFirecrawlインスタンスを指定する

FIRECRAWL_API_URL=http://localhost:3002 uv run scripts/crawl.py --url https://example.com

コンテンツの検証

各スクレイパーは、成功を返す前に出力を検証します。

  • コンテンツが100文字以上であること（空のページやエラーページを除外）
  • CAPTCHA／ボット検証ページの検出（Firecrawl）
  • Cloudflareのインタースティシャルページの検出（Scrapling — StealthyFetcherに処理を引き継ぎます）
  • Jinaのエラーページを示す語句（Error:、Access Deniedなど）の検出

ドメインルーティング

既知の互換性問題を回避するため、一部のホスト名では1つ以上のスクレイパー段階をスキップします。 ロジックはscripts/src/domain_router.pyにあります。

ドメインスキップする段階有効なチェーン
medium.com（サブドメインを含む）firecrawljina → scrapling
mp.weixin.qq.comfirecrawl + jinascraplingのみ
その他すべて—firecrawl → jina → scrapling

サブドメインの照合にはサフィックスルールを使用します。blog.medium.comは、ホスト名が.medium.comで終わるため、 medium.comのルールに一致します。other.weixin.qq.comのような別のサブドメインは、mp.weixin.qq.comには一致しません。

テストの実行

uv run pytest tests/ -v

70件すべてのテストでモックを使用しているため、ネットワーク接続もAPIキーも必要ありません。

依存関係（uv runで自動インストール）

  • firecrawl-py>=2.0 — Firecrawl Python SDK
  • httpx>=0.27 — Jina Reader用HTTPクライアント
  • scrapling>=0.2 — ステルス機能を備えたヘッドレススクレイピング
  • html2text>=2024.2.26 — HTMLからMarkdownへの変換

このスキルを呼び出すタイミング

ウェブページのテキストコンテンツが必要な場合は、いつでもcrawl.pyを呼び出してください。

result = subprocess.run(
    ["uv", "run", "scripts/crawl.py", "--url", url],
    capture_output=True, text=True
)
if result.returncode == 0:
    markdown = result.stdout

または、上記のクイックスタートに示すように、ターミナルから直接実行してください。

コメント

Markdown 対応