# RAM Prices MCP Server

Lightweight Model Context Protocol (MCP) server that caches and serves weekly DDR/DRAM price series from [memorys.com](https://en.memorys.com/price/ews/), plus historical memory technology data from [hblok.net](https://hblok.net/storage_data/memory.csv). It scrapes per-quarter pages, stores history in SQLite, and exposes tools for refresh, validation, analytics, forecasting, and chart rendering.

## Features
- Discovers available quarters and caches price history in SQLite (no re-download of old data unless forced).
- Tools for refresh, integrity checks, validation, resampling, returns, rolling stats, regime detection, forecasting (naive/ETS/ARIMA/trend), and PNG chart rendering.
- Forecasts fall back to naive when `statsmodels` is unavailable.
- Memory.csv tooling for filtering by memory type and exploring historical costs.
- Exposes results in CSV/JSONL for downstream analysis.

## Requirements
- Python 3.10+ recommended.
- Dependencies: see `requirements.txt` (`mcp`, `requests`, `matplotlib`; `statsmodels` optional but recommended).

## Installation
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Configuration
- `RAM_MCP_DB_PATH`: path to SQLite cache (default `~/.cache/ram-mcp/prices.sqlite`).
- `RAM_MCP_DEFAULT_PRODUCT_ID`: default memorys.com product ID (default `100227`).
- TTLs: `RAM_MCP_BASEPAGE_TTL_HOURS`, `RAM_MCP_CURQ_TTL_HOURS`, `RAM_MCP_OLDQ_TTL_DAYS`.
- `MCP_TRANSPORT`: `stdio` (default) or `streamable-http` for HTTP transport.

## Running the server
```bash
python ram_prices_mcp_server.py           # MCP_TRANSPORT=stdio
# or
MCP_TRANSPORT=streamable-http python ram_prices_mcp_server.py  # exposes an HTTP MCP endpoint
```
Server logs go to stderr; do not rely on stdout in MCP clients.

## Module layout
- `ram_prices_mcp_server.py`: MCP tool definitions and entrypoint only.
- `ram_mcp/config.py`: configuration/constants and defaults.
- `ram_mcp/storage.py`: SQLite cache and persistence.
- `ram_mcp/http_client.py`: HTTP session/retry logic.
- `ram_mcp/memorys.py`: memorys.com refresh/parsing.
- `ram_mcp/memory_csv.py`: memory.csv ingestion and cache.
- `ram_mcp/series.py`: time-series transforms/analytics.
- `ram_mcp/forecast.py`: ETS/ARIMA/trend forecasting.
- `ram_mcp/charts.py`: PNG chart rendering.
- `ram_mcp/validation.py`: input validation helpers.

## Key MCP tools
- `ram_refresh` / `ram_refresh_range`: refresh cache (optionally force re-download).
- `ram_cache_status`, `ram_integrity_check`, `ram_verify_sorting`, `ram_validate`: health checks for coverage, ordering, and data quality.
- `ram_get_history`, `ram_get_series`, `ram_returns`, `ram_growth`, `ram_rolling_stats`, `ram_regime_detect`: analysis helpers.
- `ram_forecast`, `ram_forecast_compare`: cached forecasts (naive/ETS/ARIMA/trend).
- `ram_export`: export cached points as CSV/JSONL.
- `ram_memory_types`, `ram_memory_history`: explore memory.csv by type/year.
- `ram_render_price_chart`, `ram_render_memory_chart`: PNG chart rendering (supports optional forecast overlay).

## Example workflows
```bash
# Refresh default product (respect TTLs)
python ram_prices_mcp_server.py  # start the server, then from client call:
ram_refresh

# Export cached data
ram_export export_format=csv > ddr_prices.csv
```

## Client configuration examples (`mcp.json`)
LM Studio:
```json
{
  "servers": {
    "ram-prices": {
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["ram_prices_mcp_server.py"]
      }
    }
  }
}
```

Claude Desktop (macOS/Windows) — same stdio transport:
```json
{
  "servers": {
    "ram-prices": {
      "transport": {
        "type": "stdio",
        "command": "python",
        "args": ["ram_prices_mcp_server.py"],
        "env": { "RAM_MCP_DB_PATH": "C:/Users/you/.cache/ram-mcp/prices.sqlite" }
      }
    }
  }
}
```

HTTP client / proxy (MCP over HTTP):
```json
{
  "servers": {
    "ram-prices-http": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:8000"
      },
      "command": "python",
      "args": ["ram_prices_mcp_server.py"],
      "env": { "MCP_TRANSPORT": "streamable-http" }
    }
  }
}
```

Generic `mcpServers` layout (alternate clients):
```json
{
  "mcpServers": {
    "ram-prices": {
      "command": "python",
      "args": ["/path/to/project/ram_prices_mcp_server.py"],
      "env": {
        "RAM_MCP_DEFAULT_PRODUCT_ID": "100227",
        "RAM_MCP_DB_PATH": "/path/to/project/prices.sqlite",
        "RAM_MCP_BASEPAGE_TTL_HOURS": "12",
        "RAM_MCP_CURQ_TTL_HOURS": "6"
      }
    }
  }
}
```

## Testing & linting
- Run unit tests: `pytest`.
- Use `ram_validate`, `ram_verify_sorting`, and `ram_integrity_check` after refreshes to sanity-check data.
- Suggested linting: `ruff` or `flake8`; aim for zero warnings.

## Data sources
- memorys.com price series: https://en.memorys.com/price/ews/
- Memory technology history CSV: https://hblok.net/storage_data/memory.csv

## Contributing
- See `AGENTS.md` for contributor guidelines (structure, style, PR expectations).
- Keep the user agent stable and honor TTLs to avoid hammering [memorys.com](https://en.memorys.com/price/ews/).