seo-firecrawl

Codex SEO 向け Firecrawl 拡張機能

共有データキャッシュ

ステップ 0 -- 共有データキャッシュを確認します：

情報を収集する前に、.seo-cache/ を確認し、関連する SEO スキルで再利用できるコンテキストがあるか調べます。 スキーマと依存関係マップについては、../seo/references/shared-data-cache.md を参照してください。

次のキャッシュファイルが存在する場合は確認します：

• .seo-cache/site-meta.json：ドメイン、ビジネスタイプ、業界、クロールのコンテキスト

• .seo-cache/audit-scores.json：過去のフル監査での優先事項

• .seo-cache/pages/{url-slug}/page-analysis.json：URL が指定された場合のページ単位のコンテキスト

• 見つかった場合：明らかに有効なフィールドを解析して使用します（「[日付] の [X] をキャッシュから使用」と記録します）

• 見つからない場合、破損している場合、または関連性がない場合：新しい根拠を使って続行します

• ユーザーが「refresh」または「re-run」と指定した場合：キャッシュの読み取りを無視し、書き込み時に上書きします

このスキルを使用するには、Firecrawl 拡張機能をインストールする必要があります：

./extensions/firecrawl/install.sh

利用可能か確認します： Firecrawl ツールを使用する前に、firecrawl_scrape または任意の Firecrawl ツールが利用可能か確認し、MCP サーバーが接続されていることを確かめます。ツールが利用できない場合は、拡張機能がインストールされていないことをユーザーに伝え、インストール手順を案内します。

クイックリファレンス

コマンド	目的
/seo firecrawl crawl <url>	コンテンツを抽出しながらサイト全体をクロールします
/seo firecrawl map <url>	サイト構造を検出します（URL のみ、高速）
/seo firecrawl scrape <url>	JS レンダリングを使って単一ページをスクレイピングします
/seo firecrawl search <query> <url>	クロール済みサイト内を検索します

コマンド

crawl -- サイト全体のクロール

指定された URL を起点に、ウェブサイト全体をクロールします。検出したすべてのページのコンテンツ、メタデータ、リンクを返します。

MCP ツール： firecrawl_crawl

パラメーター：

• url（必須）：クロールを開始する URL
• limit：クロールするページの最大数（デフォルト：100、最大：500）
• maxDepth：開始 URL からのリンク階層の最大深度（デフォルト：3）
• includePaths：含める glob パターンの配列（例：["/blog/*"]）
• excludePaths：除外する glob パターンの配列（例：["/admin/*", "/api/*"]）
• scrapeOptions.formats：出力形式 -- ["markdown", "html", "links"]

SEO の使用パターン：

1. 包括的な監査クロール：サイト全体をクロールし、サブエージェントによる分析用にすべてのページを抽出します
2. セクションに絞ったクロール：includePaths を使い、/blog/* または /products/* のみを監査します
3. リンク切れの検出：["links"] 形式でクロールし、すべての href が 404 になるか確認します
4. コンテンツの一覧作成：すべてのページタイトル、メタディスクリプション、H1 を大規模に抽出します
5. SPA／JS レンダリングされるサイト：Firecrawl が JavaScript をレンダリングし、Issue #11 の問題を解決します

/seo audit のオーケストレーション例：

1. firecrawl_map(url) -> get all URLs (fast, no content)
2. Filter to top 50 most important pages (homepage, key sections)
3. firecrawl_crawl(url, limit=50) -> get full content
4. Feed content to seo-technical, seo-content, seo-schema agents

コストに関する注意：

• 無料枠：月 500 クレジット
• 1 クレジット = クロールまたはスクレイピングするページ 1 件
• map 操作はより低コストです（検出した URL 1 件につき 0.5 クレジット）
• 大規模なクロールの前には、推定クレジット使用量を必ずユーザーに伝えます

map -- サイト構造の検出

コンテンツを取得せずに、ウェブサイト上のすべての URL を検出します。高速で、クレジット効率に優れています。

MCP ツール： firecrawl_map

パラメーター：

• url（必須）：マッピングするウェブサイトの URL
• limit：検出する URL の最大数（デフォルト：5000）
• search：URL を絞り込む任意の検索語

SEO の使用パターン：

1. サイトマップとの比較：サイトをマッピングし、検出した URL と XML サイトマップを比較します
2. 孤立ページの検出：サイトマップにはあるものの、どのページからもリンクされていない URL を特定します
3. クロールバジェットの分析：インデックス可能なページの総数と、ホームページからリンクされているページ数を比較します
4. URL パターンの分析：URL 構造のパターン、重複、パラメーターの過剰な増加を特定します
5. 監査前の検出：まず map を実行し、その後、重要なセクションを対象にクロールします

出力： URL の配列。次の形式で提示します：

Site: example.com
Pages discovered: 342

URL Pattern Breakdown:
  /blog/*          - 128 pages (37%)
  /products/*      - 89 pages (26%)
  /category/*      - 45 pages (13%)
  /pages/*         - 32 pages (9%)
  / (root pages)   - 48 pages (14%)

scrape -- 単一ページの詳細なスクレイピング

JavaScript を完全にレンダリングして、単一のページをスクレイピングします。JS を実行して動的コンテンツを待機するため、fetch_page.py よりも詳細に取得できます。

MCP ツール: firecrawl_scrape

パラメーター:

• url（必須）：スクレイピングするページの URL
• formats：出力形式 -- ["markdown", "html", "links", "screenshot"]
• onlyMainContent：ナビゲーション／フッター／サイドバーを除外します（デフォルト：true）
• waitFor：コンテンツを待機する CSS セレクターまたはミリ秒数
• timeout：リクエストのタイムアウト（ミリ秒）（デフォルト：30000）
• actions：スクレイピング前のブラウザー操作（クリック、スクロール、待機）

SEO での使用パターン:

1. SPA コンテンツの抽出：JS でレンダリングされる React/Vue/Angular ページをスクレイピングします
2. 動的コンテンツの監査：スクロールせずに見える範囲より下に遅延読み込みコンテンツがあるページを対象にします
3. ペイウォール／ログインの検出：認証画面の背後にあるコンテンツを特定します
4. メインコンテンツの抽出：onlyMainContent を使用して、E-E-A-T 分析に適した形式で取得します
5. スクリーンショットの取得：視覚的な分析に screenshot 形式を使用します

scrape と fetch_page.py の使い分け:

シナリオ	使用するもの
静的 HTML ページ	fetch_page.py（API コストなし）
JS でレンダリングされる SPA	firecrawl_scrape（JS をレンダリング）
レスポンスヘッダーが必要	fetch_page.py（ヘッダーを返す）
整形された Markdown が必要	firecrawl_scrape（より優れた抽出）
レート制限／ブロックへの対応	firecrawl_scrape（ボット対策に対応）

search -- サイト内検索

ウェブサイト内で特定のコンテンツを検索します。すべてをクロールせずに、トピックに関連するページを見つけるのに便利です。

MCP ツール: firecrawl_search

パラメーター:

• query（必須）：検索クエリ
• url（必須）：検索対象のウェブサイト
• limit：最大結果数（デフォルト：10）
• scrapeOptions.formats：一致したページの出力形式

SEO での使用パターン:

1. コンテンツギャップの検証：サイト内でキーワードを検索し、コンテンツが存在するか確認します
2. 内部リンクの機会：相互にリンクできる、あるトピックに言及しているページを見つけます
3. 重複コンテンツの検出：重要なフレーズを検索し、類似するページを見つけます
4. 競合コンテンツの調査：競合サイト内で特定のトピックを検索します

スキル間の連携

seo-audit との連携（包括的な監査）

/seo audit の実行時に Firecrawl を利用できる場合：

1. firecrawl_map を使用して、サイト上のすべての URL を検出します
2. XML サイトマップ（seo-sitemap）と比較して、孤立ページや欠落ページを特定します
3. 詳細な分析を行うページを選定します
4. クロールしたコンテンツをすべてのサブエージェント（technical、content、schema、geo）に渡します
5. クロール可能なページの合計数、URL パターン、クロールの深さを報告します

seo-technical との連携

• リンク切れの検出：すべての内部リンクをクロールし、404 がないか確認します
• リダイレクトチェーンのマッピング：すべてのリダイレクトをたどり、2 ホップを超えるチェーンを警告します
• 混合コンテンツの検出：HTTPS ページ上の HTTP リソースを確認します
• canonical の検証：canonical URL と実際の URL を比較します

seo-sitemap との連携

• サイトマップの網羅率：クロールしたページのうち、サイトマップに含まれるページの割合
• 孤立ページ：クロールで見つかったものの、サイトマップに含まれないページ
• 古くなったサイトマップの項目：サイトマップに含まれているものの、404/410 を返す URL

seo-content との連携

• コンテンツの抽出：整形された Markdown を E-E-A-T 分析に渡します
• 薄いコンテンツの検出：300 語未満のページを大規模に特定します
• 重複コンテンツ：ページ間のコンテンツを比較し、類似するページを見つけます

seo-schema との連携

• スキーマの抽出：クロールしたすべてのページから JSON-LD を取得します
• スキーマの網羅率：構造化データを含むページの割合
• スキーマの検証：抽出したスキーマを一括で検証します

エラー処理

エラー	原因	解決方法
FIRECRAWL_API_KEY not set	MCP が設定されていません	./extensions/firecrawl/install.sh を実行します
402 Payment Required	クレジットを使い切りました	firecrawl.dev/app で使用状況を確認し、プランをアップグレードします
429 Too Many Requests	レート制限に達しました	60 秒待ち、クロールの同時実行数を減らします
408 Timeout	ページのレンダリングに時間がかかりすぎています	timeout を増やし、JavaScript レンダリングを無効にして試します
403 Forbidden	サイトがクロールをブロックしています	robots.txt を確認します。このサイトをスキップする必要がある場合があります

適切なフォールバック： Firecrawl を利用できない場合は、ユーザーにその旨を伝え、次の方法を提案します。

1. 単一ページの分析には fetch_page.py を使用します（API コストはかかりません）
2. 基本的な HTML の取得には WebFetch ツールを使用します
3. Firecrawl をインストールします：./extensions/firecrawl/install.sh

共有データキャッシュへの書き込み

すべての作業が完了した後、ワークフローで長期的に有用な知見が得られた場合は、簡潔な JSON サマリーを .seo-cache/ に書き込みます。 ../seo/references/shared-data-cache.md のスキーマと命名規則を使用し、少なくとも cache_type、analyzed_at、ソース URL／ドメイン、主な調査結果、問題点、推奨事項、ツールの制限事項を含めます。.seo-cache/ が .gitignore に含まれていない場合は追加します。