ENC Charts MCP Server

Accede y analiza programáticamente Cartas Electrónicas de Navegación (ENC) de la NOAA en formato S-57.

Documentación

Servidor MCP de Cartas ENC

Un servidor MCP (Protocolo de Contexto de Modelo) para datos de Cartas Electrónicas de Navegación (ENC), que proporciona acceso programático a las cartas electrónicas de navegación de la NOAA con capacidades de análisis de formato S-57.

Descripción General

Este servidor MCP permite a los asistentes de IA acceder y analizar cartas electrónicas de navegación de la NOAA. Descarga, almacena en caché y analiza automáticamente datos de cartas en formato S-57, poniéndolos a disposición a través de una API estandarizada. El servidor admite descubrimiento de cartas basado en coordenadas, extracción de características y consultas centradas en la navegación.

Características

Análisis de Cartas S-57: Soporte completo para cartas electrónicas de navegación en formato S-57 de la OMI
Integración con NOAA: Descubrimiento y descarga automática de cartas desde las API REST de la NOAA
Consultas Basadas en Coordenadas: Encuentra y recupera cartas según coordenadas GPS
Caché Inteligente: Caché local eficiente con límites configurables de tamaño y antigüedad
Filtrado de Características: Extrae características de navegación específicas (luces, boyas, profundidades, etc.)
172 Clases de Objetos: Soporte completo para el catálogo de objetos S-57
Análisis de Profundidad: Filtra características por rangos de profundidad para seguridad en la navegación
Consultas Espaciales: Filtrado por cuadro delimitador para datos específicos de área

Requisitos Previos

Node.js: Versión 18 o superior
Python: Versión 3.7 o superior (para análisis S-57)
Enlaces Python de GDAL: Requeridos para el análisis de datos de cartas

Instalación

Instala el servidor MCP globalmente mediante npm:

npm install -g enc-charts-mcp

Instalación de Dependencias GDAL

El servidor requiere enlaces Python de GDAL para el análisis de cartas S-57:

macOS:

# Using Homebrew
brew install gdal
pip3 install gdal==$(gdal-config --version)

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install gdal-bin libgdal-dev
pip3 install gdal==$(gdal-config --version)

Windows:

# Using conda (recommended)
conda install -c conda-forge gdal

Verificar Instalación

# Check if the server is installed
enc-charts-mcp --version

# Test GDAL availability
python3 -c "from osgeo import ogr; print('GDAL installed successfully')"

Configuración

Variables de Entorno

El servidor admite las siguientes variables de entorno:

Variable	Descripción	Predeterminado
`ENC_CACHE_DIR`	Directorio para la caché de cartas	`./cache/charts/`
`ENC_CACHE_MAX_SIZE_GB`	Tamaño máximo de caché en GB	`10`
`ENC_CACHE_MAX_AGE_DAYS`	Expiración de caché en días	`7`

Integración con Claude Desktop

Agrega lo siguiente a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enc-charts": {
      "command": "npx",
      "args": ["enc-charts-mcp"],
      "transport": {
        "type": "stdio"
      },
      "env": {
        "ENC_CACHE_DIR": "~/.enc-charts/cache",
        "ENC_CACHE_MAX_SIZE_GB": "20",
        "ENC_CACHE_MAX_AGE_DAYS": "14"
      }
    }
  }
}

Nota: Ajusta la ruta del directorio de caché según tus preferencias. El servidor creará automáticamente el directorio si no existe.

Inicio Rápido

Después de la instalación y configuración, reinicia Claude Desktop. Luego puedes usar las herramientas de cartas ENC en tus conversaciones:

Encuentra cartas para una ubicación:

Use the get_chart tool with coordinates: 
lat: 37.8, lon: -122.5 (San Francisco Bay)

Busca cartas en un área:

Use search_charts with a bounding box to find all charts 
between San Diego and Los Angeles

Obtén características de navegación:

Get all lights and buoys from chart US5CA12M

Herramientas Disponibles

get_chart

Recupera características de cartas para un área específica por ID de carta o coordenadas.

Parámetros:

chartId (cadena, opcional): Identificador de carta (ej., "US5CA12M")
coordinates (objeto, opcional): Coordenadas GPS
- lat (número): Latitud (-90 a 90)
- lon (número): Longitud (-180 a 180)
boundingBox (objeto, opcional): Filtro de límites geográficos
- minLat, maxLat, minLon, maxLon (números)
featureTypes (matriz, opcional): Clases de objetos S-57 a incluir
depthRange (objeto, opcional): Filtro de profundidad en metros
- min, max (números)
includeNearby (booleano, opcional): Incluir características cercanas
limit (entero, opcional): Máximo de características a devolver (predeterminado: 100, máximo: 1000)
offset (entero, opcional): Número de características a omitir para paginación (predeterminado: 0)

Solicitud de Ejemplo:

{
  "coordinates": { "lat": 37.8, "lon": -122.5 },
  "featureTypes": ["LIGHTS", "BOYLAT", "DEPARE"],
  "depthRange": { "min": 0, "max": 20 }
}

Respuesta de Ejemplo:

{
  "chartId": "US5CA12M",
  "features": [
    {
      "id": "LIGHTS.123",
      "type": "LIGHTS",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.5295, 37.8156]
      },
      "properties": {
        "COLOUR": ["1"],
        "LITCHR": 8,
        "SIGPER": 4,
        "VALNMR": 18
      }
    }
  ],
  "featureCount": 42,
  "totalFeatures": 150,
  "hasMore": true,
  "limit": 100,
  "offset": 0,
  "source": "NOAA ENC"
}

search_charts

Busca cartas disponibles según varios criterios.

Parámetros:

query (cadena, opcional): Buscar por nombre o área
scale (objeto, opcional): Filtro de rango de escala
- min, max (números)
boundingBox (objeto, opcional): Área de búsqueda geográfica
format (cadena, opcional): Formato de carta ("S-57" o "S-101")
limit (entero, opcional): Máximo de cartas a devolver (predeterminado: 50, máximo: 100)
offset (entero, opcional): Número de cartas a omitir para paginación (predeterminado: 0)

get_chart_metadata

Obtén información detallada sobre una carta específica.

Parámetros:

chartId (cadena, opcional): Identificador de carta
coordinates (objeto, opcional): Coordenadas GPS para encontrar la carta

get_object_classes

Obtén información sobre las clases de objetos S-57 y sus representaciones.

Parámetros:

category (cadena, opcional): Filtrar por categoría
- Opciones: "navAids", "depths", "areas", "infrastructure", "natural", "hazards"
search (cadena, opcional): Buscar por acrónimo o descripción
includeAttributes (booleano, opcional): Incluir atributos estándar

Fuentes de Datos

ENC en Línea de la NOAA

El servidor se integra con los servicios de Cartas Electrónicas de Navegación de la NOAA:

Catálogo de Productos XML: Metadatos de cartas desde https://www.charts.noaa.gov/ENCs/ENCProdCat.xml
Descargas de Cartas: Archivos ZIP individuales en formato S-57 desde https://www.charts.noaa.gov/ENCs/
Frecuencia de Actualización: Semanal para la mayoría de las cartas
Cobertura: Aguas y territorios de EE. UU.
Sin Autenticación Requerida: Todos los recursos de la NOAA son de acceso público

Las cartas se descargan automáticamente bajo demanda cuando se consultan por coordenadas y se almacenan en caché localmente para mejorar el rendimiento. El catálogo XML se almacena en caché durante 24 horas para reducir las llamadas a la API.

Cómo Funciona

Descubrimiento de Cartas: El servidor consulta el catálogo de productos XML de la NOAA para encontrar cartas según coordenadas o criterios de búsqueda
Descarga Automática: Las cartas se descargan bajo demanda desde la NOAA cuando se solicitan
Caché Local: Las cartas descargadas se almacenan en caché localmente para mejorar el rendimiento
Análisis S-57: Los datos de cartas se analizan desde el formato S-57 utilizando enlaces Python de GDAL
Extracción de Características: Las características de navegación (luces, boyas, profundidades, etc.) se extraen y devuelven como GeoJSON

Clases de Objetos S-57

El servidor admite las 172 clases de objetos S-57 estándar. Las categorías clave incluyen:

Ayudas a la Navegación

LIGHTS - Todas las ayudas iluminadas (faros, balizas, boyas iluminadas)
BOYLAT - Boyas laterales (marcadores de babor/estribor)
BOYSAW - Boyas de aguas seguras
BCNLAT - Balizas laterales
DAYMAR - Marcas diurnas

Información de Profundidad

DEPARE - Áreas de profundidad con rangos
DEPCNT - Líneas de contorno de profundidad
SOUNDG - Sondas individuales
DRGARE - Áreas dragadas

Áreas y Límites

FAIRWY - Canales de navegación
ANCHRG - Áreas de fondeo
RESARE - Áreas restringidas
TSSLPT - Esquemas de separación de tráfico

Peligros

OBSTRN - Obstáculos submarinos
WRECKS - Naufragios
ROCKS - Rocas y arrecifes

Consejos de Uso

Consultas Eficientes de Cartas

Usa Filtrado de Características: Especifica featureTypes para reducir el tamaño de la respuesta
Aplica Cuadros Delimitadores: Limita el alcance geográfico cuando sea posible
Aprovecha la Paginación: Usa limit y offset para conjuntos de datos grandes
Precalentamiento de Caché: Las áreas de acceso frecuente se benefician de la descarga previa

Tipos de Características Comunes

Ayudas a la Navegación: LIGHTS, BOYLAT, BOYSAW, BCNLAT
Profundidades: DEPARE, DEPCNT, SOUNDG
Peligros: OBSTRN, WRECKS, ROCKS
Áreas: FAIRWY, ANCHRG, RESARE

Casos de Uso Comunes

1. Planificación de Navegación

Encuentra cartas y extrae ayudas a la navegación para la planificación de rutas:

// Get charts for Golden Gate area
{
  "coordinates": { "lat": 37.8199, "lon": -122.4783 },
  "featureTypes": ["LIGHTS", "BOYLAT", "BOYSAW", "BCNLAT"],
  "includeNearby": true
}

2. Análisis de Fondeo

Encuentra lugares adecuados para fondear con información de profundidad:

// Search for anchorages with specific depth range
{
  "chartId": "US5CA12M",
  "featureTypes": ["DEPARE", "ANCHRG", "SOUNDG"],
  "depthRange": { "min": 5, "max": 15 },
  "boundingBox": {
    "minLat": 37.8,
    "maxLat": 37.82,
    "minLon": -122.52,
    "maxLon": -122.5
  }
}

3. Detección de Peligros

Identifica peligros de navegación en un área:

// Get all hazards near a route
{
  "coordinates": { "lat": 32.7157, "lon": -117.1611 },
  "featureTypes": ["OBSTRN", "WRECKS", "ROCKS", "UWTROC"],
  "includeNearby": true
}

4. Descubrimiento de Cartas

Encuentra todas las cartas disponibles para una región:

// Search charts between San Diego and Los Angeles
{
  "boundingBox": {
    "minLat": 32.5,
    "maxLat": 34.0,
    "minLon": -118.5,
    "maxLon": -117.0
  },
  "scale": { "max": 50000 }  // Detailed charts only
}

Solución de Problemas

Problemas de Instalación de GDAL

"Enlaces Python de GDAL no encontrados"

Asegúrate de que Python 3 esté en tu PATH
Coincide las versiones de GDAL exactamente: pip install gdal==$(gdal-config --version)
En macOS, usa Homebrew: brew install gdal
En Windows, usa conda para una instalación más fácil

"Error al analizar datos de cartas S-57"

Verifica que GDAL esté instalado correctamente: python3 -c "from osgeo import ogr"
Comprueba que Python 3 esté en tu PATH (el servidor usa específicamente python3)
Algunas cartas pueden requerir versiones más recientes de GDAL
Ejecuta npm run gdal:validate para verificar tu instalación

Problemas con Claude Desktop

El servidor no aparece en Claude

Asegúrate de que el paquete esté instalado: npm list -g enc-charts-mcp
Verifica que la ruta de tu archivo de configuración sea correcta
Reinicia Claude Desktop después de los cambios de configuración
Verifica que el comando npx funcione: npx enc-charts-mcp --version

"No se encontraron cartas para las coordenadas"

Verifica que las coordenadas estén en aguas de EE. UU. (área de cobertura de la NOAA)
Comprueba la conexión a internet para el acceso a la API de la NOAA
Prueba con diferentes coordenadas o usa un ID de carta conocido

Problemas de Caché

Limpiar la caché

# Default cache location
rm -rf ~/.enc-charts/cache/*

# Or your custom cache directory
rm -rf $ENC_CACHE_DIR/*

Problemas de espacio en disco

Ajusta ENC_CACHE_MAX_SIZE_GB en tu configuración
Las cartas pueden tener entre 10 y 100 MB cada una
Considera almacenar la caché en una unidad con más espacio

Desarrollo

Ejecución Local

# Clone the repository
git clone https://github.com/tonybentley/enc-charts-mcp.git
cd enc-charts-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (with hot reload)
npm run dev

# Run production build
npm start

Comandos de Desarrollo

npm run dev - Ejecutar en modo de desarrollo con recarga automática
npm run build - Compilar TypeScript a JavaScript
npm run test - Ejecutar pruebas unitarias
npm run test:e2e - Ejecutar pruebas de extremo a extremo
npm run test:all - Ejecutar todas las suites de pruebas
npm run lint - Ejecutar ESLint
npm run typecheck - Ejecutar verificación de tipos de TypeScript
npm run format - Formatear código con Prettier

Validación de GDAL

npm run gdal:detect - Verificar si GDAL está instalado correctamente
npm run gdal:validate - Validar la instalación y el entorno de GDAL
npm run test:integration:check - Verificar GDAL antes de ejecutar pruebas de integración

Consideraciones de Rendimiento

Las cartas pueden tener entre 10 y 100 MB cada una
Las descargas iniciales pueden llevar tiempo
Se recomienda el precalentamiento de caché para áreas de acceso frecuente
Las consultas espaciales están optimizadas para cuadros delimitadores

Paginación

Para evitar problemas de tamaño de respuesta, las herramientas get_chart y search_charts implementan paginación:

get_chart: Devuelve hasta 100 características por defecto (máximo: 1000)
search_charts: Devuelve hasta 50 cartas por defecto (máximo: 100)

Usa los parámetros limit y offset para paginar a través de conjuntos de resultados grandes:

// First page
{ "chartId": "US5CA12M", "limit": 100, "offset": 0 }

// Next page
{ "chartId": "US5CA12M", "limit": 100, "offset": 100 }

La respuesta incluye metadatos de paginación:

totalFeatures o totalCount: Número total de elementos disponibles
hasMore: Booleano que indica si existen más resultados
limit: Número de elementos devueltos
offset: Número de elementos omitidos

Licencia

ISC

Código Fuente

El código fuente está disponible en GitHub.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía una solicitud de extracción en GitHub.

Agradecimientos

NOAA por proporcionar cartas electrónicas de navegación gratuitas
OMI por la especificación estándar S-57
Contribuyentes de GDAL por el soporte del formato S-57