mapbox-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/navigation/direction.ts:20-98 (handler)

  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,
      };
    }
  }

• src/tools/definitions/navigation/direction.ts:10-47 (schema)

  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"],
    },
  };

• src/schemas/navigation/direction.ts:9-25 (schema)

  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);
        }

• src/types/navigation/direction.ts:13-59 (schema)

  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;
  }