Metadata-Version: 2.4
Name: alpha-forge-mcp
Version: 0.1.0a3
Summary: MCP server (stdio) exposing the AlphaForge `forge` CLI to Claude Code / Cursor / Codex
Project-URL: Homepage, https://alforge-labs.github.io/
Project-URL: Repository, https://github.com/alforge-labs/alpha-forge-mcp
Project-URL: Issues, https://github.com/alforge-labs/alpha-forge-mcp/issues
Author: AlForge Labs
License: Apache-2.0
License-File: LICENSE
Keywords: alpha-forge,backtesting,mcp,model-context-protocol,quant,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: mcp>=1.27.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# alpha-forge-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes the
**AlphaForge `forge` CLI** to AI coding agents — Claude Code, Cursor, Codex, and any
MCP-capable client — over **stdio**.

> ⚠️ **Pre-release / Alpha (`0.1.0aN`).** Tool signatures and return formats may change
> without notice. Not recommended for production automation yet. Feedback welcome via Issues.

It is a thin **open-source wrapper**: it shells out to the (commercial, closed-source) `forge`
binary with `--json` and returns the parsed result. The MCP server itself contains no core
logic — `forge` plus a valid license are required for anything to actually run.

## Tools

| Tool | What it does | Underlying command |
|------|--------------|--------------------|
| `list_strategies` | List registered strategies | `forge strategy list --json` |
| `get_strategy` | Full JSON of one strategy | `forge strategy show <id> --json` |
| `list_results` | List saved backtest results | `forge backtest list [--strategy <id>] --json` |
| `get_result` | Metrics & trades of one result | `forge backtest report <result_id> --json` |
| `run_backtest` | Run a backtest | `forge backtest run <symbol> --strategy <id> [--start] [--end] --json` |
| `run_optimize` | Optimize parameters (Optuna) | `forge optimize run <symbol> --strategy <id> [--metric] [--trials] --json` |
| `generate_pinescript` | Generate Pine Script v6 source | `forge pine preview --strategy <id> [--with-webhook]` |

Streamable HTTP transport, RBAC, rate limiting, and audit logging are planned for a later
release.

## Prerequisites

1. The **`forge` binary** must be installed and on your `PATH` (or set `ALPHA_FORGE_BIN`).
2. You must be **authenticated**: run `forge system auth login` once.
3. Python **3.11+** (only needed if not using `uvx`).

## Install & run

The recommended way is via [`uvx`](https://docs.astral.sh/uv/) — no manual install needed;
your IDE launches it on demand.

```bash
uvx alpha-forge-mcp        # starts the stdio MCP server
```

Or install explicitly:

```bash
pip install alpha-forge-mcp
alpha-forge-mcp
```

### Claude Code — `~/.claude/mcp.json`

```json
{
  "mcpServers": {
    "alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
  }
}
```

### Cursor / Codex

Use the same `command` / `args` in the client's MCP server configuration:

```json
{
  "mcpServers": {
    "alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
  }
}
```

If `forge` is installed at a non-standard location, pass it via env:

```json
{
  "mcpServers": {
    "alpha-forge": {
      "command": "uvx",
      "args": ["alpha-forge-mcp"],
      "env": { "ALPHA_FORGE_BIN": "/path/to/forge" }
    }
  }
}
```

## Troubleshooting

- **`forge_not_found`** — ensure `forge`/`alpha-forge` is on `PATH`, or set
  `ALPHA_FORGE_BIN=/path/to/forge`.
- **`authentication_required`** — run `forge system auth login`. The MCP server does not
  store credentials; it relies on `forge`'s own auth.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
```

Forge binary discovery order: `ALPHA_FORGE_BIN` → `PATH` (`forge`, `alpha-forge`) → OS
default install paths.

## License

[Apache License 2.0](LICENSE)
