# rays-mcp

An [MCP](https://modelcontextprotocol.io) server exposing **global market
breadth, volume, RSI, volatility and sentiment** for 12 major equity indices
(US + Asia: S&P 500, Nasdaq 100, SOX, Russell 2000, Hang Seng, CSI 300/1000,
ChiNext, Nikkei 225, Topix, Taiwan, KOSPI 200).

Companion to [asian-etf-mcp](https://github.com/ivyyy0601/etf-mcp); same two-layer
design (data layer + thin FastMCP wrapper), same cache + refresh-on-use model.

## Tools

| tool | returns |
|------|---------|
| `list_indices` | the 12 indices + tickers (call first) |
| `get_breadth` | % of constituents above 50/200-day MA, % above/below both, advancers/decliners |
| `get_volume` | real trading volume (constituent-aggregated) vs 20-day average + deviation |
| `get_rsi` | RSI(14) per index + overbought/oversold signal |
| `get_volatility_sentiment` | VIX (+ >30 alert), GLD/VIX momentum, AAII bull/neutral/bear survey |

Every result carries `source` (with `as_of` + `computed_at`).

## How it works

```
src/server.py        FastMCP wrapper (5 tools)
src/data_access.py   reads cache.json; refresh-on-use keeps it current
build_cache.py       assembles cache.json from 3 sources:
configs/indices.json index definitions (committed)
```

cache.json is assembled from:
1. **`breadth_cache.json`** — breadth / advance-decline / real volume. The heavy
   constituent aggregation (Topix ≈ 1,574 stocks!) is precomputed daily on the
   rays server, so the MCP **reads** it rather than recomputing.
2. **yfinance** — RSI(14, Wilder), VIX, GLD/VIX momentum (computed live).
3. **`aaii_sentiment.xls`** — the weekly AAII investor sentiment survey.

When a tool is called and the cache is behind the latest trading day, the server
rebuilds it first (`sync_data.sh` + `build_cache.py`) — no cron needed.

## Quick start

```bash
python3.10+ -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/python build_cache.py        # assemble the cache
```

## Use with Claude Code

```bash
claude mcp add rays -- /abs/path/.venv/bin/python /abs/path/src/server.py
```

Then ask, e.g. *“use rays — which markets have the broadest participation and is the VIX elevated?”*

## Data access note

The breadth/volume layer is computed on the maintainer's rays server (constituent
aggregation across thousands of stocks is too heavy to recompute on demand).
`sync_data.sh` pulls that precomputed file via SSH. The RSI / VIX / GLD layer is
fetched from public Yahoo Finance, so it works anywhere; AAII comes from the synced
weekly file. To run fully standalone, supply a `data/breadth_cache.json` produced by
the [rays-dashboard](https://github.com/ivyyy0601) pipeline.

## Configuration

| env var | default | meaning |
|---------|---------|---------|
| `RAYS_CONFIG` | `./configs/indices.json` | index definitions (committed) |
| `RAYS_DATA_DIR` | `./data` | synced/generated data (gitignored) |
| `RAYS_SERVER` | `root@91.98.37.33` | rays server for `sync_data.sh` |