static-map
Generate PNG map images with customizable markers and route lines for visualizing locations and paths using Stadia Maps styles.
Instructions
Generate a PNG map image of an area, optionally including markers and a line (e.g. to draw a route or a boundary)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | The Stadia Maps style slug to use. | outdoors |
| encodedPolyline | No | The encoded polyline representing the route (precision 6). Optional, but either markers or a polyline must be specified. | |
| strokeColor | No | Optional color for the polyline (hex code or CSS color name; e.g. FFFFFF or blue). | |
| strokeWidth | No | Optional width for the route line in pixels. | |
| markers | No | Markers to add to the map. Optional, but either markers or a polyline must be specified. |
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();