Stadia Maps Location API MCP Server

Instructions

Implementation Reference

• src/tools/staticMaps.ts:79-123 (handler)

  Main handler function for 'static-map' tool. Constructs payload for Stadia Maps Static API, including optional encoded polyline (route line) and markers, then calls helper to fetch and return base64 PNG image.

  export async function staticMap({
    style = DEFAULT_STYLE,
    encodedPolyline,
    strokeColor,
    strokeWidth,
    markers,
  }: StaticMapParams): Promise<CallToolResult> {
    const payload: any = {
      // Fixed at 600x400; customize as needed
      size: "600x400@2x",
      lines: [],
    };
  
    // Add line if provided
    if (encodedPolyline) {
      // Create the line object
      const line: any = {
        shape: encodedPolyline,
      };
  
      // Add optional line properties if provided
      if (strokeColor) line.stroke_color = strokeColor;
      if (strokeWidth) line.stroke_width = strokeWidth;
  
      payload.lines.push(line);
    }
  
    // Add markers if provided
    if (markers && markers.length > 0) {
      payload.markers = markers.map((marker) => {
        const markerObj: any = {
          lat: marker.lat,
          lon: marker.lon,
        };
  
        if (marker.label) markerObj.label = marker.label;
        if (marker.color) markerObj.color = marker.color;
        if (marker.markerUrl) markerObj.style = `custom:${marker.markerUrl}`;
  
        return markerObj;
      });
    }
  
    return generateStaticMapAsCallToolResult(payload, style);
  }

• src/index.ts:104-140 (registration)

  MCP server tool registration for 'static-map', defining input schema using Zod and linking to staticMap handler.

    "static-map",
    "Generate a PNG map image of an area, optionally including markers and a line (e.g. to draw a route or a boundary)",
    {
      style: mapStyleSchema,
      encodedPolyline: z
        .string()
        .describe(
          "The encoded polyline representing the route (precision 6). Optional, but either markers or a polyline must be specified.",
        )
        .optional(),
      strokeColor: z
        .string()
        .describe(
          "Optional color for the polyline (hex code or CSS color name; e.g. FFFFFF or blue).",
        )
        .optional(),
      strokeWidth: z
        .number()
        .describe("Optional width for the route line in pixels.")
        .optional(),
      markers: z
        .array(
          z.object({
            lat: latitudeSchema,
            lon: longitudeSchema,
            label: markerLabelSchema,
            color: markerColorSchema,
            markerStyle: markerStyleSchema,
          }),
        )
        .describe(
          "Markers to add to the map. Optional, but either markers or a polyline must be specified.",
        )
        .optional(),
    },
    staticMap,
  );

• src/tools/staticMaps.ts:31-74 (helper)

  Helper function to POST payload to Stadia Maps Static API, fetch PNG image, convert to base64, and return as MCP CallToolResult.

  async function generateStaticMapAsCallToolResult(
    payload: any,
    style: string,
  ): Promise<CallToolResult> {
    return handleToolError(
      async () => {
        const url = `${STATIC_MAPS_BASE_URL}/${style}?api_key=${API_KEY}`;
  
        const response = await fetch(url, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
        });
  
        if (!response.ok) {
          throw new Error(
            `HTTP code: ${response.status}.\nPayload: ${JSON.stringify(payload)}`,
          );
        }
  
        // Get the image as a buffer
        const imageBuffer = await response.arrayBuffer();
  
        // Convert to base64
        const base64Image = Buffer.from(imageBuffer).toString("base64");
  
        return {
          content: [
            {
              type: "image",
              data: base64Image,
              mimeType: "image/png",
            },
          ],
        };
      },
      {
        contextMessage: "Failed to generate static map",
        enableLogging: true,
      },
    );
  }

• src/schemas.ts:77-82 (schema)

  Zod schema for map style parameter used in static-map tool.

  export const mapStyleSchema = z
    // See https://docs.stadiamaps.com/themes/ for more styles!
    .enum(["outdoors", "alidade_smooth", "alidade_smooth_dark"])
    .describe("The Stadia Maps style slug to use.")
    .default(DEFAULT_STYLE);

• src/schemas.ts:89-106 (schema)

  Zod schemas for marker properties (label, color, style) used in static-map markers array.

  export const markerLabelSchema = z
    .string()
    .describe(
      "Optional label for the marker. This must be either a single character or supported emoji (most emoji work).",
    )
    .optional();
  
  export const markerColorSchema = z
    .string()
    .describe(
      "Optional color for the marker (hex code or CSS color name; no quoting and no # prefix).",
    )
    .optional();
  
  export const markerStyleSchema = z
    .string()
    .describe("Optional custom marker style or URL to a custom marker image.")
    .optional();