# GeoAnalisis MCP

Servidor MCP para lectura, análisis y cartografía de datos espaciales vectoriales, integrado con Claude Desktop. De una instrucción en lenguaje natural a un mapa profesional, sin abrir un SIG de escritorio.

![Cómo funciona GeoAnalisis MCP](docs/geoanalisis_diagrama.png)

## Herramientas

| Tool | Descripción |
|------|-------------|
| `list_layers` | Lista las capas de un archivo espacial (nombre + tipo de geometría), enumeración liviana de catálogo — no abre cada capa |
| `get_layer_schema` | Esquema completo de UNA capa puntual: campos, tipos, bbox, CRS, feature count |
| `scan_field_stats` | Estadísticas descriptivas por campo (numéricos y categóricos) |
| `read_features` | Lee features como GeoJSON FeatureCollection con filtros WHERE y bbox; `geometry` controla el detalle (`full`/`simplified`/`centroid`/`bbox`/`none`) para no agotar la salida con polígonos complejos |
| `preview_geometries` | Vista previa de geometrías en WKT |
| `view_layer` | Vista rápida de UNA capa: imagen inline (garantizada en todo cliente MCP) + mapa HTML interactivo (solo en clientes que renderizan recursos HTML) |
| `render_map` | Mapa dinámico Leaflet (pan/zoom, clic para atributos, multicapa con toggle, basemap, leyenda, escala) + HTML de alta fidelidad en disco |
| `export_map_image` | Imagen del mapa (JPG/PNG/PDF/SVG) con basemap, simbología, leyenda, escala, norte y etiquetado |
| `export_map_cartographic` | Plancha cartográfica formal: título, panel lateral con leyenda e índice de localización, escala gráfica, norte y grilla de coordenadas |

**Capacidades transversales** (compartidas por las herramientas de mapas; `view_layer` es deliberadamente simple y no incluye `extra_layers` ni `basemap`):

- **Multicapa** — `extra_layers` superpone capas adicionales con color, estilo de línea, transparencia y etiqueta propios por capa. Cada capa extra acepta además `where` (filtro por atributo) y, en los exports, `color_by`/`style` para categorizarla por campo sin dividir el archivo — la leyenda muestra cada clase prefijada con el nombre de la capa.
- **Simbología** — `color_by` para categorías rápidas, o `style` avanzado `categorized` / `graduated` (rampas de color y cortes de clase).
- **Basemap personalizado** — `basemap` acepta la raíz de un ArcGIS MapServer tileado o una plantilla XYZ `{z}/{x}/{y}`; default Esri World Light Gray Canvas (CartoDB Positron, el default anterior, hornea la marca "API KEY REQUIRED" en los tiles desde 2026).
- **Filtros** — `where` (SQL OGR) y `bbox`; con `where` la extensión del mapa se ajusta a las features filtradas.
- **CRS** — reproyección automática a WGS84; `source_crs` / `crs` para archivos que no declaran sistema de referencia.
- **Etiquetado** — `label_by` etiqueta features por campo con colocación inteligente. En `export_map_image` y `export_map_cartographic` es multicapa: cada entrada de `extra_layers` acepta su propio `label_by`, con detección de colisiones compartida (las etiquetas de la capa principal tienen prioridad). El ancla se calcula sobre la parte visible de la geometría (con `where`/zoom, un polígono recortado se etiqueta dentro de la vista). El reporte de salida siempre indica cuántas etiquetas se renderizaron y cuántas se omitieron (solapamiento, tamaño mínimo, fuera de vista); `label_collision="none"` desactiva los filtros y renderiza todas las visibles.

**Formatos soportados:** FileGDB (`.gdb`), Shapefile (`.shp`), GeoJSON, GeoPackage (`.gpkg`), KML y cualquier formato vectorial compatible con GDAL/OGR.

## Instalación en Claude Desktop (recomendada)

Requiere [uv](https://docs.astral.sh/uv/) instalado.

1. Descarga `geoanalisis-mcp-X.Y.Z.mcpb` desde [Releases](https://github.com/alexrobl/geoanalisis-mcp/releases)
2. Ábrelo con Claude Desktop (doble clic o *Configuración → Extensiones → Instalar extensión*)
3. Listo — las dependencias se resuelven automáticamente con uv al primer arranque

Para generar el bundle desde el código fuente:

```bash
npx @anthropic-ai/mcpb pack . geoanalisis-mcp.mcpb
```

## Instalación manual (desarrollo)

Requiere Python ≥ 3.11 y [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/alexrobl/geoanalisis-mcp
cd geoanalisis-mcp
uv sync
```

Agrega esto a tu `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "geoanalisis": {
      "command": "/ruta/al/repo/.venv/bin/geoanalisis-mcp"
    }
  }
}
```

## ¿Qué herramienta de visualización usa Claude?

| Petición del usuario | Herramienta |
|----------------------|-------------|
| "Muéstrame la capa", "mapa básico", vista rápida | `view_layer` |
| Mapa dinámico/interactivo, varias capas, basemap, HTML como archivo | `render_map` |
| Imagen estática (PNG/JPG/PDF/SVG) | `export_map_image` |
| Plancha o producto cartográfico formal | `export_map_cartographic` |

## view_layer

Vista rápida de una sola capa. Devuelve dos representaciones, sin detectar el cliente:

- **Imagen inline (JPEG)** — sin basemap/escala/norte, con auto-encuadre y leyenda. Es la garantía real de visibilidad: se muestra en cualquier cliente MCP, incluyendo Claude Desktop/Cowork.
- **Mapa HTML interactivo** — Leaflet vectorial con grilla de coordenadas, pan/zoom, popups de atributos y escala. Solo se ve inline en clientes que renderizan recursos `text/html` como iframe (claude.ai). En clientes que no lo hacen (Cowork/Claude Desktop) llega como texto/JSON crudo — se puede ignorar, **no** indica un problema con los datos.

No escribe archivos a disco.

## render_map

Genera un mapa dinámico HTML con Leaflet directamente en Claude, con doble salida:

- **Inline en el chat** — pan, zoom, clic en un feature para ver sus atributos, control de capas con toggle, leyenda, barra de escala y coordenadas del cursor. Dentro del sandbox de Claude los tiles externos están bloqueados: si en ~1.5 s no carga ningún tile se dibuja automáticamente una grilla de coordenadas como fondo de respaldo.
- **Alta fidelidad en disco** — guarda además un HTML (`{capa}_dynamic.html`) donde el basemap sí carga al abrirlo en el navegador.

Los datos se embeben server-side (con muestreo uniforme si se supera `limit`), sin gastar contexto de la conversación.

## export_map_image y export_map_cartographic

Generan la imagen server-side con matplotlib + contextily: se muestra inline en el chat (72 DPI) y se guarda en disco en alta resolución (`dpi` configurable; con `dpi > 150` los tiles del basemap se piden a mayor zoom para conservar la nitidez). Ambas devuelven además un reporte textual de la simbología realmente aplicada a cada capa.

- `export_map_image` — vista rápida para revisión: leyenda, escala, norte y créditos opcionales. Salida `.png`, `.jpg`, `.pdf` (vectorial) o `.svg`.
- `export_map_cartographic` — producto formal de entrega: título institucional, panel lateral con leyenda, convenciones e índice de localización, y franja inferior con norte, escala gráfica y fuente. Recomendado `.jpg` para trabajo y `.pdf` para entrega.