Skip to content

Commit 31fe224

Browse files
Add 9 offline geospatial tools using Turf.js (#96)
* Add distance_tool for offline geospatial calculations Implements the first offline geospatial tool using Turf.js for calculating great-circle distance between two geographic coordinates. Features: - Calculate distance between any two points on Earth - Support for multiple units: km, miles, meters, feet, nautical miles - Haversine formula for accurate great-circle distance - Completely offline - no API calls required - Fast local calculations with OpenTelemetry tracing Technical details: - Uses Turf.js distance function - Follows project patterns (BaseTool, proper annotations) - Coordinate format: { longitude, latitude } objects (not tuples) - Read-only, idempotent, closed-world tool - Full test coverage with 8 test cases Dependencies added: - @turf/turf: Comprehensive geospatial analysis library All 433 tests passing ✅ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]> * Add 8 offline geospatial tools using Turf.js Implement fundamental geospatial calculation tools that work completely offline without requiring Mapbox API calls: - point_in_polygon_tool: Test if a point is inside a polygon - bearing_tool: Calculate compass direction between coordinates - midpoint_tool: Find geographic midpoint between two points - centroid_tool: Calculate center point of polygons - area_tool: Calculate polygon area in various units (meters, km, acres, etc) - bbox_tool: Calculate bounding box of any geometry - buffer_tool: Create buffer zones around geometries - simplify_tool: Reduce vertex count while preserving shape All tools: - Extend BaseTool (not MapboxApiBasedTool) for offline operation - Use Turf.js (@turf/turf) for geospatial calculations - Include OpenTelemetry tracing - Have proper annotations (openWorldHint: false) - Use coordinate objects for inputs to avoid JSON schema issues Updated test annotations to include all offline tools in exclusion list. All 457 tests passing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]> * Update README with offline geospatial tools documentation - Add new "Offline Geospatial Tools" section documenting all 9 tools - Update intro to mention offline calculations capability - Add example prompts for offline geospatial calculations - Document features and use cases for each offline tool 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]> * Add comprehensive test coverage for offline geospatial tools Add test suites for 8 offline tools that were missing coverage: 1. **Point in Polygon Tool** (10 tests) - Simple polygons (inside/outside) - Complex polygons - Polygons with holes - Edge cases (boundaries, extreme coordinates) - Large polygons with many vertices 2. **Bearing Tool** (15 tests) - Cardinal directions (N, S, E, W) - Ordinal directions (NE, SE, SW, NW) - Real world locations - Antimeridian crossing - Near poles - Reverse bearing validation 3. **Midpoint Tool** (15 tests) - Points on equator and meridians - Real world city pairs - Same point edge case - Antimeridian crossing - Hemispheres (N/S, E/W) - Precision and rounding 4. **Centroid Tool** (15 tests) - Simple shapes (square, rectangle, triangle) - Polygons with holes - Multipolygons - Complex irregular shapes - Extreme coordinates - Precision validation 5. **Area Tool** (16 tests) - All supported units (meters, km, feet, miles, acres, hectares) - Simple and complex polygons - Polygons with holes - Multipolygons - Different latitudes (equator, poles) - Precision rounding 6. **Bounding Box Tool** (18 tests) - All geometry types (point, line, polygon, multipolygon) - Complex shapes - Extreme coordinates - Precision validation - Format verification 7. **Buffer Tool** (19 tests) - All geometry types (point, line, polygon) - All supported units - Various distances (small to large) - Real world locations - Different hemispheres - Validation of output format 8. **Simplify Tool** (16 tests) - Linestrings and polygons - Various tolerance levels - High quality mode - Straight lines and curves - Polygons with holes - Reduction percentage calculation All 556 tests now passing (124 new tests added). Addresses PR feedback: #96 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 4.5 <[email protected]>
1 parent c4b357d commit 31fe224

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+6447
-6
lines changed

README.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The Mapbox MCP Server transforms any AI agent or application into a geospatially
1414
- **Travel time matrices** to analyze accessibility and optimize logistics
1515
- **Isochrone generation** to visualize areas reachable within specific time or distance constraints
1616
- **Static map images** to create visual representations of locations, routes, and geographic data
17+
- **Offline geospatial calculations** for distance, area, bearing, buffers, and spatial analysis without requiring API calls
1718

1819
Whether you're building an AI travel assistant, logistics optimizer, location-based recommender, or any application that needs to understand "where", the Mapbox MCP Server provides the spatial intelligence to make it possible. You can also enable it on popular clients like Claude Desktop and VS Code. See below for details
1920

@@ -77,6 +78,18 @@ Try these prompts with Claude Desktop or other MCP clients after setup:
7778
- "Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
7879
- "Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
7980

81+
### Offline Geospatial Calculations
82+
83+
- "What's the distance in miles between these two coordinates?"
84+
- "Calculate the area of this polygon in square kilometers"
85+
- "Is the point at 37.7749°N, 122.4194°W inside this service area polygon?"
86+
- "What's the bearing from San Francisco to New York?"
87+
- "Find the midpoint between London and Paris"
88+
- "Create a 5-mile buffer zone around this location"
89+
- "Calculate the centroid of this neighborhood boundary"
90+
- "What's the bounding box for these route coordinates?"
91+
- "Simplify this complex polygon to reduce the number of points"
92+
8093
### Tips for Better Results
8194

8295
- Be specific about locations (use full addresses or landmark names)
@@ -178,6 +191,119 @@ Provides access to MCP resources for clients that don't support the native MCP r
178191

179192
**Note**: If your MCP client supports native resources, prefer using the resource API directly for better performance.
180193

194+
### Offline Geospatial Tools
195+
196+
These tools perform geospatial calculations completely offline without requiring Mapbox API calls. They use [Turf.js](https://turfjs.org/) for accurate geographic computations and work anywhere, even without internet connectivity.
197+
198+
#### Distance Tool
199+
200+
Calculate the distance between two geographic coordinates using the Haversine formula.
201+
202+
**Features**:
203+
204+
- Supports multiple units: kilometers, miles, meters, feet, nautical miles
205+
- Accurate great-circle distance calculation
206+
- No API calls required
207+
208+
**Example Usage**: "What's the distance between San Francisco (37.7749°N, 122.4194°W) and New York (40.7128°N, 74.0060°W)?"
209+
210+
#### Point in Polygon Tool
211+
212+
Test whether a point is inside a polygon or multipolygon.
213+
214+
**Features**:
215+
216+
- Works with complex polygons including holes
217+
- Supports multipolygons
218+
- Useful for geofencing and service area checks
219+
220+
**Example Usage**: "Is this delivery address inside our service area?"
221+
222+
#### Bearing Tool
223+
224+
Calculate the compass direction (bearing) from one coordinate to another.
225+
226+
**Features**:
227+
228+
- Returns bearing in degrees (0-360°)
229+
- Provides cardinal direction (N, NE, E, SE, S, SW, W, NW)
230+
- Useful for navigation and directional queries
231+
232+
**Example Usage**: "What direction should I head to go from here to the airport?"
233+
234+
#### Midpoint Tool
235+
236+
Find the geographic midpoint between two coordinates along the great circle path.
237+
238+
**Features**:
239+
240+
- Calculates true midpoint on Earth's curved surface
241+
- Useful for meeting point suggestions
242+
- Handles long-distance calculations correctly
243+
244+
**Example Usage**: "What's halfway between San Francisco and New York?"
245+
246+
#### Centroid Tool
247+
248+
Calculate the geometric center (centroid) of a polygon or multipolygon.
249+
250+
**Features**:
251+
252+
- Works with complex shapes
253+
- Returns arithmetic mean of all points
254+
- Useful for placing labels or markers
255+
256+
**Example Usage**: "Where should I place a marker for this neighborhood boundary?"
257+
258+
#### Area Tool
259+
260+
Calculate the area of a polygon.
261+
262+
**Features**:
263+
264+
- Supports multiple units: square meters, square kilometers, acres, hectares, square miles, square feet
265+
- Accurate area calculation on Earth's surface
266+
- Works with polygons of any size
267+
268+
**Example Usage**: "What's the area of this park in acres?"
269+
270+
#### Bounding Box Tool
271+
272+
Calculate the minimum bounding box (bbox) that contains a geometry.
273+
274+
**Features**:
275+
276+
- Works with points, lines, polygons, and multipolygons
277+
- Returns [minLongitude, minLatitude, maxLongitude, maxLatitude]
278+
- Useful for viewport calculations and spatial indexing
279+
280+
**Example Usage**: "What's the bounding box for this route?"
281+
282+
#### Buffer Tool
283+
284+
Create a buffer zone (polygon) around a point, line, or polygon.
285+
286+
**Features**:
287+
288+
- Supports multiple distance units
289+
- Creates circular buffers around points
290+
- Useful for proximity analysis and creating zones of influence
291+
292+
**Example Usage**: "Show me a 5km buffer zone around this location"
293+
294+
#### Simplify Tool
295+
296+
Reduce the number of vertices in a line or polygon using the Douglas-Peucker algorithm.
297+
298+
**Features**:
299+
300+
- Configurable tolerance for detail level
301+
- Preserves overall shape while reducing complexity
302+
- Useful for reducing file sizes and improving rendering performance
303+
- Option to maintain topology (prevent self-intersections)
304+
305+
**Example Usage**: "Simplify this complex boundary to reduce the number of points"
306+
181307
### Mapbox API Tools
182308

183309
#### Category List Tool (Deprecated)

0 commit comments

Comments
 (0)