geolens-mcp

geolens-mcp

Servidor de Model Context Protocol de solo lectura bajo Apache-2.0 para GeoLens.

Apunte un agente de codificación (Claude Code, Cursor, Codex, …) a una instancia de GeoLens para que pueda descubrir conjuntos de datos, inspeccionar esquemas, leer entidades y mapas, y ejecutar SQL de solo lectura desde una sesión de desarrollo.

Solo lectura por diseño. Sin escrituras, ingesta ni administración. Las herramientas de descubrimiento son GETs contra endpoints de API existentes; query es un POST mecánicamente, pero se ejecuta dentro del sandbox de SQL de SOLO LECTURA del servidor, por lo que no puede modificar nada. Las llamadas están limitadas al acceso del solicitante: con una clave de API, el agente ve los conjuntos de datos que el usuario de esa clave puede ver; sin credenciales, solo ve datos públicos/publicados (query además requiere una credencial cuyo usuario tenga el permiso de chat de IA — las claves de API read_only funcionan, mediante una excepción específica de ruta en el servidor).

Instalación

pip install geolens-mcp        # or: uvx geolens-mcp

Configuración

El servidor lee su instancia objetivo y credenciales del entorno (mismos nombres que la CLI de geolens):

Variable	Obligatoria	Significado
GEOLENS_INSTANCE	sí	URL de la instancia, p. ej. https://geolens.example.com. El sufijo /api se añade automáticamente si lo omite.
GEOLENS_API_KEY	recomendada	Clave de API, enviada como X-Api-Key. Cree una en Configuración → Claves de API. Omita para acceso solo público.
GEOLENS_TOKEN	—	Token portador JWT, usado solo si GEOLENS_API_KEY no está definido.

Registro con un cliente MCP

Claude Code:

claude mcp add geolens -e GEOLENS_INSTANCE=https://geolens.example.com -e GEOLENS_API_KEY=... -- uvx geolens-mcp

Cursor / Codex / cualquier cliente que lea un bloque mcpServers:

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": ["geolens-mcp"],
      "env": {
        "GEOLENS_INSTANCE": "https://geolens.example.com",
        "GEOLENS_API_KEY": "your-api-key"
      }
    }
  }
}

Herramientas

Herramienta	Qué hace
search_datasets	Búsqueda en catálogo por texto libre (clasificación semántica cuando la instancia lo permite). Devuelve registros de conjuntos de datos como entidades GeoJSON con estado de origen y frescura seguro; las claves de salud/verificación/actualización son nulas cuando no están disponibles en el resumen de búsqueda.
get_dataset_schema	Columnas de un conjunto de datos, tipo de geometría, CRS/SRID, recuento de entidades, extensión y metadatos de confianza de la fuente.
get_features	Entidades GeoJSON acotadas para un conjunto de datos (OGC API — Features), con bbox opcional.
list_maps	Mapas guardados (id, nombre, visibilidad, número de capas).
get_map	Metadatos completos de un mapa guardado, incluidas capas y estado de vista.
query	Un SQL de solo lectura SELECT a través del sandbox reforzado del servidor (#565): una sola sentencia sobre tablas data.*, funciones en lista blanca, un ámbito restrict_tables obligatorio y un presupuesto estricto en el servidor (tiempo de espera de sentencia, límite de auto-unión, límite de filas, límites de tasa). Requiere una credencial cuyo usuario tenga el permiso de chat de IA; requiere GeoLens ≥ la versión que incluye POST /api/query/.

Desarrollo

cd mcp
uv run --extra dev python -m pytest -v