Metadata-Version: 2.4
Name: alpha-forge-mcp
Version: 0.1.0a4
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 `alpha-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)
`alpha-forge` binary with `--json` and returns the parsed result. The MCP server itself
contains no core logic — `alpha-forge` plus a valid license are required for anything to
actually run.

## Tools

| Tool | What it does | Underlying command |
|------|--------------|--------------------|
| `list_strategies` | List registered strategies | `alpha-forge strategy list --json` |
| `get_strategy` | Full JSON of one strategy | `alpha-forge strategy show <id> --json` |
| `list_results` | List saved backtest results | `alpha-forge backtest list [--strategy <id>] --json` |
| `get_result` | Metrics & trades of one result | `alpha-forge backtest report <result_id> --json` |
| `run_backtest` | Run a backtest | `alpha-forge backtest run <symbol> --strategy <id> [--start] [--end] --json` |
| `run_optimize` | Optimize parameters (Optuna) | `alpha-forge optimize run <symbol> --strategy <id> [--metric] [--trials] --json` |
| `generate_pinescript` | Generate Pine Script v6 source | `alpha-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 **`alpha-forge` binary** must be installed and on your `PATH` (or set `ALPHA_FORGE_BIN`).
2. You must be **authenticated**: run `alpha-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

The easiest way is the `claude mcp add` command (user scope — available in every project):

```bash
claude mcp add --scope user alpha-forge -- uvx alpha-forge-mcp
```

Alternatively, add the server to a project-scoped `.mcp.json` at the repository root
(checked in and shared with your team):

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

> Note: Claude Code does **not** read `~/.claude/mcp.json`. User-scoped servers are stored
> in `~/.claude.json` (managed by `claude mcp add`); project-scoped servers live in
> `.mcp.json` at the project root.

### 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 `alpha-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/alpha-forge" }
    }
  }
}
```

## Troubleshooting

- **`forge_not_found`** — ensure `alpha-forge` (or legacy `forge`) is on `PATH`, or set
  `ALPHA_FORGE_BIN=/path/to/alpha-forge`.
- **`authentication_required`** — run `alpha-forge system auth login`. The MCP server does
  not store credentials; it relies on `alpha-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)
