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
• 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 where it helps client compatibility

Planned

• Real regime calculations for metals
• Retention policy for historical candles
• 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.

Verification

• ./tests.sh
• ./run.sh
• ./killserver.sh
• ./restart.sh