mapbox_directions
Calculate navigation routes between locations using driving, walking, cycling, or traffic-aware driving modes to plan journeys efficiently.
Instructions
Get navigation route between two points
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coordinates | Yes | Array of coordinates | |
| profile | No | Navigation mode | driving-traffic |
Implementation Reference
- Main handler function that executes the Mapbox Directions API call. Takes coordinates and profile, constructs the API URL, handles errors, and returns formatted route information including distance, duration, and step-by-step instructions.
export async function handleDirections( coordinates: z.infer<typeof CoordinatesSchema>, profile: string = "driving" ) { const coordinatesString = coordinates .map((coord) => `${coord.longitude},${coord.latitude}`) .join(";"); const url = new URL( `https://api.mapbox.com/directions/v5/mapbox/${profile}/${coordinatesString}` ); url.searchParams.append("access_token", MAPBOX_ACCESS_TOKEN); url.searchParams.append("geometries", "geojson"); try { const response = await fetch(url.toString()); // Handle Server Error (HTTP Status Code >= 500) if (response.status >= 500) { return { content: [ { type: "text", text: `Mapbox Server Error: HTTP ${response.status}`, }, ], isError: true, }; } const data = (await response.json()) as MapboxDirectionsResponse; // Handle Business Logic Error (HTTP Status Code < 500) if (response.status < 500 && data.code !== "Ok") { return { content: [ { type: "text", text: data.message || `Route Planning Failed: ${data.code}`, }, ], isError: true, }; } // Success Case return { content: [ { type: "text", text: JSON.stringify({ routes: data.routes.map((route) => ({ distance: route.distance, duration: route.duration, steps: route.legs[0].steps.map((step) => ({ instruction: step.maneuver.instruction, distance: step.distance, duration: step.duration, })), })), }), }, ], isError: false, }; } catch (error) { return { content: [ { type: "text", text: `Request Failed: ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } } - Tool definition schema for MCP registration. Defines the tool name 'mapbox_directions', description, and input schema with coordinates array and profile enum (driving-traffic, driving, walking, cycling).
export const DIRECTIONS_TOOL: Tool = { name: "mapbox_directions", description: "Get navigation route between two points", inputSchema: { type: "object", properties: { coordinates: { type: "array", items: { type: "object", properties: { longitude: { type: "number", description: "Longitude", minimum: -180, maximum: 180, }, latitude: { type: "number", description: "Latitude", minimum: -90, maximum: 90, }, }, required: ["longitude", "latitude"], }, description: "Array of coordinates", }, profile: { type: "string", description: "Navigation mode", enum: ["driving-traffic", "driving", "walking", "cycling"], default: "driving-traffic", }, }, required: ["coordinates"], }, }; - Zod validation schemas for direction arguments. Defines CoordinateSchema (longitude/latitude), CoordinatesSchema (array of at least 2 coordinates), and DirectionsArgsSchema for parsing and validating input.
export const CoordinateSchema = z.object({ longitude: z.number().describe("Longitude"), latitude: z.number().describe("Latitude"), }); export const CoordinatesSchema = z .array(CoordinateSchema) .min(2) .describe("Array of coordinates"); // Directions Arguments Schema export const DirectionsArgsSchema = z.object({ coordinates: CoordinatesSchema, profile: z .enum(["driving-traffic", "driving", "walking", "cycling"]) .default("driving"), }); - src/server/handlers/navigation.ts:21-39 (registration)NavigationHandler class that registers the tool and routes requests. Constructor adds 'mapbox_directions' to the tools set, and the handle method uses a switch statement to parse arguments and call the handleDirections function.
export class NavigationHandler extends BaseHandler { constructor() { super(); this.tools.add("mapbox_directions"); this.tools.add("mapbox_directions_by_places"); this.tools.add("mapbox_matrix"); this.tools.add("mapbox_matrix_by_places"); this.toolDefinitions.push(DIRECTIONS_TOOL); this.toolDefinitions.push(DIRECTIONS_BY_PLACES_TOOL); this.toolDefinitions.push(MATRIX_TOOL); this.toolDefinitions.push(MATRIX_BY_PLACES_TOOL); } async handle({ name, args }: { name: string; args: any }) { switch (name) { case "mapbox_directions": { const { coordinates, profile } = DirectionsArgsSchema.parse(args); return await handleDirections(coordinates, profile); } - TypeScript interface for Mapbox Directions API response. Defines the complete response structure including routes array with legs, steps, maneuvers, distance, duration, and waypoints.
export interface MapboxDirectionsResponse { code: string; message?: string; routes: Array<{ geometry: string; distance: number; duration: number; weight: number; weight_name: string; legs: Array<{ summary: string; distance: number; duration: number; weight: number; steps: Array<{ distance: number; duration: number; geometry: string; mode: string; driving_side: string; weight: number; name: string; maneuver: { location: [number, number]; type: string; modifier?: string; bearing_before: number; bearing_after: number; instruction: string; }; intersections: Array<{ location: [number, number]; bearings: number[]; entry: boolean[]; in?: number; out?: number; }>; }>; }>; weight_typical?: number; }>; waypoints: Array<{ name: string; location: [number, number]; }>; uuid: string; }