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
data/options_cache/

Related MCP server: MCP Options Order Flow Server

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; 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 data/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