# 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.