mapbox/mapbox-agent-skills

mapbox-mcp-runtime-patterns

Integration patterns for Mapbox MCP Server in AI applications and agent frameworks.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-mcp-runtime-patterns

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Mapbox MCP Runtime Patterns

This skill provides patterns for integrating the Mapbox MCP Server into AI applications for production use with geospatial capabilities.

What is Mapbox MCP Server?

The Mapbox MCP Server is a Model Context Protocol (MCP) server that provides AI agents with geospatial tools:

Offline Tools (Turf.js):

  • Distance, bearing, midpoint calculations
  • Point-in-polygon tests
  • Area, buffer, centroid operations
  • Bounding box, geometry simplification
  • No API calls, instant results

Mapbox API Tools:

  • Directions and routing
  • Reverse geocoding
  • POI category search
  • Isochrones (reachability)
  • Travel time matrices
  • Static map images
  • GPS trace map matching
  • Multi-stop route optimization

Utility Tools:

  • Server version info
  • POI category list

Key benefit: Give your AI application geospatial superpowers without manually integrating multiple APIs.

Understanding Tool Categories

Before integrating, understand the key distinctions between tools to help your LLM choose correctly:

Distance: "As the Crow Flies" vs "Along Roads"

Straight-line distance (offline, instant):

  • Tools: distance_tool, bearing_tool, midpoint_tool
  • Use for: Proximity checks, "how far away is X?", comparing distances
  • Example: "Is this restaurant within 2 miles?" → distance_tool

Route distance (API, traffic-aware):

  • Tools: directions_tool, matrix_tool
  • Use for: Navigation, drive time, "how long to drive?"
  • Example: "How long to drive there?" → directions_tool

Search: Type vs Specific Place

Category/type search:

  • Tool: category_search_tool
  • Use for: "Find coffee shops", "restaurants nearby", browsing by type
  • Example: "What hotels are near me?" → category_search_tool

Specific place/address:

  • Tool: search_and_geocode_tool, reverse_geocode_tool
  • Use for: Named places, street addresses, landmarks
  • Example: "Find 123 Main Street" → search_and_geocode_tool

Travel Time: Area vs Route

Reachable area (what's within reach):

  • Tool: isochrone_tool
  • Returns: GeoJSON polygon of everywhere reachable
  • Example: "What can I reach in 15 minutes?" → isochrone_tool

Specific route (how to get there):

  • Tool: directions_tool
  • Returns: Turn-by-turn directions to one destination
  • Example: "How do I get to the airport?" → directions_tool

Cost & Performance

Offline tools (free, instant):

  • No API calls, no token usage
  • Use whenever real-time data not needed
  • Examples: distance_tool, point_in_polygon_tool, area_tool

API tools (requires token, counts against usage):

  • Real-time traffic, live POI data, current conditions
  • Use when accuracy and freshness matter
  • Examples: directions_tool, category_search_tool, isochrone_tool

Best practice: Prefer offline tools when possible, use API tools when you need real-time data or routing.

Installation & Setup

Option 1: Hosted Server (Recommended)

Easiest integration - Use Mapbox's hosted MCP server at:

https://mcp.mapbox.com/mcp

No installation required. Simply pass your Mapbox access token in the Authorization header.

Benefits:

  • No server management
  • Always up-to-date
  • Production-ready
  • Lower latency (Mapbox infrastructure)

Authentication:

Use token-based authentication (standard for programmatic access):

Authorization: Bearer your_mapbox_token

Note: The hosted server also supports OAuth, but that's primarily for interactive flows (coding assistants, not production apps).

Option 2: Self-Hosted

For custom deployments or development:

bash
npm install @mapbox/mcp-server

Or use directly via npx:

bash
npx @mapbox/mcp-server

Environment setup:

bash
export MAPBOX_ACCESS_TOKEN="your_token_here"

Reference Files

Detailed integration patterns and production guidance are organized into reference files. Load the ones relevant to your task.

  • Pydantic AI -- Type-safe Python agents

Load: references/pydantic-ai.md

  • CrewAI -- Multi-agent orchestration

Load: references/crewai.md

  • Smolagents -- Lightweight HuggingFace agents

Load: references/smolagents.md

  • Mastra -- Multi-agent TypeScript systems

Load: references/mastra.md

  • LangChain -- Conversational AI with tool chaining

Load: references/langchain.md

  • Custom Agent -- Zillow/TripAdvisor/DoorDash-style patterns, architecture diagrams, hybrid approach

Load: references/custom-agent.md

  • Use Cases -- Real Estate, Food Delivery, Travel Planning examples

Load: references/use-cases.md

  • Production Patterns -- Caching, batch operations, tool descriptions, error handling, security, rate limiting, testing

Load: references/production.md

Resources

When to Use This Skill

Invoke this skill when:

  • Integrating Mapbox MCP Server into AI applications
  • Building AI agents with geospatial capabilities
  • Architecting Zillow/TripAdvisor/DoorDash-style apps with AI
  • Choosing between MCP, direct APIs, or SDKs
  • Optimizing geospatial operations in production
  • Implementing error handling for geospatial AI features
  • Testing AI applications with geospatial tools

タスクに関連する項目

同じリポジトリから

関連する Skills

すべての Skills
mapbox
公式

mapbox-style-patterns

Common style patterns, layer configurations, and recipes for typical mapping scenarios including restaurant finders, real estate, data visualization, navigation, delivery/logistics, and more. Use when implementing specific map use cases or looking for proven style patterns.

1時間の導入数
1
GitHub Stars
87
更新日
11月19日
mapbox
公式

mapbox-style-quality

Expert guidance on validating, optimizing, and ensuring quality of Mapbox styles through validation, accessibility checks, and optimization. Use when preparing styles for production, debugging issues, or ensuring map quality standards.

1時間の導入数
1
GitHub Stars
87
更新日
11月19日
mapbox
公式

mapbox-web-performance-patterns

Performance optimization patterns for Mapbox GL JS web applications. Covers initialization waterfalls, bundle size, rendering performance, memory management, and web optimization. Prioritized by impact on user experience.

1時間の導入数
3
GitHub Stars
80
更新日
10月1日
mapbox
公式

mapbox-web-integration-patterns

Official integration patterns for Mapbox GL JS across popular web frameworks (React, Vue, Svelte, Angular). Covers setup, lifecycle management, token handling, search integration, and common pitfalls. Based on Mapbox's create-web-app scaffolding tool.

1時間の導入数
2
GitHub Stars
80
更新日
10月1日