GrabMaps MCP Server

Сервер Model Context Protocol (MCP) для интеграции с API GrabMaps, предоставляющий доступ к сервисам GrabMaps через AWS Location Service.

Обратите внимание, что этот MCP-сервер НЕ является официально аффилированным с Grab, GrabMaps или AWS Location Service.

Важно: GrabMaps поддерживает только восемь стран Юго-Восточной Азии.

• 🇲🇾 Малайзия (MYS)

• 🇸🇬 Сингапур (SGP)

• 🇹🇭 Таиланд (THA)

• 🇲🇲 Мьянма (MMR)

• 🇰🇭 Камбоджа (KHM)

• 🇻🇳 Вьетнам (VNM)

• 🇵🇭 Филиппины (PHL)

• 🇮🇩 Индонезия (IDN)

Поисковые запросы за пределами этих стран не дадут точных результатов.

Функции

Этот MCP-сервер предоставляет доступ к функциональности GrabMaps через две основные категории:

Действия с местами (доступны через MCP)

• SearchPlaceIndexForText: Прямое геокодирование для поиска мест по названию или адресу

• SearchPlaceIndexForPosition: Обратное геокодирование для поиска мест по координатам

• SearchPlaceIndexForSuggestions: Получение подсказок мест по мере ввода

• GetPlace: Получение подробной информации о конкретном месте

Действия с маршрутами (доступны через MCP)

• CalculateRoute: Расчет маршрутов между точками с промежуточными точками

• CalculateRouteMatrix: Расчет матрицы маршрутов между несколькими пунктами отправления и назначения

Аналитика и мониторинг

• Firebase Analytics: Облачное хранилище аналитики с Firebase Realtime Database

• Локальное резервное копирование: Автоматическое резервное копирование локальных файлов в качестве резервного варианта

• Визуальная панель мониторинга: Панель аналитики в реальном времени с использованием Chart.js

• Отслеживание запросов: Отслеживание запросов по методу, конечной точке, IP-адресу клиента и агенту пользователя

• Отслеживание вызовов инструментов: Мониторинг использования и производительности инструментов MCP

Функциональность карт (требуется консоль AWS)

Примечание: Функциональность рендеринга карт недоступна напрямую через MCP-сервер. Чтобы просматривать и использовать карты:

1. Перейдите в консоль AWS Location Service

2. Найдите раздел Maps и нажмите кнопку "Try it"

3. Убедитесь, что в качестве провайдера выбран "Grab"

Чтобы изучить покрытие данных GrabMaps и увидеть карты в действии без входа в AWS, посетите: https://grabmaps.grab.com/explore-data-coverage

Related MCP server: Google Maps MCP Server

Установка

Из NPM

npm install mcp-grabmaps

Из исходного кода

git clone https://github.com/hithereiamaliff/mcp-grabmaps.git
cd mcp-grabmaps
npm install

Конфигурация

VPS / HTTP-сервер (режим службы ключей)

HTTP-сервер аутентифицирует пользователей через MCP Key Service. Пользователи регистрируют свои учетные данные GrabMaps + AWS в службе ключей и получают единый API-ключ usr_XXXXXXXX.

Создайте файл .env:

# MCP Key Service (required for hosted HTTP server)
KEY_SERVICE_URL=http://mcp-key-service:8090/internal/resolve
KEY_SERVICE_TOKEN=your_server_token_here

# Place Index name (default for GrabMaps)
PLACE_INDEX_NAME=explore.place.Grab

# Map name (for rendering maps)
MAP_NAME=explore.map.Grab

# Route calculator name
ROUTE_CALCULATOR_NAME=explore.route-calculator.Grab

# Server port
PORT=3000

Smithery / Локальная разработка

При запуске через Smithery или локальной разработке учетные данные GrabMaps и AWS предоставляются напрямую через схему конфигурации SDK Smithery (не через службу ключей). Установите их в .env:

GRABMAPS_API_KEY=your_grabmaps_api_key_here
AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
AWS_REGION=ap-southeast-5

Использование

Способ 1: Локальный запуск

# Development mode
npm run dev

# Production mode
npm run build
npm start

Способ 2: Использование со Smithery

# Run in development mode
npm run smithery:dev

# Build for production
npm run smithery:build

# Deploy to Smithery
npm run smithery:deploy

Тестирование в Smithery Playground

Для наилучшего тестирования API мест и маршрутов мы рекомендуем использовать Smithery playground:

1. Запустите ваш MCP-сервер локально: npm run dev

2. Откройте Smithery playground по адресу: https://smithery.ai/playground

3. Подключитесь к вашему локальному MCP-серверу: http://localhost:3000

4. Протестируйте вызовы API мест и маршрутов, используя примеры, приведенные в SMITHERY_TESTING.md

Способ 3: Развертывание на собственном VPS

Разверните MCP-сервер на своем VPS с помощью Docker и Nginx. Аутентификация обрабатывается MCP Key Service — пользователи предоставляют один API-ключ usr_XXXXXXXX вместо необработанных учетных данных.

Формат URL для VPS

# Query parameter
https://mcp.techmavie.digital/grabmaps/mcp?api_key=usr_XXXXXXXX

# Path-based
https://mcp.techmavie.digital/grabmaps/mcp/usr_XXXXXXXX

Конфигурация клиента

Claude Desktop:

{
  "mcpServers": {
    "grabmaps": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/grabmaps/mcp?api_key=usr_XXXXXXXX"
    }
  }
}

Cursor/Windsurf: Тот же формат в их конфигурационных файлах MCP.

Живая демонстрация

Публичный экземпляр доступен по адресу:

https://mcp.techmavie.digital/grabmaps/mcp

Зарегистрируйте свои учетные данные GrabMaps + AWS в MCP Key Service, чтобы получить свой API-ключ usr_XXXXXXXX.

Развертывание на VPS

Архитектура

Client (Claude, Cursor, Windsurf, etc.)
    ↓ HTTPS (usr_XXXXXXXX key)
https://mcp.techmavie.digital/grabmaps/mcp/usr_XXXXXXXX
    ↓
Nginx (SSL termination + reverse proxy)
    ↓ HTTP
Docker Container (port 8092 → 8080)
    ↓
GrabMaps MCP Server (Streamable HTTP Transport)
    ↓ resolves usr_ key
MCP Key Service → decrypted GrabMaps + AWS credentials
    ↓
AWS Location Service (GrabMaps)

Файлы развертывания

Быстрое развертывание

# On your VPS — ensure the shared Docker network exists
docker network create mcp-network  # only needed once

mkdir -p /opt/mcp-servers/grabmaps
cd /opt/mcp-servers/grabmaps
git clone https://github.com/hithereiamaliff/mcp-grabmaps.git .

# Set key-service env vars
cp .env.example .env
nano .env  # set KEY_SERVICE_URL and KEY_SERVICE_TOKEN

docker compose up -d --build

# Configure Nginx (add location block from deploy/nginx-mcp.conf)
sudo nano /etc/nginx/sites-available/mcp.techmavie.digital
sudo nginx -t
sudo systemctl reload nginx

Конечные точки

Firebase Analytics

Развертывание на VPS включает интеграцию с Firebase Realtime Database для облачного хранения аналитики.

Функции

• Двойное хранилище: Firebase (основное) + локальное резервное копирование файлов (резервное)

• Отслеживание в реальном времени: Запросы, вызовы инструментов, IP-адреса клиентов, агенты пользователей

• Визуальная панель мониторинга: Панель мониторинга Chart.js по адресу /analytics/dashboard

• Постоянство: Аналитика сохраняется после перезапуска контейнера и повторных развертываний

• Автосохранение: Сохранение каждые 60 секунд + при корректном завершении работы

Отслеживаемые данные аналитики

• Общее количество запросов и вызовов инструментов

• Запросы по методу (GET, POST)

• Запросы по конечной точке (/, /health, /mcp, /analytics)

• Статистика использования инструментов

• Отслеживание клиентов (IP-адреса, агенты пользователей)

• Почасовые шаблоны запросов

• История недавних вызовов инструментов

Настройка Firebase

См. FIREBASE_SETUP.md для получения полных инструкций по настройке.

Быстрая настройка:

# On VPS
cd /opt/mcp-servers/grabmaps
mkdir -p .credentials
nano .credentials/firebase-service-account.json  # Paste your Firebase service account JSON

# Copy to Docker volume
docker volume create grabmaps_firebase-credentials
docker run --rm \
  -v grabmaps_firebase-credentials:/credentials \
  -v $(pwd)/.credentials:/source:ro \
  alpine cp /source/firebase-service-account.json /credentials/

# Fix permissions
docker run --rm \
  -v grabmaps_firebase-credentials:/credentials \
  alpine chown -R 1001:1001 /credentials/

# Restart
docker compose down
docker compose up -d --build

Просмотр аналитики

• Панель мониторинга: https://mcp.techmavie.digital/grabmaps/analytics/dashboard

• JSON API: https://mcp.techmavie.digital/grabmaps/analytics

• Консоль Firebase: https://console.firebase.google.com/ → Ваш проект → Realtime Database

Структура данных Firebase

mcp-analytics/
  └── mcp-grabmaps/
      ├── serverStartTime: "2026-01-06T..."
      ├── totalRequests: 123
      ├── totalToolCalls: 45
      ├── requestsByMethod: {...}
      ├── requestsByEndpoint: {...}
      ├── toolCalls: {...}
      ├── recentToolCalls: [...]
      ├── clientsByIp: {...}
      ├── clientsByUserAgent: {...}
      ├── hourlyRequests: {...}
      └── lastUpdated: 1704470400000

Важные примечания для моделей ИИ

Поддерживаемые страны

GrabMaps поддерживает ТОЛЬКО следующие восемь стран Юго-Восточной Азии:

• Малайзия (MYS)

• Сингапур (SGP)

• Таиланд (THA)

• Мьянма (MMR)

• Камбоджа (KHM)

• Вьетнам (VNM)

• Филиппины (PHL)

• Индонезия (IDN)

Модели ИИ не должны пытаться использовать GrabMaps для местоположений за пределами этих стран, так как результаты будут неточными или отсутствующими.

Требования к коду страны

При использовании функций API мест модели ИИ ДОЛЖНЫ анализировать запрос пользователя, чтобы определить соответствующую страну, и включать трехбуквенный код страны ISO во все запросы:

{
  "query": "City Square Mall",
  "country": "SGP"  // SGP for Singapore, MYS for Malaysia, THA for Thailand, etc.
}

Примеры кодов стран:

• Сингапур: SGP

• Малайзия: MYS

• Таиланд: THA

• Индонезия: IDN

• Филиппины: PHL

• Вьетнам: VNM

Включение кода страны критически важно для получения точных результатов поиска.

Этот подход позволяет вам тестировать функциональность мест и маршрутов без необходимости настройки компонентов визуализации карт.

Примеры вызовов API

Прямое геокодирование

const response = await fetch('http://localhost:3000/searchPlaceIndexForText', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'KLCC, Kuala Lumpur',
    country: 'my',
    maxResults: 5
  })
});

const data = await response.json();
console.log(data);

Расчет маршрута

const response = await fetch('http://localhost:3000/calculateRoute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: {
      longitude: 101.6942371,
      latitude: 3.1516964
    },
    destination: {
      longitude: 101.7113,
      latitude: 3.1421
    },
    travelMode: 'Car'
  })
});

const data = await response.json();
console.log(data);

Интеграция с моделями ИИ

Этот MCP-сервер можно интегрировать с моделями ИИ, поддерживающими протокол Model Context Protocol. Пример интеграции с моделью ИИ:

// Example of how an AI model would use this MCP server
const result = await mcpClient.call('grabmaps', 'searchPlaceIndexForText', {
  query: 'KLCC, Kuala Lumpur',
  country: 'my'
});

// The AI model can then use the result in its response
console.log(`The coordinates of KLCC are: ${result.results[0].coordinates.latitude}, ${result.results[0].coordinates.longitude}`);

Настройка AWS Location Service

Перед использованием этого MCP-сервера вам необходимо настроить следующие ресурсы в AWS Location Service:

1. Создайте индекс мест (Place Index) с GrabMaps в качестве поставщика данных

2. Создайте карту (Map) с GrabMaps в качестве поставщика данных

3. Создайте калькулятор маршрутов (Route Calculator) с GrabMaps в качестве поставщика данных

Ограничения компонентов карты и рекомендуемый подход

Компоненты API карт имеют определенные ограничения при использовании через MCP-сервер:

• Тайлы карт, возвращаемые конечной точкой getMapTile, представляют собой двоичные данные, закодированные как строки base64

• Стеки шрифтов для getMapGlyphs должны соответствовать тем, которые поддерживаются GrabMaps через AWS Location Service

• Имена файлов спрайтов для getMapSprites должны соответствовать определенным шаблонам regex

• Максимальные уровни масштабирования ограничены (обычно макс. масштаб 14)

Рекомендуемый подход:

• Для карт: Используйте прямую интеграцию с GrabMaps через MapLibre GL и AWS Location Service, как показано в официальной демонстрации

• Для мест и маршрутов: Используйте MCP-сервер через Smithery playground или прямые вызовы API

Такое разделение обеспечивает оптимальную производительность и визуализацию, при этом используя MCP-сервер для функциональности мест и маршрутов.

Официальная демонстрация GrabMaps MapLibre GL

Комплексная демонстрация с использованием официальной интеграции GrabMaps с MapLibre GL включена в каталог examples/official-map-demo. Эта демонстрация предоставляет полный интерфейс тестирования для всех компонентов GrabMaps:

• API мест: Прямое/обратное геокодирование и подробная информация о местах

• API карт: Тайлы карт, дескрипторы стилей, спрайты и глифы

• API маршрутов: Расчет маршрута и матрица маршрутов

Демонстрация оснащена интерфейсом с вкладками для легкого тестирования различных компонентов и предоставляет подробную обратную связь для каждого вызова API.

Ключевые особенности

• Интерактивная карта с использованием официальных тайлов карт GrabMaps через MapLibre GL

• Интерфейс с вкладками для тестирования различных компонентов GrabMaps

• Комплексное тестирование всех конечных точек API

• Настраиваемый API-ключ, регион и имена ресурсов

• Визуальное отображение маршрутов, результатов поиска и компонентов карты

Чтобы запустить демонстрацию:

# Start the MCP server
npm start

# Then open examples/official-map-demo/index.html in your browser

См. README официальной демонстрации карт для получения инструкций по настройке и использованию.

Тестирование

Комплексный набор тестов включен в каталог tests для проверки правильности работы всех конечных точек. Для получения подробных инструкций по тестированию, примеров и советов по устранению неполадок, пожалуйста, обратитесь к файлу TESTING.md.

Чтобы запустить тесты:

# Start the MCP server in one terminal
npm start

# Run the test suite in another terminal
node tests/test-suite.js

Лицензия

Этот проект лицензирован по лицензии MIT - подробности см. в файле LICENSE.

Участие

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.