Skip to main content
Glama
options-analysis

options-analysis

by mrsoto

options-analysis

Este proyecto se distribuye bajo la licencia GNU General Public License, version 3 o posterior. Consulta LICENSE.

MCP local para consultar cadenas de opciones y calcular exposicion gamma estimada para ETFs y otros subyacentes con opciones liquidas.

El alcance, los supuestos y los criterios de aceptacion se mantienen en PLAN.md.

Estructura

src/options_mcp/
|-- domain/       # Modelos y calculos puros
|-- providers/    # Fuentes externas de cadenas y precios
|-- services/     # Casos de uso de cadena, gamma y proxies
|-- storage/      # Cache local
`-- tools/        # Adaptadores expuestos por MCP
tests/            # Pruebas unitarias y fixtures sin red
../var/options-analysis/

Related MCP server: greeks-mcp

Herramientas

  • get_options_expirations

  • get_options_chain

  • get_gamma_exposure

  • get_gamma_snapshot

  • calculate_proxy_gamma

  • get_proxy_definition

  • calculate_named_proxy_gamma

  • compare_gamma_with_price

  • audit_gamma_history

La fuente inicial es Yahoo Finance mediante yfinance. Los datos pueden estar retrasados y el open interest puede corresponder a la sesion anterior.

GEX y proxy_gamma son estimaciones derivadas, no posiciones observadas de dealers. El signo depende de la convencion solicitada y siempre se devuelve junto con los supuestos y advertencias.

Ejemplo

{
  "target_symbol": "IUVL",
  "components": [
    {"symbol": "QQQ", "weight": 0.40, "reason": "technology proxy"},
    {"symbol": "IWD", "weight": 0.60, "reason": "value proxy"}
  ]
}

Los pesos son una hipotesis de proxy y deben validarse contra las tenencias vigentes del emisor del ETF.

Las definiciones durables pueden proporcionarse mediante OPTIONS_MCP_PROXY_DEFINITIONS_PATH; el runtime por defecto se configura mediante OPTIONS_DATA_ROOT y no se incluyen datos de mercado ni instantaneas historicas en el repositorio.

Fuentes publicas

  • Yahoo Finance: fuente automatizada inicial para cadenas retrasadas.

  • Cboe delayed quotes: validacion manual de cotizaciones y cadenas cuando la pagina publica esta disponible.

  • Nasdaq Option Chain: validacion optativa de vencimiento, spot y contratos comunes mediante tests/test_secondary_validation.py.

  • OCC: referencia oficial de open interest y estadisticas diarias.

Estas fuentes no publican una posicion observada de dealers. El MCP calcula gamma y GEX a partir de los campos disponibles y conserva la fecha, proveedor, calidad y supuestos del calculo.

Historico diario

El repositorio no incluye una watchlist ni datos de mercado. Para recoger una observacion manual, proporciona una watchlist externa o simbolos directamente:

uv run options-gamma-snapshot --symbols SPY QQQ IWM

La salida se guarda como OPTIONS_DATA_ROOT/options_history/GAMMA_SNAPSHOT_YYYY-MM-DD.json. La fecha del archivo usa el calendario de America/Montevideo, igual que el cron; el archivo es idempotente por fecha y conserva errores individuales de simbolos. La tarea del repositorio cron/daily/2115_options_gamma_snapshot.md ejecuta el recolector diariamente a las 21:15 en America/Montevideo.

Para auditar la cobertura acumulada sin consultar la red:

uv run options-gamma-history-audit

El auditor informa la primera y ultima observacion por simbolo y el estado de preparacion para cada horizonte diario. Tambien esta disponible como la herramienta MCP audit_gamma_history.

compare_gamma_with_price usa solo snapshots persistidos y admite next_day, short_term (cinco observaciones diarias) y medium_term (veinte observaciones diarias). Devuelve insufficient_data hasta alcanzar el minimo requerido para el horizonte. intraday devuelve unsupported_horizon porque el recolector actual solo persiste una observacion diaria. La comparacion es descriptiva y no implica causalidad ni constituye una senal.

Smoke test optativo

La suite normal no usa red. Para validar la disponibilidad de Yahoo y una cadena real de SPY, ejecutar:

OPTIONS_MCP_LIVE_TESTS=1 uv run pytest tests/test_live_smoke.py -q

Available Tools

9 tools
audit_gamma_historyC

Audit persisted gamma history readiness by symbol and daily horizon.

Inputs: symbols (required), history_dir, min_observations.

calculate_named_proxy_gammaC

Calculate GEX using a named durable proxy definition.

Inputs: target_symbol (required), expirations, dividend_yield, risk_free_rate, +2 more.

calculate_proxy_gammaB

Calculate weighted proxy GEX for an ETF with explicit components.

Inputs: components (required), target_symbol (required), expirations, dividend_yield, +3 more.

compare_gamma_with_priceC

Compare persisted GEX with daily forward returns at a selected horizon.

Inputs: symbol (required), horizon, history_dir, min_observations.

get_gamma_exposureC

Calculate estimated GEX per strike and expiration.

Inputs: symbol (required), spot, expirations, dividend_yield, +3 more.

get_gamma_snapshotC

Return compact estimated GEX reports for several symbols.

Inputs: symbols (required), max_expirations, sign_convention.

get_options_chainB

Return a normalized delayed option chain for one expiration.

Inputs: symbol (required), expiration.

get_options_expirationsB

Return available delayed option expiration dates for a symbol.

Inputs: symbol (required).

get_proxy_definitionC

Return the durable proxy definition and its verification status.

Inputs: target_symbol (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or modes: options chain data, expirations, GEX by strike, multi-symbol snapshots, explicit-component proxies, and named proxies. The cluster of gamma calculation tools could still be confused, but their descriptions distinguish direct GEX, snapshot GEX, and proxy-based GEX.

    Naming Consistency4/5

    The set mostly follows a clear verb_noun snake_case pattern: get_, calculate_, compare_, audit_. There is minor inconsistency in noun ordering (gamma_exposure vs proxy_gamma) and get_ vs calculate_ for derived data, but overall the pattern is predictable.

    Tool Count5/5

    Nine tools is well-scoped for an options analytics server. Each tool supports a distinct part of the workflow—market data retrieval, GEX calculation, proxy definitions, comparison, and auditing—without obvious redundancy.

    Completeness4/5

    The surface covers chain fetching, expiration lookup, direct GEX, proxy GEX, named proxy usage, price comparison, and history auditing. Minor gaps exist, such as no way to list all available named proxy definitions or retrieve raw gamma history directly, but core analytical workflows are supported.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time options analytics, pricing with Greeks, Monte Carlo simulations, volatility analysis, strategy backtesting, and risk metrics using actual market data from Yahoo Finance and Polygon.io.
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Exposes the Greeks options-analytics API as MCP tools, enabling live queries for GEX, Greeks, Max Pain, unusual flow, and full dashboard on any ticker.
      12
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI assistants to live options market data with 70+ tools for exposure analytics, volatility, strategy signals, and historical backtesting.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables querying FlashAlpha options-exposure analytics, including gamma exposure, key options-derived levels, implied volatility summaries, and Black-Scholes greeks.
      167 npm
      MIT