# Geo-habilitación: ArcGIS en Ecosistemas Agénticos (Implementación con Claude y MCP)
### *CUE Ecuador 2026 — Quito, 27-28 de Agosto*

[![Esri CUE 2026 Banner Placeholder](https://img.shields.io/badge/Esri_CUE_2026-Quito--Ecuador-blue?style=for-the-badge&logo=arcgis&logoColor=white)](#)

Este repositorio contiene la implementación oficial presentada en la **Conferencia de Usuarios Esri (CUE) Ecuador 2026**. Demuestra cómo el estándar abierto **Model Context Protocol (MCP)** desarrollado por Anthropic puede geo-habilitar modelos de lenguaje fundacionales (LLMs), como Claude 3.5 Sonnet, conectándolos directamente con datos geográficos autorizados de ArcGIS Online y ArcGIS Enterprise de forma segura, determinista y en tiempo real.

---

## 2. Descripción del Proyecto

Uno de los principales desafíos en la Inteligencia Artificial Geográfica (GeoIA) es la desconexión existente entre las capacidades de razonamiento lingüístico de los LLMs y la naturaleza estructurada y espacial de los Sistemas de Información Geográfica (SIG). Tradicionalmente, resolver una pregunta espacial como *"¿qué puntos de minería ilegal se encuentran cerca de esta concesión minera registrada, y cómo se ve eso en un mapa?"* requería que un analista GIS:
1. Conectara con el portal y buscara el Feature Service correspondiente.
2. Escribiera una consulta espacial SQL y construyera filtros geométricos complejos.
3. Abriera un visor web o herramienta de escritorio para ajustar simbología y etiquetado.
4. Generara y exportara el plano en PDF o imagen para presentarlo.

Este agente de IA colapsa dicho ciclo de horas a segundos. Al actuar como un puente semántico mediante el protocolo MCP, permite que Claude interactúe de forma autónoma con los endpoints de la **API REST de ArcGIS Online**, encadenando herramientas de consulta, cruzando geometrías en caliente y solicitando la generación automática de mapas estáticos con simbología real basada en Web Maps. El LLM actúa como el orquestador ejecutivo, abstrayendo la plomería técnica de GIS y entregando reportes listos para la toma de decisiones.

---

## 3. Tech Stack (Arquitectura Tecnológica)

El ecosistema técnico de este agente está compuesto por las siguientes capas:

* **Cliente de IA (Host MCP):** [Claude Desktop](https://claude.ai/download) u orquestadores basados en Python (LangChain/LlamaIndex) encargados de ejecutar el loop de agente con el modelo **Claude 3.5 Sonnet**.
* **Transporte y Protocolo:** Estándar **Model Context Protocol (MCP)** sobre protocolo **STDIO** (entrada/salida estándar para ejecuciones locales) o **HTTP con SSE** (para despliegues distribuidos).
* **Servidor MCP:** Implementación en **Python** utilizando el framework `FastMCP` para la auto-exposición de herramientas.
* **Integración GIS:** [ArcGIS API for Python](https://developers.arcgis.com/python/) (v2.3.0+) para el consumo directo de servicios REST de Esri sin dependencias de ArcPy o software de escritorio.
* **Seguridad y Middleware:** Starlette ASGI Middleware con autenticación basada en `Bearer Token` para proteger transportes de red HTTP.

---

## 4. Guía de Inicio Rápido

Sigue estos pasos para desplegar el servidor localmente y conectarlo con Claude Desktop antes de las demostraciones.

### 4.1 Clonar el Repositorio e Instalar Dependencias

Asegúrate de contar con Python 3.10 o superior instalado.

```bash
# 1. Clonar el repositorio
git clone https://github.com/tu-usuario/arcgis-agentic-mcp.git
cd arcgis-agentic-mcp

# 2. Crear y activar el entorno virtual
python -m venv .venv
source .venv/Scripts/activate  # En Windows usa: .venv\Scripts\activate

# 3. Instalar dependencias requeridas
pip install -r requirements.txt
```

### 4.2 Configuración de Variables de Entorno

Copia la plantilla de configuración e ingresa tus credenciales autorizadas del portal de ArcGIS (Online o Enterprise):

```bash
cp .env.template .env
```

Edita el archivo `.env` resultante:

```env
# URL de tu organización en ArcGIS Online o Portal Enterprise de Esri
AGOL_PORTAL_URL=https://tu-organizacion.maps.arcgis.com

# Credenciales del usuario con privilegios de consulta y edición (si aplica)
AGOL_USERNAME=tu_usuario_arcgis
AGOL_PASSWORD=tu_contrasena_segura

# Opcional: Autenticación alternativa con API Key de ArcGIS Location Platform
# AGOL_API_KEY=tu_arcgis_api_key_aqui

# Habilitar o deshabilitar herramientas de escritura (actualización de atributos)
ENABLE_EDITS=false

# Token secreto para proteger el endpoint HTTP en despliegues distribuidos
SECRET_TOKEN=token_secreto_generado_mcp
```

### 4.3 Configuración en Claude Desktop

Para que Claude Desktop cargue las herramientas de ArcGIS, edita el archivo de configuración global `claude_desktop_config.json`. 

* **Ruta en Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
* **Ruta en macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Agrega el servidor MCP apuntando a la **ruta absoluta** de tu entorno virtual y tu script `server.py`:

```json
{
  "mcpServers": {
    "arcgis-online-mcp": {
      "command": "C:\\Users\\tu-usuario\\AppData\\Local\\Programs\\Python\\Python310\\python.exe",
      "args": [
        "D:\\DATA\\Proyectos Pro\\ArcGIS Online MCP Server Local\\server.py"
      ],
      "env": {
        "// Nota": "Puedes pasar variables directamente aquí o usar el archivo .env del proyecto",
        "AGOL_PORTAL_URL": "https://rn-esri-co.maps.arcgis.com",
        "ENABLE_EDITS": "false"
      }
    }
  }
}
```
*Nota: Reinicia completamente la aplicación de Claude Desktop tras guardar los cambios.*

---

## 5. Arquitectura y Flujo de Datos

### 5.1 Diagrama de Secuencia de Transporte (Mermaid.js)

El flujo de información entre el usuario, el cliente de IA y el portal GIS en Ecuador sigue la especificación estándar del protocolo MCP:

```mermaid
sequenceDiagram
    autonumber
    actor U as Usuario (CUE 2026 Quito)
    participant Host as Claude Desktop (Host LLM)
    participant Client as MCP Client (JSON-RPC)
    participant Server as Servidor MCP (Python FastMCP)
    participant AGOL as ArcGIS Online / REST API

    U->>Host: Solicita análisis en Quito
    Note over Host: El LLM identifica que requiere<br/>habilidades geográficas (Tools)
    Host->>Client: Invoca herramienta espacial
    Client->>Server: JSON-RPC (STDIO pipe o HTTP SSE)
    activate Server
    Server->>AGOL: HTTPS Request (ArcGIS Python API)
    AGOL-->>Server: Datos crudos / Extent (Esri JSON)
    Server->>Server: Enriquecimiento semántico (dpa_geografia.py)
    Server-->>Client: Respuesta JSON-RPC simplificada (Texto + Base64)
    deactivate Server
    Client-->>Host: Contexto mapeado en tokens óptimos
    Note over Host: El LLM asimila los resultados<br/>y genera el entregable visual
    Host-->>U: Mapa temático + Reporte Ejecutivo
```

### 5.2 Esquemas de Herramientas Clave (Tools JSON Schema)

El servidor MCP autogenera y expone esquemas a Claude. A continuación se detallan las dos firmas más representativas:

#### A. `consulta_espacial_por_feature`
Realiza un cruce espacial en caliente utilizando la geometría de un feature existente (ej. una concesión minera o zona de vulnerabilidad) como filtro espacial de proximidad sobre otra capa.

```json
{
  "name": "consulta_espacial_por_feature",
  "description": "Usa la geometría de un feature de origen para buscar features en una capa destino que intersecten o estén en un radio de proximidad.",
  "input_schema": {
    "type": "object",
    "properties": {
      "source_layer_idx": {
        "type": "integer",
        "description": "Índice de la capa origen (ej: 9 para Catastro Minero)"
      },
      "source_where": {
        "type": "string",
        "description": "Cláusula SQL para filtrar el feature origen (ej: nam = 'San Antonio')"
      },
      "target_layer_idx": {
        "type": "integer",
        "description": "Índice de la capa destino a consultar (ej: 6 para Puntos de Conflicto)"
      },
      "distance": {
        "type": "number",
        "description": "Distancia del buffer de proximidad (opcional)"
      },
      "units": {
        "type": "string",
        "enum": ["esriSRUnit_Meter", "esriSRUnit_Kilometer"],
        "description": "Unidades de distancia del buffer"
      }
    },
    "required": ["source_layer_idx", "source_where", "target_layer_idx"]
  }
}
```

#### B. `generar_mapa`
Orquesta el servicio de impresión nativo de Esri (`Export Web Map Task`) para generar un documento PDF o imagen de alta calidad, calculando el encuadre óptimo del mapa a partir de un feature foco.

```json
{
  "name": "generar_mapa",
  "description": "Genera y exporta un documento cartográfico multi-capa a disco, retornando la ruta y la imagen en base64 para previsualización.",
  "input_schema": {
    "type": "object",
    "properties": {
      "tema": {
        "type": "string",
        "enum": ["mineria_legal", "riesgo_ambiental", "conflicto_social", "mineria_ilegal"],
        "description": "Tema que define qué capas pre-configuradas activar automáticamente"
      },
      "focus_layer_idx": {
        "type": "integer",
        "description": "ID de la capa que guiará el encuadre (extent) del mapa"
      },
      "focus_where": {
        "type": "string",
        "description": "Filtro SQL para localizar el feature foco (ej: OBJECTID_1 = 15)"
      },
      "webmap_item_id": {
        "type": "string",
        "description": "ID del Web Map en ArcGIS Online del cual heredar simbología, renderers y etiquetas"
      },
      "basemap": {
        "type": "string",
        "default": "topo-vector",
        "description": "Mapa base a utilizar (satellite, topo-vector, gray, etc.)"
      },
      "format": {
        "type": "string",
        "default": "PNG32",
        "description": "Formato de salida del mapa (PNG32, PDF, JPG)"
      }
    },
    "required": []
  }
}
```

---

## 6. Casos de Uso Prácticos (Demos en Vivo - CUE Ecuador 2026)

Prueba el poder del agente copiando y pegando los siguientes prompts diseñados para el set de datos del catastro de recursos de Ecuador y ejecutados durante la sesión plenaria en el **JW Marriott de Quito**:

| ID | Tipo de Análisis | Prompt de Prueba para Claude Desktop |
| :--- | :--- | :--- |
| **Demo 1** | **Cruce de Proximidad e Impacto** | *"¿Qué puntos de minería no registrada o ilegal se encuentran a menos de 5 km de la concesión minera llamada 'TRAMITE 1'? Haz la consulta espacial y genera un mapa de la zona con fondo satelital heredando la simbología del Web Map oficial."* |
| **Demo 2** | **Análisis de Vulnerabilidad y Conflicto** | *"Revisa si existe algún título minero en fase 'INSCRITA' que intersecte con territorios de comunidades indígenas de la capa 13 en la provincia de Imbabura. Dame el reporte y crea el plano temático correspondiente en PDF."* |
| **Demo 3** | **Estadística y Mapeo Temático** | *"Genera una estadística agregada de las hectáreas concesionadas activas en la provincia de Zamora Chinchipe (usa el campo st_area_sh). Muestra las 3 más grandes y genera un mapa de calor/temático usando el tema 'riesgo_ambiental'."* |

---

## 7. Licencia y Atribución

Este proyecto se distribuye bajo la Licencia MIT.  
Presentado por el equipo de **GeoIA y Soluciones Agénticas de Esri Ecuador** en la Conferencia de Usuarios Esri 2026. Para soporte técnico, abre un *Issue* en este repositorio o contacta a los expositores en el stand de Innovación Geoespacial.