Valhalla MCP Server

Um servidor para o Valhalla routing engine, oferecendo serviços de routing, isochrone, health e tile.

Documentação

Valhalla MCP Server

Um servidor Model Context Protocol (MCP) que fornece integração perfeita entre o Claude Desktop e o mecanismo de roteamento Valhalla Open-Street-Map. Acesse recursos profissionais de roteamento e isócronas diretamente de suas conversas de IA sem APIs complexas.

Exemplo de Uso

Claude Desktop Integration

Claude Desktop mostrando um cálculo de rota entre dois pontos com resposta GeoJSON detalhada do Valhalla MCP Server

Recursos

Serviços Valhalla Atualmente Suportados

Ferramenta/Recurso MCP	Serviço Valhalla	Descrição
`route` tool	`/route`	Roteamento de origem única → destino com alternativas
`isochrone` tool	`/isochrone`	Polígonos de tempo de viagem mostrando áreas alcançáveis
`health` resource	`/status`	Informações de status e versão do servidor
`tile` resource	`/tile/{z}/{x}/{y}`	Tiles vetoriais para renderização no lado do cliente

Serviços Valhalla - Em Breve

Serviço	Descrição	Casos de Uso
Matrix	Matrizes de distância/tempo para múltiplas origens/destinos	Otimização de entregas, planejamento logístico
Map-matching	Corresponder coordenadas GPS à rede viária	Limpeza de rastros GPS, correção de rotas
Elevation	Perfis de elevação ao longo de rotas ou em pontos	Trilhas de caminhada, análise de dificuldade
Expansion	Visualização de travessia de grafo	Análise de rede, estudos de acessibilidade
Locate	Metadados detalhados sobre nós e arestas	Geocodificação de endereços, atributos de estradas
Centroid	Ponto de convergência ótimo a partir de múltiplas localizações	Otimização de pontos de encontro
Optimized Route	Roteamento de entrega com múltiplas paradas e restrições	Logística, serviços de entrega

Modos de Transporte

auto - Roteamento de carro
bicycle - Roteamento de bicicleta
pedestrian - Rotas a pé
taxi - Roteamento de táxi
bus - Roteamento de transporte público

Início Rápido

Pré-requisitos

Node.js 18+
Claude Desktop
NPM ou gerenciador de pacotes Yarn

Opção 1: Servidor Valhalla Local

Para uso em produção ou conjuntos de dados personalizados:

# Prerequisites: Docker and Docker Compose
./start-mcp.sh

Este script irá:

Compilar o servidor MCP
Iniciar o Valhalla local com dados OSM de Mônaco
Aguardar os serviços ficarem prontos
Executar testes de integração
Fornecer configuração do Claude Desktop

Opção 2: Usar Seu Servidor Valhalla Existente

Se você já tem um servidor Valhalla em execução em outro lugar:

# Clone and setup
git clone <repository-url>
cd valhalla-mcp
npm install
npm run build

# Configure environment variables
cp env.example .env
# Edit .env file and set VALHALLA_BASE_URL=http://your-valhalla-server:8002

Integração com Claude Desktop

Abra as configurações do Claude Desktop
Adicione à sua configuração MCP:

Para API de Demonstração (recomendado para testes):

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

Para Servidor Valhalla Local:

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "http://localhost:8002"
      }
    }
  }
}

Atualize o caminho cwd para a localização real do seu projeto
Reinicie o Claude Desktop

Teste Sua Instalação

Experimente estes comandos no Claude Desktop para verificar se tudo funciona:

Roteamento básico:

"Calcular rota de Monaco-Ville para Monte Carlo"
"Obter instruções de direção de 43.7384,7.4246 para 43.7396,7.4263"
"Calcular rota de bicicleta de 43.7350,7.4200 para 43.7450,7.4300"

Análise de tempo de viagem:

"Mostrar isócrona de 10 minutos de carro a partir do centro de Mônaco"
"Gerar polígono de viagem de 15 minutos de bicicleta a partir de 43.7311,7.4197"

Você deve receber respostas GeoJSON detalhadas com geometrias de rota e estatísticas de viagem!

Modo de Desenvolvimento

Para desenvolvimento com recarga automática:

npm run dev

Configuração

Variáveis de Ambiente

O servidor usa variáveis de ambiente para configuração. Crie um arquivo .env a partir do modelo:

cp env.example .env

Variáveis de ambiente disponíveis:

VALHALLA_BASE_URL - URL base para o serviço Valhalla (padrão: http://localhost:8002)
DEBUG - Ativar registro de depuração (padrão: falso)
LOG_LEVEL - Nível de registro: erro, aviso, info, depuração (padrão: info)
MCP_SERVER_NAME - Nome do servidor MCP (padrão: valhalla-mcp-server)
MCP_SERVER_VERSION - Versão do servidor MCP (padrão: 0.1.0)

Endpoints comuns do Valhalla:

http://localhost:8002 - Instância Docker local (recomendado)
https://valhalla1.openstreetmap.de - API de demonstração pública (✅ testada e funcionando)
https://your-server.com:8002 - Implantação personalizada

Nota: A URL de demonstração principal https://valhalla.openstreetmap.de serve uma interface web. Use https://valhalla1.openstreetmap.de para acesso à API.

Implantação com Docker

A pilha completa pode ser implantada usando Docker Compose:

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f valhalla-mcp

# Stop services
docker-compose down

Exemplos de Uso

Cálculo de Rota

Solicite uma rota entre dois pontos:

{
  "tool": "route",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "destination": { "lat": 52.5170, "lon": 13.3888 },
    "mode": "bicycle",
    "alternatives": 2,
    "units": "kilometers"
  }
}

A resposta inclui LineString GeoJSON com geometria de rota e estatísticas resumidas:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[13.4050, 52.5200], [13.3888, 52.5170]]
    },
    "properties": {
      "distance_km": 2.1,
      "duration_seconds": 420,
      "duration_minutes": 7,
      "mode": "bicycle"
    }
  }]
}

Geração de Isócronas

Gere um polígono de tempo de viagem de 15 minutos:

{
  "tool": "isochrone",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "minutes": 15,
    "mode": "pedestrian"
  }
}

Verificação de Saúde

Acesse informações de saúde do servidor:

{
  "resource": "health://status"
}

Integração com Clientes MCP

Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "valhalla": {
      "command": "node",
      "args": ["/path/to/valhalla-mcp/dist/index.js"],
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

Nota: Variáveis de ambiente na configuração do Claude Desktop substituem os valores do arquivo .env.

Outros Clientes MCP

O servidor implementa o protocolo MCP padrão e funciona com qualquer cliente compatível. Use o transporte stdio para integração local.

Arquitetura

┌─────────────────┐     MCP Protocol     ┌─────────────────┐
│   MCP Client    │ ◄─────────────────► │ Valhalla MCP    │
│ (Claude, etc.)  │    (stdio/HTTP)      │     Server      │
└─────────────────┘                      └─────────┬───────┘
                                                   │ HTTP REST
                                         ┌─────────▼───────┐
                                         │   Valhalla      │
                                         │  Routing Engine │
                                         └─────────────────┘

Desenvolvimento

Instalação

# Install dependencies
npm install

# Build the project
npm run build

Dependências principais:

@modelcontextprotocol/sdk - SDK MCP oficial
axios - Cliente HTTP para chamadas à API Valhalla
zod - Validação de tipos em tempo de execução
geojson - Definições de tipos GeoJSON
dotenv - Gerenciamento de variáveis de ambiente

Testes

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

Verificação de Tipos

O projeto usa configuração estrita de TypeScript:

# Type check
npx tsc --noEmit

Desempenho

Cálculo de rota: < 200ms (instância Valhalla local)
Geração de isócronas: < 300ms
Serviço de tiles: < 30ms
Verificação de saúde: < 5ms

O desempenho depende da configuração do Valhalla e dos dados OSM disponíveis.

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações
Adicione testes
Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Para problemas e perguntas:

Abra um problema no GitHub
Consulte a documentação do MCP
Revise a documentação do Valhalla