Mapbox

Сервер Mapbox MCP

Сервер Node.js, реализующий протокол Model Context Protocol (MCP) для API Mapbox.

Раскройте геопространственный интеллект для ваших AI-приложений

Сервер Mapbox MCP превращает любого AI-агента или приложение в систему, осознающую геопространственные данные, предоставляя бесшовный доступ к комплексной платформе геолокационной аналитики Mapbox. С помощью этого сервера ваш ИИ может понимать и рассуждать о местах, ориентироваться в физическом мире и получать доступ к богатым геопространственным данным, включая:

• Глобальное геокодирование для преобразования адресов и названий мест в координаты и обратно
• Поиск точек интереса (POI) по миллионам предприятий, достопримечательностей и мест по всему миру
• Мультимодальная маршрутизация для вождения, ходьбы и езды на велосипеде с учетом трафика в реальном времени
• Матрицы времени в пути для анализа доступности и оптимизации логистики
• Оптимизация маршрутов для поиска оптимального порядка посещения нескольких остановок (задача коммивояжера)
• Сопоставление карт для привязки GPS-треков к дорожной сети для чистой визуализации маршрутов
• Генерация изохрон для визуализации областей, достижимых в пределах заданных временных или дистанционных ограничений
• Живая интерактивная отрисовка карт (render_map_tool) для отображения маршрутов, результатов поиска и ваших собственных кастомных GeoJSON прямо на реальной карте Mapbox GL JS внутри чата
• Статические изображения карт для создания визуальных представлений местоположений, маршрутов и географических данных
• Офлайн-геопространственные вычисления для расстояния, площади, азимута, буферов и пространственного анализа без необходимости вызова API

Создаете ли вы AI-тревел-ассистента, оптимизатор логистики, рекомендательную систему на основе местоположения или любое приложение, которому нужно понимать «где», сервер Mapbox MCP предоставляет пространственный интеллект, чтобы сделать это возможным. Вы также можете включить его на популярных клиентах, таких как Claude Desktop и VS Code. Подробности см. ниже.

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

Для использования этого MCP-сервера требуется токен доступа Mapbox.

Размещенная MCP-конечная точка

Для быстрого доступа вы можете использовать нашу размещенную MCP-конечную точку:

Конечная точка: https://mcp.mapbox.com/mcp

Подробные инструкции по настройке для различных клиентов и использованию API см. в Руководстве по размещенному MCP-серверу.

Чтобы получить токен доступа Mapbox:

1. Зарегистрируйте бесплатную учетную запись Mapbox на mapbox.com/signup
2. Перейдите на свою страницу учетной записи
3. Создайте новый токен или используйте публичный токен по умолчанию

Дополнительную информацию о токенах доступа Mapbox см. в документации Mapbox по токенам доступа.

Руководства по интеграции

Подробные инструкции по настройке для различных интеграций см. в следующих руководствах:

• Настройка Claude Desktop — инструкции по настройке Claude Desktop для работы с этим MCP-сервером
• Настройка Goose — настройка фреймворка AI-агентов Goose
• Настройка VS Code — настройка среды разработки в Visual Studio Code
• Настройка Cursor AI IDE — настройка среды разработки в Cursor AI IDE
• Интеграция Smolagents — пример подключения AI-агентов Smolagents к инструментам Mapbox
• Прямой импорт инструментов — используйте инструменты Mapbox в своих приложениях без запуска MCP-сервера
• Руководство по render_map_tool — примитив визуализации карт: полная схема полезной нагрузки и как отображать собственные данные автономно, без каких-либо других инструментов Mapbox
• Элиситации — как search_and_geocode_tool и directions_tool просят пользователя уточнить результаты или выбрать маршрут и как они корректно переходят к запасному варианту, если клиент это не поддерживает

Примеры запросов

Попробуйте эти запросы с Claude Desktop или другими MCP-клиентами после настройки:

Привязка к местоположению

Для запросов, ориентированных на координаты — «что рядом со мной», «что это за район», «что доступно за N минут» — используйте ground_location_tool. Он объединяет обратное геокодирование, поиск по категориям и изохроны в одном вызове, адаптивно выбирая правильную стратегию на основе запроса, и возвращает типизированные записи (названия, адреса, координаты, расстояния, полигоны достижимости) с цитированием.

Каждый из четырех приведенных ниже запросов задействует разные стратегии в одном вызове инструмента:

• Район — «Какой район находится по координатам 47.6097, -122.3408, и что вокруг меня?»
• POI — «Кофейни в 10 минутах ходьбы от 40.7580, -73.9855»
• Регион — «Чего я могу достичь за 15 минут ходьбы от 37.7749, -122.4194?»
• Маршрутизация — «Ближайшая точка маршрута, чтобы высадить кого-то по адресу 34.0522, -118.2437»

Поиск мест

• «Найди кофейни в пешей доступности от Эмпайр-стейт-билдинг»
• «Я хочу добраться из Сиэтла в Портленд, есть ли Starbucks по пути?»
• «Покажи заправки вдоль маршрута из Бостона в Нью-Йорк»
• «Какие рестораны находятся рядом с Таймс-сквер?»

Навигация и путешествия

• «Получи указания по вождению от LAX до Голливуда с учетом текущего трафика»
• «Сколько времени займет прогулка от Центрального парка до Таймс-сквер?»
• «Рассчитай время в пути от моего отеля (Four Seasons) до аэропорта JFK на такси в час пик»

Визуализация и карты

• «Используя инструмент отрисовки карт Mapbox, покажи мне маршрут от моста Золотые Ворота до Юнион-сквер в Сан-Франциско» — отображает живой интерактивный маршрут на реальной карте Mapbox
• «Создай изображение карты с маршрутом от моста Золотые Ворота до Рыбацкой пристани с маркерами в обоих местах»
• «Покажи спутниковый вид Манхэттена с отмеченными ключевыми достопримечательностями»
• «Сгенерируй карту с подсветкой всех местоположений Starbucks в радиусе мили от центра Сиэтла»
• «Покажи заливку-полигон по этим координатам: [...], с маркером с надписью "Склад" по адресу [...]» — отображает ваш собственный GeoJSON напрямую через render_map_tool, без необходимости других инструментов Mapbox

Анализ и планирование

• «Покажи области, достижимые в течение 30 минут на машине от центра Портленда»
• «Рассчитай матрицу времени в пути между этими 3 отелями (Marriott, Sheraton и Hilton) и конференц-центром в Денвере»
• «Найди оптимальный маршрут посещения этих 3 туристических достопримечательностей (Золотые Ворота, Музыкальные лестницы и Рыбацкая пристань) в Сан-Франциско»
• «Оптимизируй маршрут доставки для этих 8 адресов: [список адресов]»

GPS и сопоставление маршрутов

• «Очисти этот GPS-трек и покажи фактический маршрут по дорогам: [список координат с временными метками]»
• «Привяжи эту записанную велопоездку к велосипедной сети: [GPS-координаты]»
• «Сопоставь этот маршрут вождения с дорожной сетью и покажи уровень загруженности трафика»

Офлайн-геопространственные вычисления

• «Каково расстояние в милях между этими двумя координатами?»
• «Рассчитай площадь этого полигона в квадратных километрах»
• «Находится ли точка 37.7749°N, 122.4194°W внутри этого полигона зоны обслуживания?»
• «Каков азимут от Сан-Франциско до Нью-Йорка?»
• «Найди среднюю точку между Лондоном и Парижем»
• «Создай буферную зону в 5 миль вокруг этого места»
• «Рассчитай центроид границы этого района»
• «Каков ограничивающий прямоугольник для этих координат маршрута?»
• «Упрости этот сложный полигон, чтобы уменьшить количество точек»

Советы для лучших результатов

• Уточняйте местоположения (используйте полные адреса или названия достопримечательностей)
• Указывайте предпочтительный способ передвижения (вождение, ходьба, велосипед)
• Включайте временные ограничения, когда это уместно («в час пик», «в 15:00»)
• Запрашивайте конкретные форматы вывода при необходимости («как изображение карты», «в формате JSON»)

Подробные примеры: см. examples/search-along-route.md для комплексных примеров запроса поиска вдоль маршрута с различными сценариями использования и инструкциями по тестированию в MCP Inspector.

Ресурсы

MCP-сервер предоставляет статические справочные данные как MCP-ресурсы. Ресурсы обеспечивают доступ только для чтения к данным, на которые клиенты могут ссылаться напрямую без вызова инструментов.

Доступные ресурсы

Ресурс категорий Mapbox

Шаблон URI: mapbox://categories или mapbox://categories/{language}

Получите доступ к полному списку доступных идентификаторов категорий для использования с инструментом поиска по категориям. Категории можно использовать для фильтрации результатов поиска по типу (например, «ресторан», «отель», «заправка»).

Примеры:

• mapbox://categories — список категорий по умолчанию (английский)
• mapbox://categories/ja — названия категорий на японском
• mapbox://categories/es — названия категорий на испанском

Доступ к ресурсам:

• Клиенты с нативной поддержкой MCP-ресурсов: используйте метод протокола MCP resources/read
• Клиенты без поддержки ресурсов: используйте resource_reader_tool с URI ресурса

Богатые предпросмотры карт (render_map_tool)

Каждый геопространственный инструмент этого сервера (маршруты, изохроны, поиск и другие) может отображать свой результат в виде живой интерактивной карты Mapbox GL JS через render_map_tool — единый примитив визуализации сервера. Он отображается через протокол MCP Apps (@modelcontextprotocol/ext-apps) как автономная HTML-панель прямо в чате с переключателем полноэкранного режима в поддерживаемых клиентах:

• Claude Desktop ✅
• VS Code с GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Вам не нужны никакие другие инструменты этого сервера для его использования. render_map_tool также принимает вручную составленный GeoJSON напрямую — ваши собственные полигоны, маркеры и маршруты — без зависимости от directions_tool, isochrone_tool или любого другого вызова API Mapbox. См. полное руководство по render_map_tool для схемы полезной нагрузки и полного автономного примера.

Если вам нужно гарантированное статическое изображение в клиентах без поддержки MCP Apps, используйте static_map_image_tool — он возвращает изображение PNG/JPEG в кодировке base64, которое может отобразить любой клиент.

CLIENT_NEEDS_RESOURCE_FALLBACK

Инструменты запасного доступа к ресурсам (опционально для несовместимых клиентов)

Ресурсы — это основная функция MCP, поддерживаемая большинством клиентов (Claude Desktop, VS Code, MCP Inspector и т. д.). Однако некоторые клиенты (например, smolagents) вообще не поддерживают ресурсы. Для таких клиентов сервер может предоставить «инструменты запасного доступа к ресурсам», которые передают то же содержимое, что и ресурсы, но через вызовы инструментов.

Инструменты запасного доступа:

• resource_reader_tool — универсальный запасной вариант для чтения любого ресурса по URI
• category_list_tool — предоставляет доступ к списку категорий (mapbox://categories)

По умолчанию эти инструменты НЕ включены (предполагается, что ваш клиент поддерживает ресурсы). Если ваш клиент не поддерживает ресурсы, включите инструменты запасного доступа:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Когда это устанавливать:

• ✅ Установите true, если используете smolagents или другие клиенты без поддержки ресурсов
• ❌ Оставьте неустановленным (по умолчанию), если используете Claude Desktop, VS Code, MCP Inspector или любой клиент с поддержкой ресурсов
• ❌ Оставьте неустановленным, если не уверены (большинство клиентов поддерживают ресурсы)

Инструменты

Утилитарные инструменты

Инструмент чтения ресурсов

Предоставляет доступ к MCP-ресурсам для клиентов, которые не поддерживают нативный API ресурсов MCP. Используйте этот инструмент для чтения ресурсов, таких как список категорий.

Параметры:

• uri: URI ресурса для чтения (например, mapbox://categories, mapbox://categories/ja)

Пример использования:

• Чтение категорий по умолчанию: {"uri": "mapbox://categories"}
• Чтение категорий на японском: {"uri": "mapbox://categories/ja"}

Примечание: Если ваш MCP-клиент поддерживает нативные ресурсы, предпочтительнее использовать API ресурсов напрямую для лучшей производительности.

Офлайн-геопространственные инструменты

Эти инструменты выполняют геопространственные вычисления полностью офлайн без вызовов API Mapbox. Они используют Turf.js для точных географических вычислений и работают в любом месте, даже без подключения к интернету.

Инструмент расчета расстояния

Рассчитайте расстояние между двумя географическими координатами по формуле гаверсинуса.

Возможности:

• Поддержка нескольких единиц измерения: километры, мили, метры, футы, морские мили
• Точный расчет расстояния по большому кругу
• Не требует вызовов API

Пример использования: «Каково расстояние между Сан-Франциско (37.7749°N, 122.4194°W) и Нью-Йорком (40.7128°N, 74.0060°W)?»

Инструмент проверки точек внутри полигона

Проверяет одну или несколько точек на принадлежность полигону или мультиполигону, возвращая только те, что внутри. Обрабатывает одну точку или пакет за один вызов.

Возможности:

• Работает со сложными полигонами, включая отверстия
• Поддерживает мультиполигоны
• Пакетно проверяет любое количество точек за один вызов
• Полезно для геозонирования, проверки зон доставки и сегментации клиентов

Пример использования: «Какие из этих адресов доставки находятся в пределах нашей зоны обслуживания?»

Инструмент «Пункт назначения»

Вычисляет точку назначения по заданной начальной точке, азимуту и расстоянию, используя геодезическое смещение (по большому кругу).

Возможности:

• Прямолинейное смещение, а не маршрут
• Полезно для запросов вида «найти точку в 5 км к северу от X» или построения поисковых смещений
• Не требует вызовов API

Пример использования: «Какая точка находится в 10 км к северо-востоку от Космической иглы?»

Инструмент «Азимут»

Вычисляет направление по компасу (азимут) от одной координаты к другой.

Возможности:

• Возвращает азимут в градусах (0–360°)
• Указывает основное направление (С, СВ, В, ЮВ, Ю, ЮЗ, З, СЗ)
• Полезно для навигации и запросов о направлении

Пример использования: «В каком направлении мне двигаться, чтобы добраться отсюда до аэропорта?»

Инструмент «Средняя точка»

Находит географическую среднюю точку между двумя координатами вдоль пути по большому кругу.

Возможности:

• Вычисляет истинную среднюю точку на искривлённой поверхности Земли
• Полезно для предложений места встречи
• Корректно обрабатывает расчёты на больших расстояниях

Пример использования: «Что находится на полпути между Сан-Франциско и Нью-Йорком?»

Инструмент «Центроид»

Вычисляет геометрический центр (центроид) полигона или мультиполигона.

Возможности:

• Работает со сложными формами
• Возвращает среднее арифметическое всех точек
• Полезно для размещения подписей или маркеров

Пример использования: «Где мне разместить маркер для границы этого района?»

Инструмент «Площадь»

Вычисляет площадь полигона.

Возможности:

• Поддерживает несколько единиц измерения: квадратные метры, квадратные километры, акры, гектары, квадратные мили, квадратные футы
• Точный расчёт площади на поверхности Земли
• Работает с полигонами любого размера

Пример использования: «Какова площадь этого парка в акрах?»

Инструмент «Ограничивающая рамка»

Вычисляет минимальную ограничивающую рамку (bbox), содержащую геометрию.

Возможности:

• Работает с точками, линиями, полигонами и мультиполигонами
• Возвращает [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Полезно для расчётов области просмотра и пространственной индексации

Пример использования: «Какова ограничивающая рамка для этого маршрута?»

Инструмент «Буфер»

Создаёт буферную зону (полигон) вокруг точки, линии или полигона.

Возможности:

• Поддерживает несколько единиц измерения расстояния
• Создаёт круговые буферы вокруг точек
• Полезно для анализа близости и создания зон влияния

Пример использования: «Покажите мне буферную зону в 5 км вокруг этого места»

Инструмент «Упрощение»

Уменьшает количество вершин в линии или полигоне с помощью алгоритма Дугласа-Пекера.

Возможности:

• Настраиваемый допуск для уровня детализации
• Сохраняет общую форму, уменьшая сложность
• Полезно для уменьшения размера файлов и повышения производительности рендеринга
• Возможность сохранения топологии (предотвращение самопересечений)

Пример использования: «Упростите эту сложную границу, чтобы уменьшить количество точек»

Инструмент «Длина»

Измеряет общую длину линии, заданной серией координат.

Возможности:

• Поддерживает километры, мили, метры и футы
• Полезно для измерения нарисованного маршрута, пути или границы без вызова API маршрутизации

Пример использования: «Какова протяжённость этой туристической тропы?»

Инструмент «Выпуклая оболочка»

Вычисляет выпуклую оболочку набора точек — наименьший выпуклый полигон, содержащий все из них.

Возможности:

• Полезно для анализа ограничивающей области или оценки зоны покрытия
• Работает офлайн без вызовов API

Пример использования: «Каков наименьший полигон, содержащий все эти местоположения магазинов?»

Инструмент «Ближайшая точка»

Находит ближайшую точку в коллекции к заданной целевой точке.

Возможности:

• Эффективнее, чем вызов distance_tool для каждого кандидата и последующая сортировка
• Полезно для поиска ближайшего магазина, остановки или достопримечательности к местоположению

Пример использования: «Какой из этих магазинов ближе всего к моему текущему местоположению?»

Инструмент «Ближайшая точка на линии»

Привязывает точку к ближайшей позиции на линии или маршруте, возвращая эту точку и расстояние до неё.

Возможности:

• Полезно для запросов вида «какая точка на этом маршруте ближе всего к моему местоположению?» или сопоставления с картой без вызова API

Пример использования: «Где на этой туристической тропе я сейчас нахожусь ближе всего?»

Инструменты «Объединение», «Пересечение» и «Разность»

Объединяют или сравнивают два или более полигона — union_tool объединяет их в одну геометрию, intersect_tool находит область их пересечения, а difference_tool вычитает один из другого.

Возможности:

• Полезно для объединения зон обслуживания, поиска пересечений покрытия или вычисления зон исключения (например, «что покрыто зоной A, но не зоной B?»)
• Работает полностью офлайн — не требует вызовов API
• Каждый возвращает ссылку render_map_tool, чтобы результат можно было визуализировать напрямую

Пример использования: «Объедините эти две зоны доставки в одну область покрытия» / «Где пересекаются эти две изохроны?» / «Какая часть этой зоны обслуживания не покрыта нашей 15-минутной изохроной?»

Инструменты Mapbox API

Инструмент «Список категорий» (устаревший)

⚠️ Устаревший: Вместо этого используйте resource_reader_tool с URI mapbox://categories, или обратитесь напрямую к ресурсу mapbox://categories, если ваш клиент поддерживает ресурсы MCP.

Этот инструмент поддерживается для обратной совместимости с клиентами, которые не поддерживают ресурсы MCP или resource_reader_tool.

Инструмент «Матрица»

Вычисляет время в пути и расстояния между несколькими точками с помощью Mapbox Matrix API. Возможности включают:

• Эффективные расчёты маршрутов «один ко многим», «многие к одному» или «многие ко многим»
• Поддержка различных профилей передвижения (driving-traffic, driving, walking, cycling)
• Указание времени отправления для расчётов с учётом трафика
• Сводка маршрута с метриками расстояния и продолжительности
• Управление подходом (бордюр/без ограничений) и диапазоном допустимых азимутов отправления

Инструмент «Статическое изображение»

Генерирует статические изображения карт с помощью Mapbox static image API. Возможности включают:

• Пользовательские стили карт (streets, outdoors, satellite и т. д.)
• Регулируемые размеры изображения и уровни масштабирования
• Поддержка нескольких маркеров с пользовательскими цветами и подписями
• Варианты наложения, включая полилинии и полигоны
• Автоматическое подгонка под указанные координаты

Инструмент «Поиск по категориям»

Выполняет поиск по категориям с помощью Mapbox Search Box category search API. Возможности включают:

• Поиск точек интереса по категориям (рестораны, отели, заправочные станции и т. д.)
• Фильтрация по географической близости
• Настраиваемые лимиты результатов
• Богатые метаданные для каждого результата
• Поддержка нескольких языков

Инструмент «Обратное геокодирование»

Выполняет обратное геокодирование с помощью Mapbox geocoding V6 API. Возможности включают:

• Преобразование географических координат в читаемые адреса
• Настраиваемые уровни детализации (улица, район, город и т. д.)
• Фильтрация результатов по типу (адрес, POI, район и т. д.)
• Поддержка нескольких языков
• Богатая контекстная информация о местоположении

Инструмент «Местоположение на земле»

Отвечает на вопросы вида «что находится рядом с этой координатой» за один вызов — название места, ближайшие точки интереса и доступность по времени в пути — на основе живых данных Mapbox с указанием источников. Используйте его вместо цепочки reverse_geocode_tool с веб-поиском.

Возможности:

• Классифицирует запрос (маршрутизация, контекст района, поиск POI или регион/доступность) и загружает только соответствующие данные
• Поиск ближайших POI по категории, если запрошено
• Сводка доступности по времени в пути (на основе изохрон)
• Возвращает ссылку render_map_tool с отмеченными местоположением и ближайшими POI

Пример использования: «В каком районе находится эта координата, и есть ли поблизости кофейни?»

Инструмент «Детали места»

Получает подробную информацию о конкретном месте по его идентификатору Mapbox — фотографии, часы работы, рейтинги, номера телефонов и URL-адреса веб-сайтов. Используйте после search_and_geocode_tool, category_search_tool или reverse_geocode_tool, чтобы получить больше деталей о конкретном результате.

Пример использования: «Расскажите подробнее о первом результате кофейни — часы работы, номер телефона и веб-сайт»

Инструмент «Маршруты»

Получает маршруты с помощью Mapbox Directions API. Возможности включают:

• Поддержка различных профилей маршрутизации: driving (с живым трафиком или типичным), walking и cycling
• Маршрут через несколько путевых точек (2–25 пар координат)
• Вариант альтернативных маршрутов
• Аннотации маршрута (расстояние, продолжительность, скорость, загруженность)
• Варианты планирования:
  • Время отправления в будущем (depart_at) для профилей driving и driving-traffic
  • Желаемое время прибытия (arrive_by) только для профиля driving
• Оптимизации для конкретных профилей:
  • Driving: ограничения по габаритам транспортного средства (высота, ширина, вес)
• Варианты исключений для маршрутизации:
  • Общие исключения: паромные переправы, платные дороги только с наличными
  • Исключения для driving: платные дороги, автомагистрали, грунтовые дороги, тоннели, государственные границы, границы штатов
  • Пользовательские исключения точек (до 50 географических точек для избегания)
• Формат вывода геометрии GeoJSON

Инструмент «Изохрона»

Вычисляет области, достижимые за указанное время из местоположения, с помощью Mapbox Isochrone API. Возможности включают:

• Поддержка различных профилей передвижения (driving, walking, cycling)
• Настраиваемое время в пути или расстояния
• Генерация нескольких контуров (например, диапазоны 15, 30, 45 минут)
• Необязательное указание времени отправления или прибытия
• Настройка цветов для визуализации

Инструмент «Поиск и геокодирование»

Использует конечную точку Mapbox Search Box Text Search API для поиска и геокодирования POI, адресов, мест и любых других типов, поддерживаемых этим API. Этот инструмент объединяет функциональность, ранее предоставляемую ForwardGeocodeTool и PoiSearchTool (из более ранних версий этого MCP-сервера), в один инструмент.

Инструмент «Сопоставление с картой»

Привязывает GPS-треки к дорожной сети с помощью Mapbox Map Matching API. Возможности включают:

• Преобразование зашумленных GPS-треков в чистые маршруты по дорожной сети
• Поддержка различных профилей передвижения (driving, driving-traffic, walking, cycling)
• Обработка до 100 пар координат на запрос
• Необязательные временные метки для повышения точности на основе скорости
• Настраиваемые радиусы привязки для разных уровней качества GPS
• Аннотации маршрута (ограничения скорости, расстояние, продолжительность, загруженность трафика)
• Несколько форматов вывода геометрии (GeoJSON, polyline)

Пример использования: «Очистите этот GPS-трек и привяжите его к дорогам: [координаты с временными метками]»

Инструмент «Оптимизация»

Находит оптимальный маршрут через несколько местоположений с помощью Mapbox Optimization API. Возможности включают:

• Решение задачи коммивояжёра (TSP) для 2–12 местоположений
• Поддержка различных профилей передвижения (driving, driving-traffic, walking, cycling)
• Гибкая настройка начальной и конечной точек
• Оптимизация по круговому или одностороннему маршруту
• Пошаговые навигационные инструкции (необязательно)
• Аннотации маршрута (расстояние, продолжительность, скорость)
• Несколько форматов вывода геометрии (GeoJSON, polyline)

Пример использования: «Найдите оптимальный маршрут для посещения этих 5 остановок: [список адресов или координат]»

Примечание: Доступна V2 API с расширенными функциями (временные окна, ограничения вместимости, несколько транспортных средств), но требует бета-доступа. Реализация V2 включена в кодовую базу, но не зарегистрирована по умолчанию.

Разработка

Проверка сервера

С использованием Node.js

# Run the built image
npm run inspect:build

С использованием Docker

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

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

Создание нового инструмента

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Выпуск новой версии

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

Важно: Рабочий процесс издателя проверяет, что версии package.json и server.json соответствуют версии выпуска. Пропуск обновления версии или синхронизации манифеста приведёт к сбоям публикации.

Трассировка OpenTelemetry

Этот MCP-сервер включает комплексную трассировку OpenTelemetry для наблюдаемости в производственной среде:

Быстрая демонстрация

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

Примечание: Сервер автоматически загружает конфигурацию из вашего файла .env при запуске. Файл .env.example содержит примеры конфигурации для нескольких платформ наблюдаемости.

Поддерживаемые платформы наблюдаемости

Примеры конфигурации, включенные в .env.example, для:

Облачные провайдеры:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

SaaS-платформы:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Любая OTLP-совместимая серверная часть

Производственная конфигурация

См. docs/tracing.md для получения полных инструкций по настройке, включая:

• 🔧 Руководства по конфигурации для конкретных платформ
• 📊 Настройка аутентификации и конечных точек
• 🎯 Пользовательские атрибуты трассировки и контекст
• 🚀 Оптимизация производительности (минимальные накладные расходы)
• 🔍 Устранение неполадок и отладка

Возможности трассировки:

• ✅ Трассировка загрузки конфигурации (загрузка файла .env)
• ✅ Автоматическая трассировка выполнения инструментов
• ✅ Инструментирование HTTP-запросов с идентификаторами корреляции CloudFront
• ✅ Настраиваемые экспортеры (консоль, OTLP)
• ✅ Безопасность (защита данных, проверка JWT)
• ✅ Готовность к производству (менее 1% нагрузки на ЦП)

Внесение вклада

Мы приветствуем ваш вклад в Mapbox MCP Server! Пожалуйста, прочитайте CONTRIBUTING.md перед отправкой pull request.

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

• CONTRIBUTING.md — Начало работы, процесс PR, краткий справочник
• Инженерные стандарты (docs/engineering_standards.md) — Полные стандарты качества кода, тестирования, документации и совместной работы
• Руководство по Claude Code (CLAUDE.md) — Стандарты и шаблоны для участников, использующих Claude Code
• Инструкции для AI-агентов (AGENTS.md) — Руководство для других AI-ассистентов по программированию (Cursor, Continue, Aider и т. д.)
• Рекомендации по GitHub Copilot — Лучшие практики ответственного использования GitHub Copilot

Быстрый старт для участников

1. Сделайте форк репозитория и клонируйте свой форк
2. Установите зависимости: npm install
3. Внесите изменения в соответствии с нашими стандартами кодирования
4. Запустите тесты и линтинг: npm test && npm run lint
5. Добавьте тесты для любой новой функциональности
6. Отправьте pull request с понятным описанием

Все вклады должны проходить наши проверки CI и процесс рецензирования кода. См. docs/engineering_standards.md для получения подробных требований.

Использование данных и конфиденциальность

Какие данные отправляются в API Mapbox

При использовании инструментов MCP-сервера следующие данные отправляются напрямую из вашего окружения в API Mapbox:

• Инструменты геокодирования: Текст адреса/местоположения, координаты, фильтры по стране/региону
• Инструменты поиска: Поисковые запросы, координаты местоположения для близости, фильтры категорий
• Инструмент маршрутов: Координаты начала/конца, путевые точки, предпочтения маршрутизации, ограничения транспортных средств
• Инструмент матрицы: Несколько пар координат, профиль поездки, время отправления
• Инструмент статической карты: Координаты, уровень масштабирования, предпочтения стилизации, информация о маркерах
• Инструмент изохрон: Координаты начала, параметры времени/расстояния, профиль поездки

Ваша конфиденциальность

• Локальное выполнение: Все вызовы API выполняются напрямую из вашего окружения в API Mapbox
• Безопасность токена: Ваш токен API Mapbox остается на вашем локальном компьютере и никогда не передается и не хранится этим MCP-сервером
• Отсутствие хранения данных: Этот MCP-сервер не хранит, не регистрирует и не собирает ваши данные или API-запросы
• Прямая связь: Между вами и API Mapbox нет промежуточного сервера

Использование данных третьими лицами

• Политика конфиденциальности Mapbox регулирует данные, отправляемые в их API: https://www.mapbox.com/legal/privacy/
• Использование API: Стандартные условия API Mapbox применяются ко всем запросам, сделанным через эти инструменты
• Хранение данных: Обратитесь к документации Mapbox для получения информации об их политике хранения данных

Поддержка и контакты

По вопросам MCP-сервера

• Электронная почта: mcp-feedback@mapbox.com
• Проблемы GitHub: Сообщить об ошибках и запросить функции

По вопросам API Mapbox

• Поддержка Mapbox: https://support.mapbox.com/
• Документация: https://docs.mapbox.com/
• Статус API: https://status.mapbox.com/

Обязательства по обслуживанию

Этот MCP-сервер официально поддерживается Mapbox, Inc. Мы предоставляем:

• Регулярные обновления для новых функций API Mapbox
• Исправления ошибок и обновления безопасности
• Совместимость с последними версиями протокола MCP
• Поддержку сообщества через проблемы GitHub

---

Лицензия MIT