Skip to main content
Glama

RíoAlerta (rio-alerta-mcp)

Vigilancia Satelital Multitemporal de Extracción de Áridos en Ríos Argentinos mediante Sentinel-2 L2A, Controles de Dinámica Fluvial y Proyección Oficial POSGAR 2007

Python 3.11+ FastMCP CRS POSGAR 2007 License: MIT


Resumen Ejecutivo (Abstract)

RíoAlerta (rio-alerta-mcp) es un servidor Model Context Protocol (FastMCP) y motor geoespacial multitemporal diseñado para asistir a autoridades ambientales provinciales, municipios, Prefectura Naval Argentina (PNA) y organismos de recursos hídricos en la detección, cuantificación y auditoría reproducible de alteraciones compatibles con extracción de áridos (cavas inundadas, frentes de dragado, desmontes de ribera, playas de acopio y caminos de acceso) sobre corredores fluviales argentinos.

A diferencia de los detectores de cambio genéricos por diferencia simple de píxeles, RíoAlerta modela explícitamente la física espectral de sensores ópticos multiespectrales (Sentinel-2 L2A) y la geomorfología de ríos aluviales de llanura:

  1. Preservación de resoluciones nativas (10 m VNIR / 20 m SWIR+SCL) y separación estricta entre remuestreo radiométrico (bilinear) y categórico (nearest).

  2. Ingesta eficiente por HTTP Range Requests (GDAL/VSICURL) sobre Cloud-Optimized GeoTIFFs (COG) en STAC (Element 84 Earth Search / Microsoft Planetary Computer), con filtro de cobertura completa de tesela MGRS (>= 98%) para evitar truncamientos de borde.

  3. Proyección métrica automática a POSGAR 2007 (EPSG:5343–5349, Fajas 1 a 7) para garantizar áreas en $\text{m}^2/\text{ha}$ y distancias métricas exactas en todo el territorio argentino.

  4. Controles de dinámica fluvial natural (pulsos de crecida/bajante, dipolos acoplados de migración de bancos de arena, deriva fenológica de la vegetación en galería y confusores de turbidez).

  5. Prudencia institucional y trazabilidad: las geometrías emitidas constituyen anomalías morfológicas candidatas con metadatos explícitos de incertidumbre (UncertaintyMetadata), nunca calificaciones jurídicas autónomas sin cruce catastral oficial y verificación humana.


Related MCP server: Copernicus Earth Observation MCP Server

1. Marco Metodológico y Fundamento Científico (Base tipo Paper)

1.1 Problema de Detección en Llanuras Aluviales

Los sistemas fluviales argentinos —en particular el Río Paraná Medio e Inferior— presentan una dinámica hidromorfológica intensa caracterizada por variaciones de nivel hidrométrico superiores a $4\text{ m}$, migración continua de barras arenosas, inundación estacional de lagunas isleñas detrás de albardones y presencia simultánea de aguas altamente turbias (carga de sedimentos en suspensión) y aguas negras/húmicas ricas en materia orgánica disuelta (CDOM).

Un detector bitemporal ingenuo basado únicamente en índices espectrales normalizados colapsa en este entorno por tres mecanismos físicos documentados en el Experimento 001 (Paraná Medio):

  • Singularidad de cocientes en baja reflectancia: en aguas negras/húmicas (B08 -> 0, B11 < 200 DN), el denominador del Bare Soil Index (BSI) tiende a cero y amplifica ruido atmosférico residual Sen2Cor, generando falsos positivos de suelo desnudo.

  • Inundación no lineal de llanura aluvial: por encima de la cota de coronamiento de albardones ($\approx 3.0\text{--}3.2\text{ m}$ en Puerto Paraná / Santa Fe), las cubetas isleñas desconectadas del cauce de estiaje se llenan por desborde o napa freática, produciendo incrementos abruptos de MNDWI sin conexión superficial directa (<= 1.5 px) con la lámina de $T_0$.

  • Confusores de turbidez y sumersión de barras: la sumersión de un banco somero brillante (B04_T0 = 988 -> B04_T1 = 641 DN) invierte el signo de $\Delta B_{04}$, burlando filtros unidireccionales de turbidez.

1.2 Formulación Espectral

Dadas las bandas de reflectancia de superficie Sentinel-2 L2A (BOA_OFFSET_APPLIED = True, escala 10000 DN):

  • VNIR (10 m nativos): $B_{02}$ (Azul, $490\text{ nm}$), $B_{03}$ (Verde, $560\text{ nm}$), $B_{04}$ (Rojo, $665\text{ nm}$), $B_{08}$ (NIR, $842\text{ nm}$).

  • SWIR + SCL (20 m nativos): $B_{11}$ (SWIR1, $1610\text{ nm}$), $B_{12}$ (SWIR2, $2190\text{ nm}$), SCL (Scene Classification Layer).

Para cada escena válida (SCL $\notin {0,1,2,3,8,9,10,11}$), el motor calcula:

  1. Modified Normalized Difference Water Index (MNDWI, Xu 2006): $$\text{MNDWI} = \frac{B_{03} - B_{11}}{B_{03} + B_{11} + \epsilon}$$ Sensible a lámina de agua abierta, excavaciones inundadas y contenido hídrico superficial.

  2. Bare Soil Index (BSI, Rikimaru et al. 2002): $$\text{BSI} = \frac{(B_{11} + B_{04}) - (B_{08} + B_{02})}{(B_{11} + B_{04}) + (B_{08} + B_{02}) + \epsilon}$$ (En Fase 2.1 se incorpora además la variante regularizada por albedo $\text{BSI}_{\text{reg}}(k)$ con $k=800\text{ DN}$ para suprimir singularidades en aguas negras).

  3. Normalized Difference Vegetation Index (NDVI): $$\text{NDVI} = \frac{B_{08} - B_{04}}{B_{08} + B_{04} + \epsilon}$$

1.3 Reglas de Detección y Controles Naturales

Entre la línea base histórica $T_0$ (escena única o mediana libre de nubes de hasta $N$ años en ventana estacional $\pm 45\text{ días}$ del día del año DOY) y la escena actual $T_1$:

  • Normalización fenológica ribereña: sobre píxeles de vegetación densa en $T_0$ ($\text{NDVI}{T_0} > 0.45$), se estima la deriva mediana estacional $\tilde{\Delta}\text{NDVI}$ y $\tilde{\Delta}\text{BSI}$, descontando únicamente senescencia regional uniforme ($\Delta\text{NDVI}{\text{adj}}, \Delta\text{BSI}_{\text{adj}}$).

  • Control hidrométrico del tramo (compute_reach_hydrological_state): cuantifica la variación porcentual de lámina de agua (water_stage_delta_pct), la fracción de inundación perimetral (shoreline_flooding_fraction) y construye uniform_stage_belt_mask / drawdown_belt_mask mediante transformada de distancia euclidiana (EDT).

  • Control de dipolos de migración de bancos (detect_natural_bar_migration_dipoles): empareja componentes de erosión ($\Delta\text{MNDWI} > +0.35$, $\text{NDVI}{T_0} < 0.35$) con componentes de acreción aguas abajo ($\Delta\text{MNDWI} < -0.35$, $\text{MNDWI}{T_0} > 0.05$) de área comparable (ratio $\in [0.40, 2.50]$) dentro de un radio máximo de $450\text{ m}$.

  • Piso físico de detección: min_anomaly_area_m2 = 1600.0 m² ($\ge 4$ píxeles nativos SWIR de $20\text{ m} \times 20\text{ m}$), con clausura morfológica $3\times 3$ y vectorización OpenCV (RETR_EXTERNAL) en coordenadas métricas POSGAR 2007.


2. Arquitectura del Repositorio

rio-alerta-mcp/
├── pyproject.toml                  # Dependencias, ruff, mypy y configuración pytest
├── Dockerfile                      # Contenedor reproducible con GDAL/rasterio
├── LICENSE                         # Licencia MIT
├── .env.example                    # Variables de entorno (STAC, límites de RAM, CRS)
├── src/
│   ├── config.py                   # Configuración CWD-safe (PROJECT_ROOT) y fajas POSGAR 2007
│   ├── schemas.py                  # Modelos Pydantic v2 (SceneMetadata, ExtractionAnomalyFeature, etc.)
│   ├── server.py                   # Servidor FastMCP con herramientas MCP expuestas
│   └── core/
│       ├── crs_manager.py          # Resolución automática de fajas EPSG:5343–5349 y reproyección
│       ├── optical_providers.py    # Cliente STAC, filtro de cobertura MGRS, ingesta COG 10m/20m y SCL
│       ├── change_detector.py      # Índices ΔMNDWI/ΔBSI/ΔNDVI, segmentación y metadatos de incertidumbre
│       ├── hydrological_control.py # Control de crecidas/bajantes, dipolos de barras y fenología
│       ├── permits_validator.py    # Validación espacial/temporal catastral estricta y unión geométrica
│       ├── vlm_judge.py            # Dictamen auxiliar separado por modalidad (Heurística/VLM/Experto)
│       ├── case_workflow.py        # Fuente SQLite transaccional (WAL+flock) + exportación JSONL encadenada
│       ├── dossier_generator.py    # Generador de Dossiers de Investigación Territorial (9 secciones)
│       ├── report_generator.py     # Emisión atómica reproducible (`generations/<gen_id>/`) Markdown+JSON+Manifest
│       └── parana_pilot_recon.py   # Diagnóstico geodésico/STAC del tramo piloto Paraná Medio
├── scripts/
│   ├── run_exp_001_parana_medio.py # Pipeline reproducible del Experimento 001 (Paraná Medio)
│   ├── run_exp_002_validation.py   # Validación Fase 2.1 (estiaje Paraná Medio + AOI2 Diamante)
│   └── generate_dossier_rio_0184.py# Generación del Dossier técnico auditable RIO-0184 + figuras
├── data/
│   └── experiments/
│       ├── exp_001_parana_medio/   # Informe técnico, JSON resumen, GeoJSONs y 8 láminas PNG
│       ├── exp_001_recalibrated/   # Recalibración Fase 2.1 sobre Paraná Medio
│       └── exp_002_validation/     # Validación cruzada (Paraná Medio estiaje + Diamante)
├── skills/
│   └── rio-alerta/
│       └── SKILL.md                # Skill portable para Antigravity, OpenCode y Claude
└── tests/                          # Suite unitaria e integración (56 tests)

3. Catálogo de Herramientas MCP y Funciones Principales

3.1 Herramientas expuestas por el Servidor FastMCP (src/server.py)

Herramienta MCP

Parámetros Principales

Retorno (Pydantic / Dict)

Descripción Operativa

tool_server_status

(ninguno)

Dict[str, Any]

Verifica estado del servidor, versión, rutas (data/, processed/, reports/), fajas POSGAR 2007, existencia de permits.gpkg y topes de procesamiento.

tool_resolve_posgar_crs

lon: float, lat: float = -32.9

Dict[str, Any]

Resuelve automáticamente la faja oficial POSGAR 2007 (EPSG:5343–5349) para cualquier coordenada de Argentina y proyecta (lon, lat) a (x_posgar_m, y_posgar_m).

tool_search_multitemporal_pair

min_lon: float, min_lat: float, max_lon: float, max_lat: float, t1_end_date: str | None, lookback_years: int = 3

MultitemporalScenePair

Busca en STAC y recorta por HTTP Range Request un par comparable Sentinel-2 L2A (10m VNIR + 20m SWIR/SCL) en POSGAR 2007 listo para detección.

tool_compute_spectral_changes

t0_path: str, t1_path: str, t0_swir_20m_path: str | None, t1_swir_20m_path: str | None

SpectralChangeResult

Calcula GeoTIFFs Float32 de $\Delta\text{MNDWI}$, $\Delta\text{BSI}$ y $\Delta\text{NDVI}$ en POSGAR 2007 respetando 10m/20m nativos y reporta water_stage_delta_pct.

tool_detect_extraction_anomalies

t0_path: str, t1_path: str, min_area_m2: float = 1600.0, min_clearing_area_m2: float = 800.0

ChangeDetectionResult

Ejecuta el motor completo: controles hidrológicos, dipolos de barras, normalización fenológica, segmentación morfológica y emisión de FeatureCollection GeoJSON con UncertaintyMetadata.

tool_evaluate_parana_pilot

offline_mode: bool = True

Dict[str, Any]

Evalúa factibilidad geodésica (EPSG:5347), disponibilidad STAC e institucional del corredor piloto Santa Fe – Paraná.

tool_validate_permits

anomaly_dict: Dict, t1_date: str, permits_gpkg_path: str | None, cadastre_status: str = "NO_DISPONIBLE"

Dict[str, Any]

Cruza el candidato en POSGAR 2007 contra concesiones locales e hidrografía respetando completitud catastral (PermitValidationResult).

tool_evaluate_vlm_verdict

anomaly_dict: Dict, verdict: str | None, certainty_pct: float | None

Dict[str, Any]

Emite o registra un dictamen auxiliar de geomorfología fluvial (VLMFluvialVerdict) y prompt comparado T0 vs T1.

tool_generate_enforcement_report

anomaly_dict: Dict, t0_scene_id, t0_date, t1_scene_id, t1_date, open_case_workflow: bool = True

Dict[str, Any]

Orquesta cruce catastral, dictamen VLM, apertura de caso y emisión de expediente Markdown (9 secciones) + JSON (EnforcementReportResult).

tool_manage_case_workflow

action: "open" | "append_event" | "get" | "list", case_id, action_type, summary

Dict[str, Any]

Administra expedientes territoriales con bitácora JSONL append-only y consulta indexada en SQLite.

3.2 Funciones del Núcleo (src/core/)

  • Geodesia (crs_manager.py): get_posgar_faja(lon), bbox_wgs84_to_posgar(bbox), ensure_metric_crs(...), reproject_array_to_grid(...), reproject_geometry(...).

  • Ingesta Óptica (optical_providers.py): decode_scl_masks(scl), load_native_s2_scene_bundle(...), filter_seasonally_comparable_items(...), query_stac_seasonal_pair_candidates(...), search_and_fetch_stac_multitemporal(...), fetch_xyz_rgb_chip(...).

  • Detección Multitemporal (change_detector.py): compute_spectral_indices(...), compute_multitemporal_baseline_and_changes(...), detect_extraction_anomalies(...).

  • Dinámica Fluvial (hydrological_control.py): compute_reach_hydrological_state(...), detect_natural_bar_migration_dipoles(...), normalize_seasonal_riparian_indices(...), compute_turbidity_confounder_flag(...).

  • Catastro, VLM y Casos (permits_validator.py, vlm_judge.py, case_workflow.py): validate_anomaly_permits(...), build_vlm_fluvial_prompt(...), evaluate_candidate_vlm_verdict(...), CaseWorkflowManager.

  • Dossiers y Expedientes (dossier_generator.py, report_generator.py): generate_candidate_dossier(...), generate_negative_or_area_dossier(...), generate_enforcement_report(...).


4. Validación Empírica: Experimento 001 (Paraná Medio)

El script run_exp_001_parana_medio.py ejecutó el motor de Fase 2 sobre el corredor Santa Fe (Canal de Acceso / Colastiné) – Islas – Bajada Grande / Paraná ((-60.66, -31.74, -60.53, -31.64), 13,817.45 ha, EPSG:5347), comparando 2024-11-06 (estiaje, 0.67 m PNA Paraná) vs 2026-11-08 (crecida, 4.85 m PNA Paraná, +26.29% de área de agua).

  • Informe completo: INFORME_EXPERIMENTO_PARANA_MEDIO.md

  • Resultados clave: se identificaron 4 focos costeros reales sobre ribera firme con reflectancia mineral alta (B11_T1 >= 1573 DN: #218 RIO-0184, #322 RIO-0225, #380 RIO-0199, #389 RIO-0365) y se diagnosticaron con precisión las dos familias de falsos positivos (agua negra/húmica y lagunas isleñas desconectadas) que motivan la calibración científica de Fase 2.1.


5. Instalación y Uso

5.1 Requisitos e Instalación con uv

git clone https://github.com/<tu-usuario>/rio-alerta-mcp.git
cd rio-alerta-mcp

# Crear entorno virtual e instalar dependencias (incluyendo dev)
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[dev]"

5.2 Verificación de Calidad y Tests

.venv/bin/ruff check src tests scripts
.venv/bin/mypy src
.venv/bin/pytest -v

5.3 Ejecución del Servidor FastMCP

# Modo stdio (para Antigravity, Claude Desktop, OpenCode, Cursor)
.venv/bin/python -m src.server

Ejemplo de configuración en clientes MCP (mcp_config.json / claude_desktop_config.json):

{
  "mcpServers": {
    "rio-alerta": {
      "command": "/ruta/absoluta/a/rio-alerta-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/ruta/absoluta/a/rio-alerta-mcp"
    }
  }
}

5.4 Ejecución del Experimento Reproducible

.venv/bin/python scripts/run_exp_001_parana_medio.py

6. Hoja de Ruta

  • Fase 1 (Completada): Scaffolding FastMCP, esquemas Pydantic v2, config.py CWD-safe, fajas POSGAR 2007, Dockerfile y CI.

  • Fase 2 (Completada): Proveedor STAC Sentinel-2 L2A (10m/20m nativos + SCL), motor multitemporal y controles de dinámica fluvial.

  • Fase 2.1 (Completada): Corrección de agua oscura ($\text{BSI}_{\text{reg}}$ + umbrales minerales), zonificación geomorfológica en 4 zonas, hidratación de hidrómetros INA, umbral diferenciado de desmonte ribereño (800 m²) y reconstrucción de huella de píxel completo (4/4 recuperación en Paraná Medio y validación cruzada en Diamante).

  • Fase 3 (Completada): Validación catastral e hidrográfica (permits_validator.py), dictamen auxiliar VLM/morfología (vlm_judge.py), flujo auditable de casos JSONL+SQLite (case_workflow.py), generador de expedientes reproducibles Markdown+JSON (dossier_generator.py, report_generator.py) y 10 herramientas MCP operativas en src/server.py.

  • Fase 3.1 — Auditoría y robustecimiento (Completada): Seguridad semántica catastral (PERMISO_NO_VERIFICABLE_O_INCOMPATIBLE, unión geométrica sin doble conteo y degradación de OFICIAL_COMPLETO sin procedencia), workflow SQLite transaccional (WAL + flock + triggers append-only + cadena SHA-256 + idempotencia + reconstrucción desde JSONL), separación explícita HEURISTIC_SCREENING/EXTERNAL_VLM/HUMAN_EXPERT, publicación atómica de reportes (generations/<gen_id>/{report.md,report.json,manifest.json} + current_generation.json) y confinamiento estricto de rutas MCP sin symlinks ni escritura fuera de raíces autorizadas.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Production-ready satellite imagery analysis server that enables natural language queries for Earth observation data, including land cover classification, vegetation monitoring, water detection, change detection, and automated environmental reporting.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides tools to search, download, and manage satellite imagery from all Copernicus Sentinel missions via the Copernicus Data Space ecosystem. It enables advanced geospatial queries, temporal coverage analysis, and automated data management for Earth observation tasks.
      13
      10
      LGPL 3.0
    • F
      license
      B
      quality
      D
      maintenance
      A Python MCP server for discovering and analyzing Sentinel-2 L2A imagery, enabling AI agents to search scenes, check quality, and compute spectral indices like NDVI, NDWI, and NBR from remote COG windows.
      4
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to autonomously discover, stream, and compute satellite analytics from free government Earth-observation catalogs such as Sentinel-2, Landsat, and Copernicus DEM, with zero API keys or configuration. It supports place-name geocoding, STAC scene search, cloud-native COG streaming for spectral indices, elevation profiles, SAR flood detection, and sandboxed custom geospatial scripts.
      29
      16
      Apache 2.0