Singapore Location Intelligence MCP

Singapore Location Intelligence MCP 🇸🇬

Como criador deste projeto, eu, Siva (Sivasubramanian Ramanathan), desenvolvi esta plataforma abrangente de Inteligência de Localização de Singapura para explorar as capacidades do Model Context Protocol (MCP). Meu objetivo era testar como o MCP poderia ser aproveitado para ajudar a IA a planejar rotas com precisão, ao mesmo tempo em que demonstrava minha capacidade de trabalhar com diversas APIs e minha expertise nas tecnologias envolvidas.

O que começou como um experimento com integração MCP evoluiu para uma aplicação sofisticada do mundo real que demonstra o poder deste novo e empolgante protocolo para criar ferramentas que podem rivalizar com soluções comerciais. Esta plataforma fornece roteamento de transporte de nível empresarial, resolução de códigos postais e inteligência de localização com instruções de navegação detalhadas no nível do Google Maps, tudo otimizado para o ecossistema de transporte único de Singapura.

🌟 Principais Recursos

🎯 NOVO na v0.3.0 - Integração de Saídas do MRT e Correção da Ferramenta de Pontos de Referência

• 🚇 Recomendações de Saída do MRT - Precisão no nível do Google Maps com códigos de saída específicos
• 🏛️ Resolução de Localização Aprimorada - Correção da análise de strings JSON e validação de coordenadas
• 📍 Navegação no Nível da Saída - "Use a Saída E (caminhada de 14m, 1 min)" para navegação ideal na estação
• 🔧 Tratamento Robusto de Entrada - Todos os formatos de localização agora funcionam corretamente
• 🎯 Otimizado para Singapura - Limites de coordenadas adequados e validação de códigos postais

🎯 v0.2.7 - Correções do Serviço Meteorológico e Confiabilidade Aprimorada

• 🌦️ Integração Meteorológica Robusta - Corrigidas todas as inconsistências e falhas da API meteorológica
• 🔧 Tratamento de Erros Pronto para Produção - Degradação graciosa quando as APIs meteorológicas falham
• 🎯 Compatibilidade com a API Meteorológica de Singapura - Suporta todos os 5 endpoints meteorológicos oficiais
• ⚡ Planejamento de Viagem Aprimorado - Roteamento ciente do clima com fallbacks resilientes
• 🛡️ Garantia de Zero Falhas - Falhas no serviço meteorológico não interrompem mais o planejamento de viagens

🎯 NOVO na v0.2.1 - Inteligência Meteorológica

• 🌦️ Ferramentas Meteorológicas Independentes - Condições meteorológicas abrangentes e recomendações específicas por atividade
• 🎯 Recomendações de Atividades - Conselhos personalizados para caminhada, ciclismo, esportes, fotografia, refeições
• 🌡️ Análise de Conforto - Avaliação inteligente do nível de conforto com impacto na viagem
• ⏰ Recomendações de Melhor Horário - Horários ideais para atividades ao ar livre com base no clima

🎯 NOVO na v0.2.0 - Inteligência Aprimorada

• 🔍 Busca Difusa Avançada - "Opp Blk 910" → encontra "Opposite Block 910" com 95% de precisão
• 🌦️ Roteamento Ciente do Clima - Impacto do clima em tempo real nos tempos de caminhada e sugestões de rota
• 🚇 Minimização de Transferências - Algoritmos inteligentes para reduzir transferências em viagens multimodais
• 🗺️ Direções com Qualidade do Google Maps - Instruções no nível de "Vire à Esquerda para Permanecer na Thomson Road"
• 📍 Detalhes Abrangentes de Paradas - Comodidades próximas, informações de acessibilidade e contexto de localização

🎯 Recursos Principais

• 🎯 Inteligência Avançada de Códigos Postais - Resolução com 95% de precisão para todos os códigos postais de Singapura
• 🗺️ Instruções Profissionais de Navegação - Direções passo a passo como "Vire à Esquerda para Permanecer na Thomson Road"
• 🚇 Planejamento de Transporte Multimodal - Integração perfeita de MRT, LRT, ônibus e caminhada
• ⏰ Inteligência de Horário de Singapura - Horário comercial, detecção de horário de pico e otimização de horários
• 🔍 Busca Inteligente de Localização - Correspondência difusa, tolerância a erros de digitação e sugestões inteligentes
• 📍 Geocodificação Abrangente - Geocodificação direta e reversa com precisão específica para Singapura
• 🚌 Dados de Transporte em Tempo Real - Chegadas de ônibus ao vivo, status do trem e interrupções de serviço
• 💡 Roteamento Ciente do Contexto - Otimização de horário de pico, avisos de último trem, alternativas de ônibus noturno

🎯 Problema do Mundo Real Resolvido

Antes: Ferramentas básicas de transporte com falha na resolução de códigos postais Depois: Plataforma de inteligência de localização de nível empresarial com roteamento ciente do clima

INPUT: "How to get to Suntec City from Little India MRT during heavy rain?"

OUTPUT: 
✅ Postal Code 039594 → SUNTEC CITY
🌧️ Heavy rain detected - prefer covered routes
🚇 Route: DT Line (8 min) → Covered walkway (6 min) 
💰 Cost: $1.55 | 🕐 Duration: 32 minutes (adjusted for weather)
📍 Step-by-step: "Walk 246m via covered walkway to ROCHOR MRT → Take DT Line from Rochor to Promenade → Use underground connection to Suntec City"
⚠️ Weather Advisory: Allow extra 5 minutes for walking segments

🚀 Início Rápido

Instalação

npx @siva-sub/mcp-public-transport

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "singapore-transport": {
      "command": "npx",
      "args": ["-y", "@siva-sub/mcp-public-transport"],
      "env": {
        "LTA_ACCOUNT_KEY": "your_lta_api_key_here",
        "ONEMAP_TOKEN": "your_onemap_token_here",
        "ONEMAP_EMAIL": "your_onemap_email@example.com",
        "ONEMAP_PASSWORD": "your_onemap_password"
      }
    }
  }
}

⚙️ Configuração

Variáveis de Ambiente Obrigatórias

• LTA_ACCOUNT_KEY: Obrigatória. Sua chave de API do LTA DataMall (Obtenha aqui)

Variáveis de Ambiente Opcionais

• ONEMAP_TOKEN: Token da API OneMap para recursos aprimorados (Registre-se aqui)
• ONEMAP_EMAIL: E-mail da conta OneMap para autenticação
• ONEMAP_PASSWORD: Senha da conta OneMap para autenticação
• CACHE_DURATION: Duração do cache em segundos (padrão: 300)
• LOG_LEVEL: Nível de registro de log (padrão: info)

🛠️ Ferramentas Disponíveis

🌍 NOVO - Inteligência de Localização Aprimorada

• search_bus_stops ⭐ - Busca difusa avançada com abreviações de Singapura

  • Suporta: "Opp Blk 910", "Bef Jurong East MRT", "CP near Orchard"
  • Reconhecimento inteligente de padrões e tolerância a erros de digitação
  • Classificação baseada em distância e pontuação de confiança

• get_bus_stop_details ⭐ - Informações abrangentes de paradas

  • Informações de serviço em tempo real e comodidades próximas
  • Detalhes de acessibilidade e contexto de localização
  • Distâncias de caminhada até paradas próximas

• plan_comprehensive_journey ⭐ - Planejamento completo de viagens multimodais

  • Algoritmos de minimização de transferências
  • Tratamento de interrupções em tempo real
  • Direções passo a passo com qualidade do Google Maps
  • Impacto do clima em segmentos de caminhada
  • Suporta todos os tipos de entrada: endereços, códigos postais, coordenadas

🌍 Inteligência de Localização

• search_location - Aprimorada com capacidades de busca difusa
• resolve_postal_code - Resolução de códigos postais de Singapura de alta precisão (taxa de sucesso de 95%)
• reverse_geocode - Converta coordenadas em endereços com precisão específica para Singapura

🚌 Transporte Público

• get_bus_arrival - Horários de chegada de ônibus em tempo real com informações de lotação
• find_bus_stops - Encontre paradas de ônibus por localização, nome ou coordenadas
• plan_comprehensive_journey - Planejamento de viagens multimodais com instruções detalhadas

🚇 Serviços de Trem

• get_train_service_status - Status de serviço do MRT/LRT em tempo real e interrupções

🚕 Táxis e Transporte por Aplicativo

• get_nearby_taxis - Encontre táxis disponíveis e estime tempos de espera

🚦 Tráfego e Estradas

• get_traffic_conditions - Condições de tráfego ao vivo, incidentes e velocidades das vias

🌦️ NOVO - Inteligência Meteorológica

• get_weather_conditions ⭐ - Clima abrangente em tempo real com impacto na viagem

  • Dados em tempo real de temperatura, precipitação, umidade e vento
  • Análise do nível de conforto e classificações das condições de caminhada
  • Avaliação do impacto na viagem com ajustes de tempo
  • Recomendações específicas por atividade e conselhos de segurança

• get_weather_advisory ⭐ - Recomendações meteorológicas específicas por atividade

  • Conselhos personalizados para caminhada, ciclismo, refeições ao ar livre, esportes, fotografia
  • Classificações de adequação e recomendações de melhores horários
  • Orientações de segurança e precauções específicas para o clima

📊 Recursos Empresariais

Roteamento Avançado com Inteligência Meteorológica

// Weather-aware journey planning
{
  "primaryRoute": {
    "summary": {
      "totalTime": 1980, // seconds (adjusted for weather)
      "walkingTime": 720, // includes weather buffer
      "transfers": 1
    },
    "weatherImpact": {
      "conditions": {
        "rainfall": 12.5, // mm
        "temperature": 28, // °C
        "humidity": 85 // %
      },
      "advisories": [
        {
          "severity": "high",
          "type": "rain",
          "message": "Heavy rain detected. Allow extra time for walking.",
          "routingImpact": {
            "walkingTimeMultiplier": 1.5,
            "preferredModes": ["MRT", "Covered Bus Stops"]
          }
        }
      ]
    }
  }
}

Busca Aprimorada de Paradas de Ônibus

// Fuzzy search with Singapore intelligence
{
  "query": "Opp Blk 910",
  "searchType": "fuzzy",
  "results": [
    {
      "busStopCode": "83139",
      "description": "OPP BLK 910",
      "matchScore": 0.95,
      "locationPatterns": {
        "blockNumber": "910",
        "direction": "opp"
      },
      "searchContext": {
        "queryVariations": ["opposite block 910", "opp blk 910"],
        "bestMatch": "OPP BLK 910"
      }
    }
  ]
}

Detalhes Abrangentes de Paradas

// Detailed stop information with context
{
  "details": {
    "busStopCode": "83139",
    "description": "OPP BLK 910",
    "services": [...], // Real-time arrivals
    "nearbyStops": [...], // Within walking distance
    "accessibility": {
      "wheelchairAccessible": true,
      "sheltered": true,
      "tactilePaving": true
    },
    "locationContext": {
      "district": "Tampines",
      "landmarks": ["Block 910", "Tampines Mall"],
      "transportHubs": ["Tampines MRT Station"]
    },
    "nearbyAmenities": [
      {
        "name": "Tampines Mall",
        "type": "shopping",
        "distance": 250,
        "walkingTime": 3
      }
    ]
  }
}

Inteligência de Horário de Singapura

{
  "singaporeTime": "27/06/2025, 10:58 PM",
  "businessHours": false,
  "rushHour": false,
  "contextInfo": {
    "nextRushHour": "7:00 AM tomorrow",
    "travelRecommendation": "Off-peak travel - comfortable journey expected"
  }
}

Inteligência de Códigos Postais

{
  "postalCode": "039594",
  "location": {
    "name": "SUNTEC CITY",
    "address": "3 TEMASEK BOULEVARD SUNTEC CITY SINGAPORE 039594",
    "district": "Downtown Core",
    "areaType": "Central Singapore",
    "confidence": 0.98
  }
}

🎯 Casos de Uso

1. Aplicações de Navegação

• Planejamento de rotas ciente do clima
• Direções detalhadas passo a passo
• Otimização de viagens multimodais
• Integração de tráfego em tempo real

2. Entrega e Logística

• Validação e resolução de códigos postais
• Planejamento de rotas ideal com considerações climáticas
• Padronização de endereços e correspondência difusa

3. Planejamento Urbano

• Análise de acessibilidade de transporte
• Impacto do clima no tráfego de pedestres
• Otimização de tráfego em horários de pico
• Mapeamento da cobertura de transporte público

4. Turismo e Hospitalidade

• Direções amigáveis para turistas com pontos de referência
• Sugestões de rotas adequadas ao clima
• Orientação de transporte público
• Descoberta de locais com busca difusa

📈 Desempenho e Confiabilidade

• Planejamento de rotas em menos de 3 segundos com integração meteorológica
• Cache de dados meteorológicos de 5 minutos para capacidade de resposta em tempo real
• Cache inteligente com TTL ciente de localização e clima
• Degradação graciosa durante manutenção de APIs
• 95% de precisão na resolução de códigos postais
• Integração de dados em tempo real com APIs oficiais de Singapura
• Precisão de busca difusa de 90%+ para termos de Singapura

🔧 Configuração Avançada

Preferências de Rota Cientes do Clima

{
  "routingOptions": {
    "includeWeatherImpact": true,
    "maxWalkingDistance": 800,
    "weatherSensitivity": "high",
    "preferredModes": ["MRT", "Covered Bus Stops"],
    "minimizeTransfers": true
  }
}

Configuração de Busca Difusa

{
  "searchOptions": {
    "enableFuzzySearch": true,
    "minScore": 0.3,
    "singaporeAbbreviations": true,
    "typoTolerance": true
  }
}

Configuração de Horário Comercial

{
  "businessHours": {
    "weekdays": { "start": 9, "end": 18 },
    "saturday": { "start": 9, "end": 13 },
    "sunday": { "closed": true }
  }
}

🤝 Integração de APIs

Integração com OneMap

• Autenticação: Renovação automática de token com TTL de 3 dias
• Geocodificação: Resolução de endereços de alta precisão com correspondência difusa
• Roteamento: Direções passo a passo de nível profissional
• Integração Meteorológica: Dados meteorológicos em tempo real das APIs de Singapura

Integração com LTA DataMall

• Dados em Tempo Real: Chegadas de ônibus, status de trens, condições de tráfego
• Rede de Transporte: Dados completos da rede de ônibus e trens
• Alertas de Serviço: Notificações ao vivo de interrupções e manutenção
• Tratamento de Erros Aprimorado: Degradação graciosa e lógica de nova tentativa

Integração com a API Meteorológica de Singapura

• Dados em Tempo Real: Precipitação, temperatura, umidade, velocidade do vento
• Atualizações a Cada 5 Minutos: Dados meteorológicos atualizados para roteamento preciso
• Baseado em Localização: Condições meteorológicas para segmentos específicos de rota
• Geração de Recomendações: Sugestões inteligentes com base nas condições

🚀 Desenvolvimento

Desenvolvimento Local

git clone https://github.com/siva-sub/MCP-Public-Transport
cd MCP-Public-Transport
npm install
cp .env.example .env.local
# Add your API keys to .env.local
npm run dev

Compilação

npm run build    # Builds both ESM and CJS versions
npm run test     # Runs comprehensive test suite
npm run lint     # TypeScript and ESLint checks

Testes

# Unit tests
npm run test

# Integration tests with real APIs
npm run test:integration

# Performance tests
npm run test:performance

📦 Arquitetura

src/
├── services/           # Core business logic
│   ├── lta.ts         # LTA DataMall integration
│   ├── onemap.ts      # OneMap API with authentication
│   ├── weather.ts     # ⭐ Real-time weather integration
│   ├── routing.ts     # ⭐ Enhanced multi-modal routing
│   ├── fuzzySearch.ts # ⭐ Singapore-optimized fuzzy search
│   ├── time.ts        # Singapore time intelligence
│   ├── postalCode.ts  # Postal code validation & resolution
│   └── cache.ts       # Intelligent caching layer
├── tools/             # MCP tool implementations
│   ├── location/      # Enhanced location intelligence tools
│   ├── bus/           # ⭐ Enhanced bus tools with fuzzy search
│   │   ├── search.ts  # ⭐ Advanced bus stop search
│   │   └── details.ts # ⭐ Comprehensive stop details
│   ├── routing/       # ⭐ Enhanced journey planning tools
│   │   └── enhanced.ts# ⭐ Weather-aware optimal routing
│   ├── train/         # Train service tools
│   └── traffic/       # Traffic and road tools
├── types/             # TypeScript interfaces
│   ├── location.ts    # Location and search types
│   ├── transport.ts   # Transport system types
│   ├── search.ts      # Search and query types
│   └── time.ts        # Singapore time types
└── utils/             # Shared utilities
    ├── errors.ts      # Custom error handling
    ├── logger.ts      # Structured logging
    └── validation.ts  # Input validation

🌟 O Que Torna Isso Especial

1. Otimizado para Singapura: Construído especificamente para o ecossistema de transporte único de Singapura com inteligência local
2. Ciente do Clima: Integração meteorológica em tempo real que afeta as decisões de roteamento e as estimativas de tempo de caminhada
3. Nível Profissional: Instruções de roteamento comparáveis ao Google Maps com capacidades de busca difusa
4. Contexto em Tempo Real: Horário comercial, horário de pico, clima e inteligência de horários
5. Alta Precisão: Taxa de sucesso de 95% na resolução de códigos postais, precisão de busca difusa de 90%+
6. Pronto para Empresas: Tratamento abrangente de erros, resiliência climática e otimização de desempenho
7. Amigável para Desenvolvedores: Suporte completo a TypeScript com documentação abrangente
8. Minimização de Transferências: Algoritmos inteligentes para reduzir transferências em viagens multimodais

🎯 Contribuição

Aceitamos contribuições! Consulte nosso Guia de Contribuição para obter detalhes.

📝 Licença

Licença MIT - consulte LICENÇA para obter detalhes.

🙏 Agradecimentos

• Singapore Land Authority (SLA) pela API OneMap
• Land Transport Authority (LTA) pela API DataMall
• Serviço Meteorológico de Singapura pelos dados meteorológicos
• Model Context Protocol pelo framework extensível
• Iniciativa de Dados Abertos de Singapura pelos dados de transporte público

---

Construído com ❤️ para a iniciativa de cidade inteligente de Singapura e exploração do MCP

📊 Estatísticas da Versão 0.2.0

• 11 Ferramentas no Total (antes eram 8)
• 4 Novos Serviços Principais adicionados
• 3 Novas Ferramentas com capacidades avançadas
• Integração da API Meteorológica para condições em tempo real
• Mecanismo de Busca Difusa com mais de 50 abreviações de Singapura
• Direções passo a passo com qualidade do Google Maps
• Algoritmos de minimização de transferências