OSS · CLI Python · Servidor MCP

quake-lens

Prever terremotos é impossível. Estimar a taxa de réplicas é rotina científica.

Busca catálogos sísmicos públicos (JMA, P2P, USGS) e calcula as estatísticas por trás da previsão honesta de réplicas: o valor-b de Gutenberg-Richter pela MLE de forma fechada de Aki, e o decaimento de Omori modificado pela MLE de Ogata com Nelder-Mead em Python puro. Zero dependências de runtime. Um servidor MCP opcional expõe os mesmos cálculos como 4 ferramentas para clientes LLM.

Ver no GitHub Notas da v0.1.0

Demo no terminal: quake-lens recent busca terremotos ao vivo da JMA, depois estima b = 1.0449 ± 0.1306 a partir de 130 réplicas de Noto 2024 e ajusta o decaimento de Omori-Utsu com p = 0.8861.
Feed da JMA ao vivo e a sequência de réplicas de Noto (2024): valor-b 1.04 ± 0.13 (consistente com a média global de ~1.0) e decaimento p = 0.89. Dados reais, saídas reais.

Quatro subcomandos, quatro ferramentas MCP

A CLI conecta as etapas com JSON via pipe. As ferramentas MCP fazem busca e estimativa do lado do servidor e retornam apenas estatísticas, então arrays grandes de eventos nunca passam pelo contexto do LLM.

Comando / ferramenta O que faz
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.

Instalação

Roda direto do clone, sem dependências. O extra opcional adiciona o servidor MCP (SDK 1.x e 2.x suportados).

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

O pipeline completo no terremoto de Noto (2024), exatamente como foi medido:

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

Quatro armadilhas encontradas durante o desenvolvimento

Cada uma apareceu ao rodar contra APIs e SDKs reais, e não na documentação.

  1. O USGS não enxerga os terremotos pequenos do Japão

    O catálogo global do USGS perde a maioria dos eventos M3 no Japão. Se a magnitude de completude Mc ficar abaixo do que o catálogo realmente registra, a estimativa do valor-b quebra em silêncio: o mesmo dataset de Noto dá b = 1.04 com Mc 4.5 e b = 0.27 com Mc 3.0. Mais dados pioraram a estimativa. A completude do catálogo vem antes da estatística.

  2. A JMA escreve profundidade muito rasa como zero positivo

    O list.json da JMA codifica hipocentros como strings tipo ISO 6709, com profundidade como altitude negativa em metros. A exceção são os terremotos muito rasos, que chegam como "+0", um zero positivo. Inverter o sinal sem cuidado produz o -0.0 do IEEE 754, que aparece como "-0.0" na tabela de saída. Encontrado ao vivo e corrigido normalizando para zero positivo.

  3. A P2P marca hipocentro desconhecido com sentinelas, e não com null

    A API P2P reporta dados ausentes de hipocentro como latitude/longitude -200 e magnitude -1 em vez de null. Uma checagem de null passa direto e uma linha de lixo "-200.000 -200.000 -1.0" chega na saída. O mesmo feed entrega até três telegramas por terremoto, então a deduplicação por horário de origem mantém só o boletim detalhado mais recente.

  4. O SDK mcp 2.0 renomeou o FastMCP e o CI continuou verde

    O mcp 2.0.0 removeu mcp.server.fastmcp e renomeou FastMCP para MCPServer, então um pip install novo quebrava o servidor no import. O CI seguia verde porque o SDK é dependência opcional e o importorskip pulava o arquivo de teste inteiro. Código com dependência opcional precisa de um venv com o SDK realmente instalado; um dual import com try/except agora cobre as duas versões.

Artigos relacionados

Ferramentas relacionadas para devs

Todos os produtos →

← Voltar para produtos