@blackwell-systems/gcf-proxy 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# gcf-proxy
+
+MCP proxy that re-encodes JSON tool responses as [GCF](https://gcformat.com/) — the most token-efficient wire format for LLMs. Drop-in, zero code changes. A TOON/JSON alternative that saves 63-79% of tokens.
+
+**79% fewer tokens than JSON. 34% fewer than TOON. 100% LLM comprehension at scale.**
+
+Docs: [gcformat.com](https://gcformat.com/) · [Proxy Guide](https://gcformat.com/guide/proxy.html) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
+
+## Install
+
+```bash
+npm install -g @blackwell-systems/gcf-proxy
+```
+
+## Setup (one line change)
+
+**Before:**
+```json
+{"mcpServers": {"yours": {"command": "your-mcp-server"}}}
+```
+
+**After:**
+```json
+{"mcpServers": {"yours": {"command": "gcf-proxy", "args": ["your-mcp-server"]}}}
+```
+
+Your server keeps outputting JSON. The LLM receives GCF. Nothing else changes.
+
+Works with Claude Code, Claude Desktop, VS Code, Cursor, and any MCP client.
+
+## What it does
+
+```
+LLM  ←──  GCF  ←──  gcf-proxy  ←──  JSON  ←──  Your Server
+```
+
+1. Spawns your MCP server as a subprocess
+2. Proxies stdin/stdout between client and server
+3. Detects JSON payloads in tool responses
+4. Re-encodes as GCF (graph profile for code intelligence, tabular profile for everything else)
+5. Non-convertible responses (text, HTML, errors) pass through unchanged
+
+## Savings
+
+Tested on a real MCP tool response (10 symbols, 8 edges):
+
+```
+JSON   2,506 bytes  ~626 tokens
+GCF      916 bytes  ~229 tokens
+
+Savings: 63% fewer tokens
+```
+
+On a real agent-lsp blast_radius response (7 symbols, 47 callers):
+
+```
+JSON   6,515 bytes  ~1,628 tokens
+GCF    4,866 bytes  ~1,216 tokens
+
+Savings: 25% fewer tokens (generic encoding, no graph profile)
+```
+
+## When to use
+
+- You can't modify the server (third-party binary, another team's code)
+- You want to test GCF savings without writing any code
+- You want zero-effort adoption on any existing MCP server
+
+For session deduplication (92.7% savings) and delta encoding (81.2% savings), use the [GCF libraries](https://gcformat.com/ecosystem/implementations.html) directly.
+
+## Also available on
+
+- PyPI: `pip install gcf-proxy`
+- Go: `go install github.com/blackwell-systems/gcf-proxy@latest`
+
+## Links
+
+- [Full Setup Guide](https://gcformat.com/guide/proxy.html)
+- [GCF Specification](https://gcformat.com/reference/spec.html)
+- [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
+- [Playground](https://gcformat.com/playground.html)
+- [GitHub](https://github.com/blackwell-systems/gcf-proxy)

package/bin/gcf-proxy

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const os = require("os");
+
+const PLATFORMS = {
+  "darwin-arm64":  "@blackwell-systems/gcf-proxy-darwin-arm64",
+  "darwin-x64":    "@blackwell-systems/gcf-proxy-darwin-x64",
+  "linux-arm64":   "@blackwell-systems/gcf-proxy-linux-arm64",
+  "linux-x64":     "@blackwell-systems/gcf-proxy-linux-x64",
+  "win32-x64":     "@blackwell-systems/gcf-proxy-win32-x64",
+  "win32-arm64":   "@blackwell-systems/gcf-proxy-win32-arm64",
+};
+
+const platform = os.platform();
+const arch = os.arch();
+const key = `${platform}-${arch}`;
+const pkg = PLATFORMS[key];
+
+if (!pkg) {
+  process.stderr.write(`gcf-proxy: unsupported platform ${key}\n`);
+  process.stderr.write(`Supported: ${Object.keys(PLATFORMS).join(", ")}\n`);
+  process.stderr.write(`Install from https://github.com/blackwell-systems/gcf-proxy/releases\n`);
+  process.exit(1);
+}
+
+const ext = platform === "win32" ? ".exe" : "";
+
+let binPath;
+try {
+  binPath = require.resolve(`${pkg}/bin/gcf-proxy${ext}`);
+} catch {
+  process.stderr.write(`gcf-proxy: platform package ${pkg} is not installed\n`);
+  process.stderr.write(`Try: npm install -g @blackwell-systems/gcf-proxy\n`);
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status ?? 1);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@blackwell-systems/gcf-proxy",
+  "version": "0.1.0",
+  "description": "MCP proxy that re-encodes JSON tool responses as GCF. Zero code changes.",
+  "bin": {
+    "gcf-proxy": "bin/gcf-proxy"
+  },
+  "optionalDependencies": {
+    "@blackwell-systems/gcf-proxy-darwin-arm64": "0.1.0",
+    "@blackwell-systems/gcf-proxy-darwin-x64": "0.1.0",
+    "@blackwell-systems/gcf-proxy-linux-arm64": "0.1.0",
+    "@blackwell-systems/gcf-proxy-linux-x64": "0.1.0",
+    "@blackwell-systems/gcf-proxy-win32-x64": "0.1.0",
+    "@blackwell-systems/gcf-proxy-win32-arm64": "0.1.0"
+  },
+  "keywords": [
+    "gcf",
+    "mcp",
+    "proxy",
+    "llm",
+    "tokens",
+    "json",
+    "wire-format",
+    "toon-alternative"
+  ],
+  "homepage": "https://gcformat.com/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blackwell-systems/gcf-proxy.git"
+  },
+  "license": "MIT"
+}