内容
# alpha-forge-mcp
[](https://pypi.org/project/alpha-forge-mcp/)
[](https://pypi.org/project/alpha-forge-mcp/)
[](LICENSE)
> **MCP 服务器，用于 [AlphaForge](https://alforgelabs.com)** — 智能量化 CLI：使用 JSON 编写策略，使用 Optuna TPE 进行优化，使用 walk-forward 进行验证，导出到 TradingView Pine v6。此服务器允许 AI 代理通过 MCP 驱动整个流程。→ **[免费试用 AlphaForge](https://alforgelabs.com)**
---
一种 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器，暴露 **AlphaForge `alpha-forge` CLI** 给 AI 编程代理 — Claude Code、Cursor、Codex 和任何支持 MCP 的客户端 — 通过 **stdio**。
> ⚠️ **预发布 / Alpha（`0.1.0aN`）**。工具签名和返回格式可能会更改而不另行通知。暂不建议用于生产自动化。如有反馈，请通过 Issues 提供。
它是一个薄的 **开源包装器**：它调用带有 `--json` 的（商业、闭源）`alpha-forge` 二进制文件并返回解析结果。MCP 服务器本身不包含核心逻辑 — `alpha-forge` 加上有效的许可证对于实际运行是必需的。
## 工具
| 工具 | 功能 | 底层命令 |
|------|--------------|--------------------|
| `list_strategies` | 列出已注册的策略 | `alpha-forge strategy list --json` |
| `get_strategy` | 获取一个策略的完整 JSON | `alpha-forge strategy show <id> --json` |
| `list_results` | 列出已保存的回测结果 | `alpha-forge backtest list [--strategy <id>] --json` |
| `get_result` | 获取一个结果的指标（默认折叠大型数组；`summary=false` 获取完整结果） | `alpha-forge backtest report <result_id> --json` |
| `run_backtest` | 运行回测（默认 `summary=true` 省略大型数组） | `alpha-forge backtest run <symbol> --strategy <id> [--start] [--end] [--summary] --json` |
| `run_optimize` | 优化参数（Optuna） | `alpha-forge optimize run <symbol> --strategy <id> [--metric] [--trials] [--save] --json` |
| `apply_optimization` | 将优化结果文件应用于策略 | `alpha-forge optimize apply <result_file> --to-strategy <id> --yes` |
| `run_walk_forward` | 进行 walk-forward 优化 | `alpha-forge optimize walk-forward <symbol> --strategy <id> [--windows] [--metric] --json` |
| `run_monte_carlo` | 从已保存的结果进行 Monte Carlo 模拟 | `alpha-forge backtest monte-carlo <result_id> [--simulations] --json` |
| `fetch_data` | 获取并缓存历史 OHLCV 数据（`run_backtest` 的前提） | `alpha-forge data fetch <symbol> [--period]` |
| `save_strategy` | 从其 JSON 正文注册策略 | `alpha-forge strategy save <tmpfile>` |
| `generate_pinescript` | 生成 Pine Script v6 源代码 | `alpha-forge pine preview --strategy <id> [--with-webhook]` |
| `forge_status` | 报告功能/前提（doctor + 版本） | `alpha-forge system doctor --json` |
| `list_journals` | 列出具有日志的策略 | `alpha-forge journal list --json` |
| `get_journal` | 获取一个策略的完整日志（快照、运行、标签、注释） | `alpha-forge journal show <strategy_id> --json` |
| `exploration_status` | 策略探索覆盖图（已探索 vs. 未尝试） | `alpha-forge explore status [--goal] --json` |
| `get_indicator` | 获取一个技术指标的元数据 | `alpha-forge analyze indicator show <name> --json` |
`save_strategy` 将策略定义的 **JSON 正文** 作为字符串（不是文件路径，更适合代理）；它被写入临时文件，然后执行 `strategy save`。`fetch_data` 仅公开 `period`，因为 CLI 没有 `--start`/`--end` 参数。`forge_status` 是只读的，当二进制文件丢失时，它会返回 `binary_found: false`，以便客户端在执行其他操作之前进行故障排除。
`run_optimize` 默认保存结果（`save=true`），因此其 `saved_path` 可以传递给 `apply_optimization`，后者应用优化的参数并保存 `<strategy_id>_optimized`（它以非交互方式运行，带有 `--yes`）。`get_indicator` 仅返回指标 **元数据**（描述、参数、输出）— CLI 没有 `compute-over-symbol` 命令，因此它不计算价格数据上的指标。
`metric` 参数是 `run_optimize` / `run_walk_forward` 的约束 **枚举**（`sharpe_ratio`（默认）、`sortino_ratio`、`calmar_ratio`、`total_return_pct`、`cagr_pct`、`profit_factor`、`win_rate_pct`、`expectancy_pct`、`omega_ratio`），因此客户端可以选择有效的优化目标而无需猜测。该枚举 **故意较窄**，比 `alpha-forge` CLI 的 `--metric` 更为严格，后者接受更广泛的集合 — 它被策划为更大更好的指标，这些指标对于优化目标是有意义的。`trials` 默认值为 `200`（优化器默认值）。每个工具的描述说明了其前提（如 `run_backtest` 需要 `fetch_data` 先验；`apply_optimization` 需要 `run_optimize(save=true)` 结果）和后续操作。
每个参数还带有 **输入模式** 描述，以及 **示例** 和 **约束**，在有帮助时：`symbol` 显示交易所符号（`AAPL`、`^VIX`、`CL=F`、`USDJPY=X`、`BTC-USD`），`start` / `end` 广告 `YYYY-MM-DD` 模式（`format: date`），`trials` / `windows` / `simulations` 带有 `minimum: 1`，而 `save_strategy(json_body)` / `apply_optimization(result_file)` 明确说明“JSON 正文，而不是路径”与“路径，而不是内联 JSON”。格式错误的 参数在 MCP 边界处被模式验证拒绝。
仅文本（非 `--json`）CLI 包装器返回 **结构化** 字段，而不是仅文本：`apply_optimization` 添加 `applied_strategy_id`（`<strategy_id>_optimized`，准备传递给 `generate_pinescript`），`save_strategy` 返回已注册的 `strategy_id`，而 `fetch_data` 返回获取的行数作为 `rows`（原始 `output` 文本始终保留）。
### 服务器说明和长时间运行的作业
服务器宣传 **说明**（在 MCP `initialize` 响应中显示），描述端到端工作流 — `forge_status` → `fetch_data` → `run_backtest` → `run_optimize` → `run_walk_forward` → `apply_optimization` → `generate_pinescript` — 以便代理知道要调用哪些工具以及按什么顺序调用。
运行/获取/保存/应用工具是长时间运行的（`run_backtest` 最多 300 秒，`run_optimize` / `run_walk_forward` 最多 600 秒，其他工具受默认超时限制 — 在每个工具的描述中说明）。它们向支持的客户端通过 MCP 进度通知报告 **进度**（`start` → `complete` 括号；底层 `alpha-forge` 子进程不公开中间进度），并在事件循环之外运行阻塞调用，以便服务器保持响应。超时由 `alpha-forge` 强制执行；超时后，工具返回 `timeout` 错误代码，这是可以安全重试的。
所有工具都带有 MCP **工具注释**（`readOnlyHint` 用于读取工具 — `list` / `get` 查找、`generate_pinescript`、`forge_status`、`list_journals`、`get_journal`、`exploration_status` 和 `get_indicator`；`openWorldHint` 用于运行/写入工具 — `run_backtest` / `run_optimize` / `run_walk_forward` / `run_monte_carlo`，以及 `fetch_data`（获取外部市场数据）、`save_strategy` 和 `apply_optimization`（写入数据库））并返回 **结构化输出** — 带有对象 `outputSchema` 的 `structuredContent` — 与文本结果一起。
### 错误信封
每个工具返回一个统一的 **错误信封** 作为其（始终成功的）结果，而不是引发异常，以便代理可以机械地根据失败类别进行分支：
- 成功：`{"ok": true, "data": { ...alpha-forge JSON... }, "error": null}`
- 失败：`{"ok": false, "data": null, "error": {"code": "<category>", "message": "<summary>", "detail": "<raw context>"}}`
`error.code` 是机器可读的失败类别 — 例如 `forge_not_found`（二进制文件丢失 → 引导设置）、`authentication_required`（运行 `alpha-forge system auth login`）、`freemium_blocked`（仅限高级功能 → 停止）、`strategy_not_found`、`timeout`（可以安全重试）、`bad_output`、`execution_failed`。`error.message` 是一行摘要；`error.detail` 携带原始上下文（forge `stderr` 或去装饰的 freemium 面板正文，包括升级 URL），如果有的话，否则为 `null`。`outputSchema` 反映此 `ok` / `data` / `error` 形状。
## 资源
只读数据也作为 MCP **资源** 公开，以便客户端（如 Claude Code）可以引用它们，而无需显式工具调用。它们委托给相同的 `alpha-forge` 命令作为读取工具，并返回 `application/json`。
| 资源 URI | 有效载荷 |
|--------------|---------|
| `forge://strategies` | 所有已注册的策略 |
| `forge://strategy/{strategy_id}` | 一个策略定义 |
| `forge://results` | 所有已保存的回测结果 |
| `forge://result/{result_id}` | 一个结果的指标和交易 |
| `forge://journals` | 所有具有日志的策略 |
| `forge://journal/{strategy_id}` | 一个策略的完整日志（快照、运行、标签、注释） |
| `forge://exploration` | 策略探索覆盖图（默认目标） |
| `forge://indicator/{indicator}` | 一个技术指标的元数据 |
这些镜像读取工具 `list_journals` / `get_journal` / `exploration_status` / `get_indicator`。由于 CLI 的指标 *列表* 尚未作为工具/客户端方法包装，因此没有 `forge://indicators` 集合资源。
## 提示
可重用的工作流作为 MCP **提示** 公开（在 Claude Code 中显示为 `/mcp__alpha-forge__<name>` 斜杠命令）：
| 提示 | 参数 | 功能 |
|--------|-----------|--------------|
| `backtest_and_review` | `strategy_id`, `symbol` | 运行回测，然后审查关键指标和红旗 |
| `optimize_and_verify` | `strategy_id`, `symbol` | 使用 Optuna 优化，然后检查结果是否过度拟合 |
计划在后续版本中支持流式 HTTP 传输、RBAC、速率限制和审计日志。
## 先决条件
1. **`alpha-forge` 二进制文件** 必须安装并在您的 `PATH` 中（或设置 `ALPHA_FORGE_BIN`）。
2. 您必须 **已身份验证**：运行 `alpha-forge system auth login` 一次。
3. Python **3.11+**（如果不使用 `uvx` 则需要）。
## 安装和运行
推荐的方式是通过 [`uvx`](https://docs.astral.sh/uv/) — 无需手动安装；您的 IDE 会在需要时启动它。
```bash
uvx alpha-forge-mcp # 启动_stdio MCP服务器
```
或显式安装：
```bash
pip install alpha-forge-mcp
alpha-forge-mcp
```
### Claude Code
最简单的方法是使用 `claude mcp add` 命令（用户范围 — 在每个项目中可用）：
```bash
claude mcp add --scope user alpha-forge -- uvx alpha-forge-mcp
```
或者，将服务器添加到项目范围的 `.mcp.json` 中（在存储库根目录中检查并与团队共享）：
```json
{
"mcpServers": {
"alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
}
}
```
> 注意：Claude Code **不** 读取 `~/.claude/mcp.json`。用户范围的服务器存储在 `~/.claude.json` 中（由 `claude mcp add` 管理）；项目范围的服务器位于项目根目录的 `.mcp.json` 中。
### Cursor / Codex
在客户端的 MCP 服务器配置中使用相同的 `command` / `args`：
```json
{
"mcpServers": {
"alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
}
}
```
如果 `alpha-forge` 安装在非标准位置，请通过环境变量传递：
```json
{
"mcpServers": {
"alpha-forge": {
"command": "uvx",
"args": ["alpha-forge-mcp"],
"env": { "ALPHA_FORGE_BIN": "/path/to/alpha-forge" }
}
}
}
```
## 故障排除
- **`forge_not_found`** — 确保 `alpha-forge`（或旧版 `forge`）在 `PATH` 中，或设置 `ALPHA_FORGE_BIN=/path/to/alpha-forge`。
- **`authentication_required`** — 运行 `alpha-forge system auth login`。MCP 服务器不存储凭证；它依赖于 `alpha-forge` 自己的身份验证。
## 开发
```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
```
Forge 二进制文件发现顺序：`ALPHA_FORGE_BIN` → `PATH`（`forge`、`alpha-forge`）→ 操作系统默认安装路径。
## 许可证
[Apache License 2.0](LICENSE)
