gcf-proxy

gcf-proxy

双向 MCP 代理，可在 JSON 和 GCF 之间进行转换。即插即用，无需修改服务端或客户端。适用于任何结构化数据格式。

在所有前沿模型上的理解率均为 100%。与 TOON 相比，令牌数减少 29%；与 JSON 相比，减少 56%（2,400 多项评测、11 个模型、3 家提供商）。支持展平嵌套对象，也可为开放权重模型关闭此功能。只需修改 MCP 配置中的一行。

安装

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）-> 大模型（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%。

请求：大模型（GCF）-> 服务端（JSON）

如果大模型在工具调用参数中生成 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