GammaRips Options Intelligence

Official29 toolsLive

by DevDizzle · Python

Anti-firehose options-flow data for AI agents: curated daily pool, features, realized outcomes.

Captured live from the server via tools/list.

get_overnight_signals

Raw overnight scanner signals for a scan date — the wide net BEFORE curation. Use this to see where unusual options activity concentrated overnight across the full scan universe. The curated, enriched pool (what the engine actually works from) is `get_enriched_signals`.

Parameters

scan_date	any	optional
direction	any	optional
min_score	integer	optional
ticker	any	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "direction": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Direction"
    },
    "min_score": {
      "default": 0,
      "title": "Min Score",
      "type": "integer"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_overnight_signalsArguments"
}

get_enriched_signals

The curated candidate pool for a scan date — AI-enriched signals with news, technicals, catalyst context, a delta-targeted recommended contract, and (since 2026-06) the 60-day momentum feature `mom_60`. Enrichment gate: `overnight_score >= 4` AND directional UOA > $500K, then edge-ranked to the top ~50 BULLISH names. This is the pool the engine's own selection works from; your agent should treat it as the daily candidate set and reason to its OWN contract (see get_playbook("run-your-own-tournament")). Response size: by default (`summary=True`) rows carry ~21 decision-relevant scalar columns, so the full pool fits in one response. Pass `fields=[...]` to project exactly the columns you want (STRICT: any unknown/malformed name rejects the call and returns the full `valid_fields` catalog), or `summary=False` for complete rows including the long narrative fields (thesis, news_summary) — combine that with `ticker` or a small `limit`. Page with `offset` (rows are ordered by overnight_score DESC, ticker). Served from a leakage-safe view: forward-outcome columns are physically stripped, so historical dates can be queried without seeing the future. Liquidity caveat: `recommended_oi`/`recommended_volume` are scan-time snapshots, not live values; `recommended_spread_pct` is permanently NULL. Args: scan_date: YYYY-MM-DD (default: latest scan). direction: "bull"/"bear" prefix filter. ticker: exact ticker filter. limit: max rows (default 25, clamped 1-50). summary: True (default) = compact decision columns; False = full rows. fields: explicit column projection (overrides `summary`). offset: pagination offset (clamped 0-500).

Parameters

scan_date	any	optional
direction	any	optional
ticker	any	optional
limit	integer	optional
summary	boolean	optional
fields	any	optional
offset	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "direction": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Direction"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "limit": {
      "default": 25,
      "title": "Limit",
      "type": "integer"
    },
    "summary": {
      "default": true,
      "title": "Summary",
      "type": "boolean"
    },
    "fields": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Fields"
    },
    "offset": {
      "default": 0,
      "title": "Offset",
      "type": "integer"
    }
  },
  "title": "get_enriched_signalsArguments"
}

get_signal_detail

Deep dive on a single ticker's enriched signal — thesis, catalyst, the recommended contract, and point-in-time features. Served from the leakage-safe enriched view. By default the extra-long narrative fields (news_summary, flow_intent_reasoning) are omitted to keep the response tight — the thesis and all decision fields are always included. Pass `full=true` for everything. If the ticker is not in the pool for the requested date, the error lists the recent dates on which it DOES appear.

Parameters

ticker	string	required
scan_date	any	optional
full	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "title": "Ticker",
      "type": "string"
    },
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "full": {
      "default": false,
      "title": "Full",
      "type": "boolean"
    }
  },
  "required": [
    "ticker"
  ],
  "title": "get_signal_detailArguments"
}

get_freemium_preview

Top N enriched signals for the most recent scan, with minimal fields. Used for public/freemium teasers: ticker, direction, score, headline, directional UOA dollar volume. No contract specifics or full thesis — use get_signal_detail for that. Args: limit: How many preview rows to return (default 5, max 20). Returns: List of {ticker, direction, overnight_score, call_dollar_volume, put_dollar_volume, key_headline, scan_date}.

Parameters

limit

integer

optional

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 5,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_freemium_previewArguments"
}

get_contract_snapshot

FRESH (entry-day) snapshot for ONE option contract: open interest, session volume, last trade, day range, and the underlying price — the liquidity/ freshness read the pool rows cannot give you (their `recommended_oi`/ `recommended_volume` are frozen at scan time; the overnight sweep only becomes OI the next morning). Use it at decision time. CACHE-FIRST: contracts in the current pool are re-read every ~10 minutes during market hours, so the default call is fast and served from that cache when a fresh row (<15 min) exists. Pass live=true to force a fresh upstream fetch — for a fresher-than-interval read or a contract NOT in today's pool (any valid OCC ticker works). To refresh a whole shortlist in one call, use `get_pool_liquidity` instead. Deliberately serves NO bid/ask/spread (not available on the current data plan — absent, not NULL). Assess fill risk from: open_interest (updates once each morning), day_volume (live session), last_trade recency, and the day range. `retrieved_from` + `as_of` tell you exactly what you got. Args: contract: OCC-style option ticker exactly as served by the pool tools (the `recommended_contract` field), e.g. "O:UNIT260717C00030000". live: force a fresh upstream fetch instead of the ~10-min pool cache (default false = cache-first with automatic live fallback). Returns: {contract, underlying, underlying_price, underlying_price_source, as_of, open_interest, day_volume, day: {open, high, low, close, last_updated}, last_trade: {price, timestamp}, implied_volatility, greeks, source, retrieved_from, freshness_note} — plus cache_age_seconds on cache hits. Quote fields (bid/ask/mid/ spread_pct) appear ONLY if a quote feed is ever added.

Parameters

contract	string	required
live	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "contract": {
      "title": "Contract",
      "type": "string"
    },
    "live": {
      "default": false,
      "title": "Live",
      "type": "boolean"
    }
  },
  "required": [
    "contract"
  ],
  "title": "get_contract_snapshotArguments"
}

get_pool_liquidity

Latest liquidity snapshot for the WHOLE current pool (or your shortlist) in ONE call — the batch companion to `get_contract_snapshot`. The engine re-reads every pool contract's open interest, session volume, last trade, day range, and underlying price every ~10 minutes during market hours (plus one pre-open pass); this returns the most recent read per contract, each with explicit `as_of` provenance. Built for the ~10:00 ET decision window: one call replaces N per-contract fetches at the busiest minute. No bid/ask/spread on the current data plan (fields appear only if a quote feed is added — absent, not NULL). Judge fill risk from open_interest (updates once each morning), day_volume (live session), last_trade recency, and the day range. For a single contract outside the pool, or a fresher-than-interval read, use `get_contract_snapshot(..., live=true)`. Args: scan_date: pool date "YYYY-MM-DD" (the scan that produced the pool). Default: the most recent pool with snapshots (today's live pool during market hours). contracts: optional shortlist filter — OCC tickers exactly as served in `recommended_contract` (max 60). Default: the whole pool. Returns: {scan_date, count, freshest_as_of, rows: [snapshot per contract], freshness_note} — each row shaped like `get_contract_snapshot`.

Parameters

scan_date	any	optional
contracts	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "contracts": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Contracts"
    }
  },
  "title": "get_pool_liquidityArguments"
}

get_earnings_window

Next scheduled earnings date for a ticker, and — given an expiration or an OCC contract — whether that print lands ON OR BEFORE the expiration (`earnings_in_window`). This is the doctrine hard-exclusion check: never hold a long single-leg option through earnings (IV crush). The engine applies this rail only at its own pick time, NOT in the pool — pool rows CAN carry earnings-window names, so check every candidate yourself. One call per candidate: pass the pool's `recommended_contract` verbatim and both the ticker and expiration are derived for you. FAIL-CLOSED: if the date is unknown (provider gap/outage, unannounced small-cap), `earnings_in_window` is null and the response says to treat the name as in-window. A confirmed date is still a provider estimate until the company confirms — re-check near the date. Args: ticker: underlying symbol, e.g. "AAPL" (optional if contract given). expiration: option expiration "YYYY-MM-DD" to test the window against (optional; derived from contract when contract is given). contract: OCC-style option ticker (e.g. "O:UNIT260717C00030000") — supplies both ticker and expiration in one argument. Returns: {ticker, next_earnings_date, is_estimated, last_reported_date, expiration, earnings_in_window, source, as_of, note} — `earnings_in_window`: true (print on/before expiration — doctrine says exclude), false (next print is after expiration), or null (unknown — treat as in-window).

Parameters

ticker	any	optional
expiration	any	optional
contract	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "expiration": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expiration"
    },
    "contract": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Contract"
    }
  },
  "title": "get_earnings_windowArguments"
}

get_contract_marks

DAILY mark series (OHLCV) for one option contract over a date range — the data you need to mark a live paper position day by day, or to replay a closed one under YOUR OWN exit rule. Composes with `get_contract_snapshot` (the right-now read). Marks are option-premium daily bars from the upstream aggregates feed (delayed per plan; thin contracts can have gap days with no bar — a missing date means NO trades printed that day, not a data bug). The close is the honest end-of-day mark on this quotes-less data plan. This server does NOT simulate exits — bring your own rule (the RM-004 boundary). For distributional exit research use `estimate_exit_rule` / `get_harvest_curve`; for excursion context use `get_opportunity_surface`. Args: contract: OCC-style option ticker exactly as served by the pool tools (e.g. "O:UNIT260717C00030000"). from_date: start "YYYY-MM-DD" (default: 30 days before to_date). to_date: end "YYYY-MM-DD" inclusive (default: today ET). Span is capped at 120 days. Returns: {contract, from_date, to_date, bar_count, bars: [{date, open, high, low, close, volume, vwap, transactions}], source, note}

Parameters

contract	string	required
from_date	any	optional
to_date	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "contract": {
      "title": "Contract",
      "type": "string"
    },
    "from_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "From Date"
    },
    "to_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "To Date"
    }
  },
  "required": [
    "contract"
  ],
  "title": "get_contract_marksArguments"
}

replay_contract

INTRADAY minute path for one option contract on one session — the exact tape an intraday entry/exit rule replays against (RM-002). Optionally pass a bracket (target_pct/stop_pct, PERCENT of the 10:00 ET anchor) and the response also reports the exact FIRST-CROSSING sequence: when each level was first touched and which came first — measured from the tape, not inferred from extremes. Pool contracts' excursion windows (entry day + 2 sessions) are served from the engine's minute-path table; anything else falls back to an upstream minute-aggregates fetch, so ANY contract/session in plan history works. Option tape is THIN — minutes with no prints have no bar, and lows between prints are unobservable; treat touch times as evidence, not tick-perfect truth. This server does NOT simulate or validate exits (the first-crossing readout is a fact about the past tape, not a recommendation) — the rule engine is yours. For cohort-level rule scoring use `estimate_exit_rule`. Args: contract: OCC-style option ticker (e.g. "O:UNIT260717C00030000"). date: ET session date "YYYY-MM-DD". target_pct: optional +X% level (percent of the anchor mark, e.g. 40). stop_pct: optional -Y% level (e.g. 30 or -30 both mean -30%). Returns: {contract, date, bar_count, bars: [{t, open, high, low, close, volume, ...}], anchor: {price, timestamp, definition}, first_crossing?: {target_level, stop_level, first_target_touch, first_stop_touch, first: TARGET|STOP|AMBIGUOUS_SAME_BAR|NONE}, retrieved_from, note}

Parameters

contract	string	required
date	string	required
target_pct	any	optional
stop_pct	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "contract": {
      "title": "Contract",
      "type": "string"
    },
    "date": {
      "title": "Date",
      "type": "string"
    },
    "target_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Pct"
    },
    "stop_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Stop Pct"
    }
  },
  "required": [
    "contract",
    "date"
  ],
  "title": "replay_contractArguments"
}

get_pool_features

Point-in-time FEATURE VECTORS for the labeled candidate pool, served from the leakage-safe allowlist view `enriched_features_v1` (identity + features + cohort metadata only — no outcome, label, or telemetry column can appear here by construction). This is the quantitative substrate for research and for joining against `query_outcomes` / `get_opportunity_surface`. NOTE: the labeled substrate lags the live pool by ~1-2 trading days (rows appear once the same-day replay has run). For TODAY'S live pool with narrative enrichment, use `get_enriched_signals` instead. Every feature is known as-of <= scan_date (the selection point). Caveats: `recommended_oi` / `recommended_volume` (and derived `volume_oi_ratio`, `moneyness_pct`) are session-frozen snapshots; `recommended_spread_pct` is permanently NULL on the current data plan. Args: scan_date: YYYY-MM-DD. Defaults to the most recent labeled scan date. ticker: Optional ticker filter. limit: Max rows (default 50, clamped 1-100). Returns: {scan_date, row_count, rows: [feature vectors...]}

Parameters

scan_date	any	optional
ticker	any	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_pool_featuresArguments"
}

get_opportunity_surface

The OPPORTUNITY SURFACE — per-contract realized excursions of the option premium over a fixed multi-day window with NO exit rule applied. This is "profit potential with the exit left as a free variable": your agent derives any entry/exit policy offline from these extremes. Per contract: `opp_peak_return` (max favorable excursion / MFE) and `opp_trough_return` (max adverse excursion / MAE) as FRACTIONS of the 10:00 ET entry cost basis (0.40 = +40%), `opp_minutes_to_peak/trough` (minutes from entry to each extreme), `opp_window_days` (trading days in the window, entry day included), and `opp_status`. This is NOT a tradeable label and NOT a feature — it is realized excursion over a closed window. Only rows whose window has fully closed are returned by default (`opp_status='OK'`). For the DISTRIBUTIONAL "typical path" summary of this surface — P(peak reaches +X%) with confidence intervals, day-of-peak buckets (peaks land day 2-3, not day 1), stop-touch rates, and the giveback pattern — use `get_harvest_curve`; to score a specific exit rule against it, use `estimate_exit_rule`. This tool returns the per-contract rows those aggregate. Args: scan_date: YYYY-MM-DD — return just that scan date's pool. ticker: Optional ticker filter (across the lookback if no scan_date). days: Lookback window in days when scan_date is not given (default 30, clamped 1-120). include_open: Include rows whose excursion window has not closed yet (opp_status != 'OK'; their MFE/MAE columns are NULL/partial). Returns: {row_count, rows: [...], meta: {statuses_included, note}}

Parameters

scan_date	any	optional
ticker	any	optional
days	integer	optional
include_open	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "days": {
      "default": 30,
      "title": "Days",
      "type": "integer"
    },
    "include_open": {
      "default": false,
      "title": "Include Open",
      "type": "boolean"
    }
  },
  "title": "get_opportunity_surfaceArguments"
}

query_outcomes

Row-level REALIZED LABELS for the full candidate pool, joined to their point-in-time feature vectors. Ask questions like "how did pool contracts with |delta| 0.20-0.46 behave under the same-day bracket?" Two distinct label horizons — never pooled together: * `same_day`: the live V7.1 GIGO bracket (enter 10:00 ET day after scan, +40% target / -30% stop, flat 15:45 ET same day). Label = `realized_return_pct` (FRACTION). * `3d`: the legacy 3-trading-day companion bracket (+80% / -60%, exit 15:50 ET day 3). Label = `realized_return_pct_3d`. Features come from the leakage-safe `enriched_features_v1` allowlist view; label columns are joined from the outcome table (label-join pattern). Rows with NULL labels and (same-day) `illiquid_exit=TRUE` rows are EXCLUDED by default — exclusion counts are reported in `meta` because the illiquid tail (~28% of the pool) is non-random and must not be silently hidden. Args: horizon: "same_day" or "3d". scan_date_from / scan_date_to: YYYY-MM-DD range bounds (inclusive). ticker: Optional ticker filter. delta_min / delta_max: Bounds on |recommended_delta| (0-1). min_overnight_score: Floor on overnight_score (1-10). exit_reason: Filter (TARGET | STOP | TIMEOUT | ...) on the chosen horizon. limit: Max rows (default 100, clamped 1-200). aggregate_only: True = skip row-level output and return summary stats (n, win_rate, avg/median/p25/p75, avg MFE/MAE) over the filtered set — rows are verbose; use this when you only need the shape. Returns: {horizon, row_count, rows: [...features + labels...], meta: {excluded_null_label, excluded_illiquid, pool_rows_in_window, note}} or, with aggregate_only: {horizon, aggregate: {...}, meta: {...}}.

Parameters

horizon	string	optional
scan_date_from	any	optional
scan_date_to	any	optional
ticker	any	optional
delta_min	any	optional
delta_max	any	optional
min_overnight_score	any	optional
exit_reason	any	optional
limit	integer	optional
aggregate_only	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "horizon": {
      "default": "same_day",
      "title": "Horizon",
      "type": "string"
    },
    "scan_date_from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date From"
    },
    "scan_date_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date To"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "delta_min": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delta Min"
    },
    "delta_max": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delta Max"
    },
    "min_overnight_score": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Overnight Score"
    },
    "exit_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Exit Reason"
    },
    "limit": {
      "default": 100,
      "title": "Limit",
      "type": "integer"
    },
    "aggregate_only": {
      "default": false,
      "title": "Aggregate Only",
      "type": "boolean"
    }
  },
  "title": "query_outcomesArguments"
}

get_outcome_summary

Aggregate realized-label statistics over the full labeled pool, optionally grouped by a whitelisted feature dimension. The exploration companion to `query_outcomes` — use it to see how outcomes distribute before pulling row-level data. Per group: n, win_rate (label > 0), avg/median/p25/p75 of the label, avg MFE (`opp_peak_return`) and avg MAE (`opp_trough_return`). Labels and excursions are FRACTIONS (0.40 = +40%). IMPORTANT: the whole-pool composite under any fixed exit is NEGATIVE by design of the problem — the pool sells opportunity, not a return. This tool exists to study CONDITIONAL structure (which feature slices behave differently), not to compute a strategy track record. Args: horizon: "same_day" (live V7.1 GIGO bracket) or "3d" (legacy +80/-60). group_by: one of none | delta_bucket | overnight_score | premium_score | exit_reason | day_of_week | moneyness_bucket. Strict whitelist. scan_date_from / scan_date_to: YYYY-MM-DD range bounds (inclusive). Returns: {horizon, group_by, groups: [...], meta: {exclusions, disclaimer}}

Parameters

horizon	string	optional
group_by	string	optional
scan_date_from	any	optional
scan_date_to	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "horizon": {
      "default": "same_day",
      "title": "Horizon",
      "type": "string"
    },
    "group_by": {
      "default": "none",
      "title": "Group By",
      "type": "string"
    },
    "scan_date_from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date From"
    },
    "scan_date_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date To"
    }
  },
  "title": "get_outcome_summaryArguments"
}

estimate_exit_rule

RESEARCH-ONLY — "bring your exit, we score it": score YOUR exit rule against every closed-window pool contract. Two rule families: * rule="bracket" (default): fixed target/stop, classified against the realized opportunity surface (MFE/MAE extremes over the 3-trading-day window). Rows where BOTH levels were crossed are resolved by EXACT first-crossing from the minute-path tape where coverage exists (TARGET_EXACT / STOP_EXACT); only uncovered rows fall back to the extreme-order heuristic — check `heuristic_share` (now typically ~0). * rule="trailing" (TF-14): hard initial stop (stop_pct) + a trailing stop that gives back trail_pct from the running peak, optionally armed only after +activation_pct. Replayed bar-by-bar on the minute-path tape in SQL; contracts never stopped ride to the window end (last bar close). This tool surfaces excursion EVIDENCE; it does not prescribe or validate an exit — the exit is yours. Measured context (2026-07-06 pool study): every fixed target <= +80% tested EV-NEGATIVE pool-wide, because cheap targets amputate the right tail that pays for the ~half of contracts that never pop. Read any single rule's stats as a description of the surface, never as a strategy. Bracket classification per contract: * TARGET / STOP — only one level was crossed (definitive from extremes). * TARGET_EXACT / STOP_EXACT — both crossed; resolved by exact first touch on the minute tape (same-bar touch resolves STOP-first, matching the engine labeler's pessimistic rule). * TARGET_HEURISTIC / STOP_HEURISTIC — both crossed, no minute coverage; resolved by which EXTREME came first. Best-effort, not exact. * TIMEOUT — neither level hit; true exit return bounded by [avg MAE, avg MFE] of the timeout group. Also returns `exact_label_match` when your bracket equals a rule the engine labels exactly: same_day +40/-30 (`realized_return_pct`, the live V7.1 GIGO policy) or 3d +80/-60 (`realized_return_pct_3d`) — exact labels include real fill/slippage mechanics and beat any surface estimate. Thin-tape caveat (both families): option minutes with no prints have no bar and lows between prints are unobservable — touch-based results are evidence, not tick-perfect truth. No slippage is applied. Args: target_pct: bracket profit target in PERCENT of entry premium (e.g. 40 = +40%). Clamped 5-300. Required for rule="bracket"; ignored for rule="trailing". stop_pct: initial/hard stop in PERCENT (e.g. -30 or 30 both mean a -30% stop). Clamped magnitude 5-95. Used by BOTH rule families. horizon: "3d" (the excursion window) or "same_day" (trailing only: day-1 bars through 15:45 ET; bracket: exact-label stats only). scan_date_from / scan_date_to: YYYY-MM-DD range bounds (inclusive). rule: "bracket" (default) or "trailing". trail_pct: trailing giveback in PERCENT off the running peak (e.g. 25 = exit when premium falls 25% from its high-water mark). Required for rule="trailing". Clamped 5-95. activation_pct: arm the trail only once the premium has traded at/above entry x (1 + this many PERCENT). Default 0 = armed once the premium has traded at/above the entry mark. Clamped 0-300. Returns: bracket: {params, n_classified, buckets, heuristic_share, est_win_rate, ev_bounds, exact_label_match?, meta} trailing: {params, n_scored, n_excluded_no_bars, stop_share, timeout_share, est_win_rate, avg_return, median_return, p10, p90, meta}

Parameters

target_pct	any	optional
stop_pct	number	optional
horizon	string	optional
scan_date_from	any	optional
scan_date_to	any	optional
rule	string	optional
trail_pct	any	optional
activation_pct	number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "target_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Pct"
    },
    "stop_pct": {
      "default": 30,
      "title": "Stop Pct",
      "type": "number"
    },
    "horizon": {
      "default": "3d",
      "title": "Horizon",
      "type": "string"
    },
    "scan_date_from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date From"
    },
    "scan_date_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date To"
    },
    "rule": {
      "default": "bracket",
      "title": "Rule",
      "type": "string"
    },
    "trail_pct": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Trail Pct"
    },
    "activation_pct": {
      "default": 0,
      "title": "Activation Pct",
      "type": "number"
    }
  },
  "title": "estimate_exit_ruleArguments"
}

get_harvest_curve

The HARVEST CURVE — for each profit target X, the probability a pool contract's premium TOUCHED +X% at least once inside the 3-trading-day excursion window (10:00 ET entry), with confidence intervals, which day the peak landed on, and stop-touch rates. Computed live from the closed- window opportunity surface, so it moves as data accrues. This is the ceiling for any limit-at-+X% exit: a TOUCH IS NOT A FILL (bar- high events, no exit slippage). Measured context (2026-07-06 study): about half of contracts touch +20%, ~1 in 7 touches +100%, meaningful pops land on day 2-3 not day 1, and every FIXED target tested EV-negative pool-wide — use this curve to understand the surface, not as a strategy return. Args: targets: Profit targets in PERCENT (default [15,20,30,50,75,100]); each clamped 5-300, max 12 values. stops: Stop levels in PERCENT magnitude (default [30,60]); each clamped 5-95, max 6 values. scan_date_from / scan_date_to: YYYY-MM-DD range bounds (inclusive). delta_min / delta_max: Bounds on |recommended_delta| (0-1). Returns: {window, n, median_peak_return, targets: [{target_pct, p_touch, ci95, n_touch, day_of_peak: {day1,day2,day3}}], stops: [{stop_pct, p_touch, ci95}], meta}

Parameters

targets	any	optional
stops	any	optional
scan_date_from	any	optional
scan_date_to	any	optional
delta_min	any	optional
delta_max	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "targets": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Targets"
    },
    "stops": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Stops"
    },
    "scan_date_from": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date From"
    },
    "scan_date_to": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date To"
    },
    "delta_min": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delta Min"
    },
    "delta_max": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Delta Max"
    }
  },
  "title": "get_harvest_curveArguments"
}

get_regime_context

Point-in-time market-regime context for a scan date: VIX close, VIX3M, SPY trend state, and the 5-day VIX delta — all as-of <= scan_date (the selection point, leakage-safe), plus the engine's regime safety rail evaluated on those values. The rail: the engine fail-closes (no trade) when spot VIX > VIX3M (backwardation — the market pricing imminent volatility is an adverse regime for short-dated directional longs). Served from the labeled substrate, which lags the live pool by ~1-2 trading days. Values are constant per scan_date. Args: scan_date: YYYY-MM-DD. Defaults to the latest scan date carrying regime features. Returns: {scan_date, vix_at_scan, vix3m_at_enrich, spy_trend_at_scan, vix_5d_delta_at_scan, regime_rail_pass, rail_definition}

Parameters

scan_date

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    }
  },
  "title": "get_regime_contextArguments"
}

list_playbooks

List the methodology playbooks this server publishes. Playbooks are versioned server-side documentation of HOW to use the data tools: the daily workflow, the run-your-own-tournament selection pattern, the exit lab, and the data contract / leakage rules. Fetch one with `get_playbook(name)`. Returns: List of {name, title, summary}.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_playbooksArguments"
}

get_playbook

Fetch one methodology playbook (markdown) by name. Start with `start-here`. Use `list_playbooks` to see everything published. Playbooks are living documents — re-fetch rather than caching long-term; the `changelog` playbook records dated methodology/data changes. Args: name: Playbook name as returned by `list_playbooks` (e.g. "start-here", "daily-workflow", "run-your-own-tournament", "exit-lab", "leakage-and-data-contract", "changelog"). Returns: {name, title, content} — content is markdown.

Parameters

name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "get_playbookArguments"
}

get_signal_performance

UNDERLYING-STOCK directional outcomes for the broad enriched pool — did the direction call work on the stock over the 3-day forward window? This is NOT option PnL. On the same pool, the underlying moving the right way (~54%) does not mean the option made money (~41%) — theta, IV and the exit bracket eat the difference. For realized OPTION trades use `get_position_history`; for the full-pool option labels use `query_outcomes`. Args: scan_date: Filter by date (YYYY-MM-DD). ticker: Filter to specific ticker. direction: "bull" or "bear". outcome: "win" or "loss" to filter. limit: Max results (default 50). Returns: {universe, basis, note, rows: [{ticker, direction, score, entry_price, current_price, underlying_pct_change, underlying_direction_outcome, scan_date}]} — field names carry the universe on purpose.

Parameters

scan_date	any	optional
ticker	any	optional
direction	any	optional
outcome	any	optional
limit	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "scan_date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scan Date"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ticker"
    },
    "direction": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Direction"
    },
    "outcome": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Outcome"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_signal_performanceArguments"
}

get_win_rate_summary

Aggregate UNDERLYING-STOCK direction statistics for the broad enriched pool over a lookback window. This win rate answers "how often was the direction call right on the STOCK" — it is NOT an option-PnL win rate and NOT the paper-trading track record. For those use `get_historical_performance` (realized option trades) or `get_outcome_summary` (full-pool option labels). There is deliberately NO bare `win_rate` field in the response: the headline is `underlying_direction_win_rate` (and bull_/bear_ variants), so the number cannot be quoted without its universe. Args: days: Lookback period in days (default 30). Returns: Summary statistics object with universe/basis markers; underlying_direction_win_rate is the headline metric.

Parameters

days

integer

optional

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "default": 30,
      "title": "Days",
      "type": "integer"
    }
  },
  "title": "get_win_rate_summaryArguments"
}

get_position_history

The RECEIPTS — realized (closed) paper trades from the engine's own daily selection, row-level. One tournament pick per day, simulated with real fills under the bracket policy live at the time. Realized-only by construction: rows appear only after the trade's exit, never same-day, so this tool cannot front-run the engine's private selection. No-trade days are reported separately in `skip_days` (they are part of the honest track record); invalid-liquidity rows are excluded. Live policy (`V7_1_TILTED_GIGO`, cohort since 2026-06-26): enter 10:00 ET the day after scan, +40% target / -30% stop, flat 15:45 ET same day. Earlier policy_version cohorts used different exits — do not mix cohorts when computing aggregates. Args: days: Lookback window in days (default 30, clamped 1-365). limit: Max rows (default 50, clamped 1-200). policy_version: Cohort filter (default = the live cohort). Pass "all" to see every era — comparison across eras is on you. Returns: {policy_version, row_count, rows: [{scan_date, ticker, direction, recommended_contract, entry/target/stop prices, realized_return_pct, exit_reason, benchmarks, timestamps, policy_version}]}

Parameters

days	integer	optional
limit	integer	optional
policy_version	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "days": {
      "default": 30,
      "title": "Days",
      "type": "integer"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "policy_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "V7_1_TILTED_GIGO",
      "title": "Policy Version"
    }
  },
  "title": "get_position_historyArguments"
}

get_historical_performance

Aggregate realized paper-trading performance (the engine's RECEIPTS) over a lookback window — one tournament pick per day, real-fill simulation. Defaults to the LIVE cohort (`V7_1_TILTED_GIGO`, since 2026-06-26: enter 10:00 ET day after scan, +40% target / -30% stop, flat 15:45 ET same day). The cohort is young — expect small N; small-N aggregates are noise-heavy and should be quoted with their N. Pass policy_version="all" to see all eras (different exit mechanics — comparison is on you). Realized-only: rows appear after exit, never same-day. All returns are FRACTIONS of entry premium (0.40 = +40%). Paper-traded. Not investment advice. Args: lookback_days: Lookback window in calendar days (default 30, clamped 1-365). direction: Optional filter — "bullish" or "bearish" (case-insensitive). min_premium_score: Optional integer floor on premium_score (0-6 typical). policy_version: Cohort filter (default = live cohort; "all" for every era). Returns: { "total_trades": int, "wins": int, # realized_return_pct > 0 "losses": int, # realized_return_pct <= 0 "win_rate": float, # 0.0-1.0 "avg_return": float, # mean of realized_return_pct (FRACTION) "median_return": float, "best": float, "worst": float, "period": str, "filters": {direction, min_premium_score, lookback_days, policy_version}, }

Parameters

lookback_days	integer	optional
direction	any	optional
min_premium_score	any	optional
policy_version	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "lookback_days": {
      "default": 30,
      "title": "Lookback Days",
      "type": "integer"
    },
    "direction": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Direction"
    },
    "min_premium_score": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Min Premium Score"
    },
    "policy_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "V7_1_TILTED_GIGO",
      "title": "Policy Version"
    }
  },
  "title": "get_historical_performanceArguments"
}

get_daily_report

Returns the full daily intelligence report. Args: date: Filter by date (YYYY-MM-DD). Defaults to most recent. Returns: Full report with title, content (markdown), created_at, scan_date.

Parameters

date

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "date": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Date"
    }
  },
  "title": "get_daily_reportArguments"
}

get_report_list

List available reports, most recent first. Repeated titles across dates are deduplicated (the generator occasionally reuses a headline) — each title appears once, at its most recent scan_date. Args: limit: Number of reports to return (default 10). Returns: List of {scan_date, title, created_at}.

Parameters

limit

integer

optional

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 10,
      "title": "Limit",
      "type": "integer"
    }
  },
  "title": "get_report_listArguments"
}

get_available_dates

Returns which scan dates have data available. Returns: List of {scan_date, signal_count}

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "get_available_datesArguments"
}

get_enriched_signal_schema

RESEARCH / POWER-USER tool. If you just need what a field MEANS, `get_signal_explainer` is the everyday path — this is the formal contract for grounding research code. The substrate DATA CONTRACT, machine-readable: every column of the outcome/label substrate with its leakage classification and as-of boundary, plus the exact column set exposed by the point-in-time features view (what `get_pool_features` serves). Classifications: identity | feature | label | opportunity | regime_telemetry. Only `feature` columns are safe as selection inputs — everything else is realized after the selection point. Use this tool to ground research code instead of hallucinating field names, and see get_playbook("leakage-and-data-contract") for the rules in prose. Returns: {vocabulary, features_view_columns: [...], columns: [{column, data_type, classification, as_of, description}]}

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "get_enriched_signal_schemaArguments"
}

get_market_calendar_status

Returns whether the US equity market is open today + the next open/close. Uses pandas_market_calendars (NYSE) so it knows about holidays + early closes deterministically — eliminates the chat-agent "is the market open?" hallucination class. Returns: { "is_open_today": bool, "current_date": "YYYY-MM-DD" (Eastern), "current_time_et": "ISO8601" (Eastern), "next_open": "ISO8601" (Eastern, schedule open boundary), "next_close": "ISO8601" (Eastern, schedule close boundary), "is_holiday": bool, "holiday_name": str | None, "is_early_close": bool, }

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "get_market_calendar_statusArguments"
}

get_signal_explainer

Return a plain-English definition + role of a GammaRips signal field. Deterministic lookup table — no LLM, no hallucination. Use this for the "what does X mean?" pattern when a chat user asks about a metric we surfaced. If the field isn't in our dictionary, returns an "unknown" row rather than guessing. Args: field_name: Field name as it appears in tool responses (e.g., "premium_score", "volume_oi_ratio", "recommended_contract"). Returns: {field_name, label, definition, how_used, available_fields} — `available_fields` is the full list of supported field names so the agent can offer alternatives if the input was misspelled.

Parameters

field_name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "field_name": {
      "title": "Field Name",
      "type": "string"
    }
  },
  "required": [
    "field_name"
  ],
  "title": "get_signal_explainerArguments"
}

web_search

Performs a Google Web Search using the Custom Search JSON API via direct HTTP requests. Useful for finding real-time information, news, or verifying facts (grounding). Args: query: The search query string. num_results: Number of results to return (default 5, max 10). Returns: A formatted string containing the top search results (Title, Snippet, Link).

Parameters

query	string	required
num_results	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "title": "Query",
      "type": "string"
    },
    "num_results": {
      "default": 5,
      "title": "Num Results",
      "type": "integer"
    }
  },
  "required": [
    "query"
  ],
  "title": "web_searchArguments"
}

README.md9 KBView on GitHub

GammaRips MCP Server

Options-flow intelligence primitives for AI agents.

Every trading morning GammaRips scans the US options market for unusual institutional activity and curates it hard — down to a ~50-name high-signal BULLISH pool. This MCP server gives a bring-your-own-agent trader that pool plus the substrate to reason over it: point-in-time features, realized opportunity surfaces (max-favorable / max-adverse excursions with no exit applied), bracket outcome labels, regime context, and methodology playbooks.

Design principle: primitives, never a pick. There is no "what should I buy" endpoint. Every agent reasons from the same data to its own contract and its own exit. Paper-traded research data; educational only; not investment advice.

Hosted MCP endpoint

Streamable HTTP (primary): https://gammarips-mcp-406581297632.us-central1.run.app/mcp
SSE (legacy, deprecation window): https://gammarips-mcp-406581297632.us-central1.run.app/sse
Stateless JSON-RPC: https://gammarips-mcp-406581297632.us-central1.run.app/jsonrpc
Server card: https://gammarips-mcp-406581297632.us-central1.run.app/.well-known/mcp/server-card.json
Auth: bearer-token tiering (Phase 2). Free-tier tools work with no key; pro tools need a GammaRips API key (gr_live_...) sent as Authorization: Bearer <key>. Currently in shadow rollout (nothing blocked yet); flips to enforce once keys are issued. Get one at gammarips.com/pricing.

Available tools (25)

Live pool

get_contract_snapshot — fresh entry-day OI / session volume / last trade / day range for one contract (no quote fields on this data plan)
get_enriched_signals — the curated daily candidate pool: enrichment narrative, technicals, catalyst, recommended contract, mom_60 (leakage-safe view)
get_signal_detail — full enrichment for one ticker
get_overnight_signals — the raw pre-curation scan (wide net)
get_freemium_preview — top-N teaser, narrow fields

Research substrate (V3)

get_pool_features — point-in-time feature vectors from the allowlist features view
get_opportunity_surface — per-contract realized MFE/MAE excursions, exit-free (the core product surface)
query_outcomes — row-level bracket labels (same-day GIGO or 3-day) joined to features
get_outcome_summary — grouped aggregates (delta bucket, score, exit reason, ...) with honest exclusion counts
get_harvest_curve — touch-probability curve (P(peak ≥ X) w/ CIs), day-of-peak buckets, stop-touch rates, live from the closed-window surface
estimate_exit_rule — classify YOUR (target, stop) bracket against the surface; EV bounds, heuristic share reported
get_regime_context — VIX/VIX3M/SPY-trend as-of scan date + the fail-closed rail

Methodology

list_playbooks / get_playbook — server-versioned playbooks: start-here, daily-workflow, run-your-own-tournament, exit-lab, leakage-and-data-contract, changelog. Also exposed as MCP resources (gammarips://playbooks/{name}).

Performance / receipts

get_position_history — the engine's realized paper trades (T+1 receipts; cohort-filtered, default live V7_1_TILTED_GIGO)
get_historical_performance — cohort aggregate of the above
get_signal_performance / get_win_rate_summary — UNDERLYING-stock direction outcomes for the broad pool (explicitly not option PnL)

Reports & metadata

get_daily_report / get_report_list — daily intelligence reports
get_available_dates — scan dates with data
get_enriched_signal_schema — the machine-readable data contract: every substrate column with its leakage classification (feature | label | opportunity | regime_telemetry | identity) and as-of boundary

Reference / external

get_market_calendar_status — NYSE calendar status
get_signal_explainer — plain-English definition of any field (deterministic, no LLM)
web_search — Google Custom Search (rate-limited, 10 req/min/IP)

Removed in V3

get_todays_pick, list_todays_picks, get_open_position — the engine's own daily selection is no longer published same-day (realized receipts remain via get_position_history).

Prompts

morning_brief, analyze_candidate(ticker), run_your_own_tournament — thin orchestrations over the tools above. None returns a pick.

Quick connect

Claude Code

bash

# Free tier (no key):
claude mcp add --transport http gammarips https://gammarips-mcp-406581297632.us-central1.run.app/mcp

# Pro (with your key):
claude mcp add --transport http gammarips https://gammarips-mcp-406581297632.us-central1.run.app/mcp \
  --header "Authorization: Bearer gr_live_your_key"

Cursor

Easiest — install the plugin. This repo is an Open Plugins-standard plugin (.cursor-plugin/plugin.json): it bundles the hosted MCP server plus a gammarips-options-flow skill that teaches your agent the data-not-advice workflow. Install it from the plugin marketplace (search "GammaRips") or point Cursor at this repo. It connects on the free tier out of the box; add your gr_live_... key for pro tools.

Manual: Settings → MCP → Add new MCP server, or add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "gammarips": {
      "url": "https://gammarips-mcp-406581297632.us-central1.run.app/mcp",
      "headers": { "Authorization": "Bearer gr_live_your_key" }
    }
  }
}

Omit headers for the free tier.

Cline

MCP Servers → Remote Servers → Add, or add to cline_mcp_settings.json:

json

{
  "mcpServers": {
    "gammarips": {
      "url": "https://gammarips-mcp-406581297632.us-central1.run.app/mcp",
      "type": "streamableHttp",
      "headers": { "Authorization": "Bearer gr_live_your_key" }
    }
  }
}

Omit headers for the free tier (8 anon tools).

Generic MCP config

json

{
  "mcpServers": {
    "gammarips": {
      "url": "https://gammarips-mcp-406581297632.us-central1.run.app/mcp"
    }
  }
}

Clients that only speak SSE can use the legacy /sse endpoint during the deprecation window.

Free tier works with no account: get_daily_report, list_playbooks/get_playbook, get_signal_explainer, get_market_calendar_status, get_available_dates, get_report_list, get_freemium_preview. Pro tools require Agent Access ($39/mo) — generate a key at gammarips.com.

Local development

Prerequisites

Python 3.10+
Optional: Docker

Setup

bash

git clone https://github.com/DevDizzle/gammarips-mcp.git
cd gammarips-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env

Run locally

bash

PYTHONPATH=src python src/server.py

The server binds to 0.0.0.0:${PORT:-8080}, Streamable HTTP at /mcp (SSE fallback).

Docker

bash

docker build -t gammarips-mcp .
docker run --rm -p 8080:8080 --env-file .env gammarips-mcp

Environment

See .env.example for the current environment variables. Typical values include:

GCP_PROJECT_ID
FIRESTORE_DATABASE
GCS_BUCKET_NAME
LOG_LEVEL
PORT

Validation

Python compile check

bash

python -m compileall src

Docker build check

bash

docker build -t gammarips-mcp:test .

Deployment

Deployment is manual (the CD workflow was removed; .github/workflows/ci.yml only runs ruff format --check + ruff check on pushes/PRs to main).

Ship a new revision with the deploy script, which uses a Cloud Run source deploy and reproduces the live config exactly (secrets via Secret Manager, REQUIRE_API_KEY=false):

bash

bash scripts/deploy.sh

Equivalent one-liner:

bash

gcloud run deploy gammarips-mcp --source=. \
  --project=profitscout-fida8 --region=us-central1 \
  --set-env-vars="REQUIRE_API_KEY=false" \
  --set-secrets="POLYGON_API_KEY=POLYGON_API_KEY:latest,GOOGLE_API_KEY=GOOGLE_API_KEY:latest,GOOGLE_CSE_ID=GOOGLE_CSE_ID:latest"

The API keys are mounted from Secret Manager — never pass them as plain env vars (that clobbers the secret mounts).

Before any deploy that changes data exposure: run the gammarips-review leakage audit (see docs/MCP-V3-SPEC.md §2.4).

Security

See SECURITY.md for the trust model — read-only guarantee, parameterized-query SQL-injection defense, response-size bounds, per-IP rate limits, sanitized errors, leakage-safe views, and the column-classification data contract.

License

MIT

Install

Tools (29)

get_overnight_signalsget_enriched_signalsget_signal_detailget_freemium_previewget_contract_snapshotget_pool_liquidityget_earnings_windowget_contract_marks

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://gammarips-mcp-406581297632.us-central1.run.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "gammarips": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gammarips-mcp-406581297632.us-central1.run.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.