Add 9 offline geospatial tools using Turf.js #96

mattpodwysocki · 2026-01-07T23:47:13Z

Add 9 Offline Geospatial Tools Using Turf.js

This PR adds 9 new offline geospatial calculation tools that work completely without internet connectivity or API calls. All tools use Turf.js for accurate geographic computations.

Tools Added

Distance Tool - Calculate distances between coordinates
Point in Polygon Tool - Test if a point is inside a polygon
Bearing Tool - Get compass direction between two points
Midpoint Tool - Find the geographic center between two points
Centroid Tool - Calculate the center of a polygon
Area Tool - Calculate polygon area in various units
Bounding Box Tool - Get min/max coordinates containing a geometry
Buffer Tool - Create zones/radii around locations
Simplify Tool - Reduce geometry complexity while preserving shape

Key Benefits

✅ No API calls required - Works offline, no Mapbox token needed
✅ Fast calculations - Instant client-side computations
✅ Multiple units - Supports kilometers, miles, meters, feet, nautical miles, acres, hectares
✅ Comprehensive tests - 124 new tests, 556 total tests passing
✅ Full documentation - README updated with examples for all tools

Test Coverage

Added comprehensive test suites for all 9 tools:

✓ test/tools/distance-tool/DistanceTool.test.ts (15 tests)
✓ test/tools/point-in-polygon-tool/PointInPolygonTool.test.ts (10 tests)
✓ test/tools/bearing-tool/BearingTool.test.ts (15 tests)
✓ test/tools/midpoint-tool/MidpointTool.test.ts (15 tests)
✓ test/tools/centroid-tool/CentroidTool.test.ts (15 tests)
✓ test/tools/area-tool/AreaTool.test.ts (16 tests)
✓ test/tools/bounding-box-tool/BoundingBoxTool.test.ts (18 tests)
✓ test/tools/buffer-tool/BufferTool.test.ts (19 tests)
✓ test/tools/simplify-tool/SimplifyTool.test.ts (16 tests)

Total: 556 tests passing (432 existing + 124 new)

Demo Scenarios & Screenshots

1. Distance Tool

Calculate straight-line distance between two locations.

Test Scenario:

What's the distance between the Statue of Liberty (40.6892, -74.0445)
and the Empire State Building (40.7484, -73.9857) in miles?

Expected Result: ~5.2 miles

Screenshot:

2. Point in Polygon Tool

Check if a location is inside a defined area.

Test Scenario:

Is the location at coordinates (40.7829, -73.9654) inside Central Park?

Use this polygon for Central Park boundaries:
[
  [-73.9812, 40.7681],
  [-73.9581, 40.7681],
  [-73.9581, 40.8003],
  [-73.9812, 40.8003],
  [-73.9812, 40.7681]
]

Expected Result: inside: true

Screenshot:

3. Bearing Tool

Get compass direction from one location to another.

Test Scenario:

What's the compass bearing from New York City (40.7128, -74.0060)
to Los Angeles (34.0522, -118.2437)?

Expected Result: ~270° (roughly west/west-southwest)

Screenshot:

4. Buffer Tool

Create a zone/radius around a location.

Test Scenario:

Create a 1-mile buffer zone around this emergency shelter location:
Point: [40.7128, -74.0060]
Distance: 1 mile

Expected Result: Polygon representing a ~1-mile radius circle (33 vertices forming the outer ring)

Screenshot:

5. Area Tool

Calculate the size of a geographic area.

Test Scenario:

Calculate the area in square meters of this rectangular city block:
[
  [-73.9857, 40.7484],
  [-73.9847, 40.7484],
  [-73.9847, 40.7494],
  [-73.9857, 40.7494],
  [-73.9857, 40.7484]
]

Expected Result: ~10,000 square meters (approximately)

Screenshot:

6. Midpoint Tool

Find the geographic center point between two locations.

Test Scenario:

Find the midpoint between San Francisco (37.7749, -122.4194)
and Seattle (47.6062, -122.3321).

Expected Result: Coordinates near Portland, Oregon area (~42.6°N, -122.3°W)

Screenshot:

7. Centroid Tool

Find the geometric center of a polygon.

Test Scenario:

Find the centroid (center point) of Central Park:
[
  [-73.9812, 40.7681],
  [-73.9581, 40.7681],
  [-73.9581, 40.8003],
  [-73.9812, 40.8003],
  [-73.9812, 40.7681]
]

Expected Result: Coordinates near (40.7842, -73.9697)

Screenshot:

8. Bounding Box Tool

Get rectangular boundaries that contain a shape.

Test Scenario:

What's the bounding box for this route from downtown to airport:
[
  [40.7128, -74.0060],
  [40.7282, -73.9776],
  [40.7505, -73.9934],
  [40.7736, -73.8691]
]

Expected Result: [minLng, minLat, maxLng, maxLat] array containing all points

Screenshot:

9. Simplify Tool

Reduce complexity of a boundary while maintaining shape.

Test Scenario:

Simplify this zigzag path with tolerance 0.15:
[
  [0, 0],
  [1, 0.1],
  [2, -0.1],
  [3, 0.1],
  [4, -0.1],
  [5, 0]
]

Expected Result: Simplified from 6 vertices down to 2 vertices (start and end points), representing a 67% reduction. The zigzag becomes a straight line since the ±0.1 deviations are within the 0.15 tolerance.

Screenshot:

Files Changed

New Files

src/tools/distance-tool/ - Distance calculation tool
src/tools/point-in-polygon-tool/ - Point containment testing
src/tools/bearing-tool/ - Compass direction calculation
src/tools/midpoint-tool/ - Geographic midpoint finder
src/tools/centroid-tool/ - Polygon center calculator
src/tools/area-tool/ - Area measurement tool
src/tools/bounding-box-tool/ - Boundary box calculator
src/tools/buffer-tool/ - Zone/radius creator
src/tools/simplify-tool/ - Geometry simplifier
test/tools/*/ - 124 new test files for all tools

Modified Files

README.md - Documentation for all 9 tools
package.json - Added @turf/turf dependency
src/tools/toolRegistry.ts - Registered all new tools

Dependencies

Added @turf/turf@^7.1.0 for geospatial calculations.

How to Test

Build the server:
```
npm run build
```
Start with MCP Inspector:
```
npm run inspect:build
```
Try any of the test scenarios above in Claude Desktop or the Inspector

Documentation

All tools are documented in the README with:

Feature descriptions
Supported units/options
Example usage
Real-world use cases

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 <noreply@anthropic.com>

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 <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

src/tools/area-tool/AreaTool.ts

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 <noreply@anthropic.com>

src/tools/area-tool/AreaTool.input.schema.ts

mattpodwysocki and others added 2 commits January 7, 2026 18:15

mattpodwysocki requested a review from a team as a code owner January 7, 2026 23:47

mattpodwysocki and others added 2 commits January 8, 2026 15:35

Merge branch 'main' into offline-geospatial-tools

31aaa38

ctufts reviewed Jan 12, 2026

View reviewed changes

src/tools/area-tool/AreaTool.ts Show resolved Hide resolved

mattpodwysocki requested a review from ctufts January 12, 2026 18:11

ctufts reviewed Jan 12, 2026

View reviewed changes

src/tools/area-tool/AreaTool.input.schema.ts Show resolved Hide resolved

ctufts approved these changes Jan 12, 2026

View reviewed changes

mattpodwysocki merged commit 31fe224 into main Jan 12, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add 9 offline geospatial tools using Turf.js #96

Add 9 offline geospatial tools using Turf.js #96

Uh oh!

mattpodwysocki commented Jan 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add 9 offline geospatial tools using Turf.js #96

Add 9 offline geospatial tools using Turf.js #96

Uh oh!

Conversation

mattpodwysocki commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add 9 Offline Geospatial Tools Using Turf.js

Tools Added

Key Benefits

Test Coverage

Demo Scenarios & Screenshots

1. Distance Tool

2. Point in Polygon Tool

3. Bearing Tool

4. Buffer Tool

5. Area Tool

6. Midpoint Tool

7. Centroid Tool

8. Bounding Box Tool

9. Simplify Tool

Files Changed

New Files

Modified Files

Dependencies

How to Test

Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mattpodwysocki commented Jan 7, 2026 •

edited

Loading