Semantic Cache MCP

Semantic Cache MCP

同じファイルに二度も料金を払うのはやめましょう。
AI コーディングエージェント向けの MCP ファイルキャッシュです。再読み込みに必要なのは、ファイル全体ではなく約 40 トークンです。

 

---

コーディングエージェントは、編集の前後やコンテキストの圧縮後など、同じファイルを何度も読み込みます。組み込みの Read は、そのたびにファイル全体を送信します。Semantic Cache MCP は、エージェントがすでに保持している内容を把握します。7,891 トークンのファイル 1 つで測定した結果は次のとおりです。

読み込み	組み込みの Read	Semantic Cache MCP
初回の読み込み	7,891 トークン	ファイル全体とハッシュ
再読み込み（ファイルに変更なし）	7,891 トークン	77 トークン
1 行編集後の再読み込み	7,891 トークン	137 トークン（差分）

48 ファイルのプロジェクト全体では、再読み込みのトークンを 98.7% 削減でき、変更のないファイルの読み込みは 0.17 ms で完了します。また、キャッシュに対する grep、BM25 検索、glob、dry_run によるアトミック編集、トークン予算に基づく一括読み込みもエージェントに提供します。実行時依存関係は 3 つで、API キーも GPU も不要です。

クイックスタート

uv が必要です。Claude Code では次のようにします。

claude mcp add semantic-cache --scope user -- uvx semantic-cache-mcp

その他のクライアント（Cursor、Claude Desktop など、mcpServers JSON に対応するもの）では次のようにします。

{
  "mcpServers": {
    "semantic-cache": {
      "command": "uvx",
      "args": ["semantic-cache-mcp"]
    }
  }
}

VS Code、Codex、OpenCode 用の設定、およびエージェントがキャッシュを使うように組み込みファイルツールを無効にする方法については、docs/clients.md をご覧ください。

仕組み

サーバーが送信する各ファイルには content_hash が付与されます。エージェントは次回の読み込み時に、それを known_hash として渡します。

flowchart LR
    R["read(path, known_hash)"] --> M{"hash matches<br/>the file now?"}
    M -- yes --> U["unchanged<br/>~40 tokens"]
    M -- "no, older version" --> D["diff of changed lines"]
    M -- "no hash" --> F["full file + content_hash"]

• 古い内容は返しません。 読み込みのたびに、まずディスク上のファイルを確認します。ハッシュが現在のバイト列と一致する場合に限り、unchanged を返します。
• 忘れても安全です。 コンテキスト圧縮後、エージェントがハッシュなしで読み込めば、ファイル全体が返されます。
• 大きなファイルはマップになります。 max_size を超えるファイルでは、無作為に切り取るのではなく、定義の概要が返されます。
• すべてローカルに保たれます。 キャッシュは SQLite ファイルです。マシン上のすべてのクライアントに、1 つのバックグラウンドデーモンがサービスを提供します。

ツール

read · batch_read · read_image · write · edit · batch_edit · edit_preview · delete · warm · grep · search · glob · stats · clear

パラメーターと例については、docs/tools.md をご覧ください。

FAQ

検索は埋め込みの意味で「セマンティック」なのですか？ いいえ。search は BM25 によるキーワードランキングで、grep は完全一致検索です。ダウンロードするモデルも、GPU も、API キーも必要ありません。

コードはどこかに送信されますか？ いいえ。ネットワークリクエストは、o200k トークナイザーのファイルを一度だけダウンロードするものだけで、SHA-256 ハッシュで検証します。

Windows でも動作しますか？ はい。CI は Linux と macOS で実行されます。

ドキュメント

ガイド	内容
クライアント	各クライアントのセットアップ、組み込みファイルツールの無効化
ツール	すべてのツール、パラメーターと使用例
環境変数	すべての設定とデフォルト値
パフォーマンス	ベンチマークと手法
アーキテクチャ	ストレージ、アルゴリズム、共有デーモン
セキュリティ	脅威モデル、サイズ制限、パスの処理
トラブルシューティング	よくある問題、デバッグログ
高度な使い方	Python API

コントリビューション

git clone https://github.com/CoderDayton/semantic-cache-mcp.git
cd semantic-cache-mcp
uv sync --extra dev
uv run pytest

CONTRIBUTING.mdをご覧ください。Issueやプルリクエストを歓迎します。

ライセンス

MIT。