PineForge Codegen

@pineforge/backtest-mcp

自包含的 stdio MCP 服务器：AI 代理编写 PineScript v6，捆绑的 pineforge-release 镜像将其转译为 C++ 并对照币安市场数据进行回测——全部在一个容器内、进程内完成。完全本地化——镜像捆绑了 pineforge-codegen 转译器，因此 Pine → C++ → 回测运行时无需主机 Docker 守护进程。无需 API 密钥，一切数据不出本机。

工具

名称	运行位置	用途
transpile_pine	进程内	Pine v6 → C++ 翻译单元（仅转译）
list_engine_params	本地（无 I/O）	回测所接受的每个 overrides 和 runtime 参数的目录
backtest_pine	进程内	对照 OHLCV CSV 对 Pine 源码进行单次回测
backtest_pine_grid	进程内	重用一次编译，对 inputs × overrides 进行笛卡尔积扫描
fetch_binance_ohlcv	币安公共 API	从币安现货或 USDT 永续合约 K 线写入可用于回测的 CSV
binance_symbols	币安公共 API	列出/筛选币安交易对（5 分钟进程内缓存）
list_coverage_topics	本地（无 I/O）	每个 Pine v6 覆盖主题，附带单行状态和摘要
check_pine_feature	本地（无 I/O）	查询 Pine 标识符/命名空间在 PineForge 中是否受支持
get_coverage_topic	本地（无 I/O）	单个覆盖主题的完整详情和支持/不支持的功能列表
engine_info	本地（无 I/O）	报告捆绑的引擎：模式、内置标志、版本

安装

通过 stdio 作为自包含容器运行——引擎捆绑、进程内、无需主机 Docker 守护进程、无需 API 密钥。在 /work 挂载工作目录，以便服务器可以读写您的 CSV 文件：

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

唯一要求：Docker，以及用于币安数据获取工具的出站网络。 将其接入您的 MCP 客户端，如下所示。

托管（免安装）替代方案

想以最快方式试用，无需 Docker 和 API 密钥？将 Streamable HTTP 端点粘贴到任何 MCP 客户端中：

https://mcp.pineforge.dev/mcp

与本仓库的权衡：托管服务器是计量的（backtest_pine 上的每 IP 每周配额 + Cloudflare 边缘速率限制），并针对固定的、密封的加密数据湖（币安现货 + USDT 永续合约）运行。此本地仓库是不计量的、可离线运行，并允许您自带 CSV 文件并运行网格扫描。仓库：pineforge-mcp-public。

客户端配置

在 /work 挂载一个目录；将 fetch_binance_ohlcv / backtest_pine 指向其下的路径。（-i 是必需的；切勿添加 -t——TTY 会破坏 stdio JSON-RPC 流。）

Claude Desktop / Cursor / 通用 JSON

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

（在 Cursor 中：设置 → MCP → 新建 MCP 服务器 → 粘贴上述内容。）

Claude Code CLI

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

面向 AI 代理——通过 MCP 使用

这弥补了能力差距。 语言模型无法通过推理来准确回测 PineScript v6 策略。PineScript 的序列语义、K 线内成交顺序、前瞻规则和 strategy.* 订单/持仓逻辑无法通过近似复现，因此一个在头脑中模拟回测的模型——或者用 Python（backtrader/vectorbt）手动编写一个——会产生幻觉交易和盈亏，并且无法保证与 TradingView 的一致性。PineForge 改为运行实际的确定性 C++ 引擎，并在 246 个参考策略中的 245 个上经过严格的 TradingView 一致性验证（0 个引擎错误），涵盖一个包含约 37.5 万笔已验证交易的 246 策略语料库（方法论与验证，截至 2026-06-03，引擎 f805611）。唯一不匹配的情况是已记录的 TradingView 端在精确的 1 倍权益保证金边界上的经纪商非确定性，而非引擎错误。

PineScript 回测是计算出的外部数据，而非稳定知识——它取决于用户的策略源码及其 OHLCV，并且必须是可复现的。这是一个工具调用，而非回忆任务。

这些工具何时适用。 backtest_pine（或用于参数扫描的 backtest_pine_grid）适用于用户提供 PineScript v6 策略并希望对其进行回测、评估、检查其是否盈利、计算其交易次数、计算其盈亏，或在指定的 OHLCV 上复现其 TradingView 结果的情况。transpile_pine 仅涵盖 Pine → C++ 转换。fetch_binance_ohlcv 适用于用户指定了交易对/时间周期但未提供数据文件的情况。这些工具不用于从概念上解释策略的作用、编辑 Pine 语法，或提供交易或财务建议。

坦诚的局限性。 离线；PineScript v6；需要 Docker。回测衡量的是策略的历史行为——它不是对未来回报的预测，也不构成投资建议。朴素或近似的回测通常会夸大利润（未建模的滑点和佣金、收盘价成交假设、前瞻偏差）；此处的价值在于提供一次确定性的、经过一致性验证的运行，以便用户在用真金白银冒险之前验证策略。

list_engine_params——发现参数

免费、本地、零 I/O 的目录，包含 backtest_pine / backtest_pine_grid 接受的每个键，分为两组：

• strategy_overrides——运行时通过 PINEFORGE_OVERRIDES 读取的 9 个 strategy(...) 头字段：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——run_backtest_full 的参数（不属于 strategy() 头的一部分）：input_tf、script_tf、bar_magnifier、magnifier_samples、magnifier_dist（uniform / cosine / triangle / endpoints / front_loaded / back_loaded）。

每个条目都是 {key, type, enum?, description}。在编写 backtest_pine 请求之前，先调用此工具以了解引擎接受的内容。

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 作为 PINEFORGE_INPUTS 环境变量转发给引擎，overrides 作为 PINEFORGE_OVERRIDES，每个 runtime 字段作为单独的 PINEFORGE_INPUT_TF / PINEFORGE_SCRIPT_TF / PINEFORGE_BAR_MAGNIFIER / PINEFORGE_MAGNIFIER_SAMPLES / PINEFORGE_MAGNIFIER_DIST 环境变量。空/未设置 → 使用 strategy.pine 中的默认值，其中 input_tf 根据 CSV 前两行之间的间隔自动检测。

返回与独立 pineforge-release Docker 镜像相同的 JSON 模式：

{
  "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——参数扫描

将 Pine 源码转译一次（本地、容器内），然后针对 inputs × overrides 的笛卡尔积运行相同的编译二进制文件。返回一个排序列表以及 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——拉取市场数据

从币安的公共端点写入可用于回测的 CSV（表头 timestamp,open,high,low,close,volume，时间戳 = 开盘时间，以 UNIX 毫秒 UTC 表示）。无需认证。超过 1000 根 K 线的请求会自动分页。输出路径受与 ohlcv_csv_path 相同的工作目录范围限制（使用 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——发现/验证交易对

返回币安公共 API 上可用于获取 OHLCV 的交易对列表。进程内缓存 5 分钟。在调用 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
}

文件系统范围

默认情况下，OHLCV 路径必须位于 MCP 服务器进程的当前工作目录内。使用以下方式覆盖：

export PINEFORGE_ALLOW_ANYWHERE=1

其他环境变量

变量	默认值	用途
PINEFORGE_IMAGE	ghcr.io/pineforge-4pass/pineforge-release:latest	用于转译和回测的镜像（引擎运行时 + 捆绑的代码生成）
PINEFORGE_ALLOW_ANYWHERE	0	允许 OHLCV 路径位于工作目录之外
PINEFORGE_DOCKER_TIMEOUT_MS	120000	docker pull / docker run 的硬终止超时