gcf-proxy

gcf-proxy

JSON と GCF 間を変換する双方向 MCP プロキシです。サーバーやクライアントに変更を加えず、そのまま導入できます。あらゆる構造化データ形式に対応します。

すべての最先端モデルで理解率 100％を達成しています。TOON よりトークン数を 29％、JSON より 56％削減します（2,400 件以上の評価、11 モデル、3 プロバイダー）。ネストされたオブジェクトをフラット化し、オープンウェイトモデル向けに無効化することもできます。MCP 設定を 1 行変更するだけです。

インストール

pip install gcf-proxy                                         # PyPI
npm install -g @blackwell-systems/gcf-proxy                   # npm
go install github.com/blackwell-systems/gcf-proxy@latest      # Go

試してみる（30 秒、認証不要）

gcf-proxy --verbose uvx yfinance-mcp

任意の MCP クライアントで使用できます。ツールが構造化 JSON を返すと、プロキシが GCF に再エンコードし、削減量を stderr に記録します。

gcf-proxy: get_price_history              54.0KB -> 28.1KB (48% saved)
gcf-proxy: get_ticker_info                10.0KB -> 7.4KB (26% saved)
gcf-proxy: get_price_history              53.8KB -> 27.9KB (48% saved)

--- gcf-proxy session stats ---
Tool calls rewritten:  3
JSON bytes in:         117.8KB
GCF bytes out:         63.4KB
Bytes saved:           54.4KB (46.2%)
Est. tokens saved:     ~13.6K
-------------------------------

Yahoo Finance の実際の株価データを取得します。118KB の JSON が 63KB に削減されます。3 回のツール呼び出しで約 13,600 トークンを節約できます。

使い方

ローカルサーバー（stdio）

任意の MCP サーバーコマンドの前に gcf-proxy を追加します。

{
  "mcpServers": {
    "memory": {
      "command": "gcf-proxy",
      "args": ["npx", "-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

リモートサーバー（HTTP）

--upstream に任意の Streamable HTTP MCP サーバーを指定します。

{
  "mcpServers": {
    "remote": {
      "command": "gcf-proxy",
      "args": ["--upstream", "http://host:3000/mcp"]
    }
  }
}

JSON と SSE のレスポンスに対応しています。Mcp-Session-Id によるセッション ID の追跡は自動で行われます。

HTTP サービスとしてデプロイ

--http を指定すると、プロキシがリモートの Streamable HTTP サーバーになります。

gcf-proxy --http :9090 --session your-mcp-server

HTTP トランスポートに対応する MCP クライアントなら、どれでも直接接続できます。ヘルスチェックは /health で行えます。--upstream と組み合わせることで、すべてをリモートに配置できます。

どちらのモードも双方向に動作します。サーバーのレスポンスは GCF にエンコードされ、ツール呼び出し引数内の GCF は JSON にデコードされます。どちらの側にも変更は不要です。

フラグ

フラグ	説明
--session	セッション重複排除を有効にします（以前に送信したシンボルは短縮参照を使用します）
--cache	同一のツール呼び出しに対するエンコード済みレスポンスをキャッシュします
--delta	ツールのレスポンスがわずかに変化した場合、変更されたシンボルだけを送信します
--no-flatten	ネストされたオブジェクトに展開形式のエンコードを使用します（現在、オープンウェイトモデルはこの形式をより適切に理解します。いずれの形式でも GCF は JSON より優れています）
--min-size N	N バイト未満のレスポンスはエンコードをスキップします（デフォルト：100）
--stream-threshold N	ストリーミングモードが有効になる最小シンボル数（デフォルト：5）
--stats-file PATH	各呼び出し後に JSON 統計をファイルに書き込みます
--upstream URL	HTTP 経由でリモート MCP サーバーに接続します
--http ADDR	Streamable HTTP 経由で MCP を提供します
--no-progress	進捗通知を無効にします
--verbose	呼び出しごとの削減量を stderr に記録します

レスポンス：サーバー（JSON） -> LLM（GCF）

Before: {"tool":"context_for_task","symbols":[{"qualified_name":"pkg.Auth","kind":"function","score":0.78,...},...]}
After:  GCF profile=graph tool=context_for_task budget=5000 tokens=1900 symbols=50 edges=20
        ## targets
        @0 fn pkg.Auth 0.78 lsp_resolved
        ...

入力トークンを 53〜71％削減します。

リクエスト：LLM（GCF） -> サーバー（JSON）

LLM がツール呼び出し引数に GCF を出力した場合（出力トークンを 63％削減）、プロキシは転送前に JSON にデコードします。

LLM sends:    {"tool": "process", "arguments": {"data": "GCF profile=generic\nname=Alice\nage=30\n"}}
Server gets:  {"tool": "process", "arguments": {"data": {"name": "Alice", "age": 30}}}

検出は 4 バイトのプレフィックスチェック（GCF ）で行います。オーバーヘッドはありません。GCF 以外の文字列はそのまま通過します。

仕組み

1. MCP サーバーをサブプロセスとして起動します
2. クライアントとサーバー間で stdin/stdout をプロキシします
3. レスポンス：JSON-RPC レスポンスを受け取り、構造化 JSON を GCF に再エンコードします
4. リクエスト：ツール呼び出し引数内の GCF 文字列を検出し、JSON にデコードします
5. それ以外はすべて、双方向とも変更せずに通過させます

サーバーを変更しなくてよい理由

変更できない場合があるからです。サーバーがサードパーティ製のバイナリだったり、別のチームが保守していたり、依存関係を追加したくなかったりすることがあります。gcf-proxy を使えば、サーバーコードに手を加えずにトークンを削減できます。

サーバーを管理している場合は、GCF ライブラリを直接使用すると、セッションの重複排除やデルタエンコーディングをより細かく制御できます。

ベンチマーク

すべてのフロンティアモデルで、汎用理解度は100％です。敵対的コードグラフでは91.2％です（TOONは68.8％、JSONは54.1％）。トークンベンチマークでは、16のデータセットのうち15で勝利しています。

評価	GCF	TOON	JSON
汎用理解度	100%	100%	100%
敵対的コードグラフ（500シンボル）	91.2%	68.8%	54.1%
トークン効率（16データセット）	15/16で勝利	1/16	ベースライン

理解度評価の再現方法：git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0

トークンベンチマークの再現方法：git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens

リンク

• Claude Code プラグイン - Claude Code ユーザー向けのワンコマンドインストール
• Codex プラグイン - OpenAI Codex ユーザー向けのワンコマンドインストール
• GCF 仕様
• ドキュメント
• コスト計算ツール
• Go ライブラリ
• TypeScript ライブラリ
• Python ライブラリ
• Rust ライブラリ
• Swift ライブラリ
• Kotlin ライブラリ

その他のリンク

• betterthanjson.com
• jsonalternative.com
• betterthantoon.com

ライセンス

MIT - Dayna Blackwell / GCF