内容
# `@pineforge/backtest-mcp`
自包含的stdio MCP服务器：一个AI代理编写PineScript v6，捆绑的`pineforge-release`镜像将其转换为C++，并在Binance市场数据上进行回测——所有这些都在一个容器中，进程内完成。**完全本地**——镜像捆绑了[`pineforge-codegen`](https://github.com/pineforge-4pass/pineforge-codegen-oss)转换器，因此Pine → C++ → 回测在没有主机Docker守护进程的情况下运行。**无需API密钥，无需外部数据传输**。
[](https://glama.ai/mcp/servers/pineforge-4pass/pineforge-backtest-mcp)
## 工具列表
| 名称 | 运行环境 | 用途 |
| ---------------------- | -------------------- | ------------------------------------------------------------------------ |
| `transpile_pine` | 进程内 | Pine v6 → C++ 翻译单元（仅编译） |
| `list_engine_params` | 本地（无I/O） | 所有`overrides` + `runtime`旋钮的目录 |
| `backtest_pine` | 进程内 | 将单个Pine源与OHLCV CSV进行回测 |
| `backtest_pine_grid` | 进程内 | `inputs` × `overrides`的笛卡尔扫描，重复编译 |
| `fetch_binance_ohlcv` | Binance公共API | 从Binance现货或USDT永续合约klines写入回测-ready CSV |
| `binance_symbols` | Binance公共API | 列出/过滤Binance符号（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文件：
```bash
docker run --rm -i -v "$PWD:/work" ghcr.io/pineforge-4pass/pineforge-backtest-mcp:latest
```
唯一要求：Docker，以及用于Binance获取工具的外部网络。将其连接到下面的MCP客户端。
### 主机（无需安装）替代方案
想要在没有Docker和API密钥的情况下快速尝试？将Streamable HTTP端点粘贴到任何MCP客户端：
```
https://mcp.pineforge.dev/mcp
```
与此存储库的权衡：托管服务器是**按计量收费的**（每个IP每周配额在`backtest_pine` + Cloudflare边缘速率限制），并在**固定、密封的加密数据湖**（Binance现货 + USDT永续合约）上运行。此本地存储库是**无计量的，离线运行的，并允许您提供自己的CSV文件和运行网格扫描**。存储库：[`pineforge-mcp-public`](https://github.com/pineforge-4pass/pineforge-mcp-public)。
## 客户端配置
将目录挂载在`/work`；将`fetch_binance_ohlcv` / `backtest_pine`指向其下的路径。（需要`-i`；永远不要添加`-t`——TTY会损坏stdio JSON-RPC流。）
### Claude Desktop / Cursor / 通用JSON
```jsonc
{
"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
```bash
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的系列语义、帧内填充顺序、预览规则和`strategy.*`订单/头寸逻辑无法从近似值中重现，因此模拟回测的模型——或在Python中手动编写（backtrader/vectorbt）——将产生虚假的交易和损益，无法保证TradingView的对等性。PineForge改为运行实际的确定性C++引擎，该引擎在**245个参考策略中的246个上经过验证（0个引擎错误），涵盖246个策略，总共约375k个验证交易**（[方法论和验证](https://pineforge.dev/en/methodology/)，截至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` — 发现旋钮
`backtest_pine` / `backtest_pine_grid`接受的每个键的免费、本地、零I/O目录，按两组分开：
- **`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` 示例
```jsonc
{
"source": "//@version=6\nstrategy(\"sma cross\")\n...",
"ohlcv_csv_path": "./btcusdt_15m_7d.csv",
// 可选：覆盖Pine input.*() 值，无需修改源代码。
// 键 = input.*(...) 的第二个参数（例如“快速长度”）。
"inputs": { "Fast Length": 8, "Slow Length": 21 },
// 可选：覆盖 strategy(...) 头字段。每个键都是有类型的 —
// 调用 list_engine_params 获取目录。
"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"
},
// 可选：引擎运行时参数（非 strategy() 头）。使用 script_tf
// 将输入 CSV 聚合为更粗的策略时间范围 — 引擎
// 拒绝 script_tf 比 input_tf 更细的错误
// （{"engine":"pineforge","error":"..."}，退出代码 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模式：
```jsonc
{
"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`下的顶级条目。
```jsonc
{
"source": "//@version=6\nstrategy(\"macd\")\n...",
"ohlcv_csv_path": "./btcusdt_15m_7d.csv",
// 每个轴为 {key: 值列表}。尝试所有组合。
"inputs": {
"Fast Length": [8, 12, 19],
"Slow Length": [21, 26, 39]
},
"overrides": {
"default_qty_value": [1, 5],
"commission_value": [0.04]
},
// 可选旋钮：
"fixed_inputs": { "Source": "close" }, // 应用于每个组合
"fixed_overrides": {}, // 类型为 strategy() 重写
"runtime": { "input_tf": "15", // 引擎运行时参数，固定
"script_tf": "60" }, // 跨扫描
"max_combinations": 64, // 硬上限
"concurrency": 2, // 并行 Docker 运行
"include_trades": false, // 省略每笔交易列表
"sort_by": "net_pnl" // 排名指标
}
```
## `fetch_binance_ohlcv` — 拉取市场数据
从Binance公共端点写入回测-ready CSV（头`timestamp,open,high,low,close,volume`，时间戳= UNIX毫秒UTC时间）。无需身份验证。请求 > 1000个条形会自动分页。
输出路径受与`ohlcv_csv_path`相同的cwd范围限制（使用`PINEFORGE_ALLOW_ANYWHERE=1`放松限制）。
```jsonc
{
"symbol": "BTCUSDT",
"interval": "15m", // 1s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
"market": "spot", // 或 "usdt_perp" 表示USDT保证金永续期货
"limit": 672, // 总条数；> 1000分页
"output_path": "./btcusdt_15m_7d.csv"
// 可选： "start_time" / "end_time" 为UNIX毫秒UTC时间。
}
```
## `binance_symbols` — 发现/验证符号
返回Binance公共API中可用于OHLCV获取的符号列表。进程内缓存5分钟。使用此功能在调用`fetch_binance_ohlcv`之前验证符号。
```jsonc
{
"market": "usdt_perp",
"query": "BTC", // 不区分大小写的子字符串匹配
"quote_asset": "USDT",
"status": "TRADING",
"contract_type": "PERPETUAL", // 仅期货过滤器
"limit": 50
}
```
## 文件系统范围
默认情况下，OHLCV路径必须位于MCP服务器进程的工作目录内。覆盖：
```bash
export PINEFORGE_ALLOW_ANYWHERE=1
```
## 其他环境变量
| 变量 | 默认值 | 用途 |
|---|---|---|
| `PINEFORGE_IMAGE` | `ghcr.io/pineforge-4pass/pineforge-release:latest` | 用于编译 + 回测的镜像（引擎运行时 + 捆绑的代码生成器） |
| `PINEFORGE_ALLOW_ANYWHERE` | `0` | 允许 OHLCV 路径在 cwd 外 |
| `PINEFORGE_DOCKER_TIMEOUT_MS` | `120000` | `docker pull` / `docker run` 的硬杀超时 |
