gcf-proxy

Proxy MCP que re-codifica sem perdas respostas de ferramentas JSON como GCF. 71% menos tokens, 100% de compreensão em mais de 1.700 avaliações de LLM. Zero alterações de código.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Playground Benchmarks License

gcf-proxy

Proxy MCP bidirecional que traduz entre JSON e GCF. Instalação direta, zero alterações no seu servidor ou cliente. Funciona com qualquer formato de dados estruturados.

100% de compreensão em todos os modelos de fronteira. 29% menos tokens que TOON, 56% menos que JSON (2.400+ avaliações, 11 modelos, 3 provedores). Achatamento de objetos aninhados com opção de desativação para modelos de peso aberto. Mudança de uma linha na sua configuração MCP.

Instalação

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

Experimente (30 segundos, sem autenticação)

gcf-proxy --verbose uvx yfinance-mcp

Use com qualquer cliente MCP. Quando as ferramentas retornam JSON estruturado, o proxy re-codifica para GCF e registra a economia no 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
-------------------------------

Dados reais de ações ao vivo do Yahoo Finance. 118KB de JSON reduzidos para 63KB. ~13.600 tokens economizados em 3 chamadas de ferramenta.

Uso

Servidor local (stdio)

Adicione gcf-proxy na frente de qualquer comando de servidor MCP:

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

Servidor remoto (HTTP)

Aponte --upstream para qualquer servidor MCP HTTP Streamable:

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

Suporta respostas JSON e SSE. O rastreamento de ID de sessão via Mcp-Session-Id é automático.

Implantar como serviço HTTP

--http transforma o proxy em um servidor HTTP Streamable remoto:

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

Qualquer cliente MCP que suporte transporte HTTP conecta diretamente. Verificação de saúde em /health. Encadeia com --upstream para implantações totalmente remotas.

Ambos os modos são bidirecionais: respostas do servidor são codificadas para GCF, GCF em argumentos de chamada de ferramenta é decodificado para JSON. Nenhum dos lados precisa mudar.

Flags

FlagDescrição
--sessionAtiva deduplicação de sessão (referências simples para símbolos já transmitidos)
--cacheArmazena em cache respostas codificadas para chamadas de ferramenta idênticas
--deltaEnvia apenas símbolos alterados quando a resposta de uma ferramenta muda ligeiramente
--no-flattenUsa codificação expandida para objetos aninhados (modelos de peso aberto atualmente compreendem melhor esta forma; GCF ainda supera JSON de qualquer maneira)
--min-size NPula codificação para respostas menores que N bytes (padrão: 100)
--stream-threshold NSímbolos mínimos antes do modo de streaming ativar (padrão: 5)
--stats-file PATHEscreve estatísticas JSON em arquivo após cada chamada
--upstream URLConecta a um servidor MCP remoto via HTTP
--http ADDRServe MCP via HTTP Streamable
--no-progressDesativa notificações de progresso
--verboseRegistra economia por chamada no stderr

Respostas: Servidor (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% menos tokens de entrada.

Requisições: LLM (GCF) -> Servidor (JSON)

Se o LLM produz GCF em um argumento de chamada de ferramenta (63% menos tokens de saída), o proxy decodifica para JSON antes de encaminhar:

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

A detecção é uma verificação de prefixo de 4 bytes (GCF ). Zero sobrecarga. Strings não-GCF passam intactas.

Como funciona

  1. Inicia seu servidor MCP como um subprocesso
  2. Faz proxy de stdin/stdout entre cliente e servidor
  3. Respostas: intercepta respostas JSON-RPC, re-codifica JSON estruturado como GCF
  4. Requisições: verifica argumentos de chamada de ferramenta para strings GCF, decodifica para JSON
  5. Passa todo o resto inalterado em ambas as direções

Por que não modificar o servidor?

Às vezes você não pode. O servidor é um binário de terceiros, ou é mantido por outra equipe, ou você simplesmente não quer adicionar uma dependência. gcf-proxy oferece a economia de tokens sem tocar no código do servidor.

Se você controla o servidor, use as bibliotecas GCF diretamente para melhor controle sobre deduplicação de sessão e codificação delta.

Benchmarks

100% de compreensão geral em todos os modelos de fronteira. 91,2% em grafos de código adversariais (vs TOON 68,8%, JSON 54,1%). Vence 15/16 conjuntos de dados no benchmark de tokens.

AvaliaçãoGCFTOONJSON
Compreensão geral100%100%100%
Grafos de código adversariais (500 símbolos)91,2%68,8%54,1%
Eficiência de tokens (16 conjuntos de dados)15/16 vitórias1/16linha de base

Reproduzir avaliação de compreensão: git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0

Reproduzir benchmark de tokens: git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens

Links

Mais links

Licença

MIT - Dayna Blackwell / GCF