Magic Lane MCP Server

Servidor MCP Magic Lane

Introdução

O Servidor Magic Lane Model Context Protocol (MCP) permite que qualquer agente ou aplicação de IA se torne um assistente geoespacialmente inteligente, capaz de atuar como um companheiro confiável para pedestres, ciclistas e motoristas.

Construído sobre a avançada tecnologia de mapeamento e roteamento da Magic Lane, este servidor MCP baseado em TypeScript capacita agentes de IA a:

• Compreender e processar dados geoespaciais,
• Interpretar a intenção do usuário em um contexto espacial,
• Fornecer orientação de navegação precisa e contextualmente relevante.

Ao aproveitar os dados de mapas globais da Magic Lane e a inteligência geoespacial em tempo real, o Servidor MCP permite experiências de navegação e planejamento de viagens profundamente personalizadas por meio de ferramentas principais:

• Busca Inteligente - Encontre endereços, pontos de interesse (POIs) ou coordenadas com recursos de busca inteligente e filtragem por categoria de POI.

• Roteamento Inteligente - Gere rotas otimizadas entre múltiplos waypoints com suporte para diversos modos de transporte, preferências de rota e integração dinâmica de POIs.

• Planejamento de Viagem Circular - Crie rotas circulares que começam e terminam no mesmo local, perfeitas para corridas, ciclismo ou entregas.

• Geocodificação Reversa - Converta coordenadas geográficas em informações detalhadas de endereço, incluindo nome da rua, cidade, estado, país e código postal.

• Análise de Isócronas - Calcule polígonos de acessibilidade mostrando áreas alcançáveis dentro de restrições específicas de tempo ou distância.

• Visualização de Rotas - Crie imagens de mapas visuais de rotas calculadas, isócronas e viagens circulares para contexto geográfico imediato e apresentação.

• Gerenciamento de Geofences - Crie, gerencie e consulte limites geográficos para monitoramento de ativos, alertas baseados em localização e análise espacial com suporte para polígonos, círculos e retângulos.

• Mapa Interativo - Exiba um mapa vetorial interativo diretamente na conversa usando MapLibre GL JS e tiles vetoriais MagicLane. Suporta visualizações de localização, visualização de rotas, sobreposições de isócronas, rotas circulares, marcadores de resultados de busca, áreas de geofence e caminhos de coordenadas personalizados — com um ou vários overlays por mapa e interações de pan/zoom.

As funcionalidades de mapa podem ser visualizadas como imagens de mapa de alta qualidade através do nosso novo recurso beta:

• Renderização de Mapa Estático - Gere visualizações de mapa personalizadas com marcadores, caixas delimitadoras ou áreas centradas em localização sem cálculo de rota, complementando a visualização de rotas, isócronas e viagens circulares.

Juntas, essas capacidades permitem que agentes de IA atuem como verdadeiros copilotos geoespaciais - compreendendo o contexto espacial, antecipando as necessidades do usuário e otimizando cada jornada com precisão e facilidade.

Opções de Transporte: O servidor suporta tanto stdio (para clientes nativos MCP como Claude Desktop) quanto HTTP (para aplicações web, implantações serverless e integrações personalizadas).

Primeiros Passos

Pré-requisitos

O Servidor MCP Magic Lane integra-se perfeitamente a qualquer aplicação ou agente de IA, fornecendo acesso a dados geoespaciais e funcionalidade de navegação. Antes da configuração, certifique-se de ter o seguinte:

Requisitos do Sistema:

1. Node.js 22+ instalado (Baixar aqui)
2. npm (incluído com Node.js)
3. Uma Chave de API Magic Lane válida (para acesso aos dados do mapa)
4. Um cliente de IA compatível com MCP, como:
   • Claude Desktop
   • Cursor IDE
   • Visual Studio Code com GitHub Copilot

Verifique os Pré-requisitos:

# Check Node.js version (should be 22+)
node --version

# Check npm version
npm --version

Início Rápido

Para testes imediatos, use npx para executar o servidor sem instalação:

# Set your API key as environment variable
export MAGICLANE_API_KEY="your_api_key"

# Run the server directly
npx @magiclane/mcp-server

Configuração da Chave de API

Para obter um token de API Magic Lane, siga nosso guia passo a passo. As etapas detalhadas são:

1. Crie uma Conta Magic Lane

   • Visite developer.magiclane.com/api/register e registre-se para uma conta gratuita.

2. Gere uma Chave de API

   • Faça login na sua conta
   • Navegue até o Painel de Projetos
   • Siga as instruções para gerar sua chave de API exclusiva, que servirá como seu token de acesso para o Servidor MCP

Instalação

Para explorar e integrar o Servidor MCP localmente, siga estas etapas para instalar as dependências e compilar o projeto:

# Clone or navigate to the Magic Lane MCP Server directory
cd path/to/magiclane-mcp

# Install dependencies
npm install

# Build the TypeScript project
npm run build

# Verify the build was successful
ls dist/  # Should show map-server.esm.js and other compiled files

Nota: Certifique-se de que Node.js 22+ e npm estejam instalados corretamente antes de executar esses comandos.

Executando o Servidor

Servidor MCP Padrão (transporte stdio):

# Option 1: Using .env file (recommended)
cp .env.example .env
# Edit .env with your actual API key
npm start

# Option 2: Using Node's built-in env file support
node --env-file=.env dist/map-server.esm.js

# Option 3: Using environment variable directly
MAGICLANE_API_KEY=your_api_key npm start

Servidor HTTP (para clientes web e personalizados):

# Development mode (with auto-reload)
npm run dev:http

# Production mode (after build)
npm run start:http

Para documentação completa do servidor HTTP, incluindo endpoints, exemplos JSON-RPC e integração de clientes, consulte o Guia de Configuração do Servidor HTTP.

Configuração

Configure seu cliente MCP para conectar-se ao servidor Magic Lane. Siga o guia de configuração detalhado para seu cliente de IA específico:

• Guia de Configuração do Claude Desktop - Instruções completas de configuração para Claude Desktop
• Guia de Configuração do Cursor AI - Configuração passo a passo para Cursor IDE
• Guia de Configuração do VS Code - Guia de integração para Visual Studio Code com GitHub Copilot

Cada guia inclui:

• Locais de arquivos de configuração específicos do cliente
• Múltiplas opções de instalação (compilação local, NPM, Docker)
• Instruções específicas por plataforma (Windows, macOS, Linux)

Docker

Compile e execute o servidor usando Docker:

# Build the Docker image
docker build -t magiclane-mcp-server .

# Run the container (pass API key via environment variable)
docker run --rm -e MAGICLANE_API_KEY=your_api_key magiclane-mcp-server

# Or use an env file
docker run --rm --env-file .env magiclane-mcp-server

Variáveis de Ambiente:

Variável	Obrigatória	Descrição
MAGICLANE_API_KEY	Sim	Sua chave de API Magic Lane para autenticação
VERBOSE	Não	Defina como true para imprimir logs informativos/debug/aviso. Erros são sempre registrados. Padrão é false.
HTTP_TIMEOUT_SECONDS	Não	Tempo limite (em segundos) para solicitações de API Magic Lane de saída. Inteiro positivo. Padrão é 30.

O contêiner é executado com --enable-source-maps para melhores stack traces em produção.

---

Ferramentas Disponíveis

O Servidor MCP Magic Lane fornece várias ferramentas geoespaciais integradas que permitem que sistemas de IA busquem, planejem, analisem e visualizem rotas e locais.

Procurando imagens de mapas renderizados e demonstrações de mapas interativos ao vivo? Consulte Exemplos Visuais.

1. Busca de Localização

A Ferramenta de Busca de Localização usa a API REST de Busca Magic Lane para encontrar:

• Coordenadas, endereços ou áreas administrativas.
• Pontos de Interesse (POIs) ao redor de um local de referência (restaurantes, postos de gasolina, farmácias, etc.).

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
text	string	-	Consulta de texto livre (ex.: nome do POI, endereço ou cidade)
target	string	-	Tipo de resultado: pois (POIs), addresses (endereços de rua) ou cities. Obrigatório.
poi_categories	array	-	Filtros de categoria de POI. Obrigatório quando target é pois. Valores válidos: gas_stations, parking, food&drink, accommodation, medical_services, shopping, car_services, public_transport, sightseeing, etc.
reference_location	object	-	Contexto geográfico: { coordinates: { longitude, latitude } } (preferido) e/ou { location_text } (nome da cidade/região/país). Pelo menos um é obrigatório.
locale	string	"en"	Idioma da resposta (código de idioma ISO 639-2 / ISO 639-3)
limit	number	5	Número máximo de resultados, classificados por relevância

Exemplos de Prompts

• Exploração Urbana e Turismo

  • "Busque restaurantes italianos autênticos no centro de Chicago a uma distância caminhável do Millennium Park."
  • "Onde estão os caixas eletrônicos perto do Portão de Brandemburgo, Berlim?"

• Negócios e Logística

  • "Localize o 'DHL Service Point' mais próximo da Estação Central de Berlim."
  • "Encontre todas as localizações da Starbucks dentro de 1km do nosso escritório na 1 Market Street, São Francisco."
  • "Onde estão os estacionamentos perto da Estação Central de Amsterdã?"

• Imobiliário e Propriedades

  • "Mostre todas as escolas primárias perto de 456 Maple Avenue, Portland, Oregon, com suas distâncias exatas da propriedade."
  • "Localize farmácias, mercearias e paradas de transporte público perto da propriedade na Baker Street 221B, Londres."

2. Planejador de Rotas

A Ferramenta de Planejador de Rotas gera rotas otimizadas entre múltiplos pontos usando a API REST de Roteamento Magic Lane e a API REST de Gerenciamento de Frotas Magic Lane. Esta ferramenta suporta os seguintes recursos:

• Roteamento ponto a ponto e multi-paradas (A -> B -> C).
• Inclusão de POIs (ex.: postos de gasolina, restaurantes).
• Otimização avançada de VRP para rotas de múltiplas entregas.
• Considerações de tráfego, restrições e terreno.
• Instruções de rota multilíngues.

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
transport	string	"car"	Tipo de transporte (car, lorry, truck, pedestrian, bike, public)
type	string	"fastest"	Objetivo de otimização. fastest/shortest funcionam para todos os modos de transporte. economic é exclusivo para eBike — requer transport: "bike" e uma pedelec/spedelec vehicle.profile. scenic não é válido para transport: "bike".
origin	string	-	Local de partida (nome ou coordenadas)
destination	string	-	Local de chegada (nome ou coordenadas)
intermediate_waypoints	array	[]	Lista de paradas entre a partida e a chegada. A ordem determina a geração da rota. Cada waypoint define preferências e restrições específicas
avoid	array	[]	Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks)
vehicle	object	null	Características do veículo, incluindo dimensões, peso, tipo de combustível, parâmetros de veículo elétrico e preferência de perfil. Consulte Especificação do Veículo para detalhes completos.
details	string	"full"	Nível de detalhe da resposta: full (geometria + instruções de navegação), path (somente geometria), timedistance (somente totais)
number_of_routes	number	1	Número de rotas (1-3 para carro/caminhão/bicicleta/pedestre; 1-11 para transporte público)
fitness_factor	number	0.5	Tolerância de esforço de terreno para bicicleta/pedestre, 0.0 (fácil) a 1.0 (exigente)
emergency	boolean	false	Ativa roteamento para veículos de emergência (relaxa certas restrições de trânsito)
locale	string	"en"	Idioma das instruções de navegação (código de idioma ISO 639-2 / ISO 639-3)

Estrutura de Waypoint Intermediário

Cada entrada em intermediate_waypoints representa uma parada. O discriminador type determina a forma de waypoint e quais campos se aplicam:

Parâmetro	Tipo	Padrão	Descrição
type	string	-	Discriminador da forma da parada. Um de: coordinates (ponto fixo), address (resolvido a partir de um local/endereço em texto livre), reference_poi (POI resolvido próximo a um local de referência), along_route_poi (busca por categoria de POI ao longo do corredor da rota).
waypoint	object	-	Dados do local. A forma deve corresponder a type: para coordinates, forneça coordinates: { longitude, latitude }; para address/reference_poi/along_route_poi, forneça location com parâmetros de busca (text, target, reference_location e poi_categories quando o alvo for pois).
max_poi_deviation	number	1000	Distância perpendicular máxima da polilinha da rota (em metros) para considerar candidatos a POI. Aplica-se somente a along_route_poi.
location_poi_preference	string	"no matter"	Dica de posicionamento para paradas along_route_poi. Um de: based on reference location, midpoint of the route, after some distance from departure, no matter.
location_poi_distance	number	-	Dica de posicionamento numérica. Quando location_poi_preference é after some distance from departure e representa o número de metros a partir da partida. Ignorado caso contrário.

Exemplos de Prompts

• Turismo Internacional & Viagens

  • "Gere uma rota de bicicleta cênica de Viena a Bratislava, evitando rodovias."
  • "Planeje uma viagem de carro de Munique a Veneza com paradas em Innsbruck e Bolzano, otimizada para vistas cênicas."

• Transporte Público & Deslocamento

  • "Encontre uma rota de transporte público de Londres a Oxford com o mínimo de transferências."
  • "Qual é a maneira mais rápida de ir do Aeroporto JFK a Manhattan usando transporte público?"

• Passeios Turísticos com Múltiplas Paradas & Eventos

  • "Crie um passeio a pé do Coliseu à Fontana di Trevi, parando no Panteão e em uma gelateria."
  • "Estou na Torre Eiffel e preciso visitar Notre-Dame, o Museu do Louvre e voltar ao meu hotel perto da Gare du Nord. Planeje a melhor rota de carro."

• Roteamento de Emergência & Prioridade

  • "Encontre a rota mais rápida da Estação de Ambulâncias St. John, Westminster, até o Hospital Geral, evitando trânsito e bloqueios."
  • "Calcule a rota mais rápida para serviços de emergência do Quartel de Bombeiros 23 até o incidente relatado no Pike Place Market."

• Roteamento de Veículos Elétricos

  • "Estou dirigindo um Tesla Model 3 com 60% de bateria de São Francisco a Los Angeles. Encontre a rota ideal com as paradas de carregamento necessárias, garantindo que eu chegue com pelo menos 20% de carga."
  • "Calcule uma rota para minha van elétrica (bateria de 80 kWh, autonomia de 250 km) de Berlim a Praga com paradas de carregamento rápido ao longo do caminho."

3. Calculadora de Isócronas

A Ferramenta Calculadora de Isócronas fornece análise espacial para determinar todas as áreas alcançáveis a partir de um ponto de referência dentro de restrições específicas de tempo de viagem ou distância, usando a API REST de Isócronas da Magic Lane. Isso permite que sistemas de IA analisem zonas de acessibilidade, áreas de cobertura de serviços e estudos de alcançabilidade.

Principais Recursos:

• Calcular polígonos de alcançabilidade com base em restrições de tempo ou distância
• Suporte para múltiplos modos de transporte (a pé, bicicleta, carro, transporte público)
• Resolução do local de partida por coordenadas ou geocodificação
• Análise de múltiplas faixas para estudos complexos de acessibilidade

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
transport	string	"car"	Modo de transporte (car, lorry, truck, pedestrian, bike, public)
type	string	"fastest"	Modelo de custo e unidades para ranges. fastest/shortest funcionam para todos os modos de transporte. economic é somente eBike — requer transport: "bike" E um vehicle.profile pedelec/spedelec. scenic NÃO é válido para transport: "bike".
departure	object	-	Ponto de origem: { coordinates: { longitude, latitude } } ou { location: { text, ... } }
ranges	array	-	Um ou mais limites. Segundos quando type é fastest/economic/scenic; metros quando type é shortest. Todos os valores positivos.
avoid	array	[]	Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks)
vehicle	object	null	Características do veículo incluindo dimensões, peso, tipo de combustível, parâmetros de EV e preferência de perfil. Consulte Especificação do Veículo para detalhes completos.
locale	string	"en"	Idioma do resultado (código de idioma ISO 639-2 / ISO 639-3)

Exemplos de Prompts

• "Onde posso pedalar em 45 minutos a partir da Estação Central de Amsterdã?"
• "Exiba todas as áreas a 10 minutos a pé da Estação Atlantic Avenue-Barclays Center no Brooklyn."
• "Exiba a área de captação de 1 hora de carro a partir do local proposto para o armazém em Frankfurt."

4. Planejador de Rota Circular

A Ferramenta de Planejador de Rota Circular gera rotas circulares que começam e terminam no mesmo local. Esta ferramenta é perfeita para criar rotas de exploração, circuitos de ciclismo, trilhas de corrida e rotas de entrega.

Principais Recursos:

• Rotas circulares com retorno garantido ao ponto de partida
• Geração de rotas baseada em tempo ou distância
• Suporte a múltiplos modos de transporte (caminhada, ciclismo, direção)
• Preferências de terreno e de evitar colinas para ciclistas
• Comprimento e complexidade de rota personalizáveis

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
transport	string	"car"	Modo de transporte (car, lorry, truck, pedestrian, bike, public)
type	string	"fastest"	Objetivo de otimização e unidades para range. fastest/shortest funcionam para todos os modos de transporte. economic é somente eBike — requer transport: "bike" E um vehicle.profile pedelec/spedelec. scenic NÃO é válido para transport: "bike".
departure	object	-	Ponto de início E fim do loop: { coordinates: { longitude, latitude } } ou { location: { text, ... } }
range	number	-	Tamanho alvo do loop. Segundos quando type é fastest/economic/scenic; metros quando type é shortest. Deve ser positivo.
avoid	array	[]	Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks)
terrain	boolean	false	Incluir perfil de elevação/terreno na resposta
departure_time	number	0	Hora de partida como segundos de época Unix; 0 usa a hora atual do servidor
profile	string	-	Atalho de subperfil de nível superior para bicicleta (city, road, cross, mountain, opcionalmente sufixado com _pedelec/_spedelec) ou pedestre (walk, hike). Se vehicle.profile também estiver definido, vehicle.profile vence.
vehicle	object	null	Características do veículo incluindo dimensões, peso, tipo de combustível, parâmetros de EV e preferência de perfil. Consulte Especificação do Veículo para detalhes completos.
random_seed	number	0	Semente inteira para geração de loop reproduzível
locale	string	"en"	Idioma da resposta (código de idioma ISO 639-2 / ISO 639-3)

Exemplos de Prompts

• Fitness e Recreação

  • "Crie um circuito de corrida de 10 km começando no Central Park."
  • "Projete um circuito de bicicleta de 90 minutos a partir de Stephansplatz."

• Turismo e Exploração

  • "Gere um circuito de caminhada de 45 minutos a partir da Torre Eiffel."
  • "Planeje um circuito de caminhada de 2 horas começando na Times Square."

• Rotas de Ciclismo

  • "Crie um circuito de bicicleta de 25 km a partir de Whistler Village, evitando rodovias."
  • "Projete um circuito de ciclismo de 1 hora a partir do Golden Gate Park usando a rota mais curta."

5. Geocodificação Reversa

A Ferramenta de Geocodificação Reversa converte coordenadas geográficas ou áreas em informações detalhadas de endereço usando a API REST de Geocodificação Reversa da Magic Lane. Esta ferramenta fornece componentes abrangentes de endereço para várias consultas espaciais.

Principais Recursos:

• Conversão de ponto para endereço para coordenadas específicas
• Busca ao redor de um ponto, dentro de uma área ou ao longo de um caminho
• Retorna múltiplos resultados de endereço com classificação por distância
• Inclui hierarquia administrativa (assentamento, cidade, condado, estado, país)
• Identifica pontos de interesse próximos

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
coordinates	object	-	Ponto de coordenada específico { longitude, latitude } para consulta de endereço
insideArea	object	-	Definição de área: caixa delimitadora (bbox) com limites east, west, north, south; área circular com center e radius metros; ou polígono a partir de string de polilinha ou array de coordenadas (mínimo de 3 pontos)
along	object	-	Definição de caminho (polilinha codificada ou coordenadas) com radius em metros para encontrar endereços ao longo
limit	number	5	Número máximo de resultados a retornar
locale	string	"en"	Idioma do resultado (código de idioma ISO 639-2 / ISO 639-3)

Exemplos de Prompts

• "Qual é o endereço nas coordenadas 51.5074, -0.1278?"
• "Encontre todos os endereços em um raio de 500 metros do Portão de Brandemburgo."

6. Gerenciador de Geofence

A Ferramenta de Gerenciador de Geofence fornece operações abrangentes de geofence para definir e gerenciar limites geográficos, permitindo serviços baseados em localização e monitoramento de ativos. Esta ferramenta suporta criar, recuperar, atualizar, excluir geofences e verificar se pontos estão dentro dos limites definidos.

Principais Recursos:

• Criar geofences com geometrias de polígono, círculo ou retângulo
• Consultar geofences por ID, dentro de caixas delimitadoras ou por proximidade a um ponto
• Atualizar propriedades do geofence (nome, palavras-chave)
• Excluir geofences por ID
• Verificar se coordenadas específicas estão dentro de geofences
• Suporte a metadados e tags personalizados

Operações e Parâmetros

Operação de Criação - Crie um ou mais geofences com os seguintes parâmetros:

Parâmetro	Tipo	Padrão	Descrição
id	string	-	Identificador personalizado (gerado automaticamente se não fornecido)
name	string	-	Nome legível por humanos
keywords	array	[]	Tags para busca e filtragem
properties	object	-	Metadados personalizados adicionais
geojson_type	string	-	Tipo de geometria: polygon, circle ou rectangle
geojson_area	object	-	Definição de área (coordenadas de polígono, centro/raio do círculo ou bbox)

Operação de Leitura - Recupera uma ou mais geofences com os seguintes parâmetros:

Parâmetro	Tipo	Padrão	Descrição
geofence_ids	array	-	Matriz de IDs de geofences para recuperar
box_limited	object	-	Filtro de caixa delimitadora (norte, sul, leste, oeste)
proximity_area	object	-	Buscar geofences próximas a um ponto (reference_point, distance, limit)

Operação de Atualização - Modifica propriedades de uma geofence existente com os seguintes parâmetros:

Parâmetro	Tipo	Padrão	Descrição
geofence_id	string	-	ID da geofence a ser atualizada
name	string	-	Nome legível por humanos para atualizar a geofence
keywords	array	[]	Palavras-chave/tags atualizadas para a área da geofence

Operação de Exclusão - Remove uma ou mais geofences com os seguintes parâmetros:

Parâmetro	Tipo	Padrão	Descrição
geofence_ids	array	-	Matriz de IDs de geofences para excluir

Operação de Verificação de Ponto - Determina se coordenadas estão dentro de geofences com os seguintes parâmetros:

Parâmetro	Tipo	Padrão	Descrição
geofence_ids	array	-	Matriz de IDs de geofences para verificar
points	array	-	Matriz de locais para testar; cada entrada usa coordinates: { longitude, latitude } ou location (parâmetros de busca)

Exemplos de Prompts

• Monitoramento e Rastreamento de Ativos

  • "Crie uma geofence circular com raio de 500m ao redor do nosso armazém na 123 Main Street, Chicago."
  • "O veículo de entrega nas coordenadas 40.7589, -73.9851 está dentro da geofence da zona da Main Street?"

• Gerenciamento de Áreas Restritas

  • "Crie uma geofence retangular 'construction-zone-1' cobrindo o centro de Seattle delimitada por estas coordenadas: norte 47.6205, sul 47.5990, leste -122.3250, oeste -122.3450."
  • "Atualize a geofence 'construction-zone-1' para incluir as palavras-chave 'temporary' e 'high-priority'."

• Área de Serviço e Zonas de Entrega

  • "Crie três geofences circulares de zona de entrega: 'berlin-warehouse-1' nas coordenadas 13.3777, 52.5163 com raio de 2km, 'berlin-warehouse-2' em 13.4050, 52.5200 com raio de 1.5km, e 'berlin-warehouse-3' em 13.3888, 52.5170 com raio de 2.5km."
  • "Mostre-me todas as geofences dentro de 2km do Portão de Brandemburgo nas coordenadas 13.3777, 52.5163."
  • "Recupere todas as geofences com IDs: 'zone-premium-01', 'zone-premium-02' e 'zone-premium-03' que estão marcadas com 'premium-service'."

• Alertas Baseados em Localização

  • "Exclua as geofences temporárias do evento com IDs: 'summer-festival-2025-main', 'summer-festival-2025-parking' e 'summer-festival-2025-stage' agora que o evento terminou."
  • "Liste todas as geofences dentro da caixa delimitadora cobrindo Manhattan: norte 40.8820, sul 40.7006, leste -73.9070, oeste -74.0479."
  • "Encontre todas as geofences perto da Times Square dentro de 1000 metros e mostre seus nomes e palavras-chave."

7. Renderizador de Mapa Estático

A Ferramenta de Renderização gera imagens de mapa estático de rotas calculadas, isócronas, viagens de ida e volta e visualizações de mapa personalizadas usando o serviço de renderização da Magic Lane. Ela fornece contexto visual imediato sobrepondo dados geográficos em um mapa e retornando o resultado como uma imagem incorporada.

Principais Recursos:

• Renderiza rotas, isócronas e viagens de ida e volta como imagens PNG, JPEG ou WebP
• Calcula automaticamente o viewport ideal para enquadrar todos os dados relevantes
• Gera visualizações de mapa estático centradas em um local ou delimitadas por coordenadas personalizadas
• Entrega imagens diretamente ao cliente MCP como dados codificados em base64; para routing, isochrone e round_trip, um bloco de texto JSON com os detalhes da rota subjacente acompanha a imagem, portanto não é necessária uma chamada de cálculo separada.

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
render_type	string	-	Tipo de visualização: routing, isochrone, round_trip ou map_location
output_format	string	"image/png"	Formato de imagem de saída: image/png (padrão), image/jpeg ou image/webp
parameters	object	-	Parâmetros correspondentes ao render_type selecionado. Para routing, isochrone e round_trip, aceita os mesmos parâmetros da respectiva ferramenta de cálculo. Para map_location: width (px, padrão 800), height (px, padrão 600), corners ([minLon, minLat, maxLon, maxLat]) para ajustar a uma caixa delimitadora, ou around_location (referenceLocation + raio distance em metros, padrão 500) para centralizar em um ponto.

Exemplos de Prompts

• Representação de Rota

  • "Estou na 10 Downing Street, Londres - por favor, mostre uma rota de carro até a Catedral de São Paulo."

• Representação de Viagem de Ida e Volta

  • "Visualize uma rota de corrida de 5,5km começando no Rijksmuseum em Amsterdã."

• Representação de Isócrona

  • "Por favor, exiba um mapa de Paris com uma isócrona de 15 minutos a pé."

• Representação de Mapa Estático

  • "Exiba uma visão ampla de Miami, incluindo a praia e o Distrito Histórico Art Deco."

Veja Exemplos Visuais para a saída renderizada desses prompts.

8. Mapa Interativo

A Ferramenta de Mapa Interativo renderiza tiles vetoriais da MagicLane em um mapa totalmente interativo diretamente na conversa usando MapLibre GL JS e MCP Apps. Diferente do renderizador estático, os usuários podem navegar, ampliar e explorar o widget do mapa sem sair do cliente de chat.

Principais Recursos:

• Transmite tiles vetoriais ao vivo do serviço de mapas global da MagicLane
• Ajusta automaticamente o viewport aos dados exibidos: local, rota, isócrona, viagem de ida e volta, resultados de busca, áreas de geofence ou um caminho de coordenadas personalizado
• Desenha uma ou várias sobreposições no mesmo mapa (rotas, isócronas, geofences, caminhos) - cada forma em sua própria cor
• Suporta interações de navegação e zoom em clientes compatíveis com MCP Apps

Parâmetros de Entrada

Parâmetro	Tipo	Padrão	Descrição
zoom	number	12	Nível de zoom do mapa (0 = visão mundial, 16 = nível de rua). Ignorado para routing, isochrone, round_trip e path (e sempre que múltiplas sobreposições são desenhadas) - o viewport é ajustado automaticamente aos dados.
overlayParameters	array	-	Sobreposições para desenhar (pelo menos uma entrada). Cada entrada é um objeto { display_type, parameters }. Passe uma única entrada para uma sobreposição, ou várias para desenhá-las todas no mesmo mapa - as entradas podem repetir um tipo (ex.: duas entradas routing para duas rotas) ou misturar tipos (ex.: uma rota mais uma isócrona mais geofences). Cada forma desenhada recebe automaticamente uma cor distinta.

Cada entrada overlayParameters tem:

Campo	Tipo	Descrição
display_type	string	Modo de exibição: location, routing, isochrone, round_trip, search_results, geofence ou path
parameters	object	Aceita os mesmos parâmetros da ferramenta de cálculo correspondente e deve corresponder ao display_type desta entrada. Renderiza rotas com visualização completa do caminho, polígonos de acessibilidade como áreas sombreadas ou rotas circulares com pontos de início/fim marcados, dependendo do display_type selecionado. Para display_type: path, passe coordinates como uma matriz de pontos [longitude, latitude] (pelo menos 2) mais um label opcional para desenhar a polilinha como está.

Exemplos de Prompts

• Visualização de Localização

  • "Mostre-me um mapa interativo centrado na Torre Eiffel"
  • "Exiba um mapa interativo do centro de Tóquio."

• Visualização de Rota

  • "Mostre um mapa interativo da rota de carro de Amsterdã a Bruxelas."
  • "Exiba uma rota de bicicleta do Central Park à Brooklyn Bridge em um mapa interativo, incluindo uma parada em uma farmácia."

• Sobreposição de Isócrona

  • "Mostre em um mapa interativo todos os lugares que posso alcançar de carro em 30 minutos a partir da Estação Central de Berlim."
  • "Exiba uma isócrona a pé de 20 minutos a partir da Trafalgar Square em um mapa interativo."

• Viagem de Ida e Volta

  • "Mostre um percurso de corrida de 10 km a partir do Vondelpark em um mapa interativo."

• Resultados de Busca

  • "Mostre todas as cafeterias perto do Louvre em um mapa interativo."
  • "Exiba restaurantes a 1 km de Notre-Dame em um mapa interativo."

• Caminho Personalizado

  • "Desenhe esta trilha GPS em um mapa interativo: [[2.35, 48.85], [2.34, 48.86], [2.33, 48.87]]."
  • "Trace uma linha em um mapa interativo, rotule-a como 'Rota de entrega', usando as coordenadas [[11.8793, 46.4372], [11.8694, 46.4329], [11.8597, 46.4339], [11.8504, 46.4341], [11.8406, 46.4187], [11.8378, 46.4149], [11.8437, 46.4103]]."

Navegue pelos exemplos HTML executáveis para cada display_type em Exemplos Visuais.

---

Solução de Problemas

Problemas Comuns

O Servidor Não Inicia

# Check if Node.js version is 22+
node --version

# Verify API key is set
echo $MAGICLANE_API_KEY

# Check for build errors
npm run build

Problemas com Chave de API

• Certifique-se de que sua chave de API seja válida e esteja ativa no Painel Magic Lane
• Verifique se a variável de ambiente está configurada corretamente: MAGICLANE_API_KEY=your_key
• Verifique se há espaços extras ou aspas na chave de API

Problemas de Conexão

• Verifique se a configuração do seu cliente MCP corresponde ao caminho do servidor
• Certifique-se de que o servidor esteja em execução antes de conectar o cliente
• Verifique as configurações do firewall se estiver usando conexões remotas

Limitação de Taxa

• A API Magic Lane tem limites de taxa; verifique seu painel para uso atual
• Implemente cache de solicitações para rotas acessadas com frequência
• Considere atualizar seu plano de API se os limites forem excedidos

Mensagens de Erro Comuns

• Acesso não autorizado (401): Chave de API inválida. Verifique sua configuração.
• Nenhum resultado encontrado (404): O local não pôde ser encontrado. Tente uma consulta diferente.
• Muitas solicitações (429): Limite de taxa excedido. Verifique seu painel de uso.
• Solicitação inválida (400): Parâmetros inválidos. Verifique o formato da sua entrada.

Política de Privacidade

A Magic Lane está comprometida em proteger sua privacidade e lidar com seus dados de forma responsável. Para informações completas de privacidade, consulte nossa política de privacidade completa: https://www.magiclane.com/web/terms-and-conditions#privacy

Coleta de Dados

• Dados de consulta: Termos de busca de localização, origens/destinos de rotas e coordenadas enviados através do servidor MCP são transmitidos à API da Magic Lane para processamento. Eles não são armazenados ou registrados pela Magic Lane após a entrega da resposta.
• Chave de API: Sua chave de API é transmitida com cada solicitação apenas para autenticação e limitação de taxa. Ela nunca é compartilhada com terceiros.
• Sem perfil de usuário: A Magic Lane não cria perfis de usuário, rastreia padrões de uso entre sessões ou correlaciona solicitações individuais.

Como os Dados São Usados

• Todas as solicitações são processadas em tempo real para gerar a resposta geoespacial solicitada (rota, resultado de busca, isócrona, etc.).
• Os dados processados são descartados imediatamente após a entrega da resposta.
• A renderização do mapa é feita dinamicamente; as imagens geradas não são retidas após a transmissão.

Armazenamento e Retenção de Dados

• A Magic Lane não armazena persistentemente o conteúdo de solicitações de roteamento, consultas de localização, parâmetros de busca ou entradas de geocodificação reversa.
• Nenhum dado de sessão ou histórico de solicitações é retido nos servidores da Magic Lane.

Dados de Terceiros

• A Magic Lane usa dados do OpenStreetMap e outros conjuntos de dados geográficos publicamente disponíveis
• Nenhum dado de localização pessoal ou proprietário é compartilhado com terceiros
• Os dados de tráfego e roteamento são agregados e anonimizados na origem

Para informações detalhadas, revise nossos Termos de Serviço e Política de Privacidade.

---

Suporte

• Documentação: developer.magiclane.com/docs
• Painel da API: developer.magiclane.com/api/dashboard
• Issues no GitHub: github.com/magiclane/magiclane-mcp-server/issues
• Suporte do Portal do Desenvolvedor: Entre em contato com o suporte através do portal do desenvolvedor