# Traders Edge MCP

A consolidated **0DTE-focused options cockpit** for SPX / SPXW, exposed as a
[Model Context Protocol](https://modelcontextprotocol.io) server. It pulls **free, key-less**
market data and turns it into the dealer-positioning, volatility, and event signals an index-options
scalper actually watches — chain & Greeks, gamma exposure (GEX), the zero-gamma flip, call/put walls,
max-pain, 0DTE expected move, dealer DEX / vanna / charm, the full VIX term structure, and an
economic-event clock.

Greeks are **recomputed analytically** (vectorized Black–Scholes via numpy) from open interest and
implied vol, with proper Eastern-time time-to-expiry so 0DTE gamma stays realistic into the bell.

> **Data is ~15 minutes delayed** (CBOE delayed quotes). That is fine for *positioning and regime*.
> Overlay a live broker quote (e.g. Robinhood/E\*TRADE/Alpaca MCP) for execution pricing.

## Tools (70)

### Chain & Greeks
| Tool | What it does |
|------|--------------|
| `options_chain` | SPX/SPXW chain near the money with IV + recomputed delta/gamma. Defaults to the nearest SPXW expiry; `zero_dte=True` for today. |
| `option_quote` | Full detail for one OCC symbol (e.g. `SPXW260619C05500000`): quote, IV, delta/gamma/vanna/charm. |
| `expirations` | Available SPX/SPXW expirations and days-to-expiry. |

### Dealer positioning
| Tool | What it does |
|------|--------------|
| `gamma_exposure` | Total dealer **GEX** ($ per 1% move) + the **zero-gamma flip** level and long/short-gamma regime. |
| `gamma_walls` | **Call wall / put wall** (largest gamma strikes), net-gamma strikes, and **max-pain** for an expiration. |
| `zero_dte_exposure` | One-shot **0DTE dashboard**: GEX, flip, walls, max-pain pin, expected move (ATM straddle), gamma concentration. |
| `dealer_exposure` | Dealer **DEX** (dollar delta), **vanna** (per 1% vol), and **charm** (per day) exposure. |

### Vol complex
| Tool | What it does |
|------|--------------|
| `vix_complex` | VIX1D / VIX9D / VIX / VIX3M / VVIX / SKEW with a regime read. |
| `vix_term_structure` | Front-to-back VIX curve + contango/backwardation regime. |

### Event clock
| Tool | What it does |
|------|--------------|
| `economic_calendar` | Upcoming high-impact US macro events + **live Treasury auctions** over N days. |
| `next_event` | The single next macro event with an ET countdown. |

Plus `traders_edge_status` (health check / current spot).

### 0DTE decision support
| Tool | What it does |
|------|--------------|
| `expected_move` | ATM-straddle implied range (~1-sigma) for the session, plus +/-1 & +/-2 sigma levels and the IV-based move. |
| `strike_probabilities` | Per-strike risk-neutral prob-ITM and prob-of-touch (Black-Scholes from each strike's IV). |
| `daily_game_plan` | One call for today's 0DTE map: expected-move bands + gamma flip/walls + max-pain + high-OI pins, assembled into support/resistance. |

### Tier 2 — Macro context (FRED, key-less)
| Tool | What it does |
|------|--------------|
| `fed_funds` | Current Fed Funds rate + recent monthly path. |
| `yield_curve` | Treasury curve (3M–30Y), 2s10s / 3m10s spreads, inversion flags. |
| `inflation` | CPI / core CPI / PCE / core PCE (YoY) + 5Y/10Y breakevens. |
| `labor_market` | Unemployment, payroll change, participation, wages, claims. |
| `growth` | Real GDP, industrial production, retail sales. |
| `financial_conditions` | NFCI, HY & IG credit spreads, dollar index, VIX. |
| `recession_indicators` | Sahm Rule, curve spreads, composite read. |
| `series` / `latest` | Any FRED series ID over a window, or latest values for a list. |
| `series_search` | Catalog keyword search (needs free `FRED_API_KEY`). |
| `fred_status` | FRED health check. |

Macro data is pulled key-less from the FRED fredgraph CSV endpoint.

### Cross-broker risk / Greeks aggregator
| Tool | What it does |
|------|--------------|
| `net_greeks` | Net dollar delta / gamma / theta / vega across Alpaca + your positions file; delta also in SPX points. |
| `risk_summary` | Beta-weighted SPX exposure, gross/long/short notional, by-broker & by-underlying breakdowns, top contributors. |
| `concentration` | Exposure % by underlying; flags names above the threshold (default 25%, `CONCENTRATION_PCT`). |
| `scenario_shock` | Portfolio P&L across a set of SPX % moves (delta + gamma convexity). |
| `daily_target` | Today's realized P&L vs your daily target (`DAILY_TARGET`, default $524), with a post-target discipline check. Realized P&L is sourced from fee-inclusive Robinhood round trips (Alpaca equity-delta is a labeled fallback). |
| `robinhood_positions` | Live Robinhood holdings (stocks + option legs with broker-provided Greeks). |
| `etrade_positions` | Live E\*TRADE holdings (stocks + options; SPX/SPXW priced via CBOE). |
| `alpaca_positions` / `load_positions` | Raw position views from each source. |
| `risk_status` | Which position sources are configured / reachable. |

Positions are pulled **automatically** from your **Alpaca**, **Robinhood**, and **E\*TRADE** accounts,
and can be supplemented with a broker-agnostic **positions file** for anything held elsewhere:

- **Alpaca** — live `/v2/positions` (creds via `ALPACA_ENV_FILE`, default the alpaca-mcp `.env`).
- **Robinhood** — stock holdings plus option legs (with broker-provided delta/gamma/theta/vega/IV) via
  the cached `robin_stocks` session shared with the robinhood-local server. Creds from `RH_USERNAME`/
  `RH_PASSWORD` (or `RH_ENV_FILE`, default the robinhood-local `.env`); the session pickle lives in
  `~/.robinhood/` and refreshes every 7 days (a one-time device-approval prompt may appear in the
  Robinhood app on first use after expiry).
- **E\*TRADE** — stock + option positions via the cached `pyetrade` OAuth session shared with the etrade
  MCP (`~/.etrade/tokens.pickle`; idle tokens auto-renew). Creds from `ETRADE_CONSUMER_KEY`/`SECRET`
  (or `ET_ENV_FILE`). E\*TRADE access tokens expire nightly — if expired, re-authorize via the etrade
  MCP (`setup_etrade_auth.py`). SPX/SPXW E\*TRADE options are priced from CBOE; equity-option Greeks
  from E\*TRADE aren't fetched yet.
- **Positions file** — default `~/.trading/positions.json` (override `POSITIONS_FILE`).

Each source can be toggled per call via `include_alpaca` / `include_robinhood` / `include_etrade` /
`include_file`. SPX/SPXW options are auto-priced from CBOE; broker-supplied option Greeks are used
directly; equities are **beta-weighted** for SPX-equivalent exposure via a built-in beta map (editable
with `BETA_OVERRIDES="ICE:1.05,NVDA:1.7"` or `BETA_MAP_FILE=<json>`; unmapped symbols default to 1.0).
Example positions file:

```json
{"positions": [
  {"broker": "robinhood", "symbol": "ICE", "qty": 500, "type": "equity", "beta": 1.05},
  {"broker": "robinhood", "symbol": "SPXW260620P07400000", "qty": -2, "type": "option"}
]}
```

### Discipline / behavioral (Robinhood fills)
| Tool | What it does |
|------|--------------|
| `daily_pnl_curve` | Realized-P&L curve from your option fills (net of fees), with the target-cross marked and the give-back-after-target quantified. |
| `daily_review` | End-of-day scorecard: win rate, expectancy, profit factor, P&L by hour, and the before-vs-after-target split. |
| `should_i_trade` | Real-time GO / CAUTION / STOP gate from past-target status, give-back from peak, consecutive losses, churning, and time-of-session. |

Realized P&L is reconstructed from Robinhood option fills (`net_amount`, fees included) with round trips
matched open->close FIFO. These tools target the logged pattern of giving back gains after hitting target;
a recon note flags any day where positions expired or remain open (net cash flow != round-trip realized).

### Position management & macro regime
| Tool | What it does |
|------|--------------|
| `covered_call_manager` | Scans your Robinhood short calls: DTE, assignment prob (delta), premium captured vs extrinsic left, annualized yield, share-coverage check, earnings-before-expiry flag, and roll signals. |
| `earnings_calendar` | Next single-name earnings for your holdings (or a symbol list): date, BMO/AMC session, days away, within-window flag; ETFs/funds listed separately. |
| `regime_classifier` | Folds VIX + VIX term structure + NFCI + HY credit spreads + 2s10s curve + Sahm rule into one risk-on/neutral/risk-off score with a 0DTE posture. |

### Performance, tax & snapshot history
| Tool | What it does |
|------|--------------|
| `discipline_backtest` | Replays your fills through the stop-at-target rule: actual vs stop-at-target P&L, the after-target leak (losing days), win rate, expectancy, profit factor, an equity curve, and by-day-of-week / by-hour breakdowns. |
| `tax_summary` | Year-to-date realized options P&L (short vs long term, by month, gross gains/losses) plus identical-contract wash-sale candidates. CPA hand-off; not tax advice. |
| `snapshot_log` | Logs the current 0DTE state (spot, GEX, gamma flip, call/put walls, max-pain, expected move, VIX/VIX1D, regime) to local SQLite. |
| `snapshot_history` | Reads back the day's snapshots and summarizes intraday drift — GEX migration and where the key levels moved. |
| `roll_candidates` | Roll-up-and-out targets for a covered call: candidate strikes/expiries with mark, delta, net credit vs closing the current call, and annualized yield. |

### Configuration
| Tool | What it does |
|------|--------------|
| `trading_config` | View or change your goals/discipline settings (daily target, give-back %, roll thresholds…) in `config.json` — live, no restart. |

Goals and discipline thresholds live in **`config.json`** next to the server (or point `TE_CONFIG_FILE`
elsewhere). Precedence is **env var > `config.json` > built-in default**, and edits are picked up live
(no restart). Change them by editing the file or via the tool — e.g. `trading_config(action="set",
key="daily_target", value="550")`. Editable keys: `daily_target`, `weekly_target`, `giveback_frac`,
`rapid_reentry_secs`, `late_session_et`, `max_trades_per_day`, `roll_delta`, `roll_dte`. See
`config.example.json`.

### Daily workflow (v0.8.0)
| Tool | What it does |
|------|--------------|
| `morning_brief` | Pre-open command center: regime + posture, key 0DTE levels (spot, expected move, gamma flip, call/put walls, max-pain), the vol complex, high-impact econ events, holdings reporting earnings within ~7 days, your last session result, and the discipline reset. |
| `eod_wrap` | End-of-day wrap: realized vs target, discipline adherence (stopped at target vs gave back), where the key levels closed, and a snapshot logged to history. |
| `weekly_review` | This week realized P&L vs your weekly target: Mon-Fri daily breakdown, best/worst day, win rate, progress to goal. |
| `tilt_detector` | Scans a session trade sequence for tilt: revenge sizing, rushing (shrinking entry gaps), intraday win-rate decay, and trading after a give-back from peak. |

### Wheel & income (v0.8.0)
| Tool | What it does |
|------|--------------|
| `wheel_tracker` | Lifetime wheel scorecard for a symbol: net option premium (calls + puts), contracts sold to open, buy-to-close cost, cycles, share position, and effective cost basis after premium. |
| `covered_call_writer` | Fresh covered calls to write on a holding: OTM strikes near a target delta across expiries, ranked by annualized yield, with contracts covered and an earnings/ex-dividend-before-expiry flag. |
| `csp_finder` | Cash-secured puts to sell: OTM strikes near a target delta ranked by annualized yield on the cash secured, with cash required per contract and an earnings flag. |
| `dividend_calendar` | Projected next ex-dividend dates for your holdings (last ex-date + frequency), with payout cadence, dividend/share, and yield -- drives early-assignment risk on short calls. |

### Risk analytics (v0.8.0)
| Tool | What it does |
|------|--------------|
| `correlation_matrix` | Daily-return correlation across holdings: pairwise matrix, each name average correlation, most/least correlated pairs, and portfolio-wide average -- a true-diversification check. |
| `account_growth` | Risk/return profile of your current holdings over a period (total return, CAGR, annualized vol, max drawdown, rough Sharpe), valuing today positions back through price history. Synthetic, not actual past account equity. |

### 0DTE execution & tax (v0.8.0)
| Tool | What it does |
|------|--------------|
| `spot_blend` | De-stales the gamma map: compares the delayed CBOE chain spot to a live SPY-implied SPX and flags whether spot has likely crossed the gamma flip or a wall since the snapshot. When no `basis` is passed, the SPY->SPX basis auto-calibrates against the live `index_quote` SPX print. |
| `pcs_sizer` | Sizes an SPX put credit spread (ASD 0DTE PCS): short put nearest a target delta, long put a given width below, with net credit, max loss, breakeven, return-on-risk, and an approximate POP. |
| `event_risk_radar` | What can gap your book in the next N days: high-impact econ events plus holdings reporting earnings, merged into one timeline flagged by what you hold. |
| `estimated_tax` | Estimated tax set-aside on realized trading gains: YTD short/long-term options P&L x marginal federal + Georgia rates, with a quarterly figure. Trading gains only; not tax advice. |

### Robinhood-native (v0.9.0)
| Tool | What it does |
|------|--------------|
| `realized_pnl` | Authoritative realized-P&L check: reconciles the FIFO reconstruction (`daily_pnl_curve` / `tax_summary`) against a fee-inclusive round-trip figure and, when `RH_PNL_HUB_URL` is set, Robinhood's official PnL-hub payload. The reconciliation block isolates fees, expiries/assignments, and unpaired open legs. |
| `index_quote` | Live SPX / VIX / NDX index levels from Robinhood marketdata -- a real-time print to de-stale the ~15-min CBOE chain and calibrate the SPY->SPX basis. Endpoint pinnable via `RH_INDEX_QUOTE_URL`. |
| `watchlist_radar` | Catalyst radar across a named Robinhood watchlist: next earnings (BMO/AMC) and projected next ex-dividend per name, flagged within a window, plus P/E and yield, ranked by nearest event. Also folds in per-symbol technicals (trend/momentum scores + exhaustion/rebound/death-cross flags) from a shared 1y history batch. |
| `earnings_results` | Per-symbol trailing earnings: EPS actual vs estimate, surprise ($ and %), report date and timing, ~8 quarters. |
| `equity_fundamentals` | Per-symbol snapshot: P/E, P/B, market cap, shares, dividend yield, 52-week range, sector/industry, and a short profile; up to 10 symbols. |

### Technical engine (v0.10.0)
| Tool | What it does |
|------|--------------|
| `equity_technicals` | Local, deterministic per-stock trend/momentum read: ~1y daily closes -> EMA(20/50/200)+slopes, RSI-14 (Wilder), MACD(12/26/9), TRIX(15/9), Bollinger(20,2)+%B, a Trend score and Momentum score (each -2..+2), and flags (exhaustion, bearish, rebound, death cross, stretch-vs-EMA20). Descriptive only -- no buy/sell call. |
| `market_internals` | Cross-asset regime read from 8 ETFs (SPY, RSP, IWM, HYG, LQD, TLT, XLY, XLP) with the 2s10s spread auto-filled from FRED (`T10Y2Y`, fallback `DGS10 - DGS2`): composite (-1..+1), pillar score (-2..+2), regime label, inflationary flag, and SPY/TLT correlation. Complements `regime_classifier`. |

## Data sources

Most **live, historical, and fundamental** data is pulled from the **authenticated Robinhood session**
(`robin_stocks`). **CBOE** delayed quotes are the keyless chain & volatility backbone, **FRED** supplies
macro series, and a handful of sources are optional. **Yahoo Finance is used in exactly one place** -- see
the table.

| Data | Provider | Endpoint / API | Auth | Notes |
|------|----------|----------------|------|-------|
| Option chain & Greeks inputs | **CBOE** delayed quotes | `cdn.cboe.com/.../options/_SPX.json` | none | ~15-min delayed; AM **SPX** + PM **SPXW**, ~32k contracts (OI, IV, Greeks) |
| Vol indices (VIX1D...SKEW) | **CBOE** delayed quotes | `cdn.cboe.com/.../quotes/_{SYM}.json` | none | ~15-min delayed |
| Live SPY -> SPX overlay | **Robinhood** | `robin_stocks` `get_latest_price` | session | live; de-stales the chain spot |
| Live-er 0DTE chain (optional path) | **Robinhood** | `api.robinhood.com` options | session | via `_load_chain_smart` |
| Historical daily closes | **Robinhood** | `get_stock_historicals` | session | correlation / account-growth |
| Earnings dates | **Robinhood** | `get_earnings` | session | covered-call earnings-before-expiry flag |
| Dividends / ex-dividend | **Robinhood** | `get_fundamentals` | session | next ex-date is projected |
| Non-SPX equity-leg pricing | **Yahoo Finance** | `query1.finance.yahoo.com/v8/finance/chart` | none | **the only Yahoo use** -- prices non-SPX equity legs in the risk rollup (`_price_map`) |
| Macro series (NFCI, spreads, ...) | **FRED** (St. Louis Fed) | `fred.stlouisfed.org/.../fredgraph.csv` | none | key only for series **search** (`FRED_API_KEY`) |
| Treasury auctions / events | **TreasuryDirect** | `treasurydirect.gov/TA_WS/securities/upcoming` | none | |
| Economic calendar (tick-precise) | **FMP** or **Finnhub** | `financialmodelingprep.com` / `finnhub.io` | key | optional; without a key the calendar is curated/approx |
| Positions & account | **Robinhood / Alpaca / E\*TRADE** | respective APIs | session/key | cross-broker aggregator (`risk_summary`, `net_greeks`) |

> **Provider note:** Robinhood is already the authenticated backbone for live/historical/fundamental
> pulls, so the lone Yahoo dependency could be folded into `robin_stocks` `get_latest_price` to
> consolidate on a single provider. Yahoo's unauthenticated endpoint is the most rate-limit-prone
> source in the stack, but it sits **off** the hot 0DTE path.

**Optional:** set `FMP_API_KEY` or `FINNHUB_API_KEY` for a fully live economic calendar (tick-precise
CPI / PCE / PPI release dates). Without a key, the calendar is built from rule-based releases
(jobless claims, NFP, ISM), the 2026 FOMC schedule, a curated macro table, and live Treasury auctions —
every event is **source-tagged** so you know its provenance.

## Methodology & conventions

- **Greeks:** vectorized Black–Scholes, `q=0` (index options), `r=TE_RISK_FREE` (default 4.3%; gamma is
  ~insensitive to it). Normal CDF via an Abramowitz–Stegun approximation (max error ~7e-8); no scipy.
- **Time to expiry:** years from now (ET) to **16:00 ET** on the expiration date, floored at ~30 minutes
  so 0DTE gamma stays finite at the close.
- **GEX convention:** dealers assumed **long calls / short puts** → call gamma adds, put gamma subtracts.
  Dollar gamma per 1% move per option = `gamma × OI × 100 × spot² × 0.01`. Positive total GEX ⇒ dealers
  long gamma (vol-dampening / mean-reverting); negative ⇒ short gamma (moves amplified).
- **Zero-gamma flip:** net signed dollar gamma is recomputed across 81 spot levels (±10%); the flip is
  the zero-crossing nearest spot.
- **Max-pain:** the strike minimizing total option-holder intrinsic payout for that expiration.
- **Expected move (0DTE):** the ATM straddle mid (~1-sigma for the session).
- **DEX / vanna / charm:** same dealer (long-calls / short-puts) sign convention as GEX.

> These are standard market-positioning heuristics computed from delayed open interest, **not** a
> guarantee of dealer books or future price. Use as one input alongside your own read.

## Install

```bash
cd traders-edge-mcp
/Library/Frameworks/Python.framework/Versions/3.13/bin/python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

## Configure (Claude Desktop)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "traders-edge": {
      "command": "/Users/<you>/Claude/mcp/traders-edge-mcp/.venv/bin/python",
      "args": ["/Users/<you>/Claude/mcp/traders-edge-mcp/traders_edge_mcp.py"]
    }
  }
}
```

(See `claude_desktop_config.example.json`.) Restart Claude Desktop after editing.

## Test

```bash
.venv/bin/python test_traders_edge.py     # offline math/parsing tests
```

## Disclaimer

For research and educational use only. Not investment advice. Market data is delayed; positioning
metrics are modeled heuristics. You are responsible for your own trading decisions.

## License

MIT — see [LICENSE](LICENSE).