ENC Charts MCP Server

Acesse e analise programaticamente Cartas Náuticas Eletrônicas (ENC) da NOAA no formato S-57.

Documentação

Servidor MCP de Cartas ENC

Um servidor MCP (Model Context Protocol) para dados de Cartas Eletrônicas de Navegação (ENC), fornecendo acesso programático às cartas eletrônicas de navegação da NOAA com capacidade de análise do formato S-57.

Visão Geral

Este servidor MCP permite que assistentes de IA acessem e analisem cartas eletrônicas de navegação da NOAA. Ele baixa, armazena em cache e analisa automaticamente dados de cartas no formato S-57, disponibilizando-os por meio de uma API padronizada. O servidor suporta descoberta de cartas baseada em coordenadas, extração de feições e consultas focadas em navegação.

Recursos

Análise de Cartas S-57: Suporte completo para cartas eletrônicas de navegação no formato IHO S-57
Integração com a NOAA: Descoberta e download automático de cartas por meio das APIs REST da NOAA
Consultas Baseadas em Coordenadas: Encontre e recupere cartas com base em coordenadas GPS
Cache Inteligente: Cache local eficiente com limites configuráveis de tamanho e idade
Filtragem de Feições: Extraia feições específicas de navegação (faróis, bóias, profundidades, etc.)
172 Classes de Objetos: Suporte completo ao catálogo de objetos S-57
Análise de Profundidade: Filtre feições por faixas de profundidade para segurança na navegação
Consultas Espaciais: Filtragem por caixa delimitadora para dados específicos de uma área

Pré-requisitos

Node.js: Versão 18 ou superior
Python: Versão 3.7 ou superior (para análise S-57)
GDAL Python Bindings: Necessário para análise de dados de cartas

Instalação

Instale o servidor MCP globalmente via npm:

npm install -g enc-charts-mcp

Instalando Dependências GDAL

O servidor requer os bindings Python do GDAL para análise 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 Instalação

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

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

Configuração

Variáveis de Ambiente

O servidor suporta as seguintes variáveis de ambiente:

Variável	Descrição	Padrão
`ENC_CACHE_DIR`	Diretório para cache de cartas	`./cache/charts/`
`ENC_CACHE_MAX_SIZE_GB`	Tamanho máximo do cache em GB	`10`
`ENC_CACHE_MAX_AGE_DAYS`	Expiração do cache em dias	`7`

Integração com Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do 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: Ajuste o caminho do diretório de cache de acordo com suas preferências. O servidor criará o diretório automaticamente se ele não existir.

Início Rápido

Após a instalação e configuração, reinicie o Claude Desktop. Você pode então usar as ferramentas de cartas ENC em suas conversas:

Encontre cartas para um local:

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

Pesquise cartas em uma área:

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

Obtenha feições de navegação:

Get all lights and buoys from chart US5CA12M

Ferramentas Disponíveis

get_chart

Recupere feições de cartas para uma área específica por ID da carta ou coordenadas.

Parâmetros:

chartId (string, opcional): Identificador da carta (ex.: "US5CA12M")
coordinates (objeto, opcional): Coordenadas GPS
- lat (número): Latitude (-90 a 90)
- lon (número): Longitude (-180 a 180)
boundingBox (objeto, opcional): Filtro de limites geográficos
- minLat, maxLat, minLon, maxLon (números)
featureTypes (array, opcional): Classes de objetos S-57 a incluir
depthRange (objeto, opcional): Filtro de profundidade em metros
- min, max (números)
includeNearby (booleano, opcional): Incluir feições próximas
limit (inteiro, opcional): Número máximo de feições a retornar (padrão: 100, máximo: 1000)
offset (inteiro, opcional): Número de feições a pular para paginação (padrão: 0)

Exemplo de Solicitação:

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

Exemplo de Resposta:

{
  "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

Pesquise cartas disponíveis por vários critérios.

Parâmetros:

query (string, opcional): Pesquise por nome ou área
scale (objeto, opcional): Filtro de faixa de escala
- min, max (números)
boundingBox (objeto, opcional): Área de pesquisa geográfica
format (string, opcional): Formato da carta ("S-57" ou "S-101")
limit (inteiro, opcional): Número máximo de cartas a retornar (padrão: 50, máximo: 100)
offset (inteiro, opcional): Número de cartas a pular para paginação (padrão: 0)

get_chart_metadata

Obtenha informações detalhadas sobre uma carta específica.

Parâmetros:

chartId (string, opcional): Identificador da carta
coordinates (objeto, opcional): Coordenadas GPS para encontrar a carta

get_object_classes

Obtenha informações sobre classes de objetos S-57 e suas representações.

Parâmetros:

category (string, opcional): Filtrar por categoria
- Opções: "navAids", "depths", "areas", "infrastructure", "natural", "hazards"
search (string, opcional): Pesquisar por acrônimo ou descrição
includeAttributes (booleano, opcional): Incluir atributos padrão

Fontes de Dados

NOAA ENC Online

O servidor integra-se aos serviços de Cartas Eletrônicas de Navegação da NOAA:

Catálogo de Produtos XML: Metadados de cartas de https://www.charts.noaa.gov/ENCs/ENCProdCat.xml
Downloads de Cartas: Arquivos ZIP individuais no formato S-57 de https://www.charts.noaa.gov/ENCs/
Frequência de Atualização: Semanal para a maioria das cartas
Cobertura: Águas e territórios dos EUA
Sem Autenticação Necessária: Todos os recursos da NOAA são publicamente acessíveis

As cartas são baixadas automaticamente sob demanda quando consultadas por coordenadas e armazenadas em cache localmente para desempenho. O catálogo XML é armazenado em cache por 24 horas para reduzir chamadas de API.

Como Funciona

Descoberta de Cartas: O servidor consulta o catálogo de produtos XML da NOAA para encontrar cartas com base em coordenadas ou critérios de pesquisa
Download Automático: As cartas são baixadas sob demanda da NOAA quando solicitadas
Cache Local: As cartas baixadas são armazenadas em cache localmente para melhorar o desempenho
Análise S-57: Os dados das cartas são analisados do formato S-57 usando os bindings Python do GDAL
Extração de Feições: As feições de navegação (faróis, bóias, profundidades, etc.) são extraídas e retornadas como GeoJSON

Classes de Objetos S-57

O servidor suporta todas as 172 classes de objetos S-57 padrão. As principais categorias incluem:

Auxílios à Navegação

LIGHTS - Todos os auxílios iluminados (faróis, balizas, bóias iluminadas)
BOYLAT - Bóias laterais (marcadores de bombordo/estibordo)
BOYSAW - Bóias de águas seguras
BCNLAT - Balizas laterais
DAYMAR - Marcas diurnas

Informações de Profundidade

DEPARE - Áreas de profundidade com faixas
DEPCNT - Linhas de contorno de profundidade
SOUNDG - Sondagens individuais
DRGARE - Áreas dragadas

Áreas e Limites

FAIRWY - Canais de navegação
ANCHRG - Áreas de fundeio
RESARE - Áreas restritas
TSSLPT - Esquemas de separação de tráfego

Perigos

OBSTRN - Obstáculos submersos
WRECKS - Naufrágios
ROCKS - Rochas e recifes

Dicas de Uso

Consultas Eficientes de Cartas

Use Filtragem de Feições: Especifique featureTypes para reduzir o tamanho da resposta
Aplique Caixas Delimitadoras: Limite o escopo geográfico quando possível
Aproveite a Paginação: Use limit e offset para grandes conjuntos de dados
Aquecimento de Cache: Áreas acessadas com frequência se beneficiam do pré-download

Tipos Comuns de Feições

Auxílios à Navegação: LIGHTS, BOYLAT, BOYSAW, BCNLAT
Profundidades: DEPARE, DEPCNT, SOUNDG
Perigos: OBSTRN, WRECKS, ROCKS
Áreas: FAIRWY, ANCHRG, RESARE

Casos de Uso Comuns

1. Planejamento de Navegação

Encontre cartas e extraia auxílios à navegação para planejamento de rotas:

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

2. Análise de Fundeio

Encontre locais adequados para ancoragem com informações de profundidade:

// 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. Detecção de Perigos

Identifique perigos de navegação em uma área:

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

4. Descoberta de Cartas

Encontre todas as cartas disponíveis para uma região:

// 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
}

Solução de Problemas

Problemas de Instalação do GDAL

"GDAL Python bindings não encontrados"

Certifique-se de que o Python 3 está no seu PATH
Corresponda exatamente as versões do GDAL: pip install gdal==$(gdal-config --version)
No macOS, use Homebrew: brew install gdal
No Windows, use conda para instalação mais fácil

"Falha ao analisar dados de carta S-57"

Verifique se o GDAL está instalado corretamente: python3 -c "from osgeo import ogr"
Verifique se o Python 3 está no seu PATH (o servidor usa especificamente python3)
Algumas cartas podem exigir versões mais recentes do GDAL
Execute npm run gdal:validate para verificar sua instalação

Problemas com Claude Desktop

Servidor não aparecendo no Claude

Certifique-se de que o pacote está instalado: npm list -g enc-charts-mcp
Verifique se o caminho do arquivo de configuração está correto
Reinicie o Claude Desktop após alterações de configuração
Verifique se o comando npx funciona: npx enc-charts-mcp --version

"Nenhuma carta encontrada para as coordenadas"

Verifique se as coordenadas estão em águas dos EUA (área de cobertura da NOAA)
Verifique a conexão com a internet para acesso à API da NOAA
Tente coordenadas diferentes ou use um ID de carta conhecido

Problemas de Cache

Limpando o cache

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

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

Problemas de espaço em disco

Ajuste ENC_CACHE_MAX_SIZE_GB na sua configuração
As cartas podem ter de 10 a 100 MB cada
Considere armazenar o cache em uma unidade com mais espaço

Desenvolvimento

Executando Localmente

# 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 Desenvolvimento

npm run dev - Executar em modo de desenvolvimento com recarga automática
npm run build - Compilar TypeScript para JavaScript
npm run test - Executar testes unitários
npm run test:e2e - Executar testes de ponta a ponta
npm run test:all - Executar todas as suítes de testes
npm run lint - Executar ESLint
npm run typecheck - Executar verificação de tipos TypeScript
npm run format - Formatar código com Prettier

Validação GDAL

npm run gdal:detect - Verificar se o GDAL está instalado corretamente
npm run gdal:validate - Validar instalação e ambiente do GDAL
npm run test:integration:check - Verificar GDAL antes de executar testes de integração

Considerações de Desempenho

As cartas podem ter de 10 a 100 MB cada
Os downloads iniciais podem levar tempo
O aquecimento de cache é recomendado para áreas acessadas com frequência
Consultas espaciais otimizadas para caixas delimitadoras

Paginação

Para evitar problemas de tamanho de resposta, as ferramentas get_chart e search_charts implementam paginação:

get_chart: Retorna até 100 feições por padrão (máximo: 1000)
search_charts: Retorna até 50 cartas por padrão (máximo: 100)

Use os parâmetros limit e offset para paginar grandes conjuntos de resultados:

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

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

A resposta inclui metadados de paginação:

totalFeatures ou totalCount: Número total de itens disponíveis
hasMore: Booleano indicando se existem mais resultados
limit: Número de itens retornados
offset: Número de itens pulados

Licença

ISC

Código Fonte

O código fonte está disponível no GitHub.

Contribuições

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request no GitHub.

Agradecimentos

NOAA por fornecer cartas eletrônicas de navegação gratuitas
IHO pela especificação padrão S-57
Contribuidores do GDAL pelo suporte ao formato S-57