Mapbox MCP ランタイムパターン

このスキルは、地理空間機能を備えた本番環境での AI アプリケーションへの Mapbox MCP Server の統合パターンを提供します。

Mapbox MCP Server とは何ですか?

Mapbox MCP Server は Model Context Protocol (MCP) サーバーで、AI エージェントに地理空間ツールを提供します:

オフラインツール (Turf.js):

• 距離、方位、中点の計算
• ポイント・イン・ポリゴンテスト
• 面積、バッファ、重心の操作
• バウンディングボックス、ジオメトリ簡略化
• API呼び出しなし、即座に結果を返す

Mapbox API ツール:

• ルート検索とナビゲーション
• 逆ジオコーディング
• POI カテゴリー検索
• アイソクロン (到達可能性)
• トラベルタイムマトリックス
• 静止地図画像
• GPS トレースマップマッチング
• 多目的地ルート最適化

ユーティリティツール:

• サーバーバージョン情報
• POI カテゴリーリスト

主な利点: 複数の API を手動で統合することなく、AI アプリケーションに地理空間スーパーパワーを与えます。

ツールカテゴリーの理解

統合の前に、LLM が正しく選択するためにツール間の重要な違いを理解しましょう:

距離: 「直線距離」対「道路に沿った距離」

直線距離 (オフライン、即座):

• ツール: distance_tool, bearing_tool, midpoint_tool
• 用途: 近接チェック、「X はどのくらい遠いのか?」、距離の比較
• 例: 「このレストランは 2 マイル以内か?」 → distance_tool

ルート距離 (API、トラフィック対応):

• ツール: directions_tool, matrix_tool
• 用途: ナビゲーション、運転時間、「どのくらい運転時間がかかるのか?」
• 例: 「そこまで運転するのにどのくらいかかる?」 → directions_tool

検索: タイプ対特定の場所

カテゴリー/タイプ検索:

• ツール: category_search_tool
• 用途: 「コーヒーショップを探す」、「近くのレストラン」、タイプ別の閲覧
• 例: 「近くにホテルはありますか?」 → category_search_tool

特定の場所/住所:

• ツール: search_and_geocode_tool, reverse_geocode_tool
• 用途: 指定された場所、住所、ランドマーク
• 例: 「123 Main Street を探す」 → search_and_geocode_tool

トラベルタイム: エリア対ルート

到達可能エリア (到達可能な範囲):

• ツール: isochrone_tool
• 返却値: 到達可能なすべての場所の GeoJSON ポリゴン
• 例: 「15 分で到達できるのは何か?」 → isochrone_tool

特定のルート (そこへの行き方):

• ツール: directions_tool
• 返却値: 1 つの目的地への順番通りの方向
• 例: 「空港にはどうやって行きますか?」 → directions_tool

コスト と パフォーマンス

オフラインツール (無料、即座):

• API 呼び出しなし、トークン使用なし
• リアルタイムデータが不要な場合は常に使用
• 例: distance_tool, point_in_polygon_tool, area_tool

API ツール (トークン必須、使用量にカウント):

• リアルタイムトラフィック、ライブ POI データ、最新の状態
• 正確性と鮮度が重要な場合に使用
• 例: directions_tool, category_search_tool, isochrone_tool

ベストプラクティス: 可能な限りオフラインツールを優先し、リアルタイムデータまたはルート検索が必要な場合は API ツールを使用します。

インストール と セットアップ

オプション 1: ホスト型サーバー (推奨)

最も簡単な統合 - Mapbox のホスト型 MCP サーバーを使用:

https://mcp.mapbox.com/mcp

インストールは不要です。Authorization ヘッダーで Mapbox アクセストークンを渡すだけです。

メリット:

• サーバー管理なし
• 常に最新版
• 本番環境対応
• レイテンシー低下 (Mapbox インフラ)

認証:

トークンベースの認証を使用 (プログラムアクセスの標準):

Authorization: Bearer your_mapbox_token

注: ホスト型サーバーは OAuth もサポートしていますが、これは主にインタラクティブフロー (コーディングアシスタント、本番アプリ以外) 用です。

オプション 2: セルフホスト

カスタムデプロイまたは開発用:

npm install @mapbox/mcp-server

または npx 経由で直接使用:

npx @mapbox/mcp-server

環境設定:

export MAPBOX_ACCESS_TOKEN="your_token_here"

リファレンスファイル

詳細な統合パターンと本番環境ガイダンスは、リファレンスファイルに整理されています。タスクに関連するものを読み込んでください。

• Pydantic AI -- タイプセーフな Python エージェント 読み込み: references/pydantic-ai.md

• CrewAI -- マルチエージェント オーケストレーション 読み込み: references/crewai.md

• Smolagents -- 軽量な HuggingFace エージェント 読み込み: references/smolagents.md

• Mastra -- マルチエージェント TypeScript システム 読み込み: references/mastra.md

• LangChain -- ツールチェーニングを備えた会話型 AI 読み込み: references/langchain.md

• カスタムエージェント -- Zillow/TripAdvisor/DoorDash スタイルのパターン、アーキテクチャ図、ハイブリッドアプローチ 読み込み: references/custom-agent.md

• ユースケース -- 不動産、フードデリバリー、トラベルプランニングの例 読み込み: references/use-cases.md

• 本番環境パターン -- キャッシング、バッチ操作、ツール説明、エラーハンドリング、セキュリティ、レート制限、テスト 読み込み: references/production.md

リソース

• Mapbox MCP Server
• Model Context Protocol
• Pydantic AI
• Mastra
• LangChain
• Mapbox API Documentation

このスキルを使用する場合

以下の場合にこのスキルを呼び出してください:

• Mapbox MCP Server を AI アプリケーションに統合する
• 地理空間機能を備えた AI エージェントを構築する
• Zillow/TripAdvisor/DoorDash スタイルのアプリを AI で構築する
• MCP、直接 API、または SDK の間で選択する
• 本番環境で地理空間操作を最適化する
• 地理空間 AI 機能のエラーハンドリングを実装する
• 地理空間ツールを使用して AI アプリケーションをテストする