firecrawl-developer-index

Firecrawl 開発者向けインデックス

公式ドキュメント、セットアップ、例、移行、互換性については、公式ドキュメントを参照してください。ドキュメントに記載されていない実装やバグの根拠を確認する場合は、以下を参照してください。アプローチを切り替える場合は、適切な根拠を再利用してください。

開発者向けの質問には、一次情報で回答してください。バグが報告されたイシュー、修正がマージされたプルリクエスト、仕様を定めている README やドキュメントページが該当します。動作について説明するブログ記事は、それを定義している記述より根拠として弱いため、まずインデックスを確認し、次に公開ウェブを調べてください。インデックスのリポジトリ部分が対象とするのは公開リポジトリのみです。非公開または内部リポジトリは含まれないため、非公開コードに関する質問には別の方法が必要です。そのコードを直接確認してください。

決まった手順はありません。 質問を読み、どのような種類かを判断して、以下からアプローチを選んでください。エラー文字列をそのまま尋ねる質問と、「X の方法を教えて」という質問では、異なる対応が必要です。質問で求められていない仕組みは実行しないでください。

各ツールの特徴

• HTTP：GET|POST https://api.firecrawl.dev/v2/search/developer MCP：firecrawl_developer_search(query, k?, skills?) CLI：firecrawl developer <query> [--limit <n>] インデックス全体の検索結果を関連度順に返します。各結果には id（issue:owner/repo#123）、url、Markdown 形式の該当箇所が含まれるため、表やコードブロックも保持されます。成果物の種類は id のプレフィックスで判別できます：doc:、issue:、pull_request:、readme:。 開発者向けの質問では、まずこの方法を使います。該当箇所を返すのはこのインターフェイスのみであり、それによってページを案内するだけでなく、回答できます。 k / --limit は 1～100 で、既定値は 10 です。skills="only"（HTTP/MCP のみ）を指定すると、検索対象をエージェントスキルファイルに限定できます。 API キーは不要です。レート制限を緩和するには、Authorization: Bearer $FIRECRAWL_API_KEY を送信してください。

• MCP：firecrawl_search(query, categories: ["developer"]) CLI：firecrawl search <query> --categories developer web と並んで developer グループに開発者向けの検索結果を返します。各結果には url、title、description（該当箇所）、position、category: "developer" が含まれます。ウェブ検索結果には category がないため、結果を統合する際はこのフィールドを基準にしてください。 すでにウェブ検索を実行していて、同じ呼び出しで開発者向けの情報源も検索対象に含めたい場合に使用します。フィルターは利用できず、該当箇所の表示範囲も調整できません。

• MCP：firecrawl_scrape(url) / firecrawl_search(query) CLI：firecrawl scrape <url> / firecrawl search <query> 一次情報に記載されていない内容を調べるための、一般的なウェブページの取得と検索です。2 つのライブラリの比較、サービス停止、移行に関する解説、公開リポジトリやインデックス済みドキュメントがないプロジェクトなどが対象です。 また、検索結果のページが適切でも内容全体を確認する必要がある場合は、結果の url を scrape してください。

フィルターと、それぞれの代償

これらを指定できるのは HTTP インターフェースのみです。GET では types=issue,pull_request を渡すか、パラメーターを繰り返します。POST では配列を渡します。すべて任意です。

• types — 検索対象とする doc、issue、pull_request、readme。デフォルトでは 4 種類すべてが対象です。ここで対象を絞るのが、クエリを的確にする最も低コストな方法です。
• repos（owner/name）はリポジトリ側、つまり issue、pull_request、readme を対象にします。sources（ドキュメントソース ID、最大 20 件）はドキュメント側、つまり doc を対象にします。両方を渡すと、2 つの対象範囲は交差ではなく和集合になります。どちらも indexed: true|false とともにレスポンスにそのまま返されます。これにより、「インデックスにない」のか「何も見つからなかった」のかを判別できます。
• 指定した type のいずれにも一致しないフィルターは、空のリストではなく 400 エラーになります。たとえば、types にリポジトリの種類が含まれていない場合の repos や、doc が含まれていない場合の sources です。
• passages（1～5、デフォルトは 1）は、結果ごとのパッセージ数の最大値であり、保証される数ではありません。適切なページは明らかなのに、最初のパッセージがページ内の別の箇所を示している場合は、値を大きくしてください。
• language、topic、license、min_stars、max_stars、archived、fork はリポジトリについてのフィルターです。インデックス内のドキュメントページの大半は、対応するリポジトリがないため、リポジトリに関する情報では対象に含めたり除外したりできません。これらのいずれかを sources の指定なしで送信すると、レスポンスに含まれるのはリポジトリの情報、つまり issue、pull_request、readme のみです。これは設計どおりで、インデックスの不具合ではありません。再試行したり、インデックスが壊れていると報告したりしないでください。ドキュメントも対象にするには、リポジトリのフィルターを削除するか、sources でドキュメント側を指定し、sources の返却値を確認して ID がインデックスに登録されていることを確認してください。

質問に合ったアプローチを選ぶ

• 文字列そのもののエラーメッセージまたはスタックトレース → types=["issue","pull_request"] を指定し、文字列そのものとライブラリ名を検索します。その問題に遭遇した人が報告を提出しています。一致するものがなければ、変化しやすい部分（パス、行番号、ID、アドレス）を取り除いて再試行します。インデックス化されているのは、メッセージの変わらない中核部分です。
• 概念的な「X をするにはどうすればよいか」 → 自然言語の質問全文を、4 種類すべてで検索します。答えは通常、doc または readme にあります。k を増やす前に passages を増やします。
• 既知のバグ → issue で報告され、マージ済みのプルリクエストで 修正 されています。必要なのはその修正です。types=["issue","pull_request"] で検索し、次に issue 固有の用語を、その issue のリポジトリに絞って types=["pull_request"] で再検索します。マージ済み PR のパッセージから、何がどのように変更されたかが分かります。ユーザーがインストールしているバージョンの挙動として説明する前に、リリースにその修正が含まれていることを確認します。
• API の契約（「X は何を返すか」「Y は必須か」「デフォルト値は何か」）→ 信頼できる情報源は readme と doc であり、ブログ記事ではありません。types=["readme","doc"] を使います。契約が変更されたようであれば、その変更を加えた pull_request を追加で検索します。
• バージョン固有の挙動 → issue の最初の報告には不具合が発生したバージョンが記載されており、その解決内容がそれに優先します。スレッドをさらに確認できるよう passages を増やし、回答する前に解決内容とリンク先のプルリクエストを読みます。最初の報告だけを根拠に回答してはいけません。
• 特定のライブラリに限定した質問 → スラッグが分かっている場合は repos=["owner/name"] を指定し、同じ呼び出しでそのライブラリのドキュメントも検索したい場合は sources を追加します。範囲を絞った検索結果が空の場合は、まず返された indexed フラグを確認します。false は、そのリポジトリまたはソースから一致するものが見つかる可能性がなく、言い換えても役に立たないことを意味します。範囲指定を外してインデックス全体を検索するか、ウェブを利用してください。
• エコシステム全体についての質問（「どのライブラリが X をするか」「ほかに誰がこの問題に遭遇したか」）→ 範囲を絞りません。保守されているリポジトリに絞るには language ／ topic ／ min_stars を使います。ただし、この場合はすべての doc 結果が対象外になります。
• エージェントのスキルやツールに関する慣習 → skills="only"（HTTP/MCP のみ）を指定します。
• 比較、意見、ニュース、またはインデックス化されていないプロジェクト → オープンウェブを使います。firecrawl_search で検索し、詳しく読む価値のあるものを firecrawl_scrape で取得します。組み合わせるのが適切な場合もよくあります。契約についてはインデックスから、トレードオフについてはウェブから情報を得ます。

原則

• パッセージを引用し、url を出典として示します。 パッセージが根拠です。読者が確認できない主張へ言い換えるのではなく、パッセージをそのまま提示します。doc の結果には title がないことがよくあるため、その場合は url を使います。
• 修正とリリースを区別します。 マージ済みの修正は、リポジトリのコードに関する以前の issue 報告を覆すことがありますが、リリースにそのマージが含まれて初めてユーザーのバージョンに反映されます。プロジェクトのリリースノート、変更履歴の項目、またはリリースタグで確認し、その根拠を引用します（それらを検索するか、インデックスにない場合はリリースページまたは変更履歴ページをスクレイピングします）。
• 範囲を絞るのは最後にします。 まずインデックス全体を検索し、ヒット結果の様子が分かってから types、repos、または sources で範囲を絞ります。最初から絞り込むと、どこを調べるべきかを教えてくれる結果を見落とします。
• インデックスに情報がない場合はウェブを利用します。 トレードオフ、エコシステム全体の意見、インデックス化されていないプロジェクトに関する質問は、ウェブで調べるものです。無理にインデックスで答えようとせず、一般的なウェブページを一次情報源のように見せないでください。

関連項目

• firecrawl-build-search — ここで検索する代わりに、開発者向けインデックスをアプリに組み込む方法