# Metals MCP Server

FastMCP-based metals market data server backed by a Swissquote poller and local candle store.

## Transport

- MCP SSE transport mounted at `/mcp`
- SSE stream endpoint: `/mcp/sse`
- message endpoint handled by FastMCP under `/mcp/messages/`
- no legacy `/rpc` compatibility path

## Runtime

```bash
source .venv/bin/activate
pip install -r requirements.txt
./run.sh
```

Default URL base: `http://127.0.0.1:8515`

### Docker / Compose

```bash
docker compose up -d --build
```

The compose file persists `data/` and `logs/` into the project directory and keeps the candle DB bounded.

## HTTP

- `GET /` → health + tool list
- `GET /health` → health + cache/store stats

## Tools

- `get_price`
- `get_ohlcv`
- `get_last_candle`
- `get_market_snapshot`
- `get_indicator`
- `get_top_movers`
- `get_capabilities`
- `get_regime`

## Notes

### Done
- Shared MCP surface mirrors `crypto-mcp` tool names, with `get_last_candle` kept as a small metals-specific convenience.
- `get_price` fetches live Swissquote quotes for metals like `XAU`.
- An internal background poller keeps the server self-sufficient.
- 5m candles are clock-aligned and persisted in SQLite for `XAU/USD`, `XAG/USD`, `XPT/USD`, and `XPD/USD` by default.
- `get_market_snapshot` and `get_regime` now provide the useful metals context in crypto-style naming.
- Candle retention is bounded by `METALS_CANDLE_RETENTION_DAYS` (default 30), with periodic pruning to keep the DB bounded.

### Planned
- Keep refining `get_indicator`, `get_market_snapshot`, `get_top_movers`, and `get_regime` as more metals behavior becomes useful to Argus.
- Add retention cleanup for older candles.
- Expand the watched pair set only if it proves useful for market orientation.

### Design
- The public surface should mirror `crypto-mcp` where practical.
- Local default port is `8515`.
- Under the hood, the server uses Swissquote polling plus a local candle store.
- The repo now contains a working scaffold and the first live price path.

## Verification

```bash
./tests.sh
./run.sh
```

## Housekeeping

- `./killserver.sh` stops stale listeners on the configured port
- `./restart.sh` chains kill and run