Metadata-Version: 2.4
Name: backtest360-mcp
Version: 0.1.0
Summary: MCP server exposing the Backtest360 engine API as tools for AI agents
Project-URL: Homepage, https://backtest360.com
Project-URL: Repository, https://github.com/Backtest360/backtest360-mcp
Project-URL: API Reference, https://api.backtest360.com/docs
Project-URL: Changelog, https://github.com/Backtest360/backtest360-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Backtest360/backtest360-mcp/issues
Author-email: Backtest360 <hello@backtest360.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,api-client,backtesting,mcp,model-context-protocol,quantitative-finance,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# backtest360-mcp

MCP server exposing the [Backtest360](https://backtest360.com) engine API as tools for AI agents.

Connect any MCP-capable AI client and drive real backtests conversationally: discover
indicators, build and validate strategies, run backtests, and read the results — all
against the deterministic Backtest360 engine. The server contains no AI and computes no
numbers of its own; it is a thin, faithful adapter over the engine HTTP API. Your engine
API key and its plan govern everything (permissions, rate limits, data access).

**Status: pre-release (v0.1.x).** Local stdio transport. Remote (HTTP) deployment is planned.

## Install

```bash
pip install backtest360-mcp        # or, from a clone: pip install -e .
```

Requires Python 3.10+ and a Backtest360 API key — create one at
[backtest360.com](https://backtest360.com).

## Configuration

Everything is environment-driven:

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `BACKTEST360_API_KEY` | yes | — | Engine API key, sent as `X-API-Key` |
| `BACKTEST360_ENGINE_URL` | no | `https://api.backtest360.com` | Engine base URL |
| `BACKTEST360_MCP_TIMEOUT` | no | `300` | Per-request timeout (seconds) |
| `BACKTEST360_MCP_MAX_OUTPUT_BYTES` | no | `100000` | Hard cap on a single tool result |

## Connect an MCP client

Add the server to your MCP client's configuration (the common `mcpServers` shape):

```json
{
  "mcpServers": {
    "backtest360": {
      "command": "backtest360-mcp",
      "env": {
        "BACKTEST360_API_KEY": "b360_..."
      }
    }
  }
}
```

Prefer not to put the key in a config file? Point `command` at a small wrapper script
that exports the key from your secrets manager and then runs `backtest360-mcp`. A
minimal example config is in [`examples/mcp.json`](examples/mcp.json).

## Tools

| Tool | What it does |
|---|---|
| `engine_info` | Engine version, API contract, health |
| `get_catalog` | Reference catalogs: operators, execution modes, stop types, sizing methods, bar frequencies, metric sections |
| `list_indicators` | Indicator discovery; per-indicator parameter schemas |
| `get_strategy_schema` | JSON Schema for strategy documents |
| `validate_strategy` | Validate a strategy without running it — returns structured, locatable errors |
| `run_backtest` | Run a historical backtest |
| `get_latest_signal` | Evaluate the most recent bar only (no P&L) |
| `compare_backtests` | Run several strategies on the same data, side by side |
| `compute_stats` | Compute the metric set from an externally produced returns series |
| `search_tickers` / `list_tickers` | Asset discovery for server-side data fetch |
| `get_data_range` | Available history and bar-count estimate for a symbol |

The cheap static catalogs are also published as MCP resources
(`backtest360://catalog/{name}`, `backtest360://schema/strategy`) for clients that
support resource attachment.

## Response shaping

A full backtest result is megabytes; an agent's context is not. `run_backtest` and
`compare_backtests` take `response_detail`:

- `summary` (default) — headline metrics, warnings, counts, equity endpoints
- `stats` — every metric the plan allows
- `full` — plus series (downsampled, endpoints preserved) and trades (paginated)

`include=["trades", "equity_curve", "monthly_returns", "yearly_returns"]` adds specific
blocks at the lighter levels. Results exceeding the output cap are reduced further and
explicitly marked `truncated_by_mcp` — never silently cut. Shaping only ever selects and
thins what the engine returned; no value is computed or altered.

## Error semantics

Designed for agents:

- **Fixable by changing the request** → returned as a normal result: failed validations
  arrive as `{"valid": false, "errors": [...]}` with machine codes and document
  locations; engine rejections arrive as `{"accepted": false, "error": ...}` with a hint.
- **Not fixable that way** → a tool error with explicit guidance: rate limits carry the
  `Retry-After` value; engine-busy says retry with backoff; a compute timeout says
  do **not** retry and reduce scope instead; permission problems name the missing
  capability. Engine request ids are included for support.

## Development

```bash
pip install -e ".[dev]"
pytest                  # unit suite against a mock engine — no network
```

## License

MIT — see [LICENSE](LICENSE).
