mapbox-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/navigation/direction-by-places.ts:20-129 (handler)

  The main handler function that implements the mapbox_directions_by_places tool logic. It geocodes place names to coordinates, validates results, and calls the directions API to calculate routes between places.

  export async function handleDirectionsByPlaces(
    args: z.infer<typeof DirectionsByPlacesArgsSchema>
  ) {
    const { places, profile, language } = args;
    const errors: DirectionsByPlacesError[] = [];
    const coordinates: { longitude: number; latitude: number }[] = [];
    const geocodingResults: Record<string, any> = {};
  
    // 1. Geocode each place
    for (const place of places) {
      try {
        const geocodingResult = await handleGeocoding({
          searchText: place,
          limit: 1,
          language,
          fuzzyMatch: true,
        });
  
        if (geocodingResult.isError || !geocodingResult.content[0]) {
          errors.push({
            place,
            error: `Geocoding failed: ${
              JSON.parse(geocodingResult.content[0].text).message ||
              "No results found"
            }`,
          });
          geocodingResults[place] = null;
          continue;
        }
  
        const feature = JSON.parse(geocodingResult.content[0].text).results[0];
        geocodingResults[place] = feature;
        coordinates.push(feature.coordinates);
      } catch (error) {
        errors.push({
          place,
          error: `Geocoding failed: ${
            error instanceof Error ? error.message : String(error)
          }`,
        });
        geocodingResults[place] = null;
      }
    }
  
    // 2. If we don't have enough valid coordinates, return error
    if (coordinates.length < 2) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              geocodingResults,
              directionsResult: null,
              errors: [
                ...errors,
                {
                  place: "general",
                  error: "Not enough valid coordinates to calculate route",
                },
              ],
            }),
          },
        ],
        isError: true,
      };
    }
  
    // 3. Get directions using the coordinates
    try {
      const directionsResult = await handleDirections(coordinates, profile);
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              geocodingResults,
              directionsResult: directionsResult.isError
                ? null
                : JSON.parse(directionsResult.content[0].text),
              errors: errors.length > 0 ? errors : undefined,
            }),
          },
        ],
        isError: directionsResult.isError,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              geocodingResults,
              directionsResult: null,
              errors: [
                ...errors,
                {
                  place: "general",
                  error: `Directions calculation failed: ${
                    error instanceof Error ? error.message : String(error)
                  }`,
                },
              ],
            }),
          },
        ],
        isError: true,
      };
    }
  }

• src/schemas/navigation/direction-by-places.ts:10-23 (schema)

  Zod schema for validating the mapbox_directions_by_places tool arguments, including places array, profile enum, and optional language parameter.

  export const DirectionsByPlacesArgsSchema = z.object({
    places: z
      .array(z.string())
      .min(2)
      .describe("Array of place names to route between"),
    profile: z
      .enum(["driving-traffic", "driving", "walking", "cycling"])
      .default("driving"),
    language: z
      .string()
      .regex(/^[a-z]{2}$/)
      .optional()
      .describe("Language for geocoding results"),
  });

• src/server/handlers/navigation.ts:40-43 (registration)

  Registration and routing handler that processes the mapbox_directions_by_places tool call, validates arguments using the schema, and delegates to the handler function.

  case "mapbox_directions_by_places": {
    const validatedArgs = DirectionsByPlacesArgsSchema.parse(args);
    return await handleDirectionsByPlaces(validatedArgs);
  }

• src/tools/definitions/navigation/direction-by-places.ts:10-38 (registration)

  MCP tool definition that defines the input schema and description for the mapbox_directions_by_places tool exposed to clients.

  export const DIRECTIONS_BY_PLACES_TOOL: Tool = {
    name: "mapbox_directions_by_places",
    description: "Get navigation route between multiple places using their names",
    inputSchema: {
      type: "object",
      properties: {
        places: {
          type: "array",
          items: {
            type: "string",
          },
          minItems: 2,
          description: "Array of place names to route between",
        },
        profile: {
          type: "string",
          description: "Navigation mode",
          enum: ["driving-traffic", "driving", "walking", "cycling"],
          default: "driving",
        },
        language: {
          type: "string",
          description: "Language for geocoding results",
          pattern: "^[a-z]{2}$",
        },
      },
      required: ["places"],
    },
  };

• src/types/navigation/direction-by-places.ts:11-22 (schema)

  Type definitions for the direction-by-places tool including DirectionsByPlacesError interface and DirectionsByPlacesResponse interface.

  export interface DirectionsByPlacesError {
    place: string;
    error: string;
  }
  
  export interface DirectionsByPlacesResponse {
    geocodingResults: {
      [place: string]: MapboxGeocodingResponse["features"][0] | null;
    };
    directionsResult: MapboxDirectionsResponse | null;
    errors?: DirectionsByPlacesError[];
  }