mapbox-geospatial-operations by mapbox/mapbox-agent-skills
npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-geospatial-operations为 AI 助手提供关于从 Mapbox MCP 服务器选择正确地理空间工具的专家指导。重点在于根据问题需求选择工具——几何计算与路径规划、直线距离与道路网络距离,以及精度需求。
Mapbox MCP 服务器提供两类地理空间工具:
关键问题:问题实际需要什么?
| 问题特征 | 工具类别 | 原因 |
|---|---|---|
| 直线距离(两点间直线距离) | 离线几何工具 | 用于几何距离计算准确 |
| 道路/路径距离(实际行驶距离) | 路径规划 API | 只有路径规划 API 了解道路网络 |
| 行程时间 | 路径规划 API | 需要包含速度/交通数据的路径规划 |
| 点包含关系(X 是否在 Y 内部?) | 离线几何工具 | 纯几何操作 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 地理形状操作(缓冲区、质心、面积) | 离线几何工具 | 数学/几何操作 |
| 考虑交通的路径规划 | 路径规划 API | 需要实时交通数据 |
| 路线优化(访问多个点的最佳顺序) | 路径规划 API | 复杂的路径规划算法 |
| 高频检查(例如,实时地理围栏) | 离线几何工具 | 即时响应,无延迟 |
用户提问:"X 离 Y 有多远?"
| 用户实际含义 | 工具选择 | 原因 |
|---|---|---|
| 直线距离(两点间直线距离) | distance_tool | 用于几何距离计算准确,即时 |
| 驾驶距离(实际行驶距离) | directions_tool | 只有路径规划知道实际道路距离 |
| 步行/骑行距离 | directions_tool | 需要特定的路径网络 |
| 行程时间 | directions_tool 或 matrix_tool | 需要包含速度数据的路径规划 |
| 考虑当前交通的距离 | directions_tool (driving-traffic) | 需要考虑实时交通 |
示例:"这 5 个仓库之间的距离是多少?"
distance_tool(10 次计算,即时)matrix_tool(5×5 矩阵,一次 API 调用,返回实际路线距离)关键洞察: 使用与上下文中"距离"含义匹配的工具。始终澄清:是直线距离还是实际行驶距离?
用户提问:"哪些点靠近/在这个区域内?"
| 查询类型 | 工具选择 | 原因 |
|---|---|---|
| "在 X 米半径内" | distance_tool + 过滤 | 简单的几何半径 |
| "在 X 分钟车程内" | isochrone_tool → point_in_polygon_tool | 需要路径规划获取行程时间区域,然后进行几何包含检查 |
| "在这个多边形内部" | point_in_polygon_tool | 纯几何包含测试 |
| "30 分钟内可驾车到达" | isochrone_tool | 需要路径规划 + 交通数据 |
| "离这个点最近" | distance_tool(几何距离)或 matrix_tool(路径规划距离) | 取决于"最近"的定义 |
示例:"这 200 个地址是否在我们的 30 分钟配送区域内?"
isochrone_tool(路径规划 API - 需要行程时间)point_in_polygon_tool(几何操作 - 200 次即时检查)关键洞察: 使用路径规划创建行程时间区域,使用几何工具进行包含检查
用户提问:"最佳路线是什么?"
| 场景 | 工具选择 | 原因 |
|---|---|---|
| 从 A 到 B 的路线 | directions_tool | 逐向导航路线 |
| 多个停靠点的最优顺序 | optimization_tool | 解决旅行商问题 |
| 清理 GPS 轨迹 | map_matching_tool | 贴合到道路网络 |
| 仅需要方位/罗盘方向 | bearing_tool | 简单的几何计算 |
| 考虑交通的路线 | directions_tool (driving-traffic) | 实时交通感知 |
| 固定顺序的途经点 | directions_tool 配合 waypoints 参数 | 通过特定点的路线规划 |
示例:"从酒店导航到机场"
directions_toolbearing_tool关键洞察: 实际导航使用路径规划工具,方向信息使用几何工具
用户提问:"围绕这个位置创建一个区域"
| 需求 | 工具选择 | 原因 |
|---|---|---|
| 简单的圆形缓冲区 | buffer_tool | 几何圆形/半径 |
| 行程时间区域 | isochrone_tool | 基于路径规划网络 |
| 计算面积大小 | area_tool | 几何计算 |
| 简化复杂边界 | simplify_tool | 几何简化 |
| 查找形状中心 | centroid_tool | 几何质心 |
示例:"显示每家商店周围 5 公里的覆盖范围"
buffer_tool(几何圆形)isochrone_tool(基于路径规划)关键洞察: 基于距离的区域使用几何工具,基于时间的区域使用路径规划工具
小型操作(< 100 次计算):
中型操作(100-1,000 次计算):
大型操作(> 1,000 次计算):
关键洞察: 数据量很少影响几何工具的选择,但路径规划 API 有批量工具以提高效率
| 用例 | 方法 | 工具选择 |
|---|---|---|
| 实时地理围栏(每秒) | 几何检查 | point_in_polygon_tool(即时) |
| 路线规划(一次性) | 完整路径规划 | directions_tool 或 optimization_tool |
| 定期邻近性检查 | 几何距离 | distance_tool |
| 实时交通路线规划 | 考虑交通的路径规划 | directions_tool (driving-traffic) |
高频地理围栏的架构说明: 如果应用程序以非常高的频率调用包含检查(例如,50 辆车每 2 秒 = 25 次检查/秒),通过网络调用 MCP 工具会增加代理推理开销,使其不切实际。在这种情况下,建议在进程内直接使用 Turf.js(turf.booleanPointInPolygon)处理热路径,并将 MCP 工具保留用于外围任务,如区域定义(isochrone_tool)、重新规划路线(directions_tool)或可视化(static_map_image_tool)。
用户:"找到最近的商店并显示 5 公里覆盖范围"
最优方法:
category_search_tool(自动返回距离)buffer_tool(5 公里几何圆形)static_map_image_tool原因: 搜索已提供距离;简单的半径使用几何缓冲区
用户:"优化到 8 个地址的配送路线"
最优方法:
search_and_geocode_tooloptimization_tool(带路径规划的 TSP 求解器)原因: 需要实际的路径规划进行逐向配送,而不是几何距离
用户:"这 200 个地址中,哪些我们可以在 30 分钟内配送到?"
最优方法:
isochrone_tool(30 分钟车程)point_in_polygon_tool(200 次几何检查)原因: 使用路径规划获取准确的行程时间区域,使用几何工具进行快速的包含检查
用户:"这次自行车骑行有多长?"
最优方法:
map_matching_tool(贴合到自行车道)distance_tool 计算原因: 需要道路/路径匹配;距离计算两种方式都可行
用户:"我们的总服务区域是多少?"
最优方法:
buffer_toolarea_toolisochrone_tool原因: 基于距离的覆盖范围使用几何工具,基于时间的覆盖范围使用路径规划工具
// 错误:用户问"开车到那里需要多长时间?"
distance_tool({ from: A, to: B });
// 返回 10 公里(直线距离),但实际驾驶距离是 15 公里
// 正确:需要路径规划获取驾驶距离
directions_tool({
coordinates: [
{ longitude: A[0], latitude: A[1] },
{ longitude: B[0], latitude: B[1] }
],
routing_profile: 'mapbox/driving'
});
// 返回实际道路距离和驾驶时间(实际行驶距离)
错误原因: 直线距离 ≠ 实际行驶距离
// 错误:检查点是否在多边形内
// (无法使用路径规划 API 完成此操作)
// 正确:纯几何操作
point_in_polygon_tool({ point: location, polygon: boundary });
错误原因: 路径规划 API 不处理几何包含关系
// 用户问:"20 分钟内可以到达哪些地方?"
// 错误:以平均速度计算的 20 分钟距离
distance_tool + 计算 20min * avg_speed
// 正确:考虑道路网络的实际路径规划
isochrone_tool({
coordinates: {longitude: startLng, latitude: startLat},
contours_minutes: [20],
profile: "mapbox/driving"
})
错误原因: 道路不是直线;交通状况会变化
// 用户问:"机场在哪个方向?"
// 过于复杂:完整的路径规划
directions_tool({
coordinates: [
{ longitude: hotel[0], latitude: hotel[1] },
{ longitude: airport[0], latitude: airport[1] }
]
});
// 更好:只需要方位角
bearing_tool({ from: hotel, to: airport });
// 返回:"东北方向 (45°)"
更好的原因: 更简单,即时,回答了实际问题
有些问题受益于同时使用几何和路径规划工具:
1. directions_tool → 获取路线几何形状
2. buffer_tool → 围绕路线创建走廊
3. category_search_tool → 在走廊内查找兴趣点
4. point_in_polygon_tool → 过滤出实际沿路的兴趣点
用例: "在我的路线上寻找加油站"
1. category_search_tool → 查找 10 个附近位置
2. distance_tool → 计算直线距离(几何)
3. 对于前 3 个,使用 directions_tool → 获取实际驾驶时间
用例: 快速缩小范围,然后为最终候选者获取精确的路径规划
1. isochrone_tool → 创建行程时间区域(路径规划)
2. point_in_polygon_tool → 检查数百个地址(几何)
用例: "哪些客户在我们的配送区域内?"
当用户提出地理空间问题时:
1. 是否需要路径规划、道路或行程时间?
是 → 使用路径规划 API(directions, matrix, isochrone, optimization)
否 → 继续
2. 是否需要交通感知?
是 → 使用带交通配置文件的 directions_tool 或 isochrone_tool
否 → 继续
3. 是否是几何/空间操作?
- 点之间的距离(直线) → distance_tool
- 点包含关系 → point_in_polygon_tool
- 面积计算 → area_tool
- 缓冲区/区域 → buffer_tool
- 方向/方位角 → bearing_tool
- 几何中心 → centroid_tool
- 边界框 → bounding_box_tool
- 简化 → simplify_tool
4. 是否是搜索/发现操作?
是 → 使用搜索工具(search_and_geocode, category_search)
在选择工具之前,询问:
* 直线距离 → 几何工具
* 实际行驶距离 → 路径规划 API
2. 用户需要行程时间吗?
* 是 → 路径规划 API(只有它们知道速度/交通)
* 否 → 几何工具可能足够
3. 这是关于道路/路径还是纯粹的空间关系?
* 道路/路径 → 路径规划 API
* 空间关系 → 几何工具
4. 是否需要低延迟的实时处理?
* 是 + 几何问题 → 离线工具(即时)
* 是 + 路径规划问题 → 使用路径规划 API(仍然很快)
5. 精度至关重要,还是近似值即可?
* 至关重要 + 路径规划 → 路径规划 API
* 近似值即可 → 几何工具可能可行
理解用户的含义:
| 用户说法 | 通常含义 | 工具类型 |
|---|---|---|
| "距离" | 取决于上下文!询问:直线距离还是实际行驶距离? | 变化 |
| "多远" | 通常是实际行驶距离(道路距离) | 路径规划 API |
| "附近" | 通常是直线距离(直线半径) | 几何工具 |
| "近" | 可能是任何一种 - 请澄清! | 询问 |
| "可到达" | 基于行程时间(考虑交通的实际行驶距离) | 路径规划 API |
| "内部/包含" | 几何包含关系 | 几何工具 |
| "导航/路线" | 逐向导航路线 | 路径规划 API |
| "方位角/方向" | 罗盘方向(直线方向) | 几何工具 |
distance_tool - 两点之间的直线距离bearing_tool - 从 A 到 B 的罗盘方向midpoint_tool - 两点之间的中点point_in_polygon_tool - 点是否在多边形内?area_tool - 计算多边形面积buffer_tool - 创建圆形缓冲区/区域centroid_tool - 多边形的几何中心bbox_tool - 几何形状的最小/最大坐标simplify_tool - 减少几何形状复杂度directions_tool - 逐向导航路线matrix_tool - 多对多行程时间optimization_tool - 路线优化(TSP)isochrone_tool - 行程时间区域map_matching_tool - 将 GPS 点贴合到道路在以下情况使用几何工具:
在以下情况使用路径规划 API:
可与以下技能配合使用:
每周安装量
319
代码仓库
GitHub 星标数
36
首次出现
2026 年 2 月 10 日
安全审计
安装于
gemini-cli301
opencode301
github-copilot301
codex300
amp293
kimi-cli293
Expert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on what the problem requires - geometric calculations vs routing, straight-line vs road network, and accuracy needs.
The Mapbox MCP Server provides two categories of geospatial tools:
The key question: What does the problem actually require?
| Problem Characteristic | Tool Category | Why |
|---|---|---|
| Straight-line distance (as the crow flies) | Offline geometric | Accurate for geometric distance |
| Road/path distance (as the crow drives) | Routing API | Only routing APIs know road networks |
| Travel time | Routing API | Requires routing with speed/traffic data |
| Point containment (is X inside Y?) | Offline geometric | Pure geometric operation |
| Geographic shapes (buffers, centroids, areas) | Offline geometric | Mathematical/geometric operations |
| Traffic-aware routing | Routing API | Requires real-time traffic data |
| Route optimization (best order to visit) | Routing API | Complex routing algorithm |
| High-frequency checks (e.g., real-time geofencing) | Offline geometric | Instant response, no latency |
User asks: "How far is X from Y?"
| What They Actually Mean | Tool Choice | Why |
|---|---|---|
| Straight-line distance (as the crow flies) | distance_tool | Accurate for geometric distance, instant |
| Driving distance (as the crow drives) | directions_tool | Only routing knows actual road distance |
| Walking/cycling distance (as the crow walks/bikes) | directions_tool | Need specific path network |
| Travel time | directions_tool or matrix_tool | Requires routing with speed data |
Example: "What's the distance between these 5 warehouses?"
distance_tool (10 calculations, instant)matrix_tool (5×5 matrix, one API call, returns actual route distances)Key insight: Use the tool that matches what "distance" means in context. Always clarify: crow flies or crow drives?
User asks: "Which points are near/inside this area?"
| Query Type | Tool Choice | Why |
|---|---|---|
| "Within X meters radius" | distance_tool + filter | Simple geometric radius |
| "Within X minutes drive" | isochrone_tool → point_in_polygon_tool | Need routing for travel-time zone, then geometric containment |
| "Inside this polygon" | point_in_polygon_tool | Pure geometric containment test |
| "Reachable by car in 30 min" | isochrone_tool | Requires routing + traffic |
Example: "Are these 200 addresses in our 30-minute delivery zone?"
isochrone_tool (routing API - need travel time)point_in_polygon_tool (geometric - 200 instant checks)Key insight: Routing for creating travel-time zones, geometric for containment checks
User asks: "What's the best route?"
| Scenario | Tool Choice | Why |
|---|---|---|
| A to B directions | directions_tool | Turn-by-turn routing |
| Optimal order for multiple stops | optimization_tool | Solves traveling salesman problem |
| Clean GPS trace | map_matching_tool | Snaps to road network |
| Just need bearing/compass direction | bearing_tool | Simple geometric calculation |
| Route with traffic | directions_tool (driving-traffic) |
Example: "Navigate from hotel to airport"
directions_toolbearing_toolKey insight: Routing tools for actual navigation, geometric tools for directional info
User asks: "Create a zone around this location"
| Requirement | Tool Choice | Why |
|---|---|---|
| Simple circular buffer | buffer_tool | Geometric circle/radius |
| Travel-time zone | isochrone_tool | Based on routing network |
| Calculate area size | area_tool | Geometric calculation |
| Simplify complex boundary | simplify_tool | Geometric simplification |
| Find center of shape | centroid_tool |
Example: "Show 5km coverage around each store"
buffer_tool (geometric circles)isochrone_tool (routing-based)Key insight: Geometric tools for distance-based zones, routing tools for time-based zones
Small operations ( < 100 calculations):
Medium operations (100-1,000 calculations):
Large operations ( > 1,000 calculations):
Key insight: Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency
| Use Case | Approach | Tool Choice |
|---|---|---|
| Real-time geofencing (every second) | Geometric checks | point_in_polygon_tool (instant) |
| Route planning (one-time) | Full routing | directions_tool or optimization_tool |
| Periodic proximity checks | Geometric distance | distance_tool |
| Live traffic routing | Routing with traffic | directions_tool (driving-traffic) |
Architecture note for high-frequency geofencing: If the application calls containment checks at very high rates (e.g., 50 vehicles every 2 seconds = 25 checks/second), calling MCP tools over the network adds agent-reasoning overhead that makes it impractical. In those cases, recommend using Turf.js directly in-process (turf.booleanPointInPolygon) for the hot path, and reserve MCP tools for peripheral tasks like zone definition (isochrone_tool), rerouting (directions_tool), or visualization (static_map_image_tool).
User: "Find the closest store and show 5km coverage"
Optimal approach:
category_search_tool (returns distances automatically)buffer_tool (5km geometric circle)static_map_image_toolWhy: Search already gives distances; geometric buffer for simple radius
User: "Optimize delivery to 8 addresses"
Optimal approach:
search_and_geocode_tooloptimization_tool (TSP solver with routing)Why: Need actual routing for turn-by-turn delivery, not geometric distances
User: "Which of these 200 addresses can we deliver to in 30 minutes?"
Optimal approach:
isochrone_tool (30-minute driving)point_in_polygon_tool (200 geometric checks)Why: Routing for accurate travel-time zone, geometric for fast containment checks
User: "How long was this bike ride?"
Optimal approach:
map_matching_tool (snap to bike paths)distance_toolWhy: Need road/path matching; distance calculation either way works
User: "What's our total service area?"
Optimal approach:
buffer_toolarea_toolisochrone_tool for each locationWhy: Geometric for distance-based coverage, routing for time-based
// WRONG: User asks "how long to drive there?"
distance_tool({ from: A, to: B });
// Returns 10km as the crow flies, but actual drive is 15km
// CORRECT: Need routing for driving distance
directions_tool({
coordinates: [
{ longitude: A[0], latitude: A[1] },
{ longitude: B[0], latitude: B[1] }
],
routing_profile: 'mapbox/driving'
});
// Returns actual road distance and drive time as the crow drives
Why wrong: As the crow flies ≠ as the crow drives
// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)
// CORRECT: Pure geometric operation
point_in_polygon_tool({ point: location, polygon: boundary });
Why wrong: Routing APIs don't do geometric containment
// User asks: "What's reachable in 20 minutes?"
// WRONG: 20-minute distance at average speed
distance_tool + calculate 20min * avg_speed
// CORRECT: Actual routing with road network
isochrone_tool({
coordinates: {longitude: startLng, latitude: startLat},
contours_minutes: [20],
profile: "mapbox/driving"
})
Why wrong: Roads aren't straight lines; traffic varies
// User asks: "Which direction is the airport?"
// OVERCOMPLICATED: Full routing
directions_tool({
coordinates: [
{ longitude: hotel[0], latitude: hotel[1] },
{ longitude: airport[0], latitude: airport[1] }
]
});
// BETTER: Just need bearing
bearing_tool({ from: hotel, to: airport });
// Returns: "Northeast (45°)"
Why better: Simpler, instant, answers the actual question
Some problems benefit from using both geometric and routing tools:
1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route
Use case: "Find gas stations along my route"
1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time
Use case: Quickly narrow down, then get precise routing for finalists
1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)
Use case: "Which customers are in our delivery zone?"
When user asks a geospatial question:
1. Does it require routing, roads, or travel times?
YES → Use routing API (directions, matrix, isochrone, optimization)
NO → Continue
2. Does it require traffic awareness?
YES → Use directions_tool or isochrone_tool with traffic profile
NO → Continue
3. Is it a geometric/spatial operation?
- Distance between points (straight-line) → distance_tool
- Point containment → point_in_polygon_tool
- Area calculation → area_tool
- Buffer/zone → buffer_tool
- Direction/bearing → bearing_tool
- Geometric center → centroid_tool
- Bounding box → bounding_box_tool
- Simplification → simplify_tool
4. Is it a search/discovery operation?
YES → Use search tools (search_and_geocode, category_search)
Before choosing a tool, ask:
Does "distance" mean as the crow flies or as the crow drives?
Does the user need travel time?
Is this about roads/paths or pure spatial relationships?
Does this need to happen in real-time with low latency?
Is accuracy critical, or is approximation OK?
Understanding what users mean:
| User Says | Usually Means | Tool Type |
|---|---|---|
| "Distance" | Context-dependent! Ask: crow flies or crow drives? | Varies |
| "How far" | Often as the crow drives (road distance) | Routing API |
| "Nearby" | Usually as the crow flies (straight-line radius) | Geometric |
| "Close" | Could be either - clarify! | Ask |
| "Reachable" | Travel-time based (crow drives with traffic) | Routing API |
| "Inside/contains" | Geometric containment | Geometric |
| "Navigate/directions" | Turn-by-turn routing | Routing API |
| "Bearing/direction" | Compass direction (crow flies) | Geometric |
distance_tool - Straight-line distance between two pointsbearing_tool - Compass direction from A to Bmidpoint_tool - Midpoint between two pointspoint_in_polygon_tool - Is point inside polygon?area_tool - Calculate polygon areabuffer_tool - Create circular buffer/zonecentroid_tool - Geometric center of polygonbbox_tool - Min/max coordinates of geometrysimplify_tool - Reduce geometry complexitydirections_tool - Turn-by-turn routingmatrix_tool - Many-to-many travel timesoptimization_tool - Route optimization (TSP)isochrone_tool - Travel-time zonesmap_matching_tool - Snap GPS to roadsUse Geometric Tools When:
Use Routing APIs When:
Works with:
Weekly Installs
319
Repository
GitHub Stars
36
First Seen
Feb 10, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli301
opencode301
github-copilot301
codex300
amp293
kimi-cli293
DOCX文件创建、编辑与分析完整指南 - 使用docx-js、Pandoc和Python脚本
42,600 周安装
| Distance with current traffic | directions_tool (driving-traffic) | Need real-time traffic consideration |
| "Nearest to this point" |
distance_tool (geometric) or matrix_tool (routed) |
| Depends on definition of "nearest" |
| Real-time traffic awareness |
| Fixed-order waypoints | directions_tool with waypoints | Routing through specific points |
| Geometric centroid |