OSS · CLI Python · Servidor MCP

quake-lens

Predecir terremotos es imposible. Estimar la tasa de réplicas es rutina científica.

Descarga catálogos sísmicos públicos (JMA, P2P, USGS) y calcula las estadísticas detrás del pronóstico honesto de réplicas: el valor b de Gutenberg-Richter con la MLE de forma cerrada de Aki, y el decaimiento de Omori modificado con la MLE de Ogata y Nelder-Mead en Python puro. Cero dependencias de runtime. Un servidor MCP opcional expone los mismos cálculos como 4 herramientas para clientes LLM.

Ver en GitHub Notas de v0.1.0

Demo en terminal: quake-lens recent descarga terremotos en vivo de la JMA, luego estima b = 1.0449 ± 0.1306 con 130 réplicas de Noto 2024 y ajusta el decaimiento de Omori-Utsu con p = 0.8861.
Feed de la JMA en vivo y la secuencia de réplicas de Noto (2024): valor b 1.04 ± 0.13 (consistente con el promedio global de ~1.0) y decaimiento p = 0.89. Datos reales, salidas reales.

Cuatro subcomandos, cuatro herramientas MCP

La CLI conecta los pasos con JSON por pipe. Las herramientas MCP hacen la descarga y la estimación del lado del servidor y devuelven solo estadísticas, así que los arrays grandes de eventos nunca pasan por el contexto del LLM.

Comando / herramienta Qué hace
recent --src p2p|jma Latest quakes from the P2P or JMA feed, normalized to one event schema (sentinel filtering + telegram dedupe included).
catalog USGS FDSN catalog query: time window, minimum magnitude, bounding box. JSON or table output.
bvalue --mc <m> Gutenberg-Richter b-value via Aki’s closed-form MLE, with standard error b/√N.
omori --mainshock <t> Modified Omori fit via Ogata’s MLE: grid search, then Nelder-Mead in log space. Returns K, c, p, logL.
get_recent / get_catalog (MCP) The same fetchers exposed as MCP tools for LLM clients.
estimate_bvalue / fit_omori (MCP) Fetch + estimate server-side; only statistics return to the LLM context.

Instalación

Corre directo del clone, sin dependencias. El extra opcional agrega el servidor MCP (SDK 1.x y 2.x soportados).

git clone https://github.com/kenimo49/quake-lens.git
cd quake-lens
python3 -m quake_lens --help     # zero dependencies, runs as-is

# optional: MCP server (mcp SDK 1.x / 2.x)
pip install ".[mcp]"
claude mcp add quake-lens -- quake-lens-mcp

Uso

El pipeline completo con el terremoto de Noto (2024), tal como se midió:

quake-lens recent --src jma --limit 5

quake-lens catalog --start 2024-01-01 --end 2024-01-11 \
  --min-mag 4.0 --format json > noto.json

quake-lens bvalue noto.json --mc 4.5
# b = 1.0449   se = 0.1306   n_used = 64

quake-lens omori noto.json --mainshock 2024-01-01T07:10:00Z
# K = 23.3856  c = 0.0224  p = 0.8861  n_used = 130

Cuatro trampas encontradas durante el desarrollo

Cada una apareció al correr contra APIs y SDKs reales, no en la documentación.

  1. El USGS no ve los terremotos pequeños de Japón

    El catálogo global del USGS pierde la mayoría de los eventos M3 en Japón. Si la magnitud de completitud Mc queda por debajo de lo que el catálogo realmente registra, la estimación del valor b se rompe en silencio: el mismo dataset de Noto da b = 1.04 con Mc 4.5 y b = 0.27 con Mc 3.0. Más datos empeoraron la estimación. La completitud del catálogo va antes que la estadística.

  2. La JMA escribe la profundidad muy somera como cero positivo

    El list.json de la JMA codifica hipocentros como strings tipo ISO 6709, con la profundidad como altitud negativa en metros. La excepción son los terremotos muy someros, que llegan como "+0", un cero positivo. Invertir el signo sin cuidado produce el -0.0 de IEEE 754, que aparece como "-0.0" en la tabla de salida. Se encontró en vivo y se corrigió normalizando a cero positivo.

  3. La P2P marca hipocentro desconocido con centinelas, no con null

    La API P2P reporta datos faltantes de hipocentro como latitud/longitud -200 y magnitud -1 en lugar de null. Un chequeo de null pasa de largo y una fila basura "-200.000 -200.000 -1.0" llega a la salida. El mismo feed entrega hasta tres telegramas por terremoto, así que la deduplicación por hora de origen conserva solo el boletín detallado más reciente.

  4. El SDK mcp 2.0 renombró FastMCP y el CI siguió en verde

    El mcp 2.0.0 eliminó mcp.server.fastmcp y renombró FastMCP a MCPServer, así que un pip install nuevo rompía el servidor en el import. El CI seguía en verde porque el SDK es dependencia opcional y el importorskip saltaba el archivo de test completo. El código con dependencias opcionales necesita un venv con el SDK realmente instalado; un dual import con try/except ahora cubre las dos versiones.

Artículos relacionados

Herramientas relacionadas para devs

Todos los productos →

← Volver a productos