Mapbox Developer MCP Server

Сервер Model Context Protocol (MCP), который предоставляет AI-ассистентам прямой доступ к API разработчика Mapbox. Этот сервер позволяет моделям ИИ взаимодействовать с сервисами Mapbox, помогая разработчикам создавать приложения Mapbox быстрее и эффективнее.

Ищете доступ к документации Mapbox? Используйте [mcp-docs-server] вместе с этим сервером — он предоставляет AI-ассистентам доступ к документации Mapbox, руководствам и API-справочникам с docs.mapbox.com.

https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6

Table of Contents

• Mapbox Developer MCP Server

Table of Contents

• Quick Start

Integration with Developer Tools

• DXT Package Distribution

Creating the DXT Package

• Hosted MCP Endpoint

• Getting Your Mapbox Access Token

• Tools

Reference Tools

• Style Management Tools

• Token Management Tools

create-token

• list-tokens

• Feedback Tools

• Local Processing Tools

GeoJSON Preview tool (Beta)

• Coordinate Conversion tool

• Bounding Box tool

• compare_styles_tool

• Style Optimization tool

• Resources

• Observability & Tracing

Features

• Quick Start with Jaeger

• Supported Backends

• Documentation

• Environment Variables

• Development

Testing

Tool Snapshot Tests

• Inspecting Server

Using Node.js

• Using Docker

• Creating New Tools

• Environment Variables

VERBOSE_ERRORS

• Troubleshooting

• Release Process

• Contributing

Quick Start

Integration with Developer Tools

Начните с интеграции с вашей любимой средой разработки AI:

• Claude Code Integration - Командная строка разработки с Claude

• Claude Desktop Integration - Интеграция настольного приложения

• Cursor Integration - Интеграция Cursor IDE

• VS Code Integration - Visual Studio Code с GitHub Copilot

DXT Package Distribution

Этот MCP-сервер можно упаковать в файл DXT (Desktop Extension) для простой дистрибуции и установки. DXT — стандартизованный формат распространения локальных MCP-серверов, аналогично расширениям браузера.

Creating the DXT Package

Чтобы создать пакет DXT:

# Установить DXT CLI
npm install -g @anthropic-ai/dxt

# Сначала собрать сервер
npm run build

# Создать пакет DXT
npx @anthropic-ai/dxt pack

Это сгенерирует mcp-devkit-server.dxt на основе конфигурации в manifest.json.

Пакет DXT включает:

• Предсобранный код сервера (dist/esm/index.js)

• Метаданные сервера и конфигурации

• Схему конфигурации пользователя для Mapbox access token

• Автоматическую настройку переменных окружения

Hosted MCP Endpoint

Для быстрого доступа можно использовать наш размещённый MCP endpoint:

Endpoint: https://mcp-devkit.mapbox.com/mcp

Для подробной настройки для разных клиентов и использования API смотрите Hosted MCP Server Guide. Примечание: руководство ссылается на стандартный MCP endpoint — вам нужно будет обновить URL endpoint, чтобы использовать devkit endpoint выше.

Getting Your Mapbox Access Token

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

• Зарегистрируйтесь на бесплатную учётную запись Mapbox на mapbox.com/signup

• Перейдите на страницу вашего аккаунта Account page

• Создайте новый токен с необходимыми правами для вашего сценария использования

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

⚠️ IMPORTANT: Token Privileges Required

Переменная окружения MAPBOX_ACCESS_TOKEN обязателена. Каждый инструмент требует конкретных прав/ограничений токена для корректной работы. Например:

• Чтение стилей требует область доступа styles:read

• Создание стилей требует styles:write

• Управление токенами требует tokens:read и tokens:write

• Доступ к отзывам требует user-feedback:read

Tools

Reference Tools

Reference данные доступны как MCP Resources (см. раздел Resources). MCP-клиенты, поддерживающие протокол ресурсов, могут получать их напрямую.

Available References:

• resource://mapbox-style-layers - руководство по ссылкам стилевого специфика Mapbox GL JS, охватывающее все типы слоёв (fill, line, symbol, circle, fill-extrusion) и их свойства

• resource://mapbox-streets-v8-fields - полные определения полей для всех слоёв источников Mapbox Streets v8, включая перечисляемые значения для каждого поля (полезно для построения фильтров)

• resource://mapbox-token-scopes - исчерпывающее руководство по областям токенов, что позволяет понять, какие права нужны для разных операций

• resource://mapbox-layer-type-mapping - отображение слоёв Mapbox Streets v8 на совместимые типы слоёв GL JS, с примерами использования

Примеры подсказок:

• "Какие поля доступны для слоя landuse?"

• "Покажи мне справку по токен-области"

• "Какой тип слоя использовать для дорог?"

• "Получить справку по полям Streets v8"

• "Какие области нужны для отображения карты?"

Style Management Tools

Полный набор инструментов управления стилями Mapbox через Styles API:

Style Builder Tool - Создание и изменение стилей Mapbox программно через диалоговые подсказки

📖 See the Style Builder documentation for detailed usage and examples →

ListStylesTool - Перечень всех стилей для вашей учетной записи Mapbox

• Input: limit (опционально - максимальное число стилей), start (опционально - маркер пагинации)

• Returns: Массив метаданных стилей с опциональными данными пагинации

CreateStyleTool - Создать новый стиль Mapbox

• Input: name, style (Mapbox style specification)

• Returns: Детали созданного стиля с ID

RetrieveStyleTool - Получить конкретный стиль по ID

• Input: styleId

• Returns: Полная спецификация стиля

UpdateStyleTool - Обновить существующий стиль

• Input: styleId, name (optional), style (optional)

• Returns: Обновлённые детали стиля

DeleteStyleTool - Удалить стиль по ID

• Input: styleId

• Returns: Подтверждение успешности

PreviewStyleTool - Генерировать предварительную URL-страницу стиля Mapbox с использованием существующего публичного токена

• Input: styleId, title (optional), zoomwheel (optional), zoom (optional), center (optional), bearing (optional), pitch (optional)

• Returns: URL для открытия предпросмотра стиля в браузере

• Note: Этот инструмент автоматически выбирает первый доступный публичный токен из вашей учётной записи для предварительного просмотра. Требуется как минимум один публичный токен с styles:read.

ValidateStyleTool - Проверка Mapbox style JSON на соответствие Style Specification Mapbox

• Input: style (Mapbox style JSON объект или строка)

• Returns: Результаты проверки, включая ошибки, предупреждения, информационные сообщения и сводку стиля

• Выполняет всестороннюю оффлайн-валидацию:

  • Требуемые поля (version, sources, layers)

  • Правильность типов слоёв и источников

  • Ссылки на источники и IDs слоёв

  • Распространённые проблемы конфигурации

• Note: Это оффлайн-валидация, не требует доступа к API или токенов

⚠️ Required Token Scopes:

Все инструменты стилей требуют действительный Mapbox access token с определёнными правами. Использование токена без нужных прав приведёт к ошибкам аутентификации.

• ListStylesTool: требуется styles:list

• CreateStyleTool: требуется styles:write

• RetrieveStyleTool: требуется styles:download

• UpdateStyleTool: требуется styles:write

• DeleteStyleTool: требуется styles:write

• PreviewStyleTool: требует tokens:read (для перечня токенов) и хотя бы один публичный токен с styles:read

Note: Имя пользователя автоматически извлекается из JWT-пayload.

Example prompts:

• "Can you create a Christmas themed Style for me?"

• "Please generate a preview link for this style"

• "Can you change the background to snow style?"

Token Management Tools

create-token

Создать новый Mapbox access token с заданными правами и, опционально, ограничениями по URL.

Parameters:

• note (string, required): Описание токена

• scopes (array of strings, required): Множество прав/разрешений для токена. Должны быть допустимыми Mapbox scope

• allowedUrls (array of strings, optional): URL-адреса, где токен можно использовать (макс 100)

• expires (string, optional): Время истечения срока в формате ISO 8601 (максимум на 1 час в будущем)

Available Scopes:

Доступные области для публичных токенов:

• styles:tiles - Чтение стилей как растровых тайлов

• styles:read - Чтение стилей

• fonts:read - Чтение шрифтов

• datasets:read - Чтение наборов данных

• vision:read - Чтение Vision API

Example:

{
  "note": "Development token for my app",
  "scopes": ["styles:read", "fonts:read"],
  "allowedUrls": ["https://myapp.com"]
}

Example prompts:

• "Create a new Mapbox token for my web app with styles:read and fonts:read permissions"

• "Generate a token that expires in 30 minutes with styles:tiles and vision:read scopes"

• "Create a restricted token that only works on https://myapp.com with styles:read, fonts:read, and datasets:read"

list-tokens

Перечень токенов доступа Mapbox для аутентифицированного пользователя с опциональной фильтрацией и пагинацией.

Parameters:

• default (boolean, optional): Фильтр по дефолтному публичному токену

• limit (number, optional): Максимальное число токенов на страницу (1-100)

• sortby (string, optional): Сортировка токенов по времени создания или изменения

• start (string, optional): ID токена, после которого начинать перечисление (при указании отключается авто-пагинация)

• usage (string, optional): Фильтр по типу токена: "pk" (public)

Пагинация:

• При отсутствии start токены собираются по всем страницам

• При наличии start возвращается только запрошенная страница

Example:

{
  "limit": 10,
  "sortby": "created",
  "usage": "pk"
}

Example prompts:

• "List all my Mapbox tokens"

• "Show me my public tokens sorted by creation date"

• "Find my default public token"

• "List the 5 most recently modified tokens"

• "Show all public tokens in my account"

Feedback Tools

Доступ к элементам обратной связи пользователей через Mapbox Feedback API. Эти инструменты позволяют получать и просматривать проблемы, предложения и замечания пользователей о данных карты, маршрутизации и деталях POI.

list_feedback_tool - Перечень элементов обратной связи с расширенной фильтрацией, сортировкой и пагинацией.

Parameters:

• feedback_ids (array of UUIDs, optional): Фильтр по одному или нескольким ID элементов

• after (string, optional): Курсор из предыдущего ответа для пагинации

• limit (number, optional): Максимальное число элементов на ответ (1-1000, значение по умолчанию варьируется)

• sort_by (string, optional): Поле сортировки - received_at (по умолчанию), created_at, или updated_at

• order (string, optional): Направление сортировки - asc (по умолчанию) или desc

• status (array, optional): Фильтр по статусу - received, fixed, reviewed, out_of_scope

• category (array, optional): Фильтр по категориям отзывов

• search (string, optional): Поисковая фраза для соответствия тексту отзыва

• trace_id (array, optional): Фильтр по trace IDs

• created_before, created_after (ISO 8601 string, optional): Фильтр по диапазону создания

• received_before, received_after (ISO 8601 string, optional): Фильтр по диапазону получения

• updated_before, updated_after (ISO 8601 string, optional): Фильтр по диапазону обновления

• format (string, optional): Формат вывода - formatted_text (по умолчанию) или json_string

Returns: Пагинационный список элементов обратной связи с курсорами пагинации.

get_feedback_tool - Получить один элемент обратной связи пользователя по его уникальному ID.

Parameters:

• feedback_id (UUID, required): Уникальный идентификатор элемента

• format (string, optional): Формат вывода - formatted_text (по умолчанию) или json_string

Returns: Один элемент обратной связи с деталями, включая статус, категорию, текст отзыва, локацию и временные штампы.

⚠️ Required Token Scope:

• Оба инструмента обратной связи требуют user-feedback:read на токене доступа

Example prompts:

• "List all feedback items with status 'fixed'"

• "Show me feedback items in the 'poi_details' category created after July 1st"

• "Get feedback item with ID 40eae4c7-b157-4b49-a091-7e1099bba77e"

• "Find feedback items containing 'apartment building' in the feedback text"

• "List all routing issue feedback from the last month"

Local Processing Tools

GeoJSON Preview tool (Beta)

Генерирует URL geojson.io для визуализации GeoJSON. Этот инструмент:

• Валидирует формат GeoJSON (Point, LineString, Polygon, Feature, FeatureCollection и пр.)

• Возвращает прямую ссылку на geojson.io для мгновенной визуализации

• Поддерживает как объекты GeoJSON, так и JSON-строки в качестве входа

Example usage:

{
  "geojson": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Returns: Одну строку URL, которую можно открыть в браузере для просмотра GeoJSON.

Note: Это бета-функция, сейчас оптимизирована под GeoJSON небольшого и среднего размера. Большие GeoJSON-файлы могут приводить к очень длинным URL и меньшей скорости. В будущем планируем оптимизировать это другим способом обработки больших наборов данных.

Example prompts:

• "Generate a preview URL for this GeoJSON data"

• "Create a geojson.io link for my uploaded route.geojson file"

Validate GeoJSON tool

Проверяет корректность объектов GeoJSON на правильность структуры, координат и типов геометрий. Этот оффлайн-тег инструмент выполняет всестороннюю проверку GeoJSON без необходимости доступа к API.

Parameters:

• geojson (string or object, required): GeoJSON объект или JSON-строка для проверки

What it validates:

• Валидность типа GeoJSON (Feature, FeatureCollection, Point, LineString, Polygon и т. д.)

• Обязательные свойства (type, coordinates, geometry, features)

• Структура массива координат и допустимость позиций

• Диапазоны долготы [-180, 180] и широты [-90, 90]

• Замыкание колец полигона (первый и последний координаты должны совпадать)

• Минимальные требования к позициям (LineString требует 2+, Polygon-ring — 4+ позиций)

Returns:

Результаты валидации, включая:

• valid (boolean): Общая корректность

• errors (array): Критические ошибки, делающие GeoJSON недействительным

• warnings (array): Не критичные проблемы (например, незакрытые кольца полигона, координаты вне диапазона)

• info (array): Информационные сообщения

• statistics: Объект с типом, количеством объектов, типами геометрий и ограничивающей рамкой

Каждая проблема включает:

• severity: "error", "warning" или "info"

• message: Описание проблемы

• path: JSON-путь к проблеме (опционально)

• suggestion: Как исправить проблему (опционально)

Example:

{
  "geojson": {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [102.0, 0.5]
    },
    "properties": {
      "name": "Test Point"
    }
  }
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [],
  "statistics": {
    "type": "Feature",
    "featureCount": 1,
    "geometryTypes": ["Point"],
    "bbox": [102.0, 0.5, 102.0, 0.5]
  }
}

Example prompts:

• "Validate this GeoJSON file and tell me if there are any errors"

• "Check if my GeoJSON coordinates are valid"

• "Is this Feature Collection properly formatted?"

Note: Это оффлайн-валидация, не требует доступа к API.

Validate Expression tool

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

Parameters:

• expression (array or string, required): Mapbox выражение для проверки (массив или JSON-строка)

What it validates:

• Синтаксис и структура выражения

• Корректность имен операторов

• Правильность количества аргументов для каждого оператора

• Вложенность выражений

• Глубина выражения (предупреждает о чрезмерной вложенности)

Returns:

Результаты валидации, включая:

• valid (boolean): Общая корректность

• errors (array): Критические ошибки

• warnings (array): Не критичные проблемы

• info (array): Информационные сообщения

• metadata: Объект с expressionType, returnType и depth

Каждая проблема включает:

• severity: "error", "warning" или "info"

• message: Описание проблемы

• path: Путь к проблеме в выражении (опционально)

• suggestion: Как исправить проблему (опционально)

Supported expression types:

• Data: get, has, id, geometry-type, feature-state, properties

• Lookup: at, in, index-of, slice, length

• Decision: case, match, coalesce

• Ramps & interpolation: interpolate, step

• Math: +, -, *, /, %, ^, sqrt, log10, log2, ln, abs, etc.

• String: concat, downcase, upcase, is-supported-script

• Color: rgb, rgba, to-rgba, hsl, hsla

• Type: array, boolean, collator, format, image, literal, number, number-format, object, string, to-boolean, to-color, to-number, to-string, typeof

• Camera: zoom, pitch, distance-from-center

• Variable binding: let, var

Example:

{
  "expression": ["get", "population"]
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [
    {
      "severity": "info",
      "message": "Expression validated successfully"
    }
  ],
  "metadata": {
    "expressionType": "data",
    "returnType": "any",
    "depth": 1
  }
}

Example prompts:

• "Validate this Mapbox expression: ["get", "population"]"

• "Check if this interpolation expression is correct"

• "Is this expression syntax valid for Mapbox styles?"

Note: Это оффлайн-валидация, не требует доступа к API.

Coordinate Conversion tool

Преобразование координат между системами координат (CRS), в частности между WGS84 (EPSG:4326) и Web Mercator (EPSG:3857).

Parameters:

• coordinates (array, required): Массив пар координат для преобразования. Каждая пара координат должна быть [longitude, latitude] для WGS84 или [x, y] для Web Mercator

• fromCRS (string, required): Исходная система координат. Поддерживаемые значения: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)

• toCRS (string, required): Целевая система координат. Поддерживаемые значения: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)

Returns:

Массив преобразованных пар координат в целевой CRS.

Example:

{
  "coordinates": [
    [-122.4194, 37.7749],
    [-74.006, 40.7128]
  ],
  "fromCRS": "EPSG:4326",
  "toCRS": "EPSG:3857"
}

Example prompts:

• "Convert these coordinates from WGS84 to Web Mercator: [-122.4194, 37.7749] и [-74.006, 40.7128]"

• "Convert the coordinates [-13627361.0, 4544761.0] from Web Mercator to WGS84"

Bounding Box tool

Вычисляет ограничивающий прямоугольник (bounding box) для заданного содержимого GeoJSON и возвращает координаты в формате [minX, minY, maxX, maxY].

Parameters:

• geojson (string or object, required): GeoJSON-содержимое для вычисления bounding box. Может быть передано как:

A JSON string that will be parsed

• A GeoJSON object

Supported GeoJSON types:

• Point

• LineString

• Polygon

• MultiPoint

• MultiLineString

• MultiPolygon

• GeometryCollection

• Feature

• FeatureCollection

Returns:

Массив four чисел, представляющий bounding box: [minX, minY, maxX, maxY]

• minX: Западная граница долготы

• minY: Южная граница широты

• maxX: Восточная граница долготы

• maxY: Северная граница широты

Example:

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-73.9857, 40.7484]
        },
        "properties": {}
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-74.006, 40.7128]
        },
        "properties": {}
      }
    ]
  }
}

Example prompts:

• "Calculate the bounding box of this GeoJSON file" (then upload a .geojson file)

• "What's the bounding box for the coordinates in the uploaded parks.geojson file?"

Color Contrast Checker tool

Проверяет соотношение контраста цветов между передним планом и фоном на соответствие WCAG 2.1.

Parameters:

• foregroundColor (string, required): Цвет переднего плана (цвет текста) в любом CSS-формате (hex, rgb, rgba, именованные цвета)

• backgroundColor (string, required): Цвет фона в любом CSS-формате (hex, rgb, rgba, именованные цвета)

• level (string, optional): Уровень соответствия WCAG, для проверки ("AA" или "AAA", по умолчанию: "AA")

• fontSize (string, optional): Категория размера шрифта ("normal" или "large", по умолчанию: "normal")

Normal: < 18pt или < 14pt жирного

• Large: ≥ 18pt или ≥ 14pt жирного

Color format support:

• Hex colors: #RGB, #RRGGBB, #RRGGBBAA

• RGB/RGBA: rgb(r, g, b), rgba(r, g, b, a)

• Named colors: black, white, red, blue, gray, и т. д.

WCAG 2.1 requirements:

• WCAG AA: 4.5:1 для обычного текста, 3:1 для крупного текста

• WCAG AAA: 7:1 для обычного текста, 4.5:1 для крупного текста

Returns:

JSON-объект с:

• contrastRatio: Вычисленное соотношение контраста (например, 21 для черного на белом)

• passes: Соответствует ли комбинация заданному уровню WCAG

• level: Уровень WCAG, который проверялся ("AA" или "AAA")

• fontSize: Категория размера шрифта ("normal" или "large")

• minimumRequired: Минимальное требование контраста для уровня и размера шрифта

• wcagRequirements: Полные требования WCAG по контрасту для всех уровней

• recommendations: Массив предложений (включаются только при несоответствии контраста)

Example:

{
  "contrastRatio": 21,
  "passes": true,
  "level": "AA",
  "fontSize": "normal",
  "minimumRequired": 4.5,
  "wcagRequirements": {
    "AA": { "normal": 4.5, "large": 3.0 },
    "AAA": { "normal": 7.0, "large": 4.5 }
  }
}

Example prompts:

• "Check if black text on white background is WCAG AA compliant"

• "What's the contrast ratio between #4264fb and white?"

• "Does gray text (#767676) on white meet AAA standards for large text?"

• "Check color contrast for rgb(51, 51, 51) on rgb(245, 245, 245)"

• "Is this color combination accessible: foreground 'navy' on background 'lightblue'?"

compare_styles_tool

Сравнивает два стиля Mapbox и сообщает о структурных различиях, включая изменения слоёв, источников и свойств. Этот оффлайн-инструмент выполняет глубокое сравнение без необходимости доступа к API.

Parameters:

• styleA (string or object, required): Первый стиль Mapbox для сравнения (JSON-строка или объект стиля)

• styleB (string or object, required): Второй стиль Mapbox для сравнения (JSON-строка или объект стиля)

• ignoreMetadata (boolean, optional): Если true, игнорирует поля метаданных (id, owner, created, modified, draft, visibility) при сравнении

Comparison features:

• Глубокое рекурсивное сравнение вложенных структур

• Сравнение слоёв по ID (а не по позиции в массиве)

• Детализированный отчет о различиях с путями в JSON

• Выявление дополнений, удалений и изменений

• Фильтрация метаданных по запросу

Returns:

{
  "identical": false,
  "differences": [
    {
      "path": "layers.water.paint.fill-color",
      "type": "modified",
      "valueA": "#a0c8f0",
      "valueB": "#b0d0ff",
      "description": "Modified property at layers.water.paint.fill-color"
    }
  ],
  "summary": {
    "totalDifferences": 1,
    "added": 0,
    "removed": 0,
    "modified": 1
  }
}

Example prompts:

• "Compare these two Mapbox styles and show me the differences"

• "What changed between my old style and new style?"

• "Compare styles ignoring metadata fields"

Style Optimization tool

Оптимизация стилей Mapbox за счёт устранения избыточности, упрощения выражений и уменьшения размера файла.

Parameters:

• style (string or object, required): Стиль Mapbox для оптимизации (JSON-строка или стиль-объект)

• optimizations (array, optional): Специфические оптимизации, которые нужно применить. Если не указаны, применяются все доступные оптимизации. Доступные оптимизации:

remove-unused-sources: Удаление источников, не используемых ни одной слоем

• remove-duplicate-layers: Удаление дубликатов слоёв

• simplify-expressions: Упрощение выражений

• remove-empty-layers: Удаление слоёв без видимых свойств (кроме слоёв фона)

• consolidate-filters: Выявление групп слоёв с идентичными фильтрами для консолидации

Optimizations performed:

• Remove unused sources: Выявление и удаление определений источников, не связанных с слоями

• Remove duplicate layers: Поиск и удаление дубликатов слоёв по свойствам

• Simplify expressions: Упрощение логики в фильтрах и выражениях свойств:

["all", true] → true

• ["any", false] → false

• ["!", false] → true

• ["!", true] → false

• Remove empty layers: Удаление слоёв без свойств paint или layout (сохранение фоновых слоёв)

• Consolidate filters: Выявление групп слоёв с идентичными выражениями фильтра

Returns:

JSON-объект с:

• optimizedStyle: Оптимизированный Mapbox стиль

• optimizations: Массив применённых оптимизаций

• summary: Статистика, включая сохранение размера и относительную экономию

Example:

{
  "optimizedStyle": { "version": 8, "sources": {}, "layers": [] },
  "optimizations": [
    {
      "type": "remove-unused-sources",
      "description": "Removed 2 unused source(s): unused-source1, unused-source2",
      "count": 2
    }
  ],
  "summary": {
    "totalOptimizations": 2,
    "originalSize": 1234,
    "optimizedSize": 890,
    "sizeSaved": 344,
    "percentReduction": 27.88
  }
}

Example prompts:

• "Optimize this Mapbox style to reduce its file size"

• "Remove unused sources from my style"

• "Simplify the expressions in this style"

• "Find and remove duplicate layers in my map style"

• "Optimize my style but only remove unused sources and empty layers"

Agent Skills

Этот репозиторий включает Agent Skills, которые предоставляют профильные знания для построения карт с Mapbox. Навыки обучают AI-ассистентов принципам проектирования карт, лучшим практикам безопасности и общим паттернам реализации.

Available Skills:

• 🎨 mapbox-cartography: Принципы проектирования карт, теория цвета, визуальная иерархия, типографика

• 🔐 mapbox-token-security: Управление токенами, контроль областей, ограничения по URL, стратегии ротации

• 📐 mapbox-style-patterns: Распространённые схемы стилей и конфигурации слоёв для типичных сценариев

• 🔧 mapbox-integration-patterns: Паттерны интеграции для React, Vue, Svelte, Angular и ванильного JS

• ✅ mapbox-style-quality: Экспертное руководство по валидации, оптимизации и обеспечению качества стилей Mapbox через проверки и доступность

Навыки дополняют MCP server, предоставляя экспертизу (как думать о дизайне), в то время как инструменты предоставляют возможности (как выполнять действия).

Для полной документации и инструкций по использованию смотрите skills/README.md.

Using Skills with Claude Code

Чтобы использовать эти навыки в Claude Code, создайте символьную ссылку:

mkdir -p .claude
ln -s ../skills .claude/skills

Или скопируйте в ваш глобальный каталог навыков:

cp -r skills/* ~/.claude/skills/

Using Skills with Claude API

Загрузите навыки в виде zip-архивов через Skills API. См. Claude API Skills documentation.

Prompts

Prompts MCP — это готовые рабочие шаблоны, которые направляют AI-ассистентов через многоступенчатые задачи. Они координируют работу нескольких инструментов в нужной последовательности, с встроенной лучшей практикой и обработкой ошибок.

Available Prompts:

create-and-preview-style

Создать новый стиль карты Mapbox и сгенерировать общедоступную ссылку-предпросмотр с автоматическим управлением токенами.

Arguments:

• style_name (required): Название нового стиля карты

• style_description (optional): Описание темы стиля или назначения

• base_style (optional): Базовый стиль для старта (например, "streets-v12", "dark-v11")

• preview_location (optional): Место для центрирования предпросмотра

• preview_zoom (optional): Уровень масштабирования предпросмотра (0-22, по умолчанию: 12)

What it does:

• Проверяет наличие существующего публичного токена с областью styles:read

• При необходимости создаёт новый публичный токен

• Создаёт стиль карты

• Генерирует ссылку предпросмотра

Example usage:

Use prompt: create-and-preview-style
Arguments:
  style_name: "My Custom Map"
  style_description: "A dark-themed map for nighttime navigation"
  base_style: "dark-v11"
  preview_location: "San Francisco"
  preview_zoom: "13"

build-custom-map

Используйте диалоговый ИИ для создания настраиваемого стилизованного карты на основе описания темы.

Arguments:

• theme (required): Описание темы (например, "dark cyberpunk", "nature-focused", "minimal monochrome")

• emphasis (optional): Функции для акцентации (например, "parks and green spaces", "transit lines")

• preview_location (optional): Место для центрирования предпросмотра

• preview_zoom (optional): Уровень масштабирования предпросмотра (0-22, по умолчанию: 12)

What it does:

• Использует Style Builder tool для создания стилевой темы на основе вашего описания

• Создаёт стиль в вашей учётной записи Mapbox

• Генерирует ссылку предпросмотра

Example usage:

Use prompt: build-custom-map
Arguments:
  theme: "retro 80s neon"
  emphasis: "nightlife and entertainment venues"
  preview_location: "Tokyo"
  preview_zoom: "14"

analyze-geojson

Анализируйте и визуализируйте данные GeoJSON с автоматической валидацией и вычислением ограничивающего прямоугольника.

Arguments:

• geojson_data (required): GeoJSON объект или строка для анализа

• show_bounds (optional): Вычислять и отображать bounding box (true/false, default: true)

• convert_coordinates (optional): Примеры конвертации координат в Web Mercator (true/false, default: false)

What it does:

• Валидирует формат GeoJSON

• Вычисляет bounding box (при запросе)

• Предоставляет примеры конвертации координат (при запросе)

• Генерирует интерактивную визуализацию через ссылку

Example usage:

Use prompt: analyze-geojson
Arguments:
  geojson_data: {"type":"FeatureCollection","features":[...]}
  show_bounds: "true"
  convert_coordinates: "false"

setup-mapbox-project

Полный процесс настройки нового проекта Mapbox с корректной защитой токенов и инициализацией стиля.

Arguments:

• project_name (required): Название проекта или приложения

• project_type (optional): Тип проекта: "web", "mobile", "backend", или "fullstack" (default: "web")

• production_domain (optional): Продакшн-домен для ограничений по URL (например, "myapp.com")

• style_theme (optional): Изначальная тема стиля: "light", "dark", "streets", "outdoors", "satellite" (default: "light")

What it does:

• Создаёт development token с ограничениями по URL на localhost

• Создает production token с ограничениями по домену (при наличии)

• Создаёт backend secret token для серверной части (при необходимости)

• Создаёт начальный стиль с указанной темой

• Генерирует ссылку предпросмотра и предоставляет руководство по интеграции

Example usage:

Use prompt: setup-mapbox-project
Arguments:
  project_name: "Restaurant Finder"
  project_type: "fullstack"
  production_domain: "restaurantfinder.com"
  style_theme: "light"

debug-mapbox-integration

Систематизированный workflow устранения неполадок в интеграции Mapbox.

Arguments:

• issue_description (required): Описание проблемы (например, "map not loading", "401 error")

• error_message (optional): Точное сообщение об ошибке из консоли или логов

• style_id (optional): ID стиля Mapbox, применяемый по умолчанию

• environment (optional): Где возникает проблема: "development", "production", "staging"

What it does:

• Проверяет валидность токена и необходимые области

• Анализирует конфигурацию стиля и его существование

• Анализирует сообщения об ошибках и предлагает конкретные решения

• Тестирует API endpoints для локализации проблемы

• Предоставляет пошаговые инструкции по исправлению

• Предоставляет стратегии предотвращения

Example usage:

Use prompt: debug-mapbox-integration
Arguments:
  issue_description: "Getting 401 errors when map loads"
  error_message: "401 Unauthorized"
  style_id: "my-style-id"
  environment: "production"

design-data-driven-style

Создать стиль карты с данными, где свойства зависят от данных объектов с использованием выражений.

Arguments:

• style_name (required): Имя создаваемого стиля на основе данных

• data_description (required): Описание данных (например, "population by city", "earthquake magnitudes")

• property_name (required): Имя свойства данных для визуализации (например, "population", "magnitude")

• visualization_type (optional): Как визуализировать: "color", "size", "both", "heatmap" (default: "color")

• color_scheme (optional): Цветовая схема: "sequential", "diverging", "categorical" (default: "sequential")

What it does:

• Объясняет концепции и выражения для стилизации по данным

• Предоставляет соответствующие шаблоны выражений под ваш сценарий

• Предлагает цветовые шкалы и диапазоны размеров на основе типа визуализации

• Создаёт стиль с данными-ориентированными слоями

• Включает расширенные примеры выражений (изменение с зумом, условные выражения)

• Предоставляет лучшие практики по доступности и производительности

Example usage:

Use prompt: design-data-driven-style
Arguments:
  style_name: "Population Density Map"
  data_description: "City population data"
  property_name: "population"
  visualization_type: "both"
  color_scheme: "sequential"

prepare-style-for-production

Комплексная проверка качества стилей Mapbox перед выводом в продакшн.

Arguments:

• style_id_or_json (required): Либо ID стиля Mapbox, либо полный стиль JSON

• skip_optimization (optional): Установите в "true", чтобы пропустить оптимизацию стиля (по умолчанию: false)

• wcag_level (optional): Уровень соответствия WCAG: "AA" или "AAA" (default: "AA")

What it does:

• Загружает стиль (получает данные из Mapbox или парсит JSON)

• Валидирует все выражения (filters, paint и layout)

• Валидирует GeoJSON источники на корректность координат и структуры

• Проверяет контраст текста в слоях цвета (соответствие WCAG)

• Оптимизирует стиль (удаление дублирующих элементов, упрощение выражений)

• Генерирует подробный отчёт о качестве и готовности к развёртыванию

Example usage:

Use prompt: prepare-style-for-production
Arguments:
  style_id_or_json: "username/my-style-id"
  wcag_level: "AA"
  skip_optimization: "false"

Related:

Смотрите руководство по навыку mapbox-style-quality для подробных указаний о том, когда использовать инструменты валидации, лучшие практики и стратегии оптимизации.

Resources

Этот сервер предоставляет статическую справку в виде MCP Resources. MCP-клиенты, поддерживающие протокол ресурсов, могут получать их напрямую.

Available Resources:

Mapbox Style Specification Guide (resource://mapbox-style-layers)

Полное руководство по слоям Mapbox GL JS и свойствам

• Освещает слои fill, line, symbol, circle и fill-extrusion

• Включает свойства paint и layout для каждого типа слоя

Mapbox Streets v8 Fields Reference (resource://mapbox-streets-v8-fields)

Определения полей для всех слоёв Streets v8

• Перечисляемые значения для фильтруемых полей

• Важны для построения точных фильтров стилей

• Пример: слой landuse имеет поле class со значениями вроде park, cemetery, hospital и т. д.

Mapbox Token Scopes Reference (resource://mapbox-token-scopes)

Полная документация по областям токенов

• Разъяснение различий между публичными и секретными токенами

• Распространённые сочетания областей для разных сценариев использования

• Лучшие практики управления токенами

Mapbox Layer Type Mapping (resource://mapbox-layer-type-mapping)

Соотношение слоёв Streets v8 с совместимыми типами слоёв GL JS

• Организовано по типам геометрии (полигон, линия, точка)

• Включает общие примеры и паттерны использования

• Помогает избегать несовместимых сочетаний тип слоёв/слой источника

Note: Resources предоставляют статическую справку, которая не меняется часто, в то время как инструменты возвращают динамические данные, зависящие от пользователя, и позволяют выполнить действия (создать стили или токены и т. д.).

Observability & Tracing

Этот сервер включает всестороннюю распределённую трасировку с использованием OpenTelemetry (OTEL) для готовой к продакшну наблюдаемости.

Features

• Opt-in Configuration: трассировка отключена по умолчанию, включение требует только указания OTLP endpoint

• Tool Execution Tracing: автоматическая инструментированная трассировка выполнения инструментов с таймингами, статусом успеха/ошибки и деталями ошибок

• HTTP Request Instrumentation: полная трасировка HTTP-запросов/ответов к Mapbox API с корреляционными IDs CloudFront

• Configuration Tracing: загрузка конфигурации на старте с отслеживанием ошибок

• Security: размер входных/выходных данных логируется, содержимое защищено

• Low Overhead: <1% CPU-влияния, ~10MB памяти для буферов трасс

Quick Start with Jaeger

# 1. Запустите Jaeger (требуется Docker)
npm run tracing:jaeger:start

# 2. Настройте окружение
cp .env.example .env
# Отредактируйте .env, чтобы добавить MAPBOX_ACCESS_TOKEN
# OTEL_EXPORTER_OTLP_ENDPOINT уже установлен на http://localhost:4318

# 3. Запустите сервер
npm run inspect:build

# 4. Посмотрите трассы по адресу http://localhost:16686

# 5. Остановите Jaeger по окончании
npm run tracing:jaeger:stop

Supported Backends

Сервер поддерживает любой OTLP-совместимый бэкенд, включая:

• Development: Jaeger (локальный Docker)

• Cloud Providers: AWS X-Ray, Azure Monitor, Google Cloud Trace

• SaaS Platforms: Datadog, New Relic, Honeycomb

Смотрите .env.example для примеров конфигурации для каждой платформы.

Documentation

• Complete Tracing Guide - Подробная настройка, возможности и примеры интеграции

• Verification Guide - Пошаговая верификация и устранение неполадок

Environment Variables

# Включение трассировки (обязательно)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Опциональная конфигурация
OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1  # Пример: выборка 10% при большом объёме

Development

Testing

Tool Snapshot Tests

Проект включает snapshot-тесты, чтобы обеспечить целостность инструментов и предотвратить случайное добавление или удаление инструментов. Эти тесты автоматически обнаруживают все инструменты и создают снимок их метаданных.

What the snapshot test covers:

• Названия классов инструментов (TypeScript-классы следуют конвенции PascalCaseTool, например ListStylesTool)

• Названия инструментов (MCP-идентификаторы должны соответствовать конвенции snake_case_tool, например list_styles_tool)

• Описание инструментов

When to update snapshots:

Добавление нового инструмента: после создания нового инструмента запустите тест с флагом обновления снапшета:

npm test -- test/tools/tool-naming-convention.test.ts --updateSnapshot

Удаление инструмента: после удаления инструмента обновите снапшет:

npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot

Изменение метаданных инструмента: если вы изменили имя или описание инструмента, обновите снапшет:

npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot

Running snapshot tests:

# Запуск всех тестов (снапшоты будут падать, если инструменты изменились)
npm test

# Обновление снапшотов после преднамеренных изменений
npm test -- --updateSnapshot

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

Inspecting Server

Using Node.js

# Запуск собранного образа
npm run inspect:build

Using Docker

# Сборка Docker-образа
docker build -t mapbox-mcp-devkit .

# Запуск и инспекция сервера
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkit

Creating New Tools

npx plop create-tool
# 1. Выберите тип инструмента:
#    - Mapbox tool (делает API-вызовы к сервисам Mapbox)
#    - Local tool (локальная обработка, без вызовов API)
# 2. Укажите имя инструмента без суффикса в стиле PascalCase (например, Search)

Generated file structure:

Генератор plop создаёт три файла для каждого нового инструмента: