metals-mcp/AGENTS.md

AGENTS.md for metals-mcp

Purpose

This file provides guidance for agents working on the metals-mcp server.

Key Documentation

• README.md: Overview, runtime instructions, tool list, and housekeeping scripts.
• PROJECT.md: Purpose, current interface, tool set, candle model, done/planned items, and notes.
• metals-mcp_first_idea.md: Detailed design principles and system architecture.

Runtime

1. Source the virtual environment: source .venv/bin/activate
2. Install dependencies: pip install -r requirements.txt
3. Run the server: ./run.sh (or docker compose up -d --build for Docker)
4. Health check: GET http://127.0.0.1:8515/health
5. Stop server: ./killserver.sh
6. Restart: ./restart.sh

Source Structure

• src/metals_mcp/: Main package
  • server_fastmcp.py: FastAPI/FastMCP entry point and tool definitions
  • mcp_tools.py: Implementation of MCP tools (get_price, get_ohlcv, etc.)
  • poller.py: Background candle poller
  • storage.py: SQLite candle storage and initialization
  • swissquote.py: Swissquote API client
  • config.py: Configuration (DB_PATH, etc.)
• data/: SQLite candle database
• logs/: Server logs and PID file
• scripts/: Helper scripts (discover_swissquote_api.py, etc.)

Important Conventions

• Always use the local .venv before claiming missing dependencies.
• The server uses clock-aligned 5m candles as the base market view.
• Default instruments: XAU/USD, XAG/USD, XPT/USD, XPD/USD, EUR/USD, USD/JPY (configurable via METALS_PAIRS environment variable)
• Default port: 8515 (configurable via METALS_PORT environment variable)
• Candle retention: Controlled by METALS_CANDLE_RETENTION_DAYS (default 30)
• MCP tools mirror crypto-mcp where practical, with get_last_candle as a metals-specific convenience, plus get_snapshot for multi-timeframe analysis

Verification

• Run tests: ./tests.sh
• Manual verification: ./run.sh and check endpoints

Notes for Agents

• When modifying tools, ensure changes align with the shared MCP surface.
• Keep the transport small and predictable (SSE mount at /mcp).
• Store raw ticks only if useful; the system can remain simple with 5m candles as base.
• The goal is market orientation and regime reading, not execution.
• Preserve the deterministic design: consistent data over theoretically perfect data.