metals-mcp/PROJECT.md

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 - Fetch live Swissquote quotes for metals
• get_ohlcv - Get OHLCV candle data for a symbol and timeframe
• get_indicator - Calculate technical indicators (SMA, EMA, RSI, ATR, return_pct, volatility)
• get_market_snapshot - Get comprehensive market analysis for a single symbol
• get_top_movers - Get top moving symbols by percentage change
• get_capabilities - Get server capabilities and available tools
• get_regime - Get market regime classification
• get_last_candle - Get the most recent completed candle
• get_snapshot - Get comprehensive multi-timeframe, multi-symbol market snapshot

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