mcpField
M
mapbox-mcp-runtime-patterns

mapbox-mcp-runtime-patterns

github.com/mapbox开发831.4k 次安装4 周前更新
代码仓库

关于 mapbox-mcp-runtime-patterns

为在 AI 应用中集成 Mapbox MCP Server 提供运行时模式与生产指导，适合构建地理空间 Agent 的开发者。内容讲解工具选择、托管或自托管部署，以及多种 Agent 框架的集成参考。

主要功能

  1. 01离线与 API 地理空间工具选用指导
  2. 02托管和自托管部署说明
  3. 03按任务区分搜索、距离与路线工具
  4. 04多种 Agent 框架集成参考
  5. 05生产环境缓存、安全与错误处理指导

适用场景

  1. 01为 AI 应用接入地理空间能力
  2. 02构建路线规划或地点搜索 Agent
  3. 03选择直线距离或道路行程工具
  4. 04规划地理空间服务的生产部署

MCP 相关

说明如何在 AI 应用中集成 Mapbox MCP Server；该服务向 MCP 客户端提供 Turf.js 离线操作、Mapbox API 地理空间工具及实用工具。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-mcp-runtime-patterns

安装后在 Claude Code 中输入/mapbox-mcp-runtime-patterns确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
evals/
evals.json
examples/
README.md
examples/python/
crewai_example.py
pydantic_ai_example.py
requirements.txt
smolagents_example.py
examples/typescript/
langchain-example.ts
mastra-example.ts
package-lock.json
package.json
tsconfig.json
references/
crewai.md
custom-agent.md
langchain.md
mastra.md
production.md
pydantic-ai.md
smolagents.md
use-cases.md

详细介绍

Mapbox MCP 运行模式

本技能提供将 Mapbox MCP Server 集成到 AI 应用中的模式，以便在生产环境中使用地理空间功能。

什么是 Mapbox MCP Server？

Mapbox MCP Server 是一种模型上下文协议（MCP）服务，可为 AI Agent 提供地理空间工具：

离线工具（Turf.js）：

  • 距离、方位角和中点计算
  • 点是否位于多边形内的测试
  • 面积、缓冲区和质心运算
  • 边界框、几何简化
  • 无需 API 调用，即时返回结果

Mapbox API 工具：

  • 路线规划与导航
  • 反向地理编码
  • POI 类别搜索
  • 等时圈（可达范围）
  • 出行时间矩阵
  • 静态地图图像
  • GPS 轨迹地图匹配
  • 多站点路线优化

实用工具：

  • 服务版本信息
  • POI 类别列表

**主要优势：**无需手动集成多个 API，即可为 AI 应用赋予强大的地理空间能力。

了解工具类别

集成之前，请先了解工具之间的主要区别，以帮助大模型正确选择：

距离：“直线距离”与“沿道路距离”

直线距离（离线、即时）：

  • 工具：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
  • 返回：前往一个目的地的逐向导航
  • 示例：“我怎么去机场？” → 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 Agent 加载：references/pydantic-ai.md

  • CrewAI——多 Agent 编排 加载：references/crewai.md

  • Smolagents——轻量级 HuggingFace Agent 加载：references/smolagents.md

  • Mastra——多 Agent TypeScript 系统 加载：references/mastra.md

  • LangChain——使用工具链的对话式 AI 加载：references/langchain.md

  • 自定义 Agent——Zillow/TripAdvisor/DoorDash 风格的模式、架构图、混合方案 加载：references/custom-agent.md

  • 用例——房地产、外卖、旅行规划示例 加载：references/use-cases.md

  • 生产环境模式——缓存、批量操作、工具描述、错误处理、安全性、速率限制、测试 加载：references/production.md

资源

何时使用此技能

在以下情况下调用此技能：

  • 将 Mapbox MCP Server 集成到 AI 应用中
  • 构建具备地理空间能力的 AI Agent
  • 使用 AI 设计 Zillow/TripAdvisor/DoorDash 风格的应用
  • 在 MCP、直接 API 或 SDK 之间进行选择
  • 优化生产环境中的地理空间操作
  • 为地理空间 AI 功能实现错误处理
  • 使用地理空间工具测试 AI 应用

评论

支持 Markdown