mapbox-mcp-runtime-patterns

Mapbox MCP ランタイムパターン

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

Mapbox MCP Server とは？

Mapbox MCP Server は、AI エージェントに地理空間ツールを提供する Model Context Protocol（MCP）サーバーです。

オフラインツール（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

• Custom Agent — Zillow／TripAdvisor／DoorDash 形式のパターン、アーキテクチャ図、ハイブリッドアプローチ 読み込み先：references/custom-agent.md

• Use Cases — 不動産、フードデリバリー、旅行計画の例 読み込み先：references/use-cases.md

• Production Patterns — キャッシュ、バッチ処理、ツールの説明、エラー処理、セキュリティ、レート制限、テスト 読み込み先：references/production.md

リソース

• Mapbox MCP サーバー
• Model Context Protocol
• Pydantic AI
• Mastra
• LangChain
• Mapbox API ドキュメント

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

次の場合にこのスキルを呼び出してください。

• Mapbox MCP Server を AI アプリケーションに統合する場合
• 地理空間機能を備えた AI エージェントを構築する場合
• Zillow／TripAdvisor／DoorDash 形式の AI アプリを設計する場合
• MCP、直接 API、SDK のいずれを使うか選択する場合
• 本番環境で地理空間処理を最適化する場合
• 地理空間 AI 機能のエラー処理を実装する場合
• 地理空間ツールを使った AI アプリケーションをテストする場合