MapmyIndia (Mappls) MCP Server (FastMCP)

Высокопроизводительный сервер Model Context Protocol (MCP) для MapmyIndia (Mappls) REST APIs, созданный на основе фреймворка с открытым исходным кодом FastMCP.

Этот сервер позволяет ИИ-ассистентам (таким как Claude, Gemini, ChatGPT, Cursor и Antigravity) запрашивать географические данные, выполнять геокодирование, строить автомобильные и пешеходные маршруты, рассчитывать матрицу расстояний и ETA, находить точки интереса (POI) и получать сведения о местах по кодам eLoc по всей Индии.

Возможности

• FastMCP Framework: создан на основе Python-фреймворка fastmcp от Prefect HQ для автоматической генерации схем, надежной валидации и низкой задержки.

• Гибкая аутентификация:

  • Режим статического токена доступа: передайте прямой bearer-токен MAPPLS_ACCESS_TOKEN.

  • Поток учетных данных клиента OAuth 2.0: передайте MAPPLS_CLIENT_ID и MAPPLS_CLIENT_SECRET для автоматической генерации токена и его обновления до истечения срока действия.

• Комплексные инструменты Mappls:

  • mappls_geocode: преобразует названия мест в координаты широты/долготы и коды eLoc.

  • mappls_reverse_geocode: преобразует координаты в форматированные данные адреса.

  • mappls_autosuggest: живые прогнозные подсказки поиска мест.

  • mappls_get_directions: маршруты (на автомобиле, велосипеде, пешком, грузовом транспорте) с пошаговыми инструкциями.

  • mappls_distance_matrix: расчет матрицы расстояний и времени в пути от N до M точек.

  • mappls_snap_to_road: привязка зашумленных GPS-треков к дорожной сети.

  • mappls_search_nearby: поиск ближайших POI (рестораны, банкоматы, больницы, зарядные станции для электромобилей, заправки).

  • mappls_place_details: получение расширенных атрибутов для любого 6-значного кода eLoc Mappls.

  • mappls_text_search: интеллектуальный поиск мест с исправлением орфографии.

• Встроенные MCP-промпты: предварительно настроенные шаблоны, такие как plan_itinerary и optimize_logistics_hub.

• Поддержка двух транспортов: запуск через stdio (для настольных приложений) или sse (для HTTP-микросервисов).

• Офлайн / Mock-режим: бесперебойная работа в режиме пробного запуска (dry-run) при отсутствии API-ключей.

Установка и настройка

1. Требования

• Python 3.10 или выше

• Учетные данные разработчика MapmyIndia (Mappls) или токен доступа (из Mappls Console)

2. Конфигурация окружения

Клонируйте или скопируйте этот репозиторий, затем создайте файл .env из .env.example:

cp .env.example .env

Отредактируйте .env и укажите ваш токен Mappls или учетные данные клиента:

# Option A: Direct Access Token (Recommended for Token Input)
MAPPLS_ACCESS_TOKEN=your_access_token_here

# Option B: Client Credentials
MAPPLS_CLIENT_ID=your_client_id_here
MAPPLS_CLIENT_SECRET=your_client_secret_here

MCP_TRANSPORT=stdio

3. Установка пакета

Установите пакет в режиме редактирования:

pip install -e .

Или установите с зависимостями для разработки:

pip install -e ".[dev]"

Быстрая настройка для всех (запуск через uvx напрямую из GitHub)

Любой может использовать этот MCP-сервер напрямую из GitHub без клонирования или локальной установки с помощью uvx (входит в состав uv).

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_CLIENT_ID": "YOUR_MAPPLS_CLIENT_ID",
        "MAPPLS_CLIENT_SECRET": "YOUR_MAPPLS_CLIENT_SECRET"
      }
    }
  }
}

2. Antigravity / Cursor / VS Code (mcp_config.json)

{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_ACCESS_TOKEN": "YOUR_MAPPLS_ACCESS_TOKEN"
      }
    }
  }
}

Локальная разработка и использование

Запуск через Stdio (по умолчанию)

mmi-mcp
# or
python -m mmi_mcp.server --transport stdio

Запуск через SSE (HTTP-сервер)

python -m mmi_mcp.server --transport sse --host 127.0.0.1 --port 8000

Запуск тестов

Запустите набор модульных и интеграционных тестов:

$env:PYTHONPATH="src"; python -m pytest tests/ -v

Лицензия

Лицензия MIT