PineForge Codegen

@pineforge/backtest-mcp

Servidor MCP stdio autocontido: um agente de IA escreve PineScript v6, e a imagem pineforge-release empacotada o transpila para C++ e o backtesta contra dados de mercado da Binance — tudo em um contêiner, em processo. Totalmente local — a imagem empacota o transpilador pineforge-codegen, então Pine → C++ → backtest executam sem daemon Docker do host. Sem chave de API, nada sai da caixa.

Ferramentas

nome	executa em	propósito
transpile_pine	em processo	Unidade de tradução Pine v6 → C++ (apenas transpilação)
list_engine_params	local (sem E/S)	Catálogo de todos os controles overrides + runtime aceitos pelos backtests
backtest_pine	em processo	Backtest único de uma fonte Pine contra um CSV OHLCV
backtest_pine_grid	em processo	Varredura cartesiana de inputs × overrides reutilizando uma compilação
fetch_binance_ohlcv	API pública Binance	Escreve um CSV pronto para backtest a partir de klines spot ou USDT-perp da Binance
binance_symbols	API pública Binance	Lista / filtra símbolos da Binance (cache em processo de 5 min)
list_coverage_topics	local (sem E/S)	Cada tópico de cobertura do Pine v6 com status de uma linha + resumo
check_pine_feature	local (sem E/S)	Verifica se um identificador/namespace Pine é suportado no PineForge
get_coverage_topic	local (sem E/S)	Detalhes completos + listas de recursos suportados/não suportados para um tópico de cobertura
engine_info	local (sem E/S)	Relata o motor empacotado: modo, flag incorporada, versão

Instalação

Executa como um contêiner autocontido sobre stdio — motor empacotado, em processo, sem daemon Docker do host, sem chave de API. Monte um diretório de trabalho em /work para que o servidor possa ler/escrever seus CSVs:

docker run --rm -i -v "$PWD:/work" ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest

Único requisito: Docker, e rede de saída para as ferramentas de busca da Binance. Conecte-o ao seu cliente MCP abaixo.

Alternativa hospedada (sem instalação)

Quer a tentativa mais rápida sem Docker e sem chave de API? Cole o endpoint HTTP Streamable em qualquer cliente MCP:

https://mcp.pineforge.dev/mcp

Tradeoff vs este repositório: o servidor hospedado é medido (cota semanal por IP em backtest_pine + limitação de taxa na borda Cloudflare) e executa contra um data-lake cripto fixo e selado (Binance spot + USDT-perp). Este repositório local é não medido, executa offline e permite que você traga seus próprios CSVs e execute varreduras em grade. Repositório: pineforge-mcp-public.

Configuração do cliente

Monte um diretório em /work; aponte fetch_binance_ohlcv / backtest_pine para caminhos sob ele. (-i é obrigatório; nunca adicione -t — um TTY corrompe o fluxo JSON-RPC stdio.)

Claude Desktop / Cursor / JSON genérico

{
  "mcpServers": {
    "pineforge-backtest": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${workspaceFolder}:/work",
        "ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest"
      ]
    }
  }
}

(No Cursor: Configurações → MCP → Novo Servidor MCP → cole o acima.)

Claude Code CLI

claude mcp add pineforge-backtest \
  -- docker run --rm -i -v "$PWD:/work" ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest

Para agentes de IA — uso via MCP

A lacuna de capacidade que isto fecha. Um modelo de linguagem não pode fazer backtest preciso de uma estratégia PineScript v6 raciocinando sobre ela. A semântica de séries do PineScript, ordem de preenchimento intrabar, regras de look-ahead e lógica de ordem/posição strategy.* não se reproduzem por aproximação, então um modelo que simula um backtest mentalmente — ou cria um manualmente em Python (backtrader/vectorbt) — alucinará negociações e P&L e não pode garantir paridade com o TradingView. O PineForge executa o verdadeiro motor determinístico em C++, validado com paridade estrita com o TradingView em 245 de 246 estratégias de referência (0 bugs de motor), em um corpus de 246 estratégias totalizando ~375k negociações validadas (metodologia & validação, em 03/06/2026, motor f805611). A única não correspondência é um não determinismo documentado do lado do broker do TradingView no limite exato de margem de 1x equity, não um bug do motor.

Um backtest PineScript é dado externo computado, não conhecimento estável — depende do código-fonte da estratégia do usuário e de seu OHLCV, e deve ser reproduzível. Isso é uma chamada de ferramenta, não uma tarefa de recordação.

Quando essas ferramentas são adequadas. backtest_pine (ou backtest_pine_grid para uma varredura de parâmetros) cobre o caso em que um usuário fornece uma estratégia PineScript v6 e deseja fazer backtest, avaliá-la, verificar se é lucrativa, contar suas negociações, calcular seu P&L ou reproduzir seus resultados do TradingView em OHLCV especificado. transpile_pine cobre apenas a conversão Pine → C++. fetch_binance_ohlcv cobre o caso em que o usuário nomeia um símbolo/timeframe, mas não forneceu um arquivo de dados. Essas ferramentas não são para explicar conceitualmente o que uma estratégia faz, editar sintaxe Pine ou dar conselhos de negociação ou financeiros.

Limites honestos. Offline; PineScript v6; precisa do Docker. Um backtest mede o comportamento histórico de uma estratégia — não é uma previsão de retornos futuros e não é aconselhamento de investimento. Backtests ingênuos ou aproximados rotineiramente superestimam o lucro (slippage e comissões não modelados, suposições de preenchimento no fechamento, viés de look-ahead); o valor aqui é uma execução determinística e validada por paridade para que o usuário possa verificar uma estratégia antes de arriscar capital.

list_engine_params — descobrir controles

Catálogo gratuito, local, sem E/S de cada chave aceita por backtest_pine / backtest_pine_grid, dividido em dois grupos:

• strategy_overrides — os 9 campos de cabeçalho strategy(...) que o runtime lê via PINEFORGE_OVERRIDES: initial_capital, pyramiding, slippage, commission_value, commission_type (percent / cash_per_order / cash_per_contract), default_qty_value, default_qty_type (fixed / percent_of_equity / cash), process_orders_on_close, close_entries_rule (ANY / FIFO).
• runtime_args — argumentos para run_backtest_full (NÃO fazem parte do cabeçalho strategy()): input_tf, script_tf, bar_magnifier, magnifier_samples, magnifier_dist (uniform / cosine / triangle / endpoints / front_loaded / back_loaded).

Cada entrada é {key, type, enum?, description}. Chame isto primeiro para aprender o que o motor aceita antes de compor uma solicitação backtest_pine.

Exemplo de backtest_pine

{
  "source": "//@version=6\nstrategy(\"sma cross\")\n...",
  "ohlcv_csv_path": "./btcusdt_15m_7d.csv",

  // Optional: override Pine input.*() values without touching the source.
  // Keys = the second arg of input.*(...) (e.g. "Fast Length").
  "inputs":    { "Fast Length": 8, "Slow Length": 21 },

  // Optional: override strategy(...) header fields. Each key is typed —
  // call list_engine_params for the catalog.
  "overrides": {
    "initial_capital":    100000,
    "default_qty_type":   "percent_of_equity",
    "default_qty_value":  10,
    "commission_type":    "percent",
    "commission_value":   0.04,
    "slippage":           2,
    "pyramiding":         0,
    "process_orders_on_close": true,
    "close_entries_rule": "ANY"
  },

  // Optional: engine runtime args (NOT strategy() header). Use script_tf
  // to aggregate the input CSV into a coarser strategy timeframe — the
  // engine REJECTS script_tf finer than input_tf with a structured error
  // ({"engine":"pineforge","error":"..."}, exit code 1).
  "runtime": {
    "input_tf":          "15",
    "script_tf":         "60",
    "bar_magnifier":     true,
    "magnifier_samples": 8,
    "magnifier_dist":    "endpoints"
  }
}

inputs é encaminhado como a variável de ambiente PINEFORGE_INPUTS para o motor, overrides como PINEFORGE_OVERRIDES, e cada campo runtime como uma variável de ambiente PINEFORGE_INPUT_TF / PINEFORGE_SCRIPT_TF / PINEFORGE_BAR_MAGNIFIER / PINEFORGE_MAGNIFIER_SAMPLES / PINEFORGE_MAGNIFIER_DIST separada. Vazio / não definido → padrões de strategy.pine, com input_tf detectado automaticamente a partir da lacuna entre as duas primeiras linhas do CSV.

Retorna o mesmo esquema JSON da imagem Docker autônoma pineforge-release:

{
  "engine": "pineforge",
  "summary": { "total_trades": 49, "net_pnl": -190.85, ... },
  "applied_inputs":    { "Fast Length": "8", "Slow Length": "21" },
  "applied_overrides": { "default_qty_value": "5" },
  "trades": [ ... ],
  "elapsed_seconds": 0.0042,
  "_meta": { "strategy_cpp_bytes": 5079, "image": "ghcr.io/.../pineforge-release:latest" }
}

backtest_pine_grid — varredura de parâmetros

Transpila a fonte Pine uma vez (localmente, no contêiner) e então executa o mesmo binário compilado contra o produto cartesiano de inputs × overrides. Retorna uma lista classificada mais a entrada principal sob best.

{
  "source": "//@version=6\nstrategy(\"macd\")\n...",
  "ohlcv_csv_path": "./btcusdt_15m_7d.csv",

  // Each axis is {key: list-of-values}. All combinations are tried.
  "inputs": {
    "Fast Length": [8, 12, 19],
    "Slow Length": [21, 26, 39]
  },
  "overrides": {
    "default_qty_value": [1, 5],
    "commission_value":  [0.04]
  },

  // Optional knobs:
  "fixed_inputs":     { "Source": "close" },   // applied to every combo
  "fixed_overrides":  {},                      // typed strategy() overrides
  "runtime":          { "input_tf": "15",      // engine runtime args, fixed
                        "script_tf": "60" },   // across the sweep
  "max_combinations": 64,                      // hard cap
  "concurrency":      2,                       // parallel docker runs
  "include_trades":   false,                   // omit per-trade lists
  "sort_by":          "net_pnl"                // ranking metric
}

fetch_binance_ohlcv — obter dados de mercado

Escreve um CSV pronto para backtest (cabeçalho timestamp,open,high,low,close,volume, timestamp = horário de abertura em UNIX ms UTC) a partir dos endpoints públicos da Binance. Nenhuma autenticação necessária. Solicitações > 1000 barras são paginadas automaticamente. O caminho de saída está sujeito ao mesmo escopo cwd que ohlcv_csv_path (relaxe com PINEFORGE_ALLOW_ANYWHERE=1).

{
  "symbol":      "BTCUSDT",
  "interval":    "15m",          // 1s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
  "market":      "spot",         // or "usdt_perp" for USDT-margined perpetual futures
  "limit":       672,            // total bars; > 1000 paginates
  "output_path": "./btcusdt_15m_7d.csv"
  // Optional: "start_time" / "end_time" in UNIX ms UTC.
}

binance_symbols — descobrir / validar símbolos

Retorna a lista de símbolos disponíveis na API pública da Binance para busca de OHLCV. Cache de 5 min em processo. Use isto para validar um símbolo antes de chamar fetch_binance_ohlcv.

{
  "market":        "usdt_perp",
  "query":         "BTC",         // case-insensitive substring match
  "quote_asset":   "USDT",
  "status":        "TRADING",
  "contract_type": "PERPETUAL",   // futures-only filter
  "limit":         50
}

Escopo do sistema de arquivos

Por padrão, os caminhos OHLCV devem estar dentro do diretório de trabalho atual do processo do servidor MCP. Substitua com:

export PINEFORGE_ALLOW_ANYWHERE=1

Outras variáveis de ambiente

var	padrão	propósito
PINEFORGE_IMAGE	ghcr.io/pineforge-4pass/pineforge-release:latest	Imagem (runtime do motor + codegen empacotado) usada para transpilar + backtest
PINEFORGE_ALLOW_ANYWHERE	0	Permitir caminhos OHLCV fora do cwd
PINEFORGE_DOCKER_TIMEOUT_MS	120000	Kill forçado para docker pull / docker run