{
  "markdown": "<p align=\"center\">\n  <a href=\"https://gcformat.com/playground.html\"><img src=\"https://img.shields.io/badge/playground-live-2563eb?style=for-the-badge\" alt=\"Playground\"></a>\n  <a href=\"https://gcformat.com/guide/benchmarks.html\"><img src=\"https://img.shields.io/badge/benchmarks-1%2C700%2B%20evals-22c55e?style=for-the-badge\" alt=\"Benchmarks\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-333?style=for-the-badge\" alt=\"License\"></a>\n</p>\n\n# gcf-proxy\n\n**Bidirectional MCP proxy that translates between JSON and GCF. Drop-in, zero changes to your server or client. Works with any structured data format.**\n\n100% comprehension on every frontier model. 29% fewer tokens than TOON, 56% fewer than JSON ([2,400+ evals, 11 models, 3 providers](https://gcformat.com/guide/benchmarks.html)). Nested object flattening with opt-out for open-weight models. One line change in your MCP config.\n\n## Install\n\n```bash\npip install gcf-proxy                                         # PyPI\nnpm install -g @blackwell-systems/gcf-proxy                   # npm\ngo install github.com/blackwell-systems/gcf-proxy@latest      # Go\n```\n\n## Try it (30 seconds, no auth)\n\n```bash\ngcf-proxy --verbose uvx yfinance-mcp\n```\n\nUse it with any MCP client. When tools return structured JSON, the proxy re-encodes to GCF and logs savings to stderr:\n\n```\ngcf-proxy: get_price_history              54.0KB -> 28.1KB (48% saved)\ngcf-proxy: get_ticker_info                10.0KB -> 7.4KB (26% saved)\ngcf-proxy: get_price_history              53.8KB -> 27.9KB (48% saved)\n\n--- gcf-proxy session stats ---\nTool calls rewritten:  3\nJSON bytes in:         117.8KB\nGCF bytes out:         63.4KB\nBytes saved:           54.4KB (46.2%)\nEst. tokens saved:     ~13.6K\n-------------------------------\n```\n\nReal live stock data from Yahoo Finance. 118KB of JSON reduced to 63KB. ~13,600 tokens saved in 3 tool calls.\n\n## Usage\n\n### Local server (stdio)\n\nAdd `gcf-proxy` in front of any MCP server command:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"gcf-proxy\",\n      \"args\": [\"npx\", \"-y\", \"@modelcontextprotocol/server-memory\"]\n    }\n  }\n}\n```\n\n### Remote server (HTTP)\n\nPoint `--upstream` at any Streamable HTTP MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"remote\": {\n      \"command\": \"gcf-proxy\",\n      \"args\": [\"--upstream\", \"http://host:3000/mcp\"]\n    }\n  }\n}\n```\n\nSupports JSON and SSE responses. Session ID tracking via `Mcp-Session-Id` is automatic.\n\n### Deploy as HTTP service\n\n`--http` turns the proxy into a remote Streamable HTTP server:\n\n```bash\ngcf-proxy --http :9090 --session your-mcp-server\n```\n\nAny MCP client that supports HTTP transport connects directly. Health check at `/health`. Chains with `--upstream` for fully remote deployments.\n\nBoth modes are bidirectional: server responses are encoded to GCF, GCF in tool call arguments is decoded to JSON. Neither side needs to change.\n\n### Flags\n\n| Flag | Description |\n|------|-------------|\n| `--session` | Enable session dedup (bare refs for previously-transmitted symbols) |\n| `--cache` | Cache encoded responses for identical tool calls |\n| `--delta` | Send only changed symbols when a tool's response changes slightly |\n| `--no-flatten` | Use expanded encoding for nested objects (open-weight models currently comprehend this form better; GCF still outperforms JSON either way) |\n| `--min-size N` | Skip encoding for responses smaller than N bytes (default: 100) |\n| `--stream-threshold N` | Min symbols before streaming mode activates (default: 5) |\n| `--stats-file PATH` | Write JSON stats to file after each call |\n| `--upstream URL` | Connect to a remote MCP server over HTTP |\n| `--http ADDR` | Serve MCP over Streamable HTTP |\n| `--no-progress` | Disable progress notifications |\n| `--verbose` | Log per-call savings to stderr |\n\n### Responses: Server (JSON) -> LLM (GCF)\n\n```\nBefore: {\"tool\":\"context_for_task\",\"symbols\":[{\"qualified_name\":\"pkg.Auth\",\"kind\":\"function\",\"score\":0.78,...},...]}\nAfter:  GCF profile=graph tool=context_for_task budget=5000 tokens=1900 symbols=50 edges=20\n        ## targets\n        @0 fn pkg.Auth 0.78 lsp_resolved\n        ...\n```\n\n53-71% fewer input tokens.\n\n### Requests: LLM (GCF) -> Server (JSON)\n\nIf the LLM produces GCF in a tool call argument (63% fewer output tokens), the proxy decodes it to JSON before forwarding:\n\n```\nLLM sends:    {\"tool\": \"process\", \"arguments\": {\"data\": \"GCF profile=generic\\nname=Alice\\nage=30\\n\"}}\nServer gets:  {\"tool\": \"process\", \"arguments\": {\"data\": {\"name\": \"Alice\", \"age\": 30}}}\n```\n\nDetection is a 4-byte prefix check (`GCF `). Zero overhead. Non-GCF strings pass through untouched.\n\n## How it works\n\n1. Spawns your MCP server as a subprocess\n2. Proxies stdin/stdout between client and server\n3. **Responses**: intercepts JSON-RPC responses, re-encodes structured JSON as GCF\n4. **Requests**: scans tool call arguments for GCF strings, decodes to JSON\n5. Passes everything else through unchanged in both directions\n\n## Why not modify the server?\n\nSometimes you can't. The server is a third-party binary, or it's maintained by another team, or you just don't want to add a dependency. gcf-proxy gives you the token savings without touching server code.\n\nIf you control the server, use the [GCF libraries](https://github.com/blackwell-systems/gcf) directly for better control over session deduplication and delta encoding.\n\n## Benchmarks\n\n100% general comprehension on every frontier model. 91.2% on adversarial code graphs (vs TOON 68.8%, JSON 54.1%). Wins 15/16 datasets on token benchmark.\n\n| Eval | GCF | TOON | JSON |\n|------|-----|------|------|\n| **General comprehension** | **100%** | 100% | 100% |\n| **Adversarial code graphs** (500 symbols) | **91.2%** | 68.8% | 54.1% |\n| **Token efficiency** (16 datasets) | **15/16 wins** | 1/16 | baseline |\n\nReproduce comprehension eval: `git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0`\n\nReproduce token benchmark: `git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens`\n\n## Links\n\n\n- [Claude Code Plugin](https://github.com/blackwell-systems/gcf-claude-plugin) - one-command install for Claude Code users\n- [Codex Plugin](https://github.com/blackwell-systems/gcf-codex-plugin) - one-command install for OpenAI Codex users\n- [GCF Specification](https://github.com/blackwell-systems/gcf)\n- [Documentation](https://gcformat.com/)\n- [Cost Calculator](https://gcformat.com/calculator)\n- [Go library](https://github.com/blackwell-systems/gcf-go)\n- [TypeScript library](https://github.com/blackwell-systems/gcf-typescript)\n- [Python library](https://github.com/blackwell-systems/gcf-python)\n- [Rust library](https://github.com/blackwell-systems/gcf-rust)\n- [Swift library](https://github.com/blackwell-systems/gcf-swift)\n- [Kotlin library](https://github.com/blackwell-systems/gcf-kotlin)\n\n\n<details>\n<summary>More links</summary>\n\n- [betterthanjson.com](https://betterthanjson.com)\n- [jsonalternative.com](https://jsonalternative.com)\n- [betterthantoon.com](https://betterthantoon.com)\n\n</details>\n\n## License\n\nMIT - [Dayna Blackwell](https://github.com/blackwell-systems) / [GCF](https://github.com/blackwell-systems/gcf)\n",
  "bytes": 7295,
  "sha": "f3dbb62ea839632cb483e9e5f2e5f7d8028b53ea58a5c3abcc1301a3c9758bc5",
  "repo_slug": "blackwell-systems/gcf-proxy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_blackwell_systems_gcf_proxy_6ec1f144/readme"
}