構造化抽出を用いてClaudeコードのウェブリサーチトークンを削減する方法

TL;DR:

• Claude Codeのウェブリサーチトークンは、モデルに届くものによって動かされ、ネットワークを横断するものだけではありません。 生のHTML、繰り返しナビゲーション、重複URL、ツールメタデータ、冗長な結果は全てコンテキストを消費する可能性があります。
• 推論ステップの前にコンテンツを減少させること。 メインコンテンツの抽出を優先し、狭いセレクター、フィールドレベルの抽出、および不完全な結果を拒否するJSONスキーマを使用すること。
• ソースURLと証拠スニペットを保持すること。 小さなペイロードは、回答が監査可能で完全である限りにおいてのみ有用です。
• MCPは取得と推論を分離できます。 Claude Codeは制限されたScrapelessツールを選択し、そのツールはタスクに必要なフィールドのみを返します。
• 我々の再現可能なプロキシテストは、181,892から434の比較トークンに固定入力をカットしました。 これは1つの公開文書ページ、1つの質問、およびcl100k_baseを使用しました；これらはClaudeの請求トークンではありません。

Claude Codeはウェブを検索し、ページを取得し、MCPツールを呼び出し、返された素材を基に推論することができます。それは研究を便利にしますが、便利さは基本的なコスト問題を隠すことがあります：6つの事実が必要な質問は、数万の無関係な文字をコンテキストに引き込む可能性があります。

修正策は「より積極的に要約する」ことではありません。要約は別のモデルタスクであり、必要な証拠を取り除く可能性があります。より良いワークフローは、取得時にコンテンツを減少させ、結果を検証し、メインモデルに小さな証拠契約を送信します。

このチュートリアルは、Claude CodeのためにScrapeless MCPサーバーとユニバーサルスクレイピングAPIパターンを使用してそのワークフローを構築します。

Claude Codeウェブリサーチトークンの発生元

研究パスを4つの別々のボリュームとして扱います：

取得したバイト → 抽出された文字 → モデルコンテキストトークン → 構造化回答トークン

彼らは関連していますが、相互に交換可能ではありません。

ページ取得ボリューム

これはブラウザ、フェッチャー、またはスクレイピングサービスが受け取るものです。レンダリングされたページは、スクリプト、スタイル、ナビゲーション、クッキーバナー、埋め込まれた状態、および複数のルートのコンテンツを含む可能性があります。取得ボリュームはネットワークとスクレイピングのコストに影響しますが、Claudeのコンテキストに入る必要はありません。

返された文字

ツールは何を返すかを選択します：生のHTML、読みやすいMarkdown、選択された要素、またはJSONオブジェクトです。これは最も有用なコントロールポイントです。ここでボイラープレートを削除すると、後のすべてのステップがそれを処理する必要がなくなります。

メインモデルコンテキスト

Claude Codeはシステム命令、会話履歴、ツール定義、ツール結果、および現在のリクエストを読み取ります。簡潔なツールの応答は、大規模なプロジェクトコンテキストの横に座ることができます。現在のClaude Codeコンテキストウィンドウ文書を使用して、コンテキストがどのように管理されているかを理解しますが、一つの固定容量や価格を仮定するのではなく、自分のワークフローを測定してください。

構造化回答出力

JSONスキーマは最終的な回答を制約します。それはそれに先立つページコンテンツを自動的に縮小するわけではありません。ツールの結果にも、最終的な応答にも構造を適用します。

最適化する前にベースラインを設定する

1つのリサーチ質問と固定ソースセットを使用します。記録します：

• 要求されたソースURL；
• 各ツールによって返された文字；
• モデルとClaude Codeのバージョン；
• 計測に使用したトークナイザーまたはAPI使用フィールド；
• 入力および出力トークン数；
• 必要な回答フィールドと完全性結果。

Claude Codeは現在のCLIオプションをclaude --helpで公開しています。この文章で使用したマシンでは、Claude Code 2.1.162が--mcp-config、--tools、--output-format、および--json-schemaをリストしました。現在のClaude Codeツールリファレンスは、WebSearchとWebFetchを組み込みツールとして文書化しています。

これらのClaude CodeツールをAnthropic APIウェブツールと混同しないでください。APIのウェブフェッチ文書は、動的フィルタリングなどのサーバー側の機能を説明しています。APIのために文書化された機能は、自動的にClaude CodeのWebFetchオプションであるわけではありません。

ステップ1：生のHTMLよりもメインコンテンツを優先する

生のHTMLは、セレクターのデバッグや正確なマークアップの保持に役立ちますが、通常は良い研究ペイロードではありません。

取得レイヤーに以下の内容を削除するように依頼します：

• スクリプト、スタイル、SVG、テンプレートコンテンツ；
• サイトナビゲーションと繰り返しのフッター；
• 同意とアカウントシェル；
• 質問に必要のない隠れた状態；
• 無関係な推奨事項とコメント。

読みやすいMarkdownは、最初の削減にはしばしば良い選択です。見出し、リスト、リンク、コードを保持しながら、プレゼンテーションレイヤーの多くを廃棄します。それでも、タイトルと必要なセクションが存在することを確認してください；クリーンなログインページは成功した抽出ではありません。

ステップ2：質問に必要なフィールドのみを抽出する

メインコンテンツは、回答よりもはるかに大きく残る可能性があります。いくつかのページを取得する前に、質問を抽出契約に変換します。

{
  "type": "object",
  "required": ["source_url", "tools", "complete"],
  "properties": {
    "source_url": { "type": "string", "format": "uri" },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "evidence"],
        "properties": {
          "name": { "type": "string" },
          "evidence": { "type": "string", "maxLength": 1200 }
        }
      }
    },
    "complete": { "type": "boolean" }
  }
}

証拠は簡潔に保ちますが、サポートされない値に減らさないでください。例えば、supports_web: true のようなフィールドはコンパクトで監査が難しいです。ソースURLと制約された証拠スニペットにより、レビュアーは解釈を確認できます。

繰り返されるページ形状については、ターゲットセレクタまたは構造化抽出エンドポイントを使用してください。さまざまなページについては、まず読みやすいコンテンツをリクエストし、可能な限り決定論的なコードで関連セクションを選択します。

ステップ 3: 取得前にURLを重複排除する

リサーチエージェントは、ナビゲーション、検索パラメータ、言語のエイリアス、またはフラグメントを介して同じ文書に遭遇することがよくあります。取得する前に正規化します：

1. 相対URLを解決します。
2. フラグメントを削除します。
3. 承認されたクエリパラメータポリシーを適用します。
4. リダイレクトを一度だけ追跡し、最終的な標準的なアイデンティティを記録します。
5. ミラーまたは繰り返しをキャッチするために、受け入れたコンテンツをハッシュします。

すべてのクエリパラメータを削除しないでください。ロケール、バージョン、製品、または日付パラメータは文書を変更する可能性があります。正規化ルールはソースポリシーに属し、ユニバーサルな文字列クリーナーではありません。

小さなキャッシュも、一度の実行での繰り返し収集を防ぐことができます。正規のソース、ロケール、抽出契約バージョン、そして新鮮さの要件によってキーを設定します。

ステップ 4: Claude CodeをScrapeless MCPに接続する

MCPはエージェント向けインターフェースを小さく保ちます。Claude Codeは名前付きツールやスキーマを確認し、Scrapelessはその背後で検索、公的ページのスクレイピング、またはクラウドブラウザの操作を処理します。

前提条件：

• Claude CodeとNode.jsがインストールされていること；
• ScrapelessアカウントとAPIキー；
• 公的なターゲットの許可；
• ページとツールコールの予算。

キーを環境変数に保存します。このプロジェクトレベルの例は変数展開を使用しているため、秘密情報はコミットされません：

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "${SCRAPELESS_KEY}"
      }
    }
  }
}

オブジェクトを承認されたプロジェクト内の.mcp.jsonとして保存し、そのプロジェクトからClaude Codeを起動します。claude mcp listを実行して接続の健康状態を確認します。Claude CodeはプロジェクトスコープのMCPサーバーの承認を必要とします。承認する前にコマンドと環境キーを確認してください。

編集検証中、現在のScrapelessパッケージは標準MCPクライアントフローでstdio経由で起動されました。検証環境に本番キーが存在しなかったため、資格のあるウェブコールは実行されませんでした。最初の実際のツールコールは受け入れテストとして扱い：許可されたURL1つ、必要なフィールドセット1つ、そして広範なクロールはありません。

現在のClaude Code MCPドキュメントはスコープ、トランスポート、ツール発見、出力制限、環境変数の展開を説明します。Scrapeless Claude統合ガイドは製品固有のサーバー設定を提供します。

ステップ 5: エージェントに制約されたリサーチ契約を与える

「このトピックをリサーチしてください」は探究を招きます。制約されたプロンプトはソース、フィールド、停止条件を定義します。

次のようなリクエストを使用します：

名称付き製品に関する公式ソースを最大5つ検索します。標準的なURLを重複排除します。受け入れた各ソースについて、タイトル、最終URL、公開または更新日（表示されている場合）、および必要な機能をサポートする証拠スニペットを1件返します。3つの完全なソースの後に停止します。欠落しているフィールドをマーキングし、推測しないでください。

この契約は、無制限の検索、重複取得、冗長な結果、そして作成されたフィールドの4つの失敗モードを同時に制御します。

また、MCPツールセットもフィルタリングします。ドキュメントタスクには、すべてのブラウザアクションではなく、検索と一度のMarkdown抽出が必要かもしれません。少ない可視ツールは選択のあいまいさを減少させ、許可レビューを簡素化します。

ステップ 6: 減少と完全性を一緒に測定する

私たちは公共のClaude Codeツール参照ページと1つの固定された質問を使用しました：

どの組み込みのClaude Codeツールが公的なウェブコンテンツを検索または取得でき、研究ワークフローにどのような制約を適用すべきですか？

同じcl100k_baseトークナイザーが質問と各マテリアルバリアントをカウントしました。これはオープンな比較プロキシであり、Anthropicのトークナイザーでも、Claudeの請求測定でもありません。

ターゲットJSONは主なコンテンツに比べて約95.4%少ない比較トークンを使用し、生のHTMLに比べて99.8%少なくなりました。これらの割合はこのページとこの抽出契約にのみ適用されます。

完全性チェックは意図的に狭く設定されていました：両方の必要なツール名が主テキストと抽出されたオブジェクトの中に存在し、ソースのアイデンティティが保持される必要がありました。本番評価では、各証拠スニペットが最終的な答えを支持しているかどうかもスコアをつけるべきです。

ステップ7: 結果受入ゲートを追加する

圧縮は正確性ではありません。コンテンツが主要な推論ステップに入る前に、以下を検証します:

• 最終URLが許可リストに属していること;
• ページのアイデンティティが要求されたドキュメントと一致していること;
• 必須フィールドが存在し、適切なタイプであること;
• 証拠が主張されたエンティティまたは用語を含んでいること;
• コンテンツがエラー、同意、ログイン、またはアクセスチャレンジシェルでないこと;
• レコードが収集時間と抽出契約のバージョンを含んでいること;
• 戻される全体の文字数がタスクの予算内であること。

accepted、missing_fields、wrong_page、access_required、またはover_budgetのような型指定された結果を返します。Claudeは、すべての失敗を通常の文章として扱うことなく、停止するか、別の承認されたルートを使用するかを判断できます。

ユニバーサルスクレイピングAPIを代わりに使用する場合

MCPは、Claude Codeが対話的にウェブ機能を発見し選択する必要があるときに便利です。ユニバーサルスクレイピングAPIは、プログラムがすでにターゲットを知っていて、CI、データジョブ、またはサービスから予測可能なリクエストを必要とする場合により良い境界です。

APIパスを使用する必要がある場合:

• 決定論的アプリケーションコードからの抽出を呼び出すため;
• エージェントの外でレートおよび予算コントロールを集中化するため;
• Claude Codeが実行される前に結果を正規化するため;
• 多くの研究セッションで受け入れたレコードをキャッシュするため。

同じ原則が適用されます: 受入契約を満たすことができる最も費用対効果の高い出力を要求し、その後、Claudeに受け入れたフィールドのみを送信します。ユニバーサルスクレイピングAPI製品ページおよび現在のドキュメントでサポートされているエンドポイントとリクエストフィールドを確認してください。

一般的な間違い

状況に応じて生のページを「万が一」のために送信する

これはシステムの最も文脈依存の部分に選択作業を移します。生の素材をプロンプトの外に保存し、証拠バンドルを送信してください。

回答契約なしでトークンを最適化する

必須の事実を省いた小さなレスポンスは効率的ではありません。トークン削減だけでなく、コストごとに受け入れられた回答を測定します。

ソースアイデンティティを無視する

最終URLと証拠がなければ、結果は安全に監査または更新できません。

プロンプトやコミットされた設定でキーを露出させる

環境変数とプロジェクトの秘密管理を使用してください。プロンプト、例、ログ、またはリポジトリにプロダクションキーをペーストしないでください。

ツール出力制限が関連性を保証するという仮定

出力キャップは無制限のサイズを防ぎますが、正しいパッセージを選択したりページを検証したりはしません。

プロダクションチェックリスト

• ベンチマークのために質問、モデル、ソースセット、出力スキーマを修正します。
• 各ツールの境界で戻される文字数を数えます。
• 収集の前に標準的なURLを重複排除します。
• 生のHTMLよりもMarkdown、セレクター、または構造化されたフィールドを優先します。
• 最終URL、証拠、収集時間、および契約のバージョンを保持します。
• 主モデルの推論の前に誤ったページや不完全な結果を拒否します。
• 可視的なMCPツールと承認されたターゲットを制限します。
• 秘密をプロンプトやバージョン管理の外に保ちます。
• 孤立したトークン数ではなく、受け入れた結果のコストを比較します。

Scrapeless MCPサーバーの概要を読み、Scrapelessの価格設定を確認し、1つの制約のある研究タスクから始めましょう。

FAQ

Q: WebFetchはブラウザツールよりも常に少ないClaude Codeトークンを使用しますか?

いいえ。トークンの使用は、文脈に戻される素材に依存します。簡潔なブラウザ抽出は冗長なフェッチよりも小さい場合がありますが、クリーンフェッチはブラウザHTMLよりも小さい場合もあります。戻されるコンテンツを測定します。

Q: JSONスキーマは入力トークンを削減できますか？

構造化された出力を削減および検証できますが、自動的にページコンテンツを縮小するわけではありません。抽出の境界と最終回答で再度スキーマを適用します。

Q: この記事のトークン数はClaudeトークンですか?

いいえ。これらは再現可能なcl100k_baseの比較プロキシです。請求関連の数値については、現在のAnthropicトークン数カウントまたは使用インターフェースを使用し、正確なClaudeモデルを利用してください。

Q: 直接スクレイピングAPIを呼び出す代わりにMCPを使用する理由は何ですか?

MCPは、Claude Codeがインタラクティブなタスク中に制限されたツールを発見し、呼び出す必要があるときに使用します。アプリケーションコードがページを収集するタイミングと方法をすでに知っている場合は、直接APIを使用します。

Q: 抽出が必要な事実を削除しなかったことをどのように確認できますか？

収集前に必要なフィールドと証拠を定義し、その後完全性および意味的チェックを実行します。監査または再処理のために、ソースURLと生のスナップショットをプロンプトの外に保持してください。