MCP Devkit Server

🚀 Mapbox Developer MCP Server

このサーバーは、Model Context Protocol (MCP) を使用して、AIアシスタントが直接Mapbox開発者APIにアクセスできるようにします。AIモデルがMapboxサービスとやり取りできるようになり、開発者がMapboxアプリケーションをより効率的に構築するのに役立ちます。

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

🚀 クイックスタート

開発ツールとの統合

好みのAI開発環境と統合して始めましょう。

• Claude Code Integration - Claudeを使ったコマンドライン開発
• Claude Desktop Integration - デスクトップアプリケーションとの統合
• Cursor Integration - Cursor IDEとの統合
• VS Code Integration - GitHub Copilot付きのVisual Studio Code

DXTパッケージ配布

このMCPサーバーは、DXT（Desktop Extension）ファイルとしてパッケージ化でき、配布とインストールが容易です。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の使用方法については、Hosted MCP Server Guide を参照してください。なお、このガイドでは標準のMCPエンドポイントを参照しています。上記のdevkitエンドポイントを使用するには、エンドポイントURLを更新する必要があります。

Mapboxアクセストークンの取得

このMCPサーバーを使用するには、Mapboxアクセストークンが必要です。

1. mapbox.com/signup で無料のMapboxアカウントにサインアップします。
2. アカウントページ に移動します。
3. ユースケースに必要なスコープを持つ新しいトークンを作成します。

Mapboxアクセストークンの詳細については、Mapbox documentation on access tokens を参照してください。

⚠️ 重要: トークンの特権が必要

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 Desktopの現在のMCPリソースに関する制限を回避するために存在します。Claude Desktopはリソースを表示できます（resources/list を介して）が、その内容を取得するために resources/read を自動的に呼び出しません。このツールは、Claude Desktopがサポートするツールインターフェイスを通じて同じリファレンスデータを提供します。リソースプロトコルを完全にサポートする他の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スタイルをプログラムで作成および変更します。

📖 詳細な使用方法と例はこちら →

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つの公開トークンが必要です。

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

すべてのスタイルツールには、特定のスコープを持つ有効な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の権限を持つ新しいMapboxトークンを私のWebアプリ用に作成してください"
• "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の配列、オプション): 1つ以上のフィードバックアイテム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' のすべてのフィードバックアイテムをリストしてください"
• "7月1日以降に作成された 'poi_details' カテゴリのフィードバックアイテムを表示してください"
• "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リンクを作成してください"

座標変換ツール

異なる座標参照系（CRS）間で座標を変換します。具体的には、WGS84（EPSG:4326）とWeb Mercator（EPSG:3857）の間です。

パラメータ:

• coordinates (配列、必須): 変換する座標ペアの配列。各座標ペアは、WGS84の場合は [経度, 緯度]、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

戻り値: バウンディングボックスを表す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ファイルの座標のバウンディングボックスは何ですか？"

💻 使用例

プロンプト

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 (必須): テーマの説明（例: "dark cyberpunk", "nature-focused", "minimal monochrome"）
• emphasis (オプション): 強調する機能（例: "parks and green spaces", "transit lines"）
• 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 (必須): 問題の説明（例: "map not loading", "401 error"）
• 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 (必須): データの説明（例: "population by city", "earthquake magnitudes"）
• 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"

📚 ドキュメント

リソース

このサーバーは、静的なリファレンスドキュメントをMCPリソースとして公開しています。これらは主に get_reference_tool を通じてアクセスされますが、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レイヤータイプにマッピング
   • ジオメトリタイプ（ポリゴン、ライン、ポイント）で整理
   • 一般的な使用パターンと例を含む
   • 互換性のないレイヤータイプ/ソースレイヤーの組み合わせを避けるのに役立つ

リソースへのアクセス:

• Claude Desktopとほとんどの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ジェネレータは、各新しいツールに対して3つのファイルを作成します。

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 Desktopなど）は、UIResourceを無視してテキストURLを使用します。
• MCP-UIをサポートするクライアント（Gooseなど）は、より豊富なエクスペリエンスのためにiframeをレンダリングできます。

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 Development MCP Serverへのコントリビューションを歓迎します！以下のドキュメントを確認してください。

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