jmunch-mcp

jmunch-mcp

ほぼあらゆるMCPサーバーに対応する、透過的なMCPプロキシです。上流のツール応答が大きい場合に、トークンコストを削減します。単一の上流MCPをラップしてすべての呼び出しを転送し、大きなペイロードを、エージェントが共通の動詞（peek、slice、search、aggregate、describe、list_handles）で照会できる、コンテンツ対応バックエンドのハンドルに変換します。

ベンチマーク

実際に使われている2つの人気MCPサーバーを対象に、エンドツーエンドで測定しました。各実行では、固定のツール呼び出しスクリプトを2回実行します。1回目は直接、2回目はjmunch-mcp経由です。プロキシ側では、エージェントが大きな結果を丸ごと読み込むのではなく、掘り下げて調べる状況を想定し、jmunch.* の動詞を3回追加で呼び出します。

スイート	上流	直接のトークン数	jmunch-mcp経由	削減数
GitHub（facebook/react のissue／PR／コミット）	@modelcontextprotocol/server-github	379,878	44,328	335,550（88.3%）
Firecrawl（Wikipediaのスクレイピング＋サイトマップ＋検索）	firecrawl-mcp	259,574	2,928	256,646（98.9%）

追加の動詞呼び出しがあるにもかかわらず、どちらのスイートでもプロキシ経由のほうが実行時間も短縮されました。エージェントが大きなペイロードをページ送りで確認する必要がないためです。

スイート	直接	jmunch-mcp経由	差分
GitHub	8.4s	6.8s	−1.6s（−19.0%）
Firecrawl	16.4s	9.2s	−7.2s（−43.9%）

表形式のコンテンツ（GitHub）はSQLiteバックエンドにルーティングされ、peek／slice／aggregate に応答します。JSONコンテンツ（Firecrawlのスクレイピング／マップ）はJSONツリーバックエンドにルーティングされ、peek／slice（JSONPath）／search に応答します。再現方法は bench/README.md を参照してください。

インストール

pip install jmunch-mcp

ソースからインストールする場合：

git clone https://github.com/jgravelle/jmunch-mcp
cd jmunch-mcp
pip install -e .

クイックスタート

jmunch-mcp init

init は3つの情報源（MCPクライアントの設定（Claude Desktop、Claude Code、Cursor、Windsurf、Continue）、実行中のプロセス、人気の上流サービスの小規模なカタログ（GitHub、Firecrawl、filesystem、fetch、Brave Search、Slack））をスキャンし、チェックリストを表示します。ラップする上流サービスを選択すると、選択ごとに ./configs/ に <name>.toml を1つずつ書き込みます。非対話型のフラグ：--yes（クライアントにすでに登録されているものをすべて選択）、--dry-run、--overwrite、--out <dir>、--no-running、--no-catalog。

手動設定

jmunch-mcp --config examples/config.toml

上流サーバーを直接起動する代わりに、jmunch-mcp --config <path> を起動するようMCPクライアントを設定してください。終了時にセッションの概要を出力するには、--report を追加します。

ゲートウェイモード（v2 — ユニバーサルプロキシ）

上記のMCPプロキシは、MCPクライアントのトークンを節約します。ゲートウェイは、OpenAIまたはAnthropicのHTTP APIに対応するあらゆるAIアプリケーション（LangChain、LlamaIndex、CrewAI、AutoGen、Continue、Cline、Aider、または生のSDK）のトークンを節約します。アプリ側のコード変更は不要です。base_url をjmunchに向けるだけです。

pip install 'jmunch-mcp[gateway]'
jmunch-mcp gateway --config configs/gateway.example.toml
# listening on http://127.0.0.1:7879

アプリを接続します：

# OpenAI SDK, LangChain, Aider, Continue, Cline, Ollama-compat apps:
export OPENAI_API_BASE=http://127.0.0.1:7879/v1

# Native Anthropic SDK / Claude Code:
export ANTHROPIC_BASE_URL=http://127.0.0.1:7879

透過的に、次の処理を行います。

• 大きなtool_resultsをハンドル化して、送信リクエスト内で変換します。アプリのツールが100KBのJSONを返しても、モデルに表示されるのは1KBの要約と不透明なハンドルです。
• jmunchの動詞（peek、slice、search、aggregate、describe、summarize、list_handles）をリクエストの tools 配列に挿入し、モデルが詳細を調べられるようにします。
• 動詞の呼び出しをショートサーキットします。モデルが jmunch_peek を呼び出すと、ゲートウェイはハンドルレジストリを使ってローカルで解決し、後続のターンを合成します。アプリにjmunchのtool_callsが渡されることはなく、これらの補完に上流トークンは一切かかりません。
• 設定可能なTTLを使って ~/.jmunch/handles.db にハンドルを永続化し、再起動後やセッションをまたいだ読み取りでも利用できるようにします。
• 双方向にストリーミングします。OpenAI SSEとAnthropicのイベントストリームは、バッファリングしてから再送され、動詞の解決も正しく行われます。

ヘッダーを使ってリクエストごとに制御できます。

• X-Jmunch-Upstream: <name> — 設定済みの上流サービスを上書きします。
• X-Jmunch-Inject: false — この呼び出しではツールの挿入を無効にします（パススルーし、リクエスト側のハンドル化のみ行います）。

メトリクスはMCPプロキシと同じダッシュボードに送られます。/api/stats と /api/calls で ?surface=gateway または ?surface=mcp を指定して絞り込めます。

ダッシュボード

各プロキシが書き込むメトリクスデータベースを表示する、読み取り専用のローカル Web UI です。累計値、上流ごとの内訳、転送された呼び出しの時系列を表示します。

jmunch-mcp dashboard              # http://127.0.0.1:7878
jmunch-mcp dashboard --open       # also open in your default browser

フラグ：--port（デフォルトは 7878）、--host（デフォルトは 127.0.0.1）、デフォルト以外のメトリクスデータベースを指定する --db <path>、ブラウザーを起動する --open。メトリクスはプロキシが呼び出しを記録してから反映されるため、まずクライアントからラップした上流に接続して実行してください。

ライセンス

jmunch-mcp は MIT License のもとで公開されており、商用製品での使用、変更、配布、組み込みを自由に行えます。

jmunch-mcp を介してプロキシする上流 MCP サービスのライセンスは、各サービス独自の規約に準拠します。これにはサードパーティの MCP サーバー（GitHub、ファイルシステムプロバイダー、ベンダー API）や、組み合わせて使用する可能性のある、より広範な検索エコシステム内の関連ツールが含まれます。再配布する前に、各上流のライセンスを確認してください。