TomTom MCP Server

Implementation Reference

• src/handlers/mapHandler.ts:21-38 (handler)

  Factory function creating the MCP tool handler for tomtom-static-map. Processes input parameters, fetches the static map image via service, and returns it as base64 image content or error.
  export function createStaticMapHandler() { return async (params: any) => { logger.info(`🗺️ Generating static map: (${params.center.lat}, ${params.center.lon})`); try { const { base64, contentType } = await getStaticMapImage(params); logger.info(`✅ Static map generated successfully`); return { content: [{ type: "image" as const, data: base64, mimeType: contentType }], }; } catch (error: any) { logger.error(`❌ Static map generation failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
• src/schemas/map/mapSchema.ts:31-102 (schema)

  Zod schema definition for input validation of tomtom-static-map tool parameters including center, bbox, zoom, dimensions, styles, layers, etc.
  export const tomtomMapSchema = { center: coordinateSchema.describe( "Map center coordinates. Use results from geocoding or search operations for best positioning." ), // Fix: Use z.array() instead of z.tuple() bbox: z .array(z.number()) .length(4) .optional() .describe( "Bounding box in format [west, south, east, north]. Alternative to center+zoom. Example: [-122.42, 37.77, -122.40, 37.79] for part of San Francisco." ), zoom: z .number() .min(0) .max(22) .optional() .describe( "Zoom level (0-22). Examples: 3 (continent), 6 (country), 10 (city), 15 (neighborhood), 18 (street). Default: 15." ), width: z .number() .min(50) .max(2048) .optional() .describe( "Map width in pixels (50-2048). Examples: 300-500 (preview), 800-1200 (detailed). Default: 512." ), height: z .number() .min(50) .max(2048) .optional() .describe( "Map height in pixels (50-2048). Examples: 300-500 (preview), 800-1200 (detailed). Default: 512." ), style: z .enum(["main", "night"]) .optional() .describe("Map style: 'main' (default daytime), 'night' (dark theme)."), layer: z .enum(["basic", "labels", "hybrid"]) .optional() .describe( "Map layer type: 'basic' (streets), 'labels' (text only, transparent background), 'hybrid' (satellite with labels)." ), format: z .enum(["png", "jpg"]) .optional() .describe( "Image format: 'png' (better quality, supports transparency), 'jpg' (smaller file size)." ), view: z .enum(["Unified", "IL", "IN", "MA", "PK", "AR", "Arabic", "RU", "TR", "CN", "US"]) .optional() .describe( "Geopolitical view for border disputes and territories. 'Unified' is the international standard view." ), language: z .string() .optional() .describe("Language for map labels (IETF language tag). Examples: 'en-US', 'es-ES', 'fr-FR'."), };
• src/tools/mapTools.ts:29-37 (registration)

  Registration of the tomtom-static-map tool with MCP server, linking schema and handler.
  server.registerTool( "tomtom-static-map", { title: "TomTom Static Map", description: "Generate custom map images from TomTom Maps with specified center coordinates, zoom levels, and style options", inputSchema: schemas.tomtomMapSchema, }, createStaticMapHandler() );
• src/services/map/mapService.ts:126-209 (helper)

  Core service function that constructs the TomTom Static Maps API URL, fetches the image, adds copyright overlay if canvas available, and returns base64-encoded image data used by the handler.
  export async function getStaticMapImage( options: MapOptions ): Promise<{ base64: string; contentType: string }> { try { // Get the URL first const mapUrl = getStaticMapUrl(options); // Log the URL before making the request logger.info(`Making static map request to: ${tomtomClient.defaults.baseURL}${mapUrl}`); // Use tomtomClient to download the image (it automatically includes proper headers) const response = await tomtomClient.get(mapUrl, { responseType: "arraybuffer", }); // Log the actual URL that was requested (including any modifications made by axios) if (response.config && response.config.url) { logger.info(`Full request URL was: ${response.config.url}`); } if (!response.status || response.status >= 400) { throw new Error(`Failed to fetch map image: HTTP ${response.status}`); } // Get the content type from the response headers const contentType = response.headers?.["content-type"] || "image/png"; // The image data is already in the response const imageBuffer = response.data; // Add copyright overlay to the static map image let finalImageBuffer = imageBuffer; // Try to load Canvas dynamically const canvasAvailable = await loadCanvasIfAvailable(); if (canvasAvailable) { try { // Fetch Genesis copyright text (static maps are Genesis only) const copyrightText = await fetchCopyrightCaption(false); logger.info(`📄 Static map copyright text: ${copyrightText}`); // Get image dimensions from options const width = options.width || DEFAULT_MAP_OPTIONS.width; const height = options.height || DEFAULT_MAP_OPTIONS.height; // Create canvas and load the original image const canvas = createCanvas(width, height); const ctx = canvas.getContext('2d'); // Load and draw the original image const buffer = Buffer.from(imageBuffer); const { loadImage } = await import('canvas'); const img = await loadImage(buffer); ctx.drawImage(img, 0, 0, width, height); // Add copyright overlay using shared utility addCopyrightOverlay(ctx, copyrightText, width, height); // Convert canvas back to buffer finalImageBuffer = canvas.toBuffer('image/png'); logger.debug(`Added copyright overlay to static map image`); } catch (overlayError: any) { logger.error(`Failed to add copyright overlay to static map: ${overlayError.message}. Using original image.`); // Use original image if overlay fails finalImageBuffer = imageBuffer; } } else { logger.debug('Canvas not available, skipping copyright overlay for static map'); } // Convert the buffer to base64 const base64 = Buffer.from(finalImageBuffer).toString("base64"); logger.debug(`Downloaded and processed static map image (${(finalImageBuffer.byteLength / 1024).toFixed(2)} KB)`); return { base64, contentType }; } catch (error) { logger.error(`Failed to download static map: ${error}`); throw error; } }