mcp-devkit-server

Mapbox 开发者 MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 助手直接访问 Mapbox 开发者 API。该服务使 AI 模型能够与 Mapbox 服务交互，帮助开发者更高效地构建 Mapbox 应用。

需要访问 Mapbox 文档？ 请将 mcp-docs-server 与此服务搭配使用——它可让 AI 助手访问 docs.mapbox.com 上的 Mapbox 文档、指南和 API 参考。

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

目录

• Mapbox 开发者 MCP 服务
  • 目录
  • 快速开始
    • 与开发者工具集成
    • DXT 包分发
      • 创建 DXT 包
    • 托管的 MCP 端点
    • 获取 Mapbox 访问令牌
  • 工具
    • 参考工具
    • 样式管理工具
    • 令牌管理工具
      • create-token
      • list-tokens
    • 反馈工具
    • 本地处理工具
      • GeoJSON 预览工具（Beta）
      • 坐标转换工具
      • 边界框工具
      • compare_styles_tool
      • 样式优化工具
  • 资源
  • 可观测性与追踪
    • 功能
    • 使用 Jaeger 快速开始
    • 支持的后端
    • 文档
    • 环境变量
  • 开发
    • 测试
      • 工具快照测试
    • 检查服务
      • 使用 Node.js
      • 使用 Docker
    • 创建新工具
    • 环境变量
      • VERBOSE_ERRORS
  • 故障排除
  • 发布流程
  • 贡献

快速开始

与开发者工具集成

通过与首选的 AI 开发环境集成，快速开始使用：

• Claude Code 集成 - 使用 Claude 进行命令行开发
• Claude Desktop 集成 - 桌面应用集成
• Cursor 集成 - Cursor IDE 集成
• VS Code 集成 - 搭配 GitHub Copilot 使用 Visual Studio Code

DXT 包分发

此 MCP 服务可打包为 DXT（桌面扩展）文件，以便轻松分发和安装。DXT 是一种用于分发本地 MCP 服务的标准化格式，类似于浏览器扩展。

创建 DXT 包

创建 DXT 包：

# Install the DXT CLI tool
npm install -g @anthropic-ai/dxt

# Build the server first
npm run build

# Create the DXT package
npx @anthropic-ai/dxt pack

这将使用 manifest.json 中的配置生成 mcp-devkit-server.dxt。

DXT 包包含：

• 预构建的服务代码（dist/esm/index.js）
• 服务元数据和配置
• Mapbox 访问令牌的用户配置架构
• 自动设置环境变量

托管的 MCP 端点

如需快速访问，可以使用我们托管的 MCP 端点：

端点：https://mcp-devkit.mapbox.com/mcp

有关不同客户端的详细设置说明和 API 用法，请参阅托管 MCP 服务指南。注意：本指南引用的是标准 MCP 端点——你需要将端点 URL 更新为上方的 devkit 端点。

获取 Mapbox 访问令牌

使用此 MCP 服务需要 Mapbox 访问令牌。

1. 在 mapbox.com/signup 注册免费的 Mapbox 账户
2. 前往你的账户页面
3. 创建一个新令牌，并为你的使用场景授予所需权限范围

有关 Mapbox 访问令牌的更多信息，请参阅 Mapbox 关于访问令牌的文档。

⚠️ 重要：所需令牌权限

必须设置 MAPBOX_ACCESS_TOKEN 环境变量。**每个工具都需要特定的令牌权限范围才能正常运行。**例如：

• 读取样式需要 styles:read 权限范围
• 创建样式需要 styles:write 权限范围
• 管理令牌需要 tokens:read 和 tokens:write 权限范围
• 访问反馈需要 user-feedback:read 权限范围

工具

参考工具

参考数据以 MCP 资源的形式提供（参见资源部分）。支持资源协议的 MCP 客户端可以直接访问这些资源。

可用参考资料：

• 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 字段参考”
• “显示地图需要哪些权限范围？”

样式管理工具

用于通过 Styles API 管理 Mapbox 样式的完整工具集：

Style Builder Tool - 通过对话提示词，以编程方式创建和修改 Mapbox 样式

📖 查看 Style Builder 文档，了解详细用法和示例 →

ListStylesTool - 列出 Mapbox 账户的所有样式

• 输入：limit（可选——样式数量上限）、start（可选——分页令牌）
• 返回：样式元数据数组，可包含分页信息

CreateStyleTool - 创建新的 Mapbox 样式

• 输入：name、style（Mapbox 样式规范）
• 返回：已创建样式的详细信息及 ID

RetrieveStyleTool - 按 ID 获取特定样式

• 输入：styleId
• 返回：完整的样式规范

UpdateStyleTool - 更新现有样式

• 输入：styleId、name（可选）、style（可选）
• 返回：已更新样式的详细信息

DeleteStyleTool - 按 ID 删除样式

• 输入：styleId
• 返回：成功确认信息

PreviewStyleTool - 使用现有的公开令牌生成 Mapbox 样式预览 URL

• 输入：styleId、title（可选）、zoomwheel（可选）、zoom（可选）、center（可选）、bearing（可选）、pitch（可选）
• 返回：在浏览器中打开样式预览的 URL
• 注意：此工具会自动从你的账户中获取第一个可用的公开令牌，用于生成预览 URL。至少需要一个具有 styles:read 范围的公开令牌。

ValidateStyleTool - 根据 Mapbox Style Specification 验证 Mapbox 样式 JSON

• 输入：style（Mapbox 样式 JSON 对象或 JSON 字符串）
• 返回：验证结果，包括错误、警告、提示信息和样式摘要
• 执行全面的离线验证，检查：
  • 必需字段（version、sources、layers）
  • 有效的图层和来源类型
  • 来源引用和图层 ID
  • 常见配置问题
• 注意：这是离线验证工具，无需 API 访问权限或令牌范围

⚠️ 必需的令牌范围：

所有样式工具都需要具有特定范围的有效 Mapbox 访问令牌。使用范围不正确的令牌会导致身份验证错误。

• ListStylesTool：需要 styles:list 范围
• CreateStyleTool：需要 styles:write 范围
• RetrieveStyleTool：需要 styles:download 范围
• UpdateStyleTool：需要 styles:write 范围
• DeleteStyleTool：需要 styles:write 范围
• PreviewStyleTool：需要 tokens:read 范围（用于列出令牌），且至少需要一个具有 styles:read 范围的公开令牌

注意： 用户名会从 JWT 令牌载荷中自动提取。

提示词示例：

• “可以帮我创建一个圣诞主题的样式吗？”
• “请为这个样式生成预览链接”
• “可以把背景改成雪景风格吗？”

令牌管理工具

create-token

创建具有指定范围和可选 URL 限制的新 Mapbox 访问令牌。

参数：

• note（字符串，必需）：令牌说明
• scopes（字符串数组，必需）：令牌的范围／权限数组。必须是有效的 Mapbox 范围（见下文）
• allowedUrls（字符串数组，可选）：可使用此令牌的 URL（最多 100 个）
• expires（字符串，可选）：ISO 8601 格式的到期时间（最晚为未来 1 小时）

可用范围：

公开令牌可用的范围：

• styles:tiles - 以栅格瓦片形式读取样式
• styles:read - 读取样式
• fonts:read - 读取字体
• datasets:read - 读取数据集
• vision:read - 读取 Vision API

示例：

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

提示词示例：

• “为我的 Web 应用创建一个具有 styles:read 和 fonts:read 权限的新 Mapbox 令牌”
• “生成一个 30 分钟后过期、具有 styles:tiles 和 vision:read 范围的令牌”
• “创建一个仅适用于 https://myapp.com、具有 styles:read、fonts:read 和 datasets:read 权限的受限令牌”

list-tokens

列出已通过身份验证的用户的 Mapbox 访问令牌，并支持筛选和分页。

参数：

• default（布尔值，可选）：筛选并仅显示默认公共令牌
• limit（数字，可选）：每页返回的最大令牌数（1-100）
• sortby（字符串，可选）：按「created」或「modified」时间戳对令牌排序
• start（字符串，可选）：开始列出时所依据的令牌 ID（提供此参数时会禁用自动分页）
• usage（字符串，可选）：按令牌类型筛选：「pk」（公共）

分页行为：

• 未提供 start 参数时，工具会自动获取所有页面的结果
• 提供 start 参数时，仅返回请求的页面（用于手动控制分页）

示例：

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

示例提示词：

• 「列出我的所有 Mapbox 令牌」
• 「显示我的公共令牌，并按创建日期排序」
• 「查找我的默认公共令牌」
• 「列出最近修改的 5 个令牌」
• 「显示我账户中的所有公共令牌」

反馈工具

通过 Mapbox Feedback API 访问用户反馈条目。这些工具可用于检索和查看用户报告的有关地图数据、路线规划和 POI 详情的问题、建议与反馈。

list_feedback_tool - 列出用户反馈条目，并提供全面的筛选、排序和分页选项。

参数：

• feedback_ids（UUID 数组，可选）：按一个或多个反馈条目 ID 筛选
• after（字符串，可选）：用于分页的上一次响应中的游标
• limit（数字，可选）：返回的最大条目数（1-1000，默认值因情况而异）
• sort_by（字符串，可选）：排序字段：received_at（默认）、created_at 或 updated_at
• order（字符串，可选）：排序方向：asc（默认）或 desc
• status（数组，可选）：按状态筛选：received、fixed、reviewed、out_of_scope
• category（数组，可选）：按反馈类别筛选
• search（字符串，可选）：用于匹配反馈文本的搜索词
• trace_id（数组，可选）：按轨迹 ID 筛选
• created_before、created_after（ISO 8601 字符串，可选）：按创建日期范围筛选
• received_before、received_after（ISO 8601 字符串，可选）：按接收日期范围筛选
• updated_before、updated_after（ISO 8601 字符串，可选）：按更新日期范围筛选
• format（字符串，可选）：输出格式：formatted_text（默认）或 json_string

**返回：**包含分页游标的分页反馈条目列表。

get_feedback_tool - 根据唯一 ID 获取单条用户反馈。

参数：

• feedback_id（UUID，必填）：反馈条目的唯一标识符
• format（字符串，可选）：输出格式：formatted_text（默认）或 json_string

**返回：**包含状态、类别、反馈文本、位置和时间戳等详细信息的单条反馈。

⚠️ 必需的令牌范围：

• 两个反馈工具：访问令牌必须具有 user-feedback:read 范围

示例提示词：

• 「列出所有状态为『fixed』的反馈条目」
• 「显示『poi_details』类别中 7 月 1 日之后创建的反馈条目」
• 「获取 ID 为 40eae4c7-b157-4b49-a091-7e1099bba77e 的反馈条目」
• 「查找反馈文本中包含『apartment building』的反馈条目」
• 「列出上个月所有与路线规划问题相关的反馈」

本地处理工具

GeoJSON 预览工具（Beta）

生成 geojson.io URL，以可视化 GeoJSON 数据。此工具：

• 验证 GeoJSON 格式（Point、LineString、Polygon、Feature、FeatureCollection 等）
• 返回可直接访问 geojson.io 的 URL，即时可视化数据
• 支持将 GeoJSON 对象和 JSON 字符串作为输入

用法示例：

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

**返回：**一个 URL 字符串，可在浏览器中打开以查看 GeoJSON 数据。

**注意：**这是一项 Beta 功能，目前针对中小型 GeoJSON 文件进行了优化。大型 GeoJSON 文件可能会导致 URL 非常长且性能较慢。我们计划在未来版本中通过实现其他处理大型数据集的方式进行优化。

提示词示例：

• “为这份 GeoJSON 数据生成预览 URL”
• “为我上传的 route.geojson 文件创建一个 geojson.io 链接”

验证 GeoJSON 工具

验证 GeoJSON 对象是否正确，并检查其结构、坐标和几何类型。此离线验证工具无需 API 访问权限，即可全面检查 GeoJSON 数据。

参数：

• geojson（字符串或对象，必需）：要验证的 GeoJSON 对象或 JSON 字符串

验证内容：

• GeoJSON 类型是否有效（Feature、FeatureCollection、Point、LineString、Polygon 等）
• 必需属性（type、coordinates、geometry、features）
• 坐标数组结构和位置是否有效
• 经度范围 [-180, 180] 和纬度范围 [-90, 90]
• Polygon 环是否闭合（首尾坐标应一致）
• 最少位置数要求（LineString 至少需要 2 个位置，Polygon 环至少需要 4 个位置）

返回：

验证结果包括：

• valid（布尔值）：整体有效性
• errors（数组）：导致 GeoJSON 无效的严重错误
• warnings（数组）：非严重问题（例如，未闭合的 Polygon 环、超出范围的坐标）
• info（数组）：说明性消息
• statistics：包含类型、要素数量、几何类型和边界框的对象

每个问题都包含：

• severity：“error”“warning”或“info”
• message：问题描述
• path：指向问题的 JSON 路径（可选）
• suggestion：问题修复建议（可选）

示例：

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

返回：

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

提示词示例：

• “验证这个 GeoJSON 文件，并告诉我是否有错误”
• “检查我的 GeoJSON 坐标是否有效”
• “这个 Feature Collection 的格式是否正确？”

**注意：**这是一款离线验证工具，无需 API 访问权限或令牌范围。

验证表达式工具

验证 Mapbox 样式表达式的语法、运算符和参数是否正确。此离线验证工具可全面检查 Mapbox 表达式，无需访问 API。

参数：

• expression（数组或字符串，必填）：要验证的 Mapbox 表达式（数组格式或 JSON 字符串）

验证内容：

• 表达式语法和结构
• 运算符名称是否有效
• 各运算符的参数数量是否正确
• 嵌套表达式验证
• 表达式深度（对深度嵌套的表达式发出警告）

返回：

验证结果包括：

• valid（布尔值）：整体是否有效
• errors（数组）：导致表达式无效的严重错误
• warnings（数组）：非严重问题（例如，表达式深度嵌套）
• info（数组）：信息性消息
• metadata：包含 expressionType、returnType 和 depth 的对象

每个问题都包括：

• severity：「error」、「warning」或「info」
• message：问题描述
• path：表达式中问题所在的位置（可选）
• suggestion：问题修复方法（可选）

支持的表达式类型：

• 数据：get、has、id、geometry-type、feature-state、properties
• 查找：at、in、index-of、slice、length
• 判断：case、match、coalesce
• 渐变和插值：interpolate、step
• 数学：+、-、*、/、%、^、sqrt、log10、log2、ln、abs 等
• 字符串：concat、downcase、upcase、is-supported-script
• 颜色：rgb、rgba、to-rgba、hsl、hsla
• 类型：array、boolean、collator、format、image、literal、number、number-format、object、string、to-boolean、to-color、to-number、to-string、typeof
• 相机：zoom、pitch、distance-from-center
• 变量绑定：let、var

示例：

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

返回：

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

提示词示例：

• “验证此 Mapbox 表达式：["get", "population"]”
• “检查此插值表达式是否正确”
• “此表达式语法是否适用于 Mapbox 样式？”

**注意：**这是离线验证工具，无需访问 API 或令牌作用域。

坐标转换工具

在不同坐标参考系（CRS）之间转换坐标，具体支持 WGS84（EPSG:4326）与 Web Mercator（EPSG:3857）之间的转换。

参数：

• coordinates（数组，必填）：要转换的坐标对数组。WGS84 坐标对格式为 [longitude, latitude]，Web Mercator 坐标对格式为 [x, y]
• fromCRS（字符串，必填）：源坐标参考系。支持的值："EPSG:4326"（WGS84）、"EPSG:3857"（Web Mercator）
• toCRS（字符串，必填）：目标坐标参考系。支持的值："EPSG:4326"（WGS84）、"EPSG:3857"（Web Mercator）

返回：

目标 CRS 格式的转换后坐标对数组。

示例：

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

提示词示例：

• “将这些坐标从 WGS84 转换为 Web Mercator：[-122.4194, 37.7749] 和 [-74.006, 40.7128]”
• “将坐标 [-13627361.0, 4544761.0] 从 Web Mercator 转换为 WGS84”

边界框工具

计算给定 GeoJSON 内容的边界框，并以 [minX, minY, maxX, maxY] 的形式返回坐标。

参数：

• geojson（字符串或对象，必填）：用于计算边界框的 GeoJSON 内容。可按以下形式提供：
  • 将解析的 JSON 字符串
  • GeoJSON 对象

支持的 GeoJSON 类型：

• Point
• LineString
• Polygon
• MultiPoint
• MultiLineString
• MultiPolygon
• GeometryCollection
• Feature
• FeatureCollection

返回：

由四个数字组成的数组，表示边界框：[minX, minY, maxX, maxY]

• minX：最西侧经度
• minY：最南侧纬度
• maxX：最东侧经度
• maxY：最北侧纬度

示例：

{
  "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": {}
      }
    ]
  }
}

提示词示例：

• “计算此 GeoJSON 文件的边界框”（然后上传一个 .geojson 文件）
• “上传的 parks.geojson 文件中坐标的边界框是什么？”

颜色对比度检查工具

检查前景色与背景色之间的对比度，以确保符合 WCAG 2.1 无障碍要求。

参数：

• foregroundColor (string，必填)：任意 CSS 格式的前景色（文本颜色），例如 hex、rgb、rgba、命名颜色
• backgroundColor (string，必填)：任意 CSS 格式的背景色，例如 hex、rgb、rgba、命名颜色
• level (string，可选)：要检查的 WCAG 一致性级别（“AA”或“AAA”，默认值：“AA”）
• fontSize (string，可选)：字体大小类别（“normal”或“large”，默认值：“normal”）
  • 普通：< 18pt 或 < 14pt 粗体
  • 大号：≥ 18pt 或 ≥ 14pt 粗体

颜色格式支持：

• Hex 颜色：#RGB、#RRGGBB、#RRGGBBAA
• RGB/RGBA：rgb(r, g, b)、rgba(r, g, b, a)
• 命名颜色：black、white、red、blue、gray 等

WCAG 2.1 要求：

• WCAG AA：普通文本为 4.5:1，大号文本为 3:1
• WCAG AAA：普通文本为 7:1，大号文本为 4.5:1

返回内容：

包含以下内容的 JSON 对象：

• contrastRatio：计算得出的对比度（例如，黑色文字在白色背景上的对比度为 21）
• passes：该组合是否符合指定的 WCAG 级别
• level：检查的 WCAG 级别（“AA”或“AAA”）
• fontSize：字体大小类别（“normal”或“large”）
• minimumRequired：该级别和字体大小所需的最低对比度
• wcagRequirements：所有级别的完整 WCAG 对比度要求
• recommendations：建议数组（仅在对比度不达标时包含）

示例：

{
  "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 }
  }
}

示例提示词：

• “检查白色背景上的黑色文字是否符合 WCAG AA 标准”
• “#4264fb 和白色之间的对比度是多少？”
• “白色背景上的灰色文字（#767676）在大号文本情况下是否符合 AAA 标准？”
• “检查 rgb(51, 51, 51) 在 rgb(245, 245, 245) 上的颜色对比度”
• “这个颜色组合是否易于访问：前景色为 'navy'，背景色为 'lightblue'？”

compare_styles_tool

比较两个 Mapbox 样式并报告结构差异，包括图层、数据源和属性的变化。此离线比较工具可对对象进行深度比较，无需访问 API。

参数：

• styleA (string 或 object，必填)：要比较的第一个 Mapbox 样式（JSON 字符串或样式对象）
• styleB (string 或 object，必填)：要比较的第二个 Mapbox 样式（JSON 字符串或样式对象）
• ignoreMetadata (boolean，可选)：如果为 true，比较时忽略元数据字段（id、owner、created、modified、draft、visibility）

比较功能：

• 对嵌套结构进行深度递归比较
• 按 ID（而非数组位置）比较图层
• 通过 JSON 路径详细报告差异
• 识别新增、移除和修改
• 可选的元数据筛选

返回内容：

{
  "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
  }
}

示例提示词：

• “比较这两个 Mapbox 样式并显示差异”
• “我的旧样式和新样式之间有哪些变化？”
• “比较样式时忽略元数据字段”

样式优化工具

通过移除冗余内容、简化表达式和缩小文件大小来优化 Mapbox 样式。

参数：

• style（字符串或对象，必填）：要优化的 Mapbox 样式（JSON 字符串或样式对象）
• optimizations（数组，可选）：要执行的特定优化。如果未指定，则执行所有优化。可用的优化包括：
  • remove-unused-sources：移除未被任何图层引用的数据源
  • remove-duplicate-layers：移除完全重复的图层
  • simplify-expressions：简化布尔表达式（例如，["all", true] → true）
  • remove-empty-layers：移除不包含可见属性的图层（背景图层除外）
  • consolidate-filters：识别具有相同过滤器且可合并的图层

执行的优化：

• 移除未使用的数据源：识别并移除未被任何图层引用的数据源定义
• 移除重复图层：检测属性完全相同（ID 除外）的图层并移除重复项
• 简化表达式：简化过滤器和属性表达式中的布尔逻辑：
  • ["all", true] → true
  • ["any", false] → false
  • ["!", false] → true
  • ["!", true] → false
• 移除空图层：移除不含绘制或布局属性的图层（保留背景图层）
• 合并过滤器：识别具有相同过滤器表达式的图层组

返回值：

包含以下内容的 JSON 对象：

• optimizedStyle：优化后的 Mapbox 样式
• optimizations：已执行的优化数组
• summary：包含大小节省量和缩减百分比的统计信息

示例：

{
  "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
  }
}

示例提示词：

• “优化此 Mapbox 样式以缩小文件大小”
• “从我的样式中移除未使用的数据源”
• “简化此样式中的表达式”
• “查找并移除地图样式中的重复图层”
• “优化我的样式，但仅移除未使用的数据源和空图层”

Agent 技能

Agent 技能为使用 Mapbox 构建地图提供领域专业知识，包括地图设计、安全最佳实践和框架集成模式。这些技能现已发布在专门的 mapbox-agent-skills 仓库中，不在本仓库内。

技能通过提供专业知识（如何思考设计）来补充此 MCP 服务，而工具则提供能力（如何执行操作）。

# Install all Mapbox skills
npx add-skill mapbox/mapbox-agent-skills

# Install a specific skill
npx add-skill mapbox/mapbox-agent-skills --skill mapbox-cartography

如需查看可用技能的完整列表，以及如何在 Claude Code 或 Claude API 中使用这些技能，请参阅 mapbox-agent-skills README。

提示词

MCP 提示词是预先构建的工作流模板，可引导 AI 助手完成多步骤任务。它们会按正确顺序协调多个工具，并内置最佳实践和错误处理。

可用提示词：

create-and-preview-style

创建新的 Mapbox 地图样式，并通过自动管理令牌生成可分享的预览链接。

参数：

• style_name（必填）：新地图样式的名称
• style_description（可选）：样式主题或用途的描述
• base_style（可选）：作为起点的基础样式（例如，“streets-v12”、“dark-v11”）
• preview_location（可选）：预览地图的中心位置
• preview_zoom（可选）：预览地图的缩放级别（0-22，默认值：12）

执行内容：

1. 检查是否存在具有 styles:read 权限范围的现有公开令牌
2. 如有需要，创建新的公开令牌
3. 创建地图样式
4. 生成预览链接

使用示例：

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

使用对话式 AI，根据主题描述构建自定义样式的地图。

参数：

• theme（必填）：主题描述（例如“暗黑赛博朋克”“自然风”“极简单色”）
• emphasis（可选）：要突出显示的要素（例如“公园和绿地”“公交线路”）
• preview_location（可选）：预览地图的中心位置
• preview_zoom（可选）：预览地图的缩放级别（0-22，默认值：12）

功能：

1. 使用 Style Builder 工具根据你的描述创建主题样式
2. 在你的 Mapbox 帐户中创建该样式
3. 生成预览链接

使用示例：

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

analyze-geojson

分析并可视化 GeoJSON 数据，自动进行验证并计算边界框。

参数：

• geojson_data（必填）：要分析的 GeoJSON 对象或字符串
• show_bounds（可选）：计算并显示边界框（true/false，默认值：true）
• convert_coordinates（可选）：提供 Web Mercator 坐标转换示例（true/false，默认值：false）

功能：

1. 验证 GeoJSON 格式
2. 计算边界框（如果请求）
3. 提供坐标转换示例（如果请求）
4. 生成交互式可视化链接

使用示例：

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

setup-mapbox-project

为新的 Mapbox 项目完成设置工作流，包括正确的令牌安全设置和样式初始化。

参数：

• project_name（必填）：项目或应用程序的名称
• project_type（可选）：项目类型：“web”“mobile”“backend”或“fullstack”（默认值：“web”）
• production_domain（可选）：用于 URL 限制的生产域名（例如“myapp.com”）
• style_theme（可选）：初始样式主题：“light”“dark”“streets”“outdoors”“satellite”（默认值：“light”）

功能：

1. 创建带有 localhost URL 限制的开发令牌
2. 创建带有域名 URL 限制的生产令牌（如果提供了域名）
3. 创建用于服务器端操作的后端机密令牌（如有需要）
4. 使用指定主题创建初始地图样式
5. 生成预览链接并提供集成指南

使用示例：

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

debug-mapbox-integration

用于诊断和修复 Mapbox 集成问题的系统化故障排查工作流。

参数：

• issue_description（必填）：问题描述（例如“地图无法加载”“401 错误”）
• error_message（可选）：控制台或日志中的确切错误消息
• style_id（可选）：正在使用的 Mapbox 样式 ID（如适用）
• environment（可选）：问题发生的环境：“development”“production”“staging”

功能：

1. 验证令牌是否有效，以及是否具有所需的权限范围
2. 检查样式配置和是否存在
3. 分析错误消息并提供具体解决方案
4. 测试 API 端点以定位问题
5. 提供逐步修复说明
6. 提供预防策略

使用示例：

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

使用表达式创建具有数据驱动属性的地图样式，使其能够根据要素数据动态响应。

参数：

• style_name（必需）：数据驱动样式的名称
• data_description（必需）：数据说明（例如，“按城市划分的人口数量”“地震震级”）
• property_name（必需）：要可视化的数据属性名称（例如，“population”“magnitude”）
• visualization_type（可选）：可视化方式：“color”“size”“both”“heatmap”（默认值：“color”）
• color_scheme（可选）：配色方案：“sequential”“diverging”“categorical”（默认值：“sequential”）

功能：

1. 讲解数据驱动样式和表达式的概念
2. 根据使用场景提供合适的表达式模板
3. 根据可视化类型提供色阶和尺寸范围
4. 创建带有数据驱动图层的样式
5. 提供高级表达式示例（基于缩放级别、条件表达式）
6. 提供有关无障碍性和性能的最佳实践

用法示例：

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 样式部署到生产环境之前，执行全面的质量验证工作流。

参数：

• style_id_or_json（必需）：Mapbox 样式 ID 或完整的样式 JSON
• skip_optimization（可选）：设为 "true" 可跳过样式优化（默认值：false）
• wcag_level（可选）：WCAG 合规级别：“AA”或“AAA”（默认值：“AA”）

功能：

1. 加载样式（从 Mapbox 获取或解析 JSON）
2. 验证所有表达式（筛选条件、绘制属性、布局属性）
3. 验证 GeoJSON 源中的坐标和结构错误
4. 检查文本图层的颜色对比度（WCAG 合规性）
5. 优化样式（移除冗余内容、简化表达式）
6. 生成全面的质量报告，并评估是否已准备好部署

用法示例：

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

相关内容：

请参阅 mapbox-style-quality 技能，了解何时使用验证工具、最佳实践和优化策略的详细指南。

资源

此服务以 MCP 资源的形式公开静态参考文档。支持 resources 协议的 MCP 客户端可以直接访问这些资源。

可用资源：

1. Mapbox 样式规范指南（resource://mapbox-style-layers）

   • Mapbox GL JS 图层类型和属性的完整参考
   • 涵盖填充、线条、符号、圆形和拉伸填充图层
   • 包含每种图层类型的绘制和布局属性

2. Mapbox Streets v8 字段参考（resource://mapbox-streets-v8-fields）

   • 所有 Streets v8 源图层的字段定义
   • 可用于筛选字段的枚举值
   • 构建准确样式筛选条件的必备资料
   • 示例：landuse 图层有一个 class 字段，其值包括 park、cemetery、hospital 等

3. Mapbox 令牌范围参考（resource://mapbox-token-scopes）

   • 令牌范围的全面文档
   • 说明公开令牌与密钥令牌的范围
   • 适用于不同使用场景的常见范围组合
   • 令牌管理的最佳实践

4. Mapbox 图层类型映射（resource://mapbox-layer-type-mapping）

   • 将 Streets v8 源图层映射到兼容的 GL JS 图层类型
   • 按几何类型（多边形、线条、点）分类
   • 包含常见用法模式和示例
   • 帮助避免图层类型与源图层不兼容的组合

**注意：**资源提供不常变动的静态参考数据；工具则提供动态的用户专属数据（例如，列出你的样式或令牌），并执行操作（例如，创建样式或令牌）。

可观测性与追踪

此服务使用 OpenTelemetry（OTEL）进行全面的分布式追踪，提供适用于生产环境的可观测性。

功能

• 选择性启用配置：默认禁用追踪，只需设置 OTLP 端点即可启用
• 工具执行追踪：自动为所有工具执行添加检测，记录耗时、成功／失败状态和错误详情
• HTTP 请求检测：完整追踪 Mapbox API 调用的请求／响应，并记录 CloudFront 关联 ID
• 配置追踪：追踪启动时的配置加载过程和错误
• 安全性：记录输入／输出大小，但会保护内容
• 低开销：CPU 影响低于 1%，追踪缓冲区约占用 10MB 内存

使用 Jaeger 快速入门

# 1. Start Jaeger (Docker required)
npm run tracing:jaeger:start

# 2. Configure environment
cp .env.example .env
# Edit .env to add MAPBOX_ACCESS_TOKEN
# OTEL_EXPORTER_OTLP_ENDPOINT is already set to http://localhost:4318

# 3. Run the server
npm run inspect:build

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

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

支持的后端

该服务支持任何兼容 OTLP 的后端，包括：

• 开发：Jaeger（本地 Docker）
• 云服务提供商：AWS X-Ray、Azure Monitor、Google Cloud Trace
• SaaS 平台：Datadog、New Relic、Honeycomb

各个平台的配置示例请参见 .env.example。

文档

• 完整追踪指南 - 详细的配置、功能和集成示例
• 验证指南 - 分步验证和故障排查

环境变量

# Enable tracing (required)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Optional configuration
OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1  # Sample 10% for high-volume

开发

测试

工具快照测试

该项目包含快照测试，用于确保工具完整性并防止意外添加或移除工具。这些测试会自动发现所有工具，并为其元数据创建快照。

快照测试涵盖的内容：

• 工具类名称（TypeScript 类遵循 PascalCaseTool 约定，例如 ListStylesTool）
• 工具名称（MCP 标识符必须遵循 snake_case_tool 约定，例如 list_styles_tool）
• 工具描述

何时更新快照：

1. 添加新工具：创建新工具后，使用快照更新标志运行测试：

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

2. 移除工具：移除工具后，更新快照：

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

3. 修改工具元数据：更改工具名称或描述后，更新快照：

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

运行快照测试：

# Run all tests (snapshot will fail if tools have changed)
npm test

# Update snapshots after intentional changes
npm test -- --updateSnapshot

重要提示：仅在有意添加、移除或修改工具时更新快照。意外的快照测试失败表明工具结构发生了意外变更。

检查服务

使用 Node.js

# Run the built image
npm run inspect:build

使用 Docker

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

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

创建新工具

npx plop create-tool
# 1. Choose tool type:
#    - Mapbox tool (makes API calls to Mapbox services)
#    - Local tool (local processing, no API calls)
# 2. Provide tool name without suffix using PascalCase (e.g. Search)

生成的文件结构：

plop 生成器会为每个新工具创建三个文件：

src/tools/your-tool-name-tool/
├── YourToolNameTool.schema.ts    # Input schema definition and types
├── YourToolNameTool.ts           # Main tool implementation
└── YourToolNameTool.test.ts      # Unit tests

创建新工具后：

1. 更新输入架构，位于 YourToolNameTool.schema.ts：

   • 使用 Zod 架构定义输入参数
   • 同时导出架构和推断出的 TypeScript 类型

2. 更新工具描述，位于 YourToolNameTool.ts：

   • 清晰说明工具的功能

3. 在 execute 方法中实现工具逻辑

4. 在 YourToolNameTool.test.ts 中使用实际测试数据更新测试用例

5. 更新快照测试以包含新工具：

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

6. 运行所有测试以确保一切正常：

   npm test
   

分离架构的优势：

• 将架构文件分开，改善代码组织
• 架构变更时更易于维护
• 与项目中的现有工具保持一致
• 增强 TypeScript 类型安全性

环境变量

VERBOSE_ERRORS

设置 VERBOSE_ERRORS=true，以获取 MCP 服务的详细错误消息。这有助于在与 MCP 客户端集成时调试问题。

默认情况下，服务会返回通用错误消息。启用详细错误后，你将收到实际错误详情，有助于诊断 API 连接问题、无效参数或其他问题。

ENABLE_MCP_UI

交互式预览：MCP Apps（主要方案）和 MCP-UI（兼容方案）

此服务积极投入 MCP Apps，将其作为主要的交互式预览协议，可直接在聊天中提供独立的 HTML 应用面板。Claude Desktop、集成 GitHub Copilot 的 VS Code 和 Claude Code 均支持 MCP Apps，无需配置。

同时也会维护 MCP-UI（@mcp-ui/server），以向后兼容 Goose 等客户端。MCP-UI 不会被移除，但新的交互式预览开发将聚焦于 MCP Apps。

支持的工具：

• preview_style_tool - 交互式 Mapbox 样式预览面板
• geojson_preview_tool - 交互式 GeoJSON 可视化面板
• style_comparison_tool - 并排样式对比面板

客户端支持：

客户端	MCP Apps	MCP-UI
Claude Desktop	✅
集成 GitHub Copilot 的 VS Code	✅
Claude Code	✅
Goose	✅	✅
其他客户端

禁用 MCP-UI（可选）：

MCP Apps 支持始终处于启用状态。如果要禁用 MCP-UI UIResource（Goose 使用），可以：

通过环境变量：

export ENABLE_MCP_UI=false

或通过命令行标志：

node dist/esm/index.js --disable-mcp-ui

**注意：**通常无需禁用此功能。所有客户端始终会收到可用的文本 URL；交互式预览是在此基础上的渐进增强。

故障排除

**问题：**工具因身份验证错误而失败

**解决方案：**检查你的 MAPBOX_ACCESS_TOKEN 是否具有所用工具所需的权限范围。请参阅上方的令牌权限范围部分。

**问题：**大型 GeoJSON 文件导致性能缓慢

**解决方案：**处理非常大的文件时，GeoJSON 预览工具可能会比较慢。可以考虑简化几何图形，或使用较小的数据集进行预览。

发布流程

按照以下步骤发布新版本：

1. 在 package.json 中更新版本号，设为目标版本（例如 1.0.0）。

2. 同步 manifest.json 和 server.json 中的版本号：

   node scripts/sync-manifest-version.cjs
   

   此脚本会读取 package.json 中的版本号，并更新 manifest.json 和 server.json（包括 packages[0].version），使其保持一致。

3. 准备变更日志——将“Unreleased”标题替换为版本号和日期：

   npm run changelog:prepare-release 1.0.0
   

4. 提交、打标签并推送：

   git add package.json manifest.json server.json CHANGELOG.md
   git commit -m "Release v1.0.0"
   git tag v1.0.0
   git push && git push --tags
   

5. 通过 mcp-server-publisher 工作流发布：

   • 前往 mcp-server-publisher 仓库中的 Actions 选项卡
   • 选择“Release MCP Server”
   • 在仓库下拉菜单中选择 mcp-devkit-server
   • 输入版本号——必须与 package.json 中的版本号完全一致
   • 稳定版发布时将分支字段留空（或为开发版指定分支）
   • 工作流将执行以下操作：构建、测试、发布到 NPM（@mapbox/mcp-devkit-server）、发布到 MCP Registry、创建 DXT 包，并创建 GitHub Release

版本文件

发布前，以下文件中的版本号必须一致：

文件	字段
package.json	version（唯一可信来源）
manifest.json	version
server.json	version、packages[0].version

sync-manifest-version.cjs 脚本会自动根据 package.json 同步这些版本号。

开发版发布

要从功能分支发布预发布版本：

1. 在 package.json 中设置带有预发布后缀 -dev 的版本号（例如 1.0.0-dev）
2. 运行 node scripts/sync-manifest-version.cjs
3. 在发布工作流中输入版本号并指定分支名称
4. 此包将以 dev 标签发布到 NPM（不会影响 latest）

贡献

欢迎为 Mapbox Development MCP Server 做出贡献！请查阅我们的文档：

• 工程标准 (docs/engineering_standards.md) - 面向所有贡献者的全面指南
• CLAUDE.md - 架构和技术模式
• AGENTS.md - AI Agent 的关键模式和常见错误
• GitHub Copilot 指南 - Copilot 专用开发实践