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的開發實踐