Macrostrat MCP Server

Instructions

Implementation Reference

• src/index.ts:1137-1233 (handler)

  The handler function for the 'map-tiles' tool. It takes parameters like scale, z (zoom), x, y coordinates, format, and fetch_image flag. Constructs the tile URL from Macrostrat server. If fetch_image is true and format png, fetches the image, converts to base64, and returns both text metadata and image content for analysis. Otherwise or on error, returns text with URL and info.
  async (request) => { const { scale, z, x, y, format, fetch_image } = request; const tileUrl = `https://tiles.macrostrat.org/${scale}/${z}/${x}/${y}.${format}`; if (fetch_image && format === "png") { try { const response = await fetch(tileUrl); if (response.ok) { const buffer = await response.arrayBuffer(); const base64 = Buffer.from(buffer).toString('base64'); // Return both text info and image content return { content: [ { type: "text" as const, text: JSON.stringify({ url: tileUrl, scale, z, x, y, format, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers", note: "Geological map tile image provided below for visual analysis" } }, null, 2) }, { type: "image" as const, data: base64, mimeType: "image/png" }, ], }; } else { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } } catch (error) { console.error("Error fetching tile image:", error); const data = { url: tileUrl, scale, z, x, y, format, error: `Failed to fetch image: ${error instanceof Error ? error.message : String(error)}`, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers" } }; return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } } else { const data = { url: tileUrl, scale, z, x, y, format, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers" } }; return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } }
• src/index.ts:1125-1136 (schema)

  Input schema definition for the map-tiles tool using Zod, defining parameters: scale (enum with default 'carto'), z (zoom 0-18), x/y (tile coords), format (mvt/png default png), fetch_image (bool default false). Includes title and description.
  { title: "Map Tiles", description: "Get map tile URLs from the Macrostrat tiles server. Use lat-lng-to-tile tool first to get proper x,y coordinates. Defaults to 'carto' scale which automatically adapts detail level to zoom.", inputSchema: { scale: z.enum(["carto", "tiny", "small", "medium", "large"]).default("carto").describe("Map scale layer - 'carto' automatically selects appropriate detail level based on zoom. Other scales (tiny, small, medium, large) may have limited coverage."), z: z.number().int().min(0).max(18).describe("Zoom level (0-18). Higher zoom = more detailed view of smaller area. Typical values: z=3 (continent), z=6 (country), z=10 (city), z=15 (neighborhood)"), x: z.number().int().min(0).describe("Tile X coordinate - use lat-lng-to-tile tool to calculate this from lat/lng"), y: z.number().int().min(0).describe("Tile Y coordinate - use lat-lng-to-tile tool to calculate this from lat/lng"), format: z.enum(["mvt", "png"]).default("png").describe("Tile format: 'png' for images, 'mvt' for vector tiles"), fetch_image: z.boolean().default(false).describe("If true, actually fetch the tile image data so Claude can analyze the geological features visually"), } },
• src/index.ts:1123-1234 (registration)

  Registration of the 'map-tiles' tool with the MCP server using server.registerTool, including name, schema, and inline anonymous handler function.
  server.registerTool( "map-tiles", { title: "Map Tiles", description: "Get map tile URLs from the Macrostrat tiles server. Use lat-lng-to-tile tool first to get proper x,y coordinates. Defaults to 'carto' scale which automatically adapts detail level to zoom.", inputSchema: { scale: z.enum(["carto", "tiny", "small", "medium", "large"]).default("carto").describe("Map scale layer - 'carto' automatically selects appropriate detail level based on zoom. Other scales (tiny, small, medium, large) may have limited coverage."), z: z.number().int().min(0).max(18).describe("Zoom level (0-18). Higher zoom = more detailed view of smaller area. Typical values: z=3 (continent), z=6 (country), z=10 (city), z=15 (neighborhood)"), x: z.number().int().min(0).describe("Tile X coordinate - use lat-lng-to-tile tool to calculate this from lat/lng"), y: z.number().int().min(0).describe("Tile Y coordinate - use lat-lng-to-tile tool to calculate this from lat/lng"), format: z.enum(["mvt", "png"]).default("png").describe("Tile format: 'png' for images, 'mvt' for vector tiles"), fetch_image: z.boolean().default(false).describe("If true, actually fetch the tile image data so Claude can analyze the geological features visually"), } }, async (request) => { const { scale, z, x, y, format, fetch_image } = request; const tileUrl = `https://tiles.macrostrat.org/${scale}/${z}/${x}/${y}.${format}`; if (fetch_image && format === "png") { try { const response = await fetch(tileUrl); if (response.ok) { const buffer = await response.arrayBuffer(); const base64 = Buffer.from(buffer).toString('base64'); // Return both text info and image content return { content: [ { type: "text" as const, text: JSON.stringify({ url: tileUrl, scale, z, x, y, format, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers", note: "Geological map tile image provided below for visual analysis" } }, null, 2) }, { type: "image" as const, data: base64, mimeType: "image/png" }, ], }; } else { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } } catch (error) { console.error("Error fetching tile image:", error); const data = { url: tileUrl, scale, z, x, y, format, error: `Failed to fetch image: ${error instanceof Error ? error.message : String(error)}`, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers" } }; return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } } else { const data = { url: tileUrl, scale, z, x, y, format, info: { layers: ["units", "lines"], description: scale === "carto" ? "Adaptive geological map that selects appropriate detail level based on zoom" : `Maps from the "${scale}" scale (may have limited geographic coverage)`, license: "CC BY 4.0 International", attribution: "Macrostrat and original data providers" } }; return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } } );