# PROJECT.md

## Purpose

`metals-mcp` is a compact MCP server for metals-related tools.
The implementation lives under `src/metals_mcp/`.
The public interface is intended to resemble `crypto-mcp` closely, while the backend uses Swissquote polling and a local candle store.
The intended analytical shape is simple: clock-aligned **5m candles** as the base market view, with gold and silver as the primary focus.

## Current interface

- `GET /` → health + tool list
- `GET /health` → health + store stats
- FastMCP SSE transport mounted at `GET /mcp/sse`
- Local default port: `8515`

Tool calls are performed via FastMCP’s message transport under `/mcp/messages/`.

## Tool set

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

## Candle model

- Base timeframe: `5m`
- Candles are clock-aligned, e.g. `00:00–00:05`, `00:05–00:10`
- Missing ticks inside a window do not break the candle, the window itself is the candle boundary
- The system is for market orientation and regime reading, not execution

## Done

- Live Swissquote `get_price` for metals like `XAU`
- Background poller that keeps the server alive and updating
- Clock-aligned 5m candle storage in SQLite
- Crypto-like tool naming on the shared surface, with `get_last_candle` as a small convenience helper
- Gold, silver, platinum, and palladium candles are tracked by default, with context surfaced through the shared `get_market_snapshot` and `get_regime` names

## Planned

- Real regime calculations for metals
- Additional pair coverage only if it proves useful

## Notes

- Keep the transport small and predictable.
- Mirror the crypto server’s MCP/HTTP shape where it helps client compatibility.
- Keep Swissquote polling, storage, and candle aggregation behind the tools.
- Candle retention defaults to 30 days via `METALS_CANDLE_RETENTION_DAYS`, with periodic pruning in the poller.

## Verification

- `./tests.sh`
- `./run.sh`
- `./killserver.sh`
- `./restart.sh`