context-firewall

Context Firewall

中国語のドキュメント

大きな MCP ツールの出力をモデルのコンテキストウィンドウに届く前に 60～95％縮小し、50 個以上のツール定義を 4 個にまとめます。 実際の HTML／JSON を計測しています。ベンチマークをご覧ください。あらゆる MCP クライアント、あらゆるモデルで動作します。圧縮後も設定したトークン予算を超える内容は、その予算まで強制的に切り詰められます。元の全文はいつでも read_more で取得できます。

シャットダウン時に出力されるセッションレポートです。実際の 3 回の呼び出し（大きなファイルの読み取り 2 回、エコー 1 回）によるものです。すべての数値は実測値であり、シミュレーションではありません。

Context Firewall は、AI エージェント（Claude Code、Claude Desktop、Cursor、Cline など）と、設定済みのすべての下流 MCP サーバーとの間に配置されるローカル MCP プロキシです。大きなツール出力（生の HTML、base64 の塊、巨大な JSON）は、モデルのコンテキストウィンドウに届く前に圧縮されます。また、下流サーバーの実際のツール数にかかわらず、クライアントには常に 4 個のツールだけが表示されます。

計測結果

指標	結果
出力の圧縮	実際の HTML ページで 70～94％、大きな構造化 JSON で 約 97％（予算に基づく切り詰め前のスマート処理のみ）— 例：fetch ツールで取得した実際の Wikipedia ページ：232,391 → 6,907 文字（97.0％、実測）；jsonSummary ステージで処理した GitHub の issue JSON ペイロード：186,810 → 3,480 文字（98.1％、実測）
ツールの集約	公開するメタツールを 122 → 4 に削減（公式の GitHub github-mcp-server（85 個のツール）を含む、実際の下流サーバー 5 台）
ツール定義による節約	約 28,600 トークン（推定値、文字数 ÷ 3.5）— 生の定義 102,158 文字に対して、公開される定義は 2,146 文字

すべての数値は合成データではなく、実際の下流 MCP サーバーで計測しています。詳しい方法と表はdocs/BENCHMARKS.mdをご覧ください。

できること

• 段階的なツールの公開 — 起動時にすべての下流ツールの完全なスキーマを読み込む代わりに、クライアントには 4 個のメタツール（list_tool_categories、search_tools、invoke_tool、read_more）だけを表示します。実際に検索したツールの完全なスキーマに対してのみ、トークンコストが発生します。
• 出力圧縮パイプライン — 大きなツール結果は、base64 の除去、主要コンテンツの抽出と HTML から Markdown への変換（ページに識別可能なコンテンツ領域がある場合、ページの装飾要素（ナビゲーション、サイトのヘッダー／フッター）を取り除きます。これにより、トークン予算をナビゲーションリンクではなく実際のコンテンツに使えます）、JSON の構造を考慮した要約、最後に文字数予算に基づく切り詰めの順に処理されてから返されます。
• read_more で出力全文を取得可能 — 何も通知せずに破棄することはありません。圧縮された出力はすべて、全文がメモリ内に不透明なハンドルとして保存され、read_more(handle, offset, length) でページ単位に取得できます。
• セッション節約レポート — シャットダウン時に、共有可能なターミナルカード（および任意の Markdown ファイル）を出力します。セッション中のツール定義と出力トークンの節約量に加え、最も節約効果の大きかったツールの内訳も表示します。

クイックスタート

npx context-firewall --config context-firewall.json

最小限の context-firewall.json（downstreams ブロックは、すでにご存じの mcpServers 形式に対応しています）：

{
  "downstreams": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

（上記の ${GITHUB_TOKEN} は、この例で使う環境変数の 名前 にすぎません。シェルですでに設定されているものを選んでください。この値は、ダウンストリームサーバー自体が実際に読み取る環境変数名 GITHUB_PERSONAL_ACCESS_TOKEN に展開されます。）

どの GitHub サーバーを使いますか？ ツール数の異なる2つの選択肢があります。

• @modelcontextprotocol/server-github（上記で使用） — 元の npm パッケージで、ツールは26個です。npx -y の1行だけで使え、追加のセットアップは不要です。上流ではアーカイブされ、メンテナンスも終了していますが、引き続き動作します。

• github/github-mcp-server — 現在も積極的にメンテナンスされている公式サーバーです。ツールは44個（デフォルトのツールセット）から85個（GITHUB_TOOLSETS=all）です。Go バイナリまたは Docker イメージとして提供されており、npm パッケージではありません。

  "github": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
  }
  

  または、ローカルでビルド／ダウンロードしたバイナリを直接実行する場合："command": "/path/to/github-mcp-server", "args": ["stdio"]（同じ env ブロックを使います。公開する85個のツールの範囲を指定するには、GITHUB_TOOLSETS を追加してください）。

ツールごとの許可／拒否ポリシー。 任意のダウンストリームエントリに allowTools／denyTools（完全一致する名前または * グロブの配列）を追加して、呼び出し可能なツールを制限できます。

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "denyTools": ["delete_*"]
}

拒否は常に許可より優先されます。allowTools が設定されている場合、一致するツールのみが許可され、それ以外の同サーバー上のツールはすべてブロックされます。空の allowTools: [] は省略した場合と同じ扱い（すべて許可）となり、「すべて拒否」にはなりません。ブロックされたツールは search_tools の結果に表示されず、invoke_tool でもダウンストリームサーバーへのディスパッチ前に拒否されます。list_tool_categories およびメタツールの説明に表示されるツール数はフィルターされていない合計です。ポリシーが適用されるのは、search_tools／invoke_tool の実行時のみです。

クライアントのセットアップ

Context Firewall を唯一の MCP サーバーとして設定してください — 現在直接設定しているすべてのダウンストリームサーバー（filesystem、github、その他すべて）を context-firewall.json の downstreams ブロックに移してください。エージェントに表示されるツールは、すべてのダウンストリームサーバーのツール数の合計ではなく4個になります。Context Firewall を既存のサーバーと併用してクライアントに設定しても、ツール数の削減や圧縮のメリットは得られません。

以下の各クライアントでは、同じサーバーエントリを使用します。

{
  "mcpServers": {
    "context-firewall": {
      "command": "npx",
      "args": ["-y", "context-firewall", "--config", "/absolute/path/to/context-firewall.json"]
    }
  }
}

Claude Code

リポジトリのルートにプロジェクトスコープの .mcp.json を配置する（上記参照）か、CLI から設定します。

claude mcp add --transport stdio context-firewall -- npx -y context-firewall --config /absolute/path/to/context-firewall.json

Claude Desktop

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json）に、上記と同じ mcpServers ブロックを設定します。

Cursor

.cursor/mcp.json（プロジェクトスコープ）または ~/.cursor/mcp.json（グローバル）に、上記と同じ mcpServers ブロックを設定します。

Cline

cline_mcp_settings.json（VS Code 拡張機能のストレージ。macOS：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）に、上記と同じ mcpServers ブロックを設定します。

互換性の状況

クライアント	状況
Claude Code	実際のエージェントセッションでテスト済み — 自律的な list → search → invoke → read_more のワークフローをエンドツーエンドで検証済み
Claude Desktop	プロトコル検証済み*
Cursor	設定形式をドキュメント化済み。コミュニティによるテストを歓迎します
Cline	設定形式をドキュメント化済み。コミュニティによるテストを歓迎します

* MCP プロトコル統合テスト（実際のダウンストリームサーバーに対する stdio プロトコルの完全な往復テストを含む、自動テスト236件）で検証済みです。プッシュのたびに CI で実行されています。実際のクライアントでの動作報告も歓迎します。

設定

downstreams

各エントリは stdio サーバー（mcpServers と同じ形式）または Streamable HTTP サーバーです。

{
  "downstreams": {
    "local-tool": { "command": "npx", "args": ["-y", "some-mcp-server"], "env": { "TOKEN": "${TOKEN}" } },
    "remote-tool": { "url": "https://mcp.example.com/mcp", "transport": "streamable-http" }
  }
}

文字列値の ${VAR_NAME} は、環境変数から展開されます。変数が見つからない場合は、わかりやすいエラーを表示して設定の読み込みに失敗します。

compression

ポリシーの適用順序は default < perServer < perTool です（後の設定が、項目ごとに前の設定を上書きします）。

{
  "compression": {
    "default": {
      "maxOutputTokens": 2000,
      "htmlToMarkdown": true,
      "stripBase64": true,
      "jsonSummary": true,
      "llmSummary": false,
      "bypass": false
    },
    "perServer": { "github": { "maxOutputTokens": 4000 } },
    "perTool": { "filesystem/read_file": { "maxOutputTokens": 8000 } }
  }
}

項目	型	デフォルト	意味
maxOutputTokens	number	2000	圧縮された出力を、最終手段として切り詰める際のソフト上限です（文字数 ≈ トークン数 × 3.5）。
htmlToMarkdown	boolean	true	検出された HTML を Markdown に変換します。判別できる場合は、メインコンテンツ領域を抽出します（ナビゲーション／ヘッダー／フッターの装飾部分は除去されます）。
stripBase64	boolean	true	base64 の塊（データ URI および単独のブロック）を read_more ハンドルに置き換えます。
jsonSummary	boolean	true	JSON の構造を維持しつつ、同種の JSON 配列をまとめ、長い文字列フィールドを短縮します。
llmSummary	boolean	false	予算を超えた出力を、選択した LLM で意味的に要約します。トップレベルの llm ブロックが必要です。詳しくはLLM による要約（オプトイン）を参照してください。
bypass	boolean	false	このサーバー／ツールのパイプライン全体をスキップします。出力は変更されずにそのまま渡されます。

report

{
  "report": {
    "enabled": true,
    "markdownPath": "./context-firewall-report.md"
  }
}

項目	型	デフォルト	意味
enabled	boolean	true	シャットダウン時にセッションレポートを stderr に出力します。
markdownPath	string	(なし)	設定すると、指定したパスにレポートを Markdown ファイルとしても書き込みます。

callToolTimeoutMs

トップレベルの設定です（compression の下にはネストしません）。下流の MCP SDK クライアントに渡す、invoke_tool ごとのタイムアウトをミリ秒単位で指定します。応答せずに停止した下流は、この時間が経過すると invoke_tool をブロックし続ける代わりに、isError 結果を返します。未設定の場合、SDK 独自のデフォルト値（60,000ms）が適用されます。

{ "callToolTimeoutMs": 30000 }

仕組み

クライアントは list_tool_categories() を呼び出して、接続されているものとその大まかな機能を確認し、search_tools(query) を呼び出して候補ツールの完全な入力スキーマを取得し、invoke_tool(server, tool, args) を呼び出して実際にツールを実行します（戻り時に圧縮されます）。圧縮された内容をページ単位で取得するには、read_more(handle, offset, length) を呼び出します。圧縮を行う場合、常に同じ順序で適用されます。base64 の除去 → メインコンテンツの抽出と HTML から Markdown への変換 → JSON 構造の要約 → 予算に合わせた切り詰めです（以下のオプトイン方式の LLM 要約ステージが有効な場合は、切り詰めの直前に実行されます）。コンテンツ抽出は、意図的に保守的な設計になっています。意味的なコンテンツ領域（<article>／<main>）を識別できる場合、または除去対象がページの実際のコンテンツではないことが明らかな場合にのみ、ページの装飾部分を除去します。それ以外の場合はページ全体を変換し、どちらの場合も元の内容全体を read_more から取得できます。セキュリティに関わる出力（エラー、権限／警告／確認メッセージ）は、黙って圧縮されることはありません。そのまま渡されますが、呼び出し元のコンテキストが単一の異常に大きなエラーダンプで圧迫されないよう、50,000 文字でハード上限を設けています。

LLM による要約（オプトイン）

決定論的なパイプラインでは、マークアップを除去し、繰り返しの多い構造をまとめ、出力を切り詰めることができますが、長い自然言語の出力（ログファイル、記事、レポートなど）を意味的に圧縮することはできません。決定論的な段階を終えても予算を超えている部分は、そのまま切り捨てられます。このオプションの段階は、その不足を補います。予算を超えたテキストを選択したモデルに送り、事実に即した要約を作成します（ID、パス、URL、数値、エラーメッセージは保持します）。未加工の全文を参照する read_more ポインターを追加し、最後の保護策として切り詰めを残します。デフォルトでは無効で、トップレベルの llm ブロックと、圧縮ポリシー内の llmSummary: true の2つの層で明示的なオプトインが必要です。OpenAI 互換の /chat/completions エンドポイントであれば利用できます。プロバイダーのプリセットを選ぶか、baseUrl を任意のエンドポイントに指定してください。

{
  "llm": {
    "provider": "openrouter",
    "model": "your-model-name"
  },
  "compression": {
    "default": { "llmSummary": true }
  }
}

provider は、プリセットのベース URL と慣例的な API キー環境変数をまとめて指定するものです。

プロバイダー	ベース URL	キーの環境変数
openai	https://api.openai.com/v1	OPENAI_API_KEY
openrouter	https://openrouter.ai/api/v1	OPENROUTER_API_KEY
orcarouter	https://api.orcarouter.ai/v1	ORCAROUTER_API_KEY
deepseek	https://api.deepseek.com/v1	DEEPSEEK_API_KEY

その他の OpenAI 互換エンドポイントは、代わりに baseUrl で指定できます（その場合、apiKey が必要です）。

{
  "llm": {
    "baseUrl": "https://api.your-provider.example/v1",
    "apiKey": "${LLM_API_KEY}",
    "model": "your-model-name"
  },
  "compression": {
    "default": { "llmSummary": true }
  }
}

フィールド	型	デフォルト	意味
provider	string	(なし)	上記のプリセット名のいずれかです。provider または baseUrl のどちらかが必要です。両方が設定されている場合は、明示的に指定された baseUrl が優先されます（警告が表示されます）。
baseUrl	string	(プリセットから取得)	任意の OpenAI 互換エンドポイントのベース URL です。この段階では <baseUrl>/chat/completions に POST リクエストを送信します。provider が設定されていない場合は必須です。
apiKey	string	(プリセットの環境変数から取得)	Authorization: Bearer ... として送信されます。provider を指定した場合、デフォルトではプリセットのキー環境変数を使用します。明示的な値（${ENV_VAR} による展開を使用してください。キーを直接記述しないでください）を指定すると、それが優先されます。baseUrl のみを指定する場合は必須です。
model	string	(必須)	エンドポイントにそのまま渡されるモデル名です。
timeoutMs	number	20000	この時間が経過するとリクエストを中止します。タイムアウト時、この段階は何もせずに終了します。
maxInputChars	number	120000	API に送信するテキストを、先頭からこの文字数までに切り詰めます（設定にかかわらず絶対上限は 400,000 文字で、コストを抑えるための制限です）。

OrcaRouter を使用する例です。無料モデルでうまく動作します（orcarouter/free は難易度に応じてルーティングされる同社の無料ティアです。API キーは ORCAROUTER_API_KEY から読み込まれます）。

{
  "llm": {
    "provider": "orcarouter",
    "model": "orcarouter/free"
  },
  "compression": {
    "default": { "llmSummary": true }
  }
}

実行可能な設定例全体は、examples/config.llm-orcarouter.json と examples/config.llm-generic.json を参照してください。

障害時の動作：エンドポイントがダウンしている、到達できない、タイムアウトする、または形式が不正な応答を返した場合、この段階は何もせずに終了し、出力は決定論的な切り詰めにフォールバックします。エンドポイントが利用できなくても、ツールに支障をきたすことはありません。

プライバシー：この機能を有効にすると、予算を超えたセキュリティ上重要ではないツール出力が、設定したエンドポイントに送信されます。それ以外のものが、ほかの場所に送信されることはありません。エラー、権限の拒否、警告、確認などのセキュリティ上重要な出力は、この段階に到達する前に圧縮パイプラインをバイパスするため、送信されることはありません。ツール出力の内容をそのエンドポイントに送信することが、データの取り扱い上許容できない場合は、この機能を有効にしないでください。

開示事項

Context Firewall は OrcaRouter Open Source Program に参加しています。エンドポイントとして OrcaRouter を選択した場合、このプロジェクトは使用によって生じる収益の 5% を受け取ります。料金は変わらず、完全に任意です。また、OpenAI 互換のプロバイダーであれば、どれを使用しても同様に動作します。

位置づけ

Context Firewall は Anthropic の Tool Search Tool を補完するものであり、競合するものではありません。Tool Search は、ツールを呼び出す前にコンテキストへ読み込まれるスキーマによって起動時に発生する、ツール定義の肥大化を解決するもので、Claude 専用です。Context Firewall は、Tool Search が扱わない問題のもう半分である、呼び出し時のツール出力を圧縮します。また、Claude だけでなく、あらゆる MCP クライアントおよびあらゆるモデルで動作します。

トークン数について

このプロジェクトにおけるトークン数（切り詰めの上限、セッションレポート）はすべて chars / 3.5 による推定値であり、モデル固有の正確な数ではありません。デフォルトでは、トークン数の計測を含め、ツール出力の内容を外部 API に送信するコードパスはありません。任意の LLM 要約ステージを明示的に有効にした場合、上限を超える出力は、ユーザーが設定したエンドポイントにのみ送信されます。それ以外の場所には送信されません。いずれの場合も、トークン数の計測はローカルで行われます。このため、セッションレポートには常に「(推定値)」と記載されます。

安全性

• ツールの引数や出力内容がログやセッションレポートに記録されることはありません。記録されるのはサーバー名／ツール名と文字数／トークン数のみです。
• エラー、権限拒否、警告、確認など、セキュリティに関わる出力が黙って圧縮されることはありません。
• デフォルトでは、ツール出力の内容がご使用のマシンから外部に送信されることはありません（設定した下流サーバーへの送信を除きます）。オプトインの LLM 要約ステージだけが、内容を別の場所に送信できるコードパスです。この機能はデフォルトで無効であり、セキュリティ上重要な出力がこのステージに送られることはありません。
• 下流ツールの説明は信頼できない入力として扱われ、表示されるだけで、実行されることはありません。
• 下流ツールの説明はそのまま渡され、サニタイズされません。search_tools が、悪意のある下流サーバーが説明に含める可能性のあるプロンプトインジェクションのテキストを除去またはフィルタリングすることはありません。信頼境界となるのは、ゲートウェイではなく、設定する下流サーバーの選択です。
• 段階的な情報開示には、実際のトレードオフがあります。ツールの説明は、呼び出し元のモデルが search_tools を介して要求したそのとき、セッションの途中で届きます。そのタイミングは、セッション開始時にすべてのツールが提示される場合と比べ、モデルが埋め込まれた指示を精査する可能性が最も低いときでもあります。v0.3.0 では、次の 2 つの方法でリスクを軽減しています。search_tools の結果を、プロセス起動時に一度生成されるランダムな nonce（crypto.randomBytes(8).toString('hex')、プロセスの全稼働期間を通じて固定）を含む <untrusted-tool-descriptions nonce="...">...</untrusted-tool-descriptions nonce="..."> 区切り文字で囲み、一致する nonce を含む閉じタグだけがブロックを終了することをモデルに伝える注記を付けています。また、CLI は起動時に人が読めるダイジェスト（サーバー名、ツール数、主要カテゴリ）を stderr に出力するため、オペレーターは実際に何が接続されたかをすぐに確認できます。この nonce は、下流サーバーが説明に独自の </untrusted-tool-descriptions> 文字列と偽の「信頼できるシステム」指示を埋め込むという、文字列を使ったバイパスを特に防ぎます。nonce を予測できないため、一致する閉じタグを偽造できません。残存リスク：これは依然としてテキストレベルの取り決めであり、サンドボックスではありません。呼び出し元のモデルが実際に注記を読み、nonce の一致を尊重することに依存しており、モデルが枠組み全体を無視するのを防ぐ手段はありません。どちらの軽減策も説明内容そのものをサニタイズするものではありません。上記をご覧ください。区切り文字による枠組みの追加コストは、search_tools の呼び出しごとに約 80～85 トークンです（約 289 文字。このプロジェクトの chars/3.5 による推定値）。
• list_tool_categories が表示するカテゴリも、下流から提供されたデータ（ツール名。registry.ts の単純な動詞プレフィックス判定による）から導出されます。ただし、ツール名は自由記述の説明よりも指示を紛れ込ませる帯域幅がはるかに小さく、この出力は上記の区切り文字で囲まれていません。search_tools の出力よりリスクは低いものの、リスクがないわけではないものとして扱ってください。

ライセンス

MIT