mcp-devkit-server

🚀 Mapbox开发者MCP服务器

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

点击查看相关资源

🚀 快速开始

与开发工具集成

你可以先将本服务器与你偏好的AI开发环境进行集成：

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

DXT包分发

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

创建DXT包

若要创建DXT包，可按以下步骤操作：

# 安装DXT CLI工具
npm install -g @anthropic-ai/dxt

# 首先构建服务器
npm run build

# 创建DXT包
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才能使用上述开发工具包端点。

获取你的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权限范围。

✨ 主要特性

工具

文档工具

get_latest_mapbox_docs_tool - 可直接从源获取最新的Mapbox官方文档。该工具能从docs.mapbox.com/llms.txt获取有关所有Mapbox API、SDK和开发者资源的全面且最新的信息。

示例提示：

• “开发者可用的最新Mapbox API有哪些？”
• “展示所有当前的Mapbox服务和SDK”
• “我需要为我的项目获取最新的Mapbox文档”
• “Mapbox为我的技术栈提供了哪些地图解决方案？”
• “概述一下Mapbox的导航和路由功能”
• “比较Mapbox Web SDK和移动SDK”
• “Mapbox生态系统有哪些新动态？”

📖 查看更多示例和交互式演示 →

参考工具

get_reference_tool - 可访问静态的Mapbox参考文档和模式。该工具提供了必要的参考信息，有助于AI助手理解Mapbox概念并构建正确的样式和令牌。

注意：此工具是为解决Claude桌面版当前在MCP资源方面的限制而存在的。Claude桌面版可以看到资源（通过resources/list），但不会自动调用resources/read来获取其内容。此工具通过工具界面提供相同的参考数据，Claude桌面版支持这种方式。其他完全支持资源协议的MCP客户端可以直接将此数据作为MCP资源进行访问（请参阅下面的资源部分）。

可用参考资料：

• resource://mapbox-style-layers - Mapbox GL JS样式规范参考指南，涵盖所有图层类型（填充、线、符号、圆形、填充挤压）及其属性。
• resource://mapbox-streets-v8-fields - 所有Mapbox Streets v8源图层的完整字段定义，包括每个字段的枚举值（对构建过滤器很有用）。
• resource://mapbox-token-scopes - 全面的令牌权限范围参考，解释了每个权限范围允许的操作以及不同操作所需的权限范围。
• resource://mapbox-layer-type-mapping - Mapbox Streets v8源图层与兼容的GL JS图层类型的映射，包含常见的使用模式。

示例提示：

• “土地利用图层有哪些可用字段？”
• “展示令牌权限范围参考”
• “道路应该使用哪种图层类型？”
• “获取Streets v8字段参考”
• “显示地图需要哪些权限范围？”

样式管理工具

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

• 样式构建工具 - 通过对话式提示以编程方式创建和修改Mapbox样式。 📖 查看样式构建器文档以获取详细用法和示例 →
• 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权限范围的公共令牌。

⚠️ 重要提示

所有样式工具都需要具有特定权限范围的有效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 - 读取视觉API

示例：

{
  "note": "我的应用程序的开发令牌",
  "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反馈API访问用户反馈项。这些工具允许你检索和查看用户报告的有关地图数据、路由和兴趣点详细信息的问题、建议和反馈。

• 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权限范围。

示例提示：

• “列出所有状态为‘已修复’的反馈项”
• “显示7月1日之后创建的‘兴趣点详细信息’类别中的反馈项”
• “获取ID为40eae4c7 - b157 - 4b49 - a091 - 7e1099bba77e的反馈项”
• “查找反馈文本中包含‘公寓楼’的反馈项”
• “列出上个月的所有路由问题反馈”

本地处理工具

GeoJSON预览工具（测试版）

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

• 验证GeoJSON格式（点、线串、多边形、要素、要素集合等）。
• 返回直接指向geojson.io的URL以实现即时可视化。
• 支持将GeoJSON对象和JSON字符串作为输入。

示例用法：

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

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

注意：这是一个测试版功能，目前针对中小规模的GeoJSON文件进行了优化。大型GeoJSON文件可能会导致URL过长和性能下降。我们计划在未来版本中通过实施处理大型数据集的替代方法来优化此功能。

示例提示：

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

坐标转换工具

在不同的坐标参考系统（CRS）之间转换坐标，具体是在WGS84（EPSG:4326）和网络墨卡托（EPSG:3857）之间转换。

参数：

• coordinates（数组，必需）：要转换的坐标对数组。每个坐标对在WGS84中应为[经度, 纬度]，在网络墨卡托中应为[x, y]。
• fromCRS（字符串，必需）：源坐标参考系统。支持的值："EPSG:4326"（WGS84），"EPSG:3857"（网络墨卡托）。
• toCRS（字符串，必需）：目标坐标参考系统。支持的值："EPSG:4326"（WGS84），"EPSG:3857"（网络墨卡托）。

返回： 以目标CRS格式表示的转换后的坐标对数组。

示例：

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

示例提示：

• “将这些坐标从WGS84转换为网络墨卡托：[-122.4194, 37.7749]和[-74.006, 40.7128]”
• “将坐标[-13627361.0, 4544761.0]从网络墨卡托转换为WGS84”

边界框工具

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

参数：

• geojson（字符串或对象，必需）：要计算边界框的GeoJSON内容。可以是：
  • 将被解析的JSON字符串
  • GeoJSON对象

支持的GeoJSON类型：

• 点
• 线串
• 多边形
• 多点
• 多线串
• 多多边形
• 几何集合
• 要素
• 要素集合

返回： 表示边界框的四个数字数组：[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文件中的坐标的边界框是多少？”

提示

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. 生成预览链接。

示例用法：

使用提示：create-and-preview-style
参数：
  style_name: "我的自定义地图"
  style_description: "用于夜间导航的深色主题地图"
  base_style: "dark-v11"
  preview_location: "旧金山"
  preview_zoom: "13"

build-custom-map

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

参数：

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

功能：

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

示例用法：

使用提示：build-custom-map
参数：
  theme: "复古80年代霓虹灯"
  emphasis: "夜生活和娱乐场所"
  preview_location: "东京"
  preview_zoom: "14"

analyze-geojson

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

参数：

• geojson_data（必需）：要分析的GeoJSON对象或字符串
• show_bounds（可选）：计算并显示边界框（true/false，默认值：true）
• convert_coordinates（可选）：提供网络墨卡托转换示例（true/false，默认值：false）

功能：

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

示例用法：

使用提示：analyze-geojson
参数：
  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. 创建具有本地主机URL限制的开发令牌。
2. （如果提供）创建具有域名URL限制的生产令牌。
3. （如果需要）为服务器端操作创建后端秘密令牌。
4. 使用指定的主题创建初始地图样式。
5. 生成预览链接并提供集成指南。

示例用法：

使用提示：setup-mapbox-project
参数：
  project_name: "餐厅查找器"
  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. 提供预防策略。

示例用法：

使用提示：debug-mapbox-integration
参数：
  issue_description: "地图加载时出现401错误"
  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. 提供可访问性和性能的最佳实践。

示例用法：

使用提示：design-data-driven-style
参数：
  style_name: "人口密度地图"
  data_description: "城市人口数据"
  property_name: "population"
  visualization_type: "both"
  color_scheme: "sequential"

资源

此服务器将静态参考文档作为MCP资源公开。虽然这些资源主要通过get_reference_tool访问，但完全支持资源协议的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图层类型。
   • 按几何类型（多边形、线、点）组织。
   • 包含常见的使用模式和示例。
   • 有助于避免不兼容的图层类型/源图层组合。

访问资源：

• Claude桌面版和大多数MCP客户端：使用get_reference_tool访问这些参考资料。
• 未来的MCP客户端：可能支持通过MCP资源协议直接访问资源。

注意：资源提供的是不经常变化的静态参考数据，而工具提供的是动态的、用户特定的数据（如列出你的样式或令牌）并执行操作（如创建样式或令牌）。

可观测性与跟踪

此服务器使用OpenTelemetry（OTEL）进行全面的分布式跟踪，以实现生产就绪的可观测性。

特性

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

快速开始使用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

支持的后端

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

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

有关每个平台的配置示例，请参阅.env.example。

文档

• 完整跟踪指南 - 详细的配置、特性和集成示例。
• 验证指南 - 分步验证和故障排除。

环境变量

# 启用跟踪（必需）
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%

🔧 技术细节

开发

测试

工具快照测试

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

快照测试涵盖内容：

• 工具类名（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
   

运行快照测试：

# 运行所有测试（如果工具发生更改，快照将失败）
npm test

# 有意更改后更新快照
npm test -- --updateSnapshot

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

检查服务器

使用Node.js

# 运行构建后的镜像
npm run inspect:build

使用Docker

# 构建Docker镜像
docker build -t mapbox-mcp-devkit .

# 运行并检查服务器
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkit

创建新工具

npx plop create-tool
# 1. 选择工具类型：
#    - Mapbox工具（对Mapbox服务进行API调用）
#    - 本地工具（本地处理，无API调用）
# 2. 使用PascalCase提供不带后缀的工具名称（例如Search）

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

src/tools/your-tool-name-tool/
├── YourToolNameTool.schema.ts    # 输入模式定义和类型
├── YourToolNameTool.ts           # 主要工具实现
└── YourToolNameTool.test.ts      # 单元测试

创建新工具后：

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 - UI支持（默认启用）

MCP - UI允许返回URL的工具还返回可直接嵌入支持MCP客户端的交互式iframe资源。这默认启用，并且与所有MCP客户端完全向后兼容。

支持的工具：

• preview_style_tool - 嵌入Mapbox样式预览。
• geojson_preview_tool - 嵌入geojson.io可视化。
• style_comparison_tool - 嵌入并排样式比较。

工作原理：

• 工具返回文本URL（始终有效） 和用于iframe嵌入的UIResource。
• 不支持MCP - UI的客户端（如Claude桌面版）会忽略UIResource并使用文本URL。
• 支持MCP - UI的客户端（如Goose）可以渲染iframe以获得更丰富的体验。

禁用MCP - UI（可选）： 如果你想禁用MCP - UI支持： 通过环境变量：

export ENABLE_MCP_UI=false

或通过命令行标志：

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

注意：通常不需要禁用此功能。该实现完全向后兼容，不会影响不支持MCP - UI的客户端。有关兼容客户端，请参阅mcpui.dev。

📚 详细文档

故障排除

问题：工具因身份验证错误而失败。 解决方案：检查你的MAPBOX_ACCESS_TOKEN是否具有你正在使用的工具所需的权限范围。请参阅上面的令牌权限范围部分。

问题：大型GeoJSON文件导致性能下降。 解决方案：GeoJSON预览工具在处理非常大的文件时可能会变慢。考虑简化几何图形或使用较小的数据集进行预览。

贡献

我们欢迎对Mapbox开发MCP服务器进行贡献！请查看我们的文档：

• 工程标准 (docs/engineering_standards.md) - 为所有贡献者提供的综合指南
• CLAUDE.md - 架构和技术模式
• AGENTS.md - AI代理的关键模式和常见错误
• GitHub Copilot指南 - 特定于Copilot的开发实践