Add Map Matching and Optimization tools (V1 API) (#97)

* Add Map Matching and Optimization tools

Implements two new Mapbox Navigation API tools:

- Map Matching Tool (map_matching_tool): Snaps GPS traces to roads
  - Supports 2-100 coordinates with optional timestamps and radiuses
  - Returns confidence scores, matched geometry, and annotations
  - Handles driving, cycling, walking, and driving-traffic profiles

- Optimization Tool (optimization_tool): Solves vehicle routing problems
  - Supports up to 1000 coordinates
  - Simplified mode: auto-generates vehicle and services
  - Advanced mode: custom vehicles, services, shipments, time windows
  - Async polling mechanism (POST + GET)

Both tools include:
- Complete input/output schemas with Zod validation
- Comprehensive unit tests (19 tests total)
- Proper annotations (readOnlyHint, openWorldHint, etc.)

All 422 tests passing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* Update @modelcontextprotocol/sdk to 1.25.2 (CVE fix)

Update SDK from 1.25.1 to 1.25.2 which includes security fixes.
Update patch file to match new SDK version.

All 457 tests passing with updated SDK.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* Refactor optimization tool to use V1 API with V2 ready for future

- Switch optimization_tool to use V1 synchronous GET API (publicly available)
- V1 supports 2-12 coordinates, simple TSP, works immediately
- Preserve V2 implementation as OptimizationV2Tool (not registered)
- V2 code ready to enable when API becomes public
- Remove task-based infrastructure from main registration
- All 456 tests passing

V1 endpoint: GET /optimized-trips/v1/{profile}/{coordinates}
V2 endpoint: POST /optimized-trips/v2 (requires beta access)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* Document Map Matching and Optimization tools in README

- Add Map Matching tool section with features and example usage
- Add Optimization tool section with features and example usage
- Note about V2 Optimization API implementation (beta access required)
- Update intro to mention route optimization and map matching capabilities
- Add new "GPS & Route Matching" example prompts section
- Add optimization example to Analysis & Planning section

🤖 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]>

Author: mattpodwysocki

README.md

@@ -12,6 +12,8 @@ The Mapbox MCP Server transforms any AI agent or application into a geospatially
 - **Points of interest (POI) search** across millions of businesses, landmarks, and places worldwide
 - **Multi-modal routing** for driving, walking, and cycling with real-time traffic
 - **Travel time matrices** to analyze accessibility and optimize logistics
+- **Route optimization** to find the optimal visiting order for multiple stops (traveling salesman problem)
+- **Map matching** to snap GPS traces to the road network for clean route visualization
 - **Isochrone generation** to visualize areas reachable within specific time or distance constraints
 - **Static map images** to create visual representations of locations, routes, and geographic data
 - **Offline geospatial calculations** for distance, area, bearing, buffers, and spatial analysis without requiring API calls
@@ -77,6 +79,13 @@ Try these prompts with Claude Desktop or other MCP clients after setup:
 - "Show me areas reachable within 30 minutes of downtown Portland by car"
 - "Calculate a travel time matrix between these 3 hotel locations (Marriott, Sheraton and Hilton) and the convention center in Denver"
 - "Find the optimal route visiting these 3 tourist attractions (Golden Gate, Musical Stairs and Fisherman's Wharf) in San Francisco"
+- "Optimize a delivery route for these 8 addresses: [list of addresses]"
+
+### GPS & Route Matching
+
+- "Clean up this GPS trace and show the actual route on roads: [list of coordinates with timestamps]"
+- "Snap this recorded bicycle ride to the cycling network: [GPS coordinates]"
+- "Match this driving route to the road network and show traffic congestion levels"
 
 ### Offline Geospatial Calculations
 
@@ -386,6 +395,36 @@ Computes areas that are reachable within a specified amount of times from a loca
 Uses the [Mapbox Search Box Text Search API](https://docs.mapbox.com/api/search/search-box/#search-request) endpoint to power searching for and geocoding POIs, addresses, places, and any other types supported by that API.
 This tool consolidates the functionality that was previously provided by the ForwardGeocodeTool and PoiSearchTool (from earlier versions of this MCP server) into a single tool.
 
+#### Map matching tool
+
+Snaps GPS traces to the road network using the [Mapbox Map Matching API](https://docs.mapbox.com/api/navigation/map-matching/). Features include:
+
+- Convert noisy GPS traces to clean routes on the road network
+- Support for different travel profiles (driving, driving-traffic, walking, cycling)
+- Handle up to 100 coordinate pairs per request
+- Optional timestamps for improved accuracy based on speed
+- Configurable snap radiuses for different GPS quality levels
+- Route annotations (speed limits, distance, duration, traffic congestion)
+- Multiple geometry output formats (GeoJSON, polyline)
+
+**Example Usage**: "Clean up this GPS trace and snap it to roads: [coordinates with timestamps]"
+
+#### Optimization tool
+
+Finds the optimal route through multiple locations using the [Mapbox Optimization API](https://docs.mapbox.com/api/navigation/optimization/). Features include:
+
+- Solve traveling salesman problem (TSP) for 2-12 locations
+- Support for different travel profiles (driving, driving-traffic, walking, cycling)
+- Flexible start and end point configuration
+- Roundtrip or one-way trip optimization
+- Turn-by-turn navigation instructions (optional)
+- Route annotations (distance, duration, speed)
+- Multiple geometry output formats (GeoJSON, polyline)
+
+**Example Usage**: "Find the optimal route to visit these 5 stops: [list of addresses or coordinates]"
+
+**Note**: A V2 API with advanced features (time windows, capacity constraints, multiple vehicles) is available but requires beta access. The V2 implementation is included in the codebase but not registered by default.
+
 # Development
 
 ## Inspecting server

package-lock.json

@@ -76,7 +76,7 @@
   ],
   "dependencies": {
     "@mcp-ui/server": "^5.13.1",
-    "@modelcontextprotocol/sdk": "^1.25.1",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.56.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.56.0",

package.json

@@ -0,0 +1,74 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { z } from 'zod';
+import { coordinateSchema } from '../../schemas/shared.js';
+
+export const MapMatchingInputSchema = z.object({
+  coordinates: z
+    .array(coordinateSchema)
+    .min(2, 'At least two coordinate pairs are required.')
+    .max(100, 'Up to 100 coordinate pairs are supported.')
+    .describe(
+      'Array of coordinate objects with longitude and latitude properties representing a GPS trace. ' +
+        'Must include at least 2 and up to 100 coordinate pairs. ' +
+        'Coordinates should be in the order they were recorded.'
+    ),
+  profile: z
+    .enum(['driving', 'driving-traffic', 'walking', 'cycling'])
+    .default('driving')
+    .describe(
+      'Routing profile for different modes of transport. Options: \n' +
+        '- driving: automotive based on road network\n' +
+        '- driving-traffic: automotive with current traffic conditions\n' +
+        '- walking: pedestrian/hiking\n' +
+        '- cycling: bicycle'
+    ),
+  timestamps: z
+    .array(z.number().int().positive())
+    .optional()
+    .describe(
+      'Array of Unix timestamps (in seconds) corresponding to each coordinate. ' +
+        'If provided, must have the same length as coordinates array. ' +
+        'Used to improve matching accuracy based on speed.'
+    ),
+  radiuses: z
+    .array(z.number().min(0))
+    .optional()
+    .describe(
+      'Array of maximum distances (in meters) each coordinate can snap to the road network. ' +
+        'If provided, must have the same length as coordinates array. ' +
+        'Default is unlimited. Use smaller values (5-25m) for high-quality GPS, ' +
+        'larger values (50-100m) for noisy GPS traces.'
+    ),
+  annotations: z
+    .array(z.enum(['speed', 'distance', 'duration', 'congestion']))
+    .optional()
+    .describe(
+      'Additional data to include in the response. Options: \n' +
+        '- speed: Speed limit per segment (km/h)\n' +
+        '- distance: Distance per segment (meters)\n' +
+        '- duration: Duration per segment (seconds)\n' +
+        '- congestion: Traffic level per segment (low, moderate, heavy, severe)'
+    ),
+  overview: z
+    .enum(['full', 'simplified', 'false'])
+    .default('full')
+    .describe(
+      'Format of the returned geometry. Options: \n' +
+        '- full: Returns full geometry with all points\n' +
+        '- simplified: Returns simplified geometry\n' +
+        '- false: No geometry returned'
+    ),
+  geometries: z
+    .enum(['geojson', 'polyline', 'polyline6'])
+    .default('geojson')
+    .describe(
+      'Format of the returned geometry. Options: \n' +
+        '- geojson: GeoJSON LineString (recommended)\n' +
+        '- polyline: Polyline with precision 5\n' +
+        '- polyline6: Polyline with precision 6'
+    )
+});
+
+export type MapMatchingInput = z.infer<typeof MapMatchingInputSchema>;

…s/@modelcontextprotocol+sdk+1.25.1.patch …s/@modelcontextprotocol+sdk+1.25.2.patchpatches/@modelcontextprotocol+sdk+1.25.1.patch renamed to patches/@modelcontextprotocol+sdk+1.25.2.patch patches/@modelcontextprotocol+sdk+1.25.1.patch renamed to patches/@modelcontextprotocol+sdk+1.25.2.patch

@@ -0,0 +1,56 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { z } from 'zod';
+
+// GeoJSON LineString schema
+const GeoJSONLineStringSchema = z.object({
+  type: z.literal('LineString'),
+  coordinates: z.array(
+    z
+      .tuple([z.number(), z.number()])
+      .or(z.tuple([z.number(), z.number(), z.number()]))
+  )
+});
+
+// Tracepoint schema - represents a snapped coordinate
+const TracepointSchema = z.object({
+  name: z.string().optional(),
+  location: z.tuple([z.number(), z.number()]),
+  waypoint_index: z.number().optional(),
+  matchings_index: z.number(),
+  alternatives_count: z.number()
+});
+
+// Matching schema - represents a matched route
+const MatchingSchema = z.object({
+  confidence: z.number().min(0).max(1),
+  distance: z.number(),
+  duration: z.number(),
+  geometry: z.union([GeoJSONLineStringSchema, z.string()]),
+  legs: z
+    .array(
+      z.object({
+        distance: z.number(),
+        duration: z.number(),
+        annotation: z
+          .object({
+            speed: z.array(z.number()).optional(),
+            distance: z.array(z.number()).optional(),
+            duration: z.array(z.number()).optional(),
+            congestion: z.array(z.string()).optional()
+          })
+          .optional()
+      })
+    )
+    .optional()
+});
+
+// Main output schema
+export const MapMatchingOutputSchema = z.object({
+  code: z.string(),
+  matchings: z.array(MatchingSchema),
+  tracepoints: z.array(TracepointSchema.nullable())
+});
+
+export type MapMatchingOutput = z.infer<typeof MapMatchingOutputSchema>;

src/tools/map-matching-tool/MapMatchingTool.input.schema.ts

@@ -0,0 +1,155 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { URLSearchParams } from 'node:url';
+import type { z } from 'zod';
+import { MapboxApiBasedTool } from '../MapboxApiBasedTool.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { MapMatchingInputSchema } from './MapMatchingTool.input.schema.js';
+import {
+  MapMatchingOutputSchema,
+  type MapMatchingOutput
+} from './MapMatchingTool.output.schema.js';
+import type { HttpRequest } from '../../utils/types.js';
+
+// Docs: https://docs.mapbox.com/api/navigation/map-matching/
+
+export class MapMatchingTool extends MapboxApiBasedTool<
+  typeof MapMatchingInputSchema,
+  typeof MapMatchingOutputSchema
+> {
+  name = 'map_matching_tool';
+  description =
+    'Snap GPS traces to roads using Mapbox Map Matching API. Takes noisy/inaccurate ' +
+    'coordinate sequences (2-100 points) and returns clean routes aligned with actual ' +
+    'roads, bike paths, or walkways. Useful for analyzing recorded trips, cleaning ' +
+    'fleet tracking data, or processing fitness activity traces. Returns confidence ' +
+    'scores, matched geometry, and optional traffic/speed annotations.';
+  annotations = {
+    title: 'Map Matching Tool',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  };
+
+  constructor(params: { httpRequest: HttpRequest }) {
+    super({
+      inputSchema: MapMatchingInputSchema,
+      outputSchema: MapMatchingOutputSchema,
+      httpRequest: params.httpRequest
+    });
+  }
+
+  protected async execute(
+    input: z.infer<typeof MapMatchingInputSchema>,
+    accessToken: string
+  ): Promise<CallToolResult> {
+    // Validate timestamps array length matches coordinates
+    if (
+      input.timestamps &&
+      input.timestamps.length !== input.coordinates.length
+    ) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'The timestamps array must have the same length as the coordinates array'
+          }
+        ],
+        isError: true
+      };
+    }
+
+    // Validate radiuses array length matches coordinates
+    if (input.radiuses && input.radiuses.length !== input.coordinates.length) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'The radiuses array must have the same length as the coordinates array'
+          }
+        ],
+        isError: true
+      };
+    }
+
+    // Build coordinate string: "lon1,lat1;lon2,lat2;..."
+    const coordsString = input.coordinates
+      .map((coord) => `${coord.longitude},${coord.latitude}`)
+      .join(';');
+
+    // Build query parameters
+    const queryParams = new URLSearchParams();
+    queryParams.append('access_token', accessToken);
+    queryParams.append('geometries', input.geometries);
+    queryParams.append('overview', input.overview);
+
+    // Add timestamps if provided (semicolon-separated)
+    if (input.timestamps) {
+      queryParams.append('timestamps', input.timestamps.join(';'));
+    }
+
+    // Add radiuses if provided (semicolon-separated)
+    if (input.radiuses) {
+      queryParams.append('radiuses', input.radiuses.join(';'));
+    }
+
+    // Add annotations if provided (comma-separated)
+    if (input.annotations && input.annotations.length > 0) {
+      queryParams.append('annotations', input.annotations.join(','));
+    }
+
+    const url = `${MapboxApiBasedTool.mapboxApiEndpoint}matching/v5/mapbox/${input.profile}/${coordsString}?${queryParams.toString()}`;
+
+    const response = await this.httpRequest(url);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      let errorMessage = `Request failed with status ${response.status}: ${response.statusText}`;
+
+      try {
+        const errorJson = JSON.parse(errorText);
+        if (errorJson.message) {
+          errorMessage = `${errorMessage} - ${errorJson.message}`;
+        }
+      } catch {
+        if (errorText) {
+          errorMessage = `${errorMessage} - ${errorText}`;
+        }
+      }
+
+      return {
+        content: [{ type: 'text', text: errorMessage }],
+        isError: true
+      };
+    }
+
+    const data = (await response.json()) as MapMatchingOutput;
+
+    // Validate the response against our output schema
+    try {
+      const validatedData = MapMatchingOutputSchema.parse(data);
+
+      return {
+        content: [
+          { type: 'text', text: JSON.stringify(validatedData, null, 2) }
+        ],
+        structuredContent: validatedData,
+        isError: false
+      };
+    } catch (validationError) {
+      // If validation fails, return the raw result anyway with a warning
+      this.log(
+        'warning',
+        `Schema validation warning: ${validationError instanceof Error ? validationError.message : String(validationError)}`
+      );
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+        isError: false
+      };
+    }
+  }
+}