mcp-devkit-server

Mapbox Developer MCP Server

AI アシスタントが Mapbox の開発者向け API に直接アクセスできる Model Context Protocol（MCP）サーバーです。このサーバーを使うと、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 Developer MCP Server
  • 目次
  • クイックスタート
    • 開発者ツールとの連携
    • DXT パッケージの配布
      • DXT パッケージの作成
    • ホスト型 MCP エンドポイント
    • Mapbox アクセストークンの取得
  • ツール
    • リファレンスツール
    • スタイル管理ツール
    • トークン管理ツール
      • create-token
      • list-tokens
    • フィードバックツール
    • ローカル処理ツール
      • GeoJSON プレビューツール（ベータ版）
      • 座標変換ツール
      • バウンディングボックスツール
      • 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（Desktop Extension）ファイルとしてパッケージ化できます。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 エンドポイントを参照しています。上記の devkit エンドポイントを使用するには、エンドポイント 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 スコープが必要です

ツール

リファレンスツール

リファレンスデータは MCP リソースとして公開されています（「リソース」セクションをご覧ください）。リソースプロトコルに対応する MCP クライアントは、これらに直接アクセスできます。

利用可能なリファレンス：

• resource://mapbox-style-layers - すべてのレイヤータイプ（fill、line、symbol、circle、fill-extrusion）とそのプロパティを網羅した、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 レイヤータイプの対応表。一般的な使用パターンも含まれます

プロンプトの例：

• 「landuse レイヤーで利用できるフィールドは何ですか？」
• 「トークンスコープのリファレンスを表示してください」
• 「道路にはどのレイヤータイプを使えばよいですか？」
• 「Streets v8 のフィールドリファレンスを取得してください」
• 「地図を表示するにはどのスコープが必要ですか？」

スタイル管理ツール

Styles 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 スコープを持つ公開トークンが少なくとも 1 つ必要です。

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 スコープを持つ公開トークンが少なくとも 1 つ必要です

**注：**ユーザー名は 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"]
}

プロンプトの例：

• 「styles:read と fonts:read の権限を持つ、Web アプリ用の新しい Mapbox トークンを作成してください」
• 「styles:tiles と vision:read のスコープを持ち、30 分後に期限切れになるトークンを生成してください」
• 「styles:read、fonts:read、datasets:read のスコープを持ち、https://myapp.com でのみ使用できる制限付きトークンを作成してください」

list-tokens

認証済みユーザーの Mapbox アクセストークンを、任意のフィルタリングやページネーションを使用して一覧表示します。

パラメーター：

• default (boolean, optional): デフォルトのパブリックトークンのみを表示するように絞り込みます
• limit (number, optional): 1 ページあたりに返すトークンの最大数（1～100）
• sortby (string, optional): トークンを「created」または「modified」のタイムスタンプで並べ替えます
• start (string, optional): 一覧表示を開始する位置となるトークン ID（指定すると、自動ページネーションは無効になります）
• usage (string, optional): トークンの種類で絞り込みます：「pk」（パブリック）

ページネーションの動作：

• start パラメーターを指定しない場合、このツールはすべてのページの結果を自動的に取得します
• start パラメーターを指定した場合、指定されたページのみが返されます（手動でページネーションを制御する場合）

例：

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

プロンプトの例：

• 「Mapbox のすべてのトークンを一覧表示して」
• 「作成日順に並べたパブリックトークンを表示して」
• 「デフォルトのパブリックトークンを探して」
• 「最近更新された 5 件のトークンを一覧表示して」
• 「アカウント内のすべてのパブリックトークンを表示して」

フィードバックツール

Mapbox Feedback API からユーザーフィードバック項目にアクセスします。これらのツールを使用すると、地図データ、ルーティング、POI の詳細に関してユーザーから報告された問題、提案、フィードバックを取得して確認できます。

list_feedback_tool - 包括的なフィルタリング、並べ替え、ページネーションのオプションを使用して、ユーザーフィードバック項目を一覧表示します。

パラメーター：

• feedback_ids (array of UUIDs, optional): 1 つ以上のフィードバック項目 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): トレース ID で絞り込みます
• 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

戻り値： ページネーションカーソルを含む、ページネーションされたフィードバック項目の一覧。

get_feedback_tool - 固有の ID を指定して、単一のユーザーフィードバック項目を取得します。

パラメーター：

• feedback_id (UUID, required): フィードバック項目の固有識別子
• format (string, optional): 出力形式：formatted_text（デフォルト）または json_string

戻り値： ステータス、カテゴリ、フィードバックテキスト、場所、タイムスタンプなどの詳細を含む単一のフィードバック項目。

⚠️ 必要なトークンスコープ：

• 両方のフィードバックツール：アクセストークンに user-feedback:read スコープが必要です

プロンプトの例：

• 「ステータスが『fixed』のフィードバック項目をすべて一覧表示して」
• 「『poi_details』カテゴリで、7 月 1 日以降に作成されたフィードバック項目を表示して」
• 「ID が 40eae4c7-b157-4b49-a091-7e1099bba77e のフィードバック項目を取得して」
• 「フィードバックテキストに『apartment building』を含む項目を探して」
• 「先月のルーティングに関する問題のフィードバックをすべて一覧表示して」

ローカル処理ツール

GeoJSON プレビュー ツール（ベータ）

GeoJSON データを可視化するための geojson.io URL を生成します。このツールでは、次のことができます。

• GeoJSON 形式（Point、LineString、Polygon、Feature、FeatureCollection など）を検証します
• すぐに可視化できる geojson.io への直接 URL を返します
• GeoJSON オブジェクトと JSON 文字列の両方を入力としてサポートします

使用例：

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

戻り値： GeoJSON データを表示するため、ブラウザーで開ける単一の URL 文字列です。

注意： このベータ機能は現在、小〜中サイズの 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 のスタイル式について、構文、演算子、引数が正しいかを検証します。このオフライン検証ツールは、API アクセスを必要とせずに、Mapbox の式を包括的にチェックします。

パラメーター：

• 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 アクセスやトークンスコープは不要です。

座標変換ツール

WGS84（EPSG:4326）と Web Mercator（EPSG:3857）の間で、座標参照系（CRS）を変換します。

パラメーター：

• 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 ]"
• "Web Mercator の座標 [-13627361.0, 4544761.0] を WGS84 に変換してください"

バウンディングボックスツール

指定された GeoJSON コンテンツのバウンディングボックスを計算し、座標を[minX, minY, maxX, maxY]の形式で返します。

パラメーター：

• geojson（文字列またはオブジェクト、必須）：バウンディングボックスを計算する GeoJSON コンテンツ。次の形式で指定できます：
  • 解析対象の JSON 文字列
  • GeoJSON オブジェクト

サポートされている GeoJSON の種類：

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

戻り値：

バウンディングボックスを表す4つの数値の配列：[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（文字列、必須）：前景色（テキストの色）。任意の CSS 形式（hex、rgb、rgba、名前付きカラー）を指定します
• backgroundColor（文字列、必須）：背景色。任意の CSS 形式（hex、rgb、rgba、名前付きカラー）を指定します
• level（文字列、任意）：チェックする WCAG 適合レベル（「AA」または「AAA」、デフォルト：「AA」）
• fontSize（文字列、任意）：フォントサイズのカテゴリ（「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

2 つの Mapbox スタイルを比較し、レイヤー、ソース、プロパティの変更など、構造上の違いを報告します。このオフライン比較ツールは、API アクセスを必要とせずにオブジェクトを詳細に比較します。

パラメーター：

• styleA（文字列またはオブジェクト、必須）：比較する 1 つ目の Mapbox スタイル（JSON 文字列またはスタイルオブジェクト）
• styleB（文字列またはオブジェクト、必須）：比較する 2 つ目の Mapbox スタイル（JSON 文字列またはスタイルオブジェクト）
• ignoreMetadata（ブール値、任意）：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
  }
}

プロンプトの例：

• 「この 2 つの 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 スタイルを最適化して、ファイルサイズを縮小してください」
• 「スタイルから未使用のソースを削除してください」
• 「このスタイルの式を簡素化してください」
• 「マップスタイル内の重複するレイヤーを探して削除してください」
• 「未使用のソースと空のレイヤーだけを削除して、スタイルを最適化してください」

エージェントスキル

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（必須）：可視化するデータプロパティの名前（例：「人口」、「マグニチュード」）
• 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 リソースとして公開します。リソースプロトコルをサポートする MCP クライアントから、これらに直接アクセスできます。

利用可能なリソース：

1. Mapbox Style Specification Guide（resource://mapbox-style-layers）

   • Mapbox GL JS のレイヤータイプとプロパティに関する完全なリファレンス
   • fill、line、symbol、circle、fill-extrusion レイヤーを網羅
   • 各レイヤータイプのペイントプロパティとレイアウトプロパティを含む

2. Mapbox Streets v8 Fields Reference（resource://mapbox-streets-v8-fields）

   • すべての Streets v8 ソースレイヤーのフィールド定義
   • フィルター可能なフィールドの列挙値
   • 正確なスタイルフィルターの作成に不可欠です
   • 例：landuse レイヤーには class フィールドがあり、park、cemetery、hospital などの値を持ちます

3. Mapbox Token Scopes Reference（resource://mapbox-token-scopes）

   • トークンスコープに関する包括的なドキュメント
   • 公開トークンとシークレットトークンのスコープについて説明
   • さまざまなユースケースで一般的なスコープの組み合わせ
   • トークン管理のベストプラクティス

4. Mapbox Layer Type Mapping（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 のクラスは ListStylesTool など、PascalCaseTool の規則に従います）
• ツール名（MCP 識別子は list_styles_tool など、snake_case_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 ジェネレーターは、新しいツールごとに 3 つのファイルを作成します。

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（互換性）

このサーバーは、チャット内に自己完結型のHTMLアプリパネルを直接表示する、メインのインタラクティブプレビュープロトコルとして、MCP Apps に積極的に取り組んでいます。MCP AppsはClaude Desktop、GitHub Copilotを搭載したVS Code、Claude Codeでサポートされており、設定は不要です。

MCP-UI（@mcp-ui/server）も、Gooseなどのクライアントとの後方互換性のために保守されています。削除されることはありませんが、新しいインタラクティブプレビューの開発では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. パッケージはNPMにdevタグで公開されます（latestには影響しません）

コントリビューション

Mapbox Development MCP Server へのコントリビューションを歓迎します！ドキュメントをご確認ください。

• エンジニアリング標準 (docs/engineering_standards.md) - すべてのコントリビューター向けの包括的なガイドライン
• CLAUDE.md - アーキテクチャと技術的なパターン
• AGENTS.md - AI エージェント向けの重要なパターンとよくあるエラー
• GitHub Copilot ガイドライン - Copilot 固有の開発プラクティス