context-mode徹底解説｜AIコーディングのトークン浪費を防ぐMCPサーバー【ツール出力98%圧縮】

context-mode は、AIコーディングエージェントの「コンテキスト浪費」を根本から抑えるためのオープンソースのMCP（Model Context Protocol）サーバーだ。Claude Code や Gemini CLI のようなエージェントは、ツールを呼び出すたびに生の出力をコンテキストウィンドウへ丸ごと流し込む。その結果トークンが急速に枯渇し、会話が途中でコンパクション（自動要約）されて作業の文脈が失われる。context-mode は、この課題に対してツール出力の圧縮・セッションの永続化・ナレッジ検索という3つの仕組みで応える。

AIエージェントを支えるフレームワークやオーケストレーションの全体像は AIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 にまとめている。本記事はその中でも「エージェントのコンテキスト管理」に特化したツールとして context-mode を掘り下げる。

context-mode とは：AIコーディングのコンテキスト枯渇を防ぐMCPサーバー

context-mode（GitHubリポジトリ mksglu/context-mode）は、TypeScriptで実装されたMCP（Model Context Protocol）サーバーだ。GitHub Starは18,000超、Forksは1,300超（いずれも2026年7月時点）、コミット数は2,000超と開発は活発に続いている。ライセンスは Elastic License 2.0（ELv2）で、個人利用・社内利用は無償だが、これを「マネージドサービスとして第三者に提供する」用途には制限がかかる点に留意したい。

一般に「コンテキスト問題」というと、LLMに渡す情報をどう集めるか（RAGや検索、ファイル読み込み）が語られがちだ。context-mode が狙うのは、その裏側にある「集めた情報がどれだけコンテキストを食い潰すか」という、もう一方の問題である。公式READMEはこれを「the other half of the context problem（コンテキスト問題のもう半分）」と表現している。

どれだけ賢いモデルでも、コンテキストウィンドウは有限だ。そこにツールの生出力が無秩序に積み上がれば、モデルは「本題を考えるための余白」を失う。しかも一度あふれてコンパクションが走ると、それまでの試行錯誤の記憶ごと要約されてしまう。context-mode は、この「入れすぎ」と「忘れすぎ」の両方に効く仕組みとして設計されている点がユニークだ。

MCPツールの出力がコンテキストを食い潰す

現在のAIコーディングエージェントは、MCP経由でブラウザ操作・GitHub API・ファイル検索など多彩なツールを呼び出せる。ところが問題は、ツールの実行結果（生データ）がそのままコンテキストウィンドウに積み上がることだ。READMEは具体的な数字を挙げている。Playwrightのページスナップショット1回で約56KB、GitHub Issueを20件取得すれば約59KB。数回のツール呼び出しで、モデルが本来コードを考えるために使うべきトークン枠が、生データで埋め尽くされてしまう。

context-mode はこの生データを一度サンドボックスで受け止め、「AIが本当に必要とする要約・抽出結果だけ」をコンテキストに返す。開発思想は “Think in Code”（コードで考える）と名付けられており、READMEは「LLMは分析を計算するのではなく、分析をプログラムするべきだ。50個のファイルをコンテキストに読み込んで関数の数を数えるのではなく、エージェントがスクリプトを書いて数えさせる」と説明する。

context-mode が解決する4つの課題

READMEは、context-mode が取り組む課題を4つに整理している。いずれも「ツールを使えば使うほどコンテキストが痩せていく」という、エージェント運用の構造的な弱点だ。

・巨大なツール出力によるコンテキストの氾濫：前述のとおり、Playwrightのスナップショットで56KB、GitHub Issue20件で59KBといった生データが、要約されないままコンテキストへ流れ込む。数回の呼び出しで枠が埋まり、モデルが本来の推論に使えるトークンが痩せていく
・コンパクションによるセッション状態の喪失：会話が長くなるとモデルは自動で履歴を要約する。この過程で「どこまで何をやったか」という作業の足跡が抜け落ち、エージェントが同じ調査や編集を繰り返してしまう
・非効率なデータ処理：本来ならスクリプト1本で済む集計を、ファイルを全文コンテキストに読み込ませて「読んで数える」ように解かせると、トークンも時間も無駄になる
・冗長なレスポンスによるトークン浪費：ツールが返す定型的なメタデータやボイラープレートが、答えに関係なくコンテキストを占有する

context-mode は、これら4つを「サンドボックスで処理して結果だけ返す」「状態をSQLiteに逃がして後で復元する」という2つの原則でまとめて解消する。

context-mode が答える読者の3つの疑問

・何ができるのか：MCPツールの巨大な出力をサンドボックス内で処理して圧縮し、コンテキストに返すトークン量を劇的に減らす。加えてセッション状態を永続化し、ドキュメントを検索できるナレッジベースを提供する
・何を解決するのか：ツール出力によるコンテキスト枯渇、コンパクションでの作業文脈の消失、冗長なレスポンスによるトークン浪費という「もう半分のコンテキスト問題」を解決する
・何を代替できるのか：巨大なツール結果を手作業でコピペ・要約する運用、会話が要約されるたびに前提を貼り直す運用、そしてナレッジ参照のための場当たり的なファイル読み込みを代替する

context-mode の主要機能｜出力圧縮・セッション継続・ナレッジ検索

context-mode の機能は大きく3本柱に整理できる。いずれも「トークンをどう節約し、作業の連続性をどう保つか」という一点に向かっている。

サンドボックス実行によるツール出力の圧縮

context-mode は、ツールの実行を隔離されたサブプロセス（サンドボックス）内で行い、標準出力に出た必要な結果だけをコンテキストへ返す。READMEによれば圧縮率は約98%に達し、315KBの出力が5.4KBまで削減された例が示されている。

サンドボックスは12のランタイムに対応する。JavaScript・TypeScript・Python・Shell・Ruby・Go・Rust・PHP・Perl・R・Elixir・C# だ。つまりエージェントは、ログ解析でもデータ集計でも、その場でスクリプトを書いて実行し、「答えの数字だけ」を受け取れる。50件のログを全文読ませてトークンを浪費する代わりに、grep 相当の処理をコードで書かせて件数だけ返す、という発想である。

処理を隔離されたサブプロセスで走らせる意味は2つある。ひとつは、実行時に生成される中間データ（読み込んだファイルの中身、APIレスポンスの全文など）がコンテキストに一切漏れないこと。もうひとつは、console.log などで明示的に出力した結果だけがモデルに返るため、「何をコンテキストに載せるか」をコード側で完全に制御できることだ。結果として、315KB→5.4KBのような大幅な削減が現実的な数字として得られる。

たとえば「あるディレクトリに関数がいくつ定義されているか」を知りたいとき、従来型のやり方では50個のソースを順にコンテキストへ読み込ませ、モデルに数えさせる。これはトークンも遅延も膨らむ。”Think in Code” では、モデルに「関数定義を正規表現でカウントして件数だけ出力するスクリプト」を書かせ、ctx_execute で走らせて console.log(count) の1行だけを返す。モデルが受け取るのは「128」のような答えだけで、ソースコード本体はコンテキストに一切載らない。計算の重い部分をLLMの外へ追い出す、という発想の転換がここにある。

セッションの永続化とコンパクション対策

長い会話を続けると、モデルのコンテキストは自動的にコンパクション（要約）される。このときに失われがちなのが「どのファイルをどう編集したか」「どのgit操作をしたか」「何のエラーが出て、ユーザーが何を決めたか」といった作業の履歴だ。

context-mode は、これらのイベントを SQLite に逐次記録する。記録対象はファイル編集・git操作・タスク・エラー・ユーザーの判断など。検索には全文検索エンジンの FTS5 と BM25 ランキングを使い、会話が圧縮されたときに「いま関連する過去の文脈」だけを取り出して復元する。コマンドラインからは --continue / --resume で以前のセッション状態を明示的に呼び戻せる。

ここで効いてくるのが、状態をモデルのコンテキストではなく外部のSQLiteに逃がしている点だ。コンテキストは有限で、コンパクションのたびに古い情報から削られていく。一方でSQLiteに記録された履歴は消えないため、「20分前に修正したファイルのパス」や「一度失敗したテストの原因」を、必要になった瞬間にFTS5検索でピンポイントに引き戻せる。エージェントが同じ調査をやり直したり、既に決まった方針を忘れて逆戻りしたりする事故が減る、というのがこの機能の実利だ。

ナレッジベースとスマート検索（FTS5 / BM25）

3つ目はドキュメント検索だ。context-mode はMarkdownを見出し単位でチャンク分割し、FTS5に索引化して、BM25ランキングで関連チャンクを返す。単なる全文一致ではなく、Porterステミング（語形の揺れを吸収）、トライグラムによる部分文字列マッチ、近接リランキング、タイポを許容するファジー補正まで備える。

さらに ctx_fetch_and_index を使えば、URLを取得してMarkdownへ変換し、24時間TTLのキャッシュ付きで索引化できる。公式ドキュメントを丸ごとコンテキストに貼り付ける代わりに、必要な段落だけを検索して渡せるわけだ。

検索の中核にベクタ埋め込みではなく BM25（キーワードベースのランキング） を据えているのは、context-mode の実務的な設計判断だ。埋め込み検索は埋め込みモデルの呼び出しやベクタDBの用意が前提になるが、FTS5＋BM25なら追加のAPIコストもインフラも要らず、ローカルで完結する。見出し単位のチャンク分割・語形の揺れ吸収・タイポ補正を組み合わせることで、「エンジニアが検索窓に打ち込む語」に近い素朴なクエリでも、関連チャンクを十分な精度で拾える設計になっている。

見出し単位でチャンクを切るのにも理由がある。Markdownのドキュメントは見出しが意味のまとまりの境界になっていることが多く、そこで区切れば「認証フローの節」「レート制限の節」といった単位で検索結果を返せる。段落の途中でぶつ切りにするより、モデルが読んで理解しやすい塊になる。ctx_fetch_and_index の24時間キャッシュも、同じドキュメントを何度も取得し直す無駄を省くための工夫で、頻繁に参照する公式ドキュメントほど効いてくる。

context-mode の6つのMCPツールと5つのメタツール

context-mode がエージェントに公開するのは、6つの中核MCPツールと、運用向けの5つのメタツールだ。エージェントはこれらをMCP経由で呼び出す。

中核ツールは「実行系（ctx_execute 系）」と「知識系（ctx_index / ctx_search / ctx_fetch_and_index）」に分けて捉えると理解しやすい。実行系はツール出力を圧縮し、知識系はドキュメントを検索可能な形で保持する。メタツールは主に運用・診断のためのもので、導入直後は ctx_doctor で接続状態を確認するのが定石だ。

実行系の3つは似ているようで役割が違う。ctx_execute はその場で書いたコード片を走らせる最も基本的なツール、ctx_execute_file は既存のスクリプトファイルを対象に実行するツール、ctx_batch_execute は複数コマンドを並行度（concurrency）を指定してまとめて回すツールだ。テスト・ビルド・リンターのように独立した処理を一度に片付けたい場面では ctx_batch_execute が効率的で、往復回数そのものを減らせる。知識系では ctx_index がローカルのMarkdownを、ctx_fetch_and_index がリモートのドキュメントを索引化し、どちらも ctx_search で横断的に引ける。運用が長くなってデータが肥大化したら ctx_purge で不要な索引・履歴を掃除し、ctx_insight で蓄積から傾向を振り返る、という使い分けになる。

context-mode の導入方法｜Claude Code・Gemini CLI・Copilot CLI

導入方式はプラットフォームによって3通りある。プラグイン方式（推奨）、設定ファイル方式、そして手動MCP接続だ。以下は公式READMEに掲載されている代表的な手順である。

方式選びの基準はシンプルで、「そのツールが hooks に対応しているか」に尽きる。プラグイン方式や設定ファイル方式では、MCPサーバーの登録と同時に hooks が構成されるため、ツール呼び出しが自動でサンドボックスへ回る（遵守率およそ98%）。一方、手動MCP接続はサーバーとしての最低限の接続だけで、ルーティングは指示ファイル頼み（遵守率およそ60%）になる。効果を最大化したいなら、対応レベルの高い方式を選びたい。

Claude Code（プラグインマーケットプレイス・推奨）

Claude Code では、プラグインマーケットプレイス経由で導入するのが最も手軽だ。

# Claude Code のプラグインとして追加
/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode
/reload-plugins

# 導入状態を診断
/context-mode:ctx-doctor

プラグイン方式では、後述する hooks が自動で構成されるため、ツール呼び出しのルーティングを手作業で書く必要がない。

Gemini CLI（設定ファイル方式）

Gemini CLI では npm でグローバルインストールし、~/.gemini/settings.json にMCPサーバーと4つのhooksを追加する。

# npm でグローバルインストール
npm install -g context-mode

# ~/.gemini/settings.json に MCP サーバー定義と hooks を追記
# （PreToolUse / PostToolUse / PreCompact / SessionStart 等）

GitHub Copilot CLI（プラグイン方式）

npm install -g context-mode
copilot plugin install mksglu/context-mode:configs/copilot-cli

手動MCP接続（任意のMCP対応ツール）

hooks非対応のツールでも、MCPサーバーとしてなら接続できる。.claude/mcp.json（または各ツールの相当設定）にサーバーを登録するだけだ。

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

MCPサーバーそのものの仕組み（stdio/SSEによる接続、ツール定義、クライアント設定）を先に押さえておきたい場合は、MCPサーバーとは｜仕組み・代表的なサーバー一覧・自作手順を2026年最新で解説 を参照するとスムーズだ。

context-mode が対応するプラットフォームとhooksによる自動ルーティング

context-mode は17以上のプラットフォームに対応する。ただし「どこまで自動化されるか」は対応レベルによって異なる。ポイントは、ツール呼び出しを自動でサンドボックスへ回す hooks に対応しているかどうかだ。同じ context-mode でも、Claude Code のようなネイティブ対応環境と、Zed のようなMCPのみ対応環境では、得られる恩恵の深さが変わる。

ルーティングの強制には2つの仕組みがある。ひとつは hooks（プログラム的強制）で、READMEによればおよそ98%の遵守率でツール呼び出しをサンドボックスへ自動回送する。もうひとつは 指示ファイル（ガイダンス）で、CLAUDE.md や AGENTS.md にルーティング指示を手動でコピーする方式。こちらは遵守率が約60%にとどまる。hooksが使えるプラットフォームほど、context-mode の効果を安定して引き出せるということだ。

セッションの完全な継続（作業状態の記録と復元）に必要な6つのhooks——PreToolUse・PostToolUse・PreCompact・SessionStart・UserPromptSubmit・Stop——がそろって動作するのは、Claude Code・Gemini CLI・VS Code Copilot・JetBrains Copilot・OpenCode・KiloCode・OpenClaw だ。導入前に、自分の使うツールがどの対応レベルなのかを確認しておきたい。

6つのhooksが担う役割

これらのhooksは、エージェントの動作ライフサイクルの各ポイントに割り込み、イベント記録・スナップショット作成・状態復元を分担する。おおまかな役割は次のとおりだ。

・PreToolUse：ツールが実行される直前に割り込み、対象の呼び出しをサンドボックス経由へルーティングする
・PostToolUse：ツール実行後の結果を受け取り、圧縮とSQLiteへの記録を行う
・PreCompact：コンテキストのコンパクションが起きる直前に、現在の作業状態のスナップショットを保存する
・SessionStart：セッション開始時に、保存済みのスナップショットから作業状態を復元する
・UserPromptSubmit：ユーザーが入力を送った時点でイベントを記録し、意図や判断を履歴に残す
・Stop：セッション終了時の後処理を担当する

hooksが1つでも欠けると、この「記録→スナップショット→復元」の連携が途切れる。MCPのみ対応のツールで context-mode が「動くが継続が弱い」と感じられるのは、この連携がプログラム的に強制されず、指示ファイルによるガイダンス（約60%遵守）に頼るためだ。

context-mode の実際の使い方｜ctx_execute・ctx_index・ctx_search

実際にエージェントがどうツールを呼ぶのか、READMEの用例で見てみよう。いずれも「生データを読ませずに、結果だけを返す」という設計思想が貫かれている。

ログを解析する（コンテキストを溢れさせない）

50万行のアクセスログを全文コンテキストに載せる代わりに、ctx_execute にコードを書かせてエラー件数だけを返す。

ctx_execute("javascript", `
  const logs = fs.readFileSync('access.log', 'utf8').split('\n');
  const errorCount = logs.filter(l => l.includes('ERROR')).length;
  console.log('Total errors: ' + errorCount);
`);

ドキュメントを索引化して検索する

ctx_index でディレクトリを索引化し、ctx_search に複数クエリを渡して関連箇所だけを取得する。

ctx_index(path: "docs/", format: "markdown")
ctx_search(queries: ["authentication flow", "rate limiting"])

複数の処理をまとめて実行する

テストとリンターを1回のツール呼び出しで並行実行し、出力を圧縮して返す。

ctx_batch_execute(
  commands: [
    { type: "shell", command: "npm test" },
    { type: "shell", command: "npm run lint" }
  ],
  concurrency: 2
)

こうした使い方の効果は ctx_stats で可視化できる。どれだけのトークンを削減できたかが数字で分かるため、導入前後の比較にも使える。

context-mode を使う典型的なワークフロー

実際のコーディングセッションでは、これらのツールが次のように連携する。

1. セッション開始：SessionStart hookが前回のスナップショットを読み込み、「どのファイルを触っていたか」「未解決のエラーは何か」を復元する
   
2. ドキュメント参照：新しいライブラリを使う場面で ctx_fetch_and_index が公式ドキュメントを取得・索引化し、ctx_search が該当APIの説明だけを引く。README全文はコンテキストに載らない
   
3. 調査・集計：大量のログやファイルを調べる場面では ctx_execute がスクリプトを走らせ、結果の数字や抜粋だけを返す
   
4. 編集とテスト：ctx_batch_execute でテストとリンターをまとめて回し、PostToolUse が出力を圧縮しつつ履歴に記録する
   
5. コンパクション：会話が長くなり要約が発生する直前、PreCompact がスナップショットを保存。要約後も文脈が失われない

この一連の流れで、モデルのコンテキストには「いま判断に必要な情報」だけが残り続ける。生データの氾濫を避けながら、長い作業でも一貫性を保てるのが context-mode の狙いだ。

context-mode は何を代替できるのか｜比較と導入時の注意点

context-mode は、エージェント運用における次のような「手作業・力技」を置き換える。従来手法と並べると、その立ち位置がはっきりする。

要するに context-mode は、「巨大なツール結果を手でコピペ・要約する運用」「会話が要約されるたびに前提を貼り直す運用」「参照のための場当たり的なファイル読み込み」をまとめて肩代わりする。RAGが「外部知識をどう取り込むか」を担うのに対し、context-mode は「取り込んだ結果でコンテキストを溢れさせない」側を担う——両者は競合ではなく補完関係にある。実際、RAGで引いてきた大量のチャンクを ctx_index に流し込み、ctx_search でさらに絞り込む、という組み合わせも成立する。

「LangChain等のエージェントフレームワークがあれば不要では」と感じるかもしれないが、レイヤーが異なる。フレームワークはエージェントの制御フロー（どのツールをどの順で呼ぶか）を組み立てるためのもので、context-mode は個々のツール呼び出しがコンテキストに与える負荷を下げるためのもの。前者の上で後者が動く、と考えると位置づけがはっきりする。context-mode は特定のフレームワークに縛られず、MCPというプロトコル層で横断的に効くのが強みだ。

導入時の注意点とライセンス（ELv2）

導入判断のポイントはシンプルだ。MCPツールを多用し、長時間の会話でコンテキスト枯渇やコンパクションに悩んでいるなら、hooks対応のツール（Claude Code・Gemini CLI等）で context-mode を試す価値が高い。逆に、短い単発タスク中心で外部ツール呼び出しが少ない使い方であれば、効果は限定的になる。まずは ctx_doctor で接続を確認し、ctx_stats で削減トークンを実測してから本格運用に移すのが堅実だ。

特に相性が良いのは、ブラウザ操作（Playwright/Puppeteer系MCP）・大規模リポジトリの調査・多数のIssueやPRを横断する運用など、1回のツール呼び出しで数十KB規模の生データが返ってくるケースだ。こうした場面では圧縮の効果がそのままトークン単価の節約と、モデルの推論余地の確保につながる。GitHub Star18,000超・コミット2,000超という活発な開発状況も、継続的に使うツールとしての安心材料になる。ELv2という選択は、OSSとして広く使ってもらいつつ、クラウド事業者による無断のマネージド再提供を防ぐという、近年のインフラ系OSSに共通する狙いを反映したものだ。

参照ソース

• mksglu/context-mode GitHub リポジトリ
• Model Context Protocol 公式仕様
• Claude Code MCP設定ドキュメント（Anthropic公式）