feat(hex): fetch add_hex_tile_layer color-scale metadata by hash (#276) (#315)

Stop routing server-computed value_stats/bounds/value_column/layer_name through
the LLM's tool-call arguments — the surface GLM-5.2 corrupted on ca-30x30
(2026-07-14). add_hex_tile_layer now requires only tile_url and fetches the
metadata.json sidecar (mcp-data-server#316 serve_metadata) by content hash,
deriving the URL from tile_url via metadataUrlFromTileUrl.

- required: ['tile_url']; value_stats/bounds/value_column/layer_name are now
  optional overrides; the description tells the model to pass only tile_url.
- resolveHexMetadata: prefer caller-supplied values (fast path, back-compat),
  else fetch and fill gaps, else fall back to whatever was supplied. Returns a
  clear error (never a silent blank layer) when neither source yields usable
  stats, with a hint to ensure mcp-data-server >= v0.8.6.

Deploy ordering: the tile host must serve metadata.json (v0.8.6, promoted but
awaiting cluster rollout) BEFORE any app bumps its pin to this code.

Composes with #313 (dialect scrub recovers a leaked value_stats upstream; this
fetches when it is absent/invalid). Full suite 516 green.

Author: cboettig

app/hex-layer-helpers.js

@@ -17,6 +17,27 @@ export function extractHashFromUrl(url) {
     return match ? match[1] : null;
 }
 
+/**
+ * Derive a hex tileset's `metadata.json` URL from its tile-URL template (#276).
+ *
+ * The MCP tile host serves the color-scale sidecar (value_stats, bounds,
+ * value_columns, layer_name, …) at the same path as the tiles, with the
+ * `/{z}/{x}/{y}.pbf` suffix swapped for `metadata.json`
+ * (mcp-data-server#316 `serve_metadata`). Fetching it by content hash means
+ * those inputs never have to be transcribed through the LLM's tool-call
+ * arguments, where large value_stats blobs get corrupted (see add_hex_tile_layer
+ * and the GLM-5.2 incident that reopened #276).
+ *
+ * @param {string} url - a `.../tiles/hex/<hash>/{z}/{x}/{y}.pbf` template.
+ * @returns {string|null} the `.../tiles/hex/<hash>/metadata.json` URL, or null
+ *   if the input isn't a recognized hex tile template.
+ */
+export function metadataUrlFromTileUrl(url) {
+    if (typeof url !== 'string') return null;
+    const m = url.match(/^(.*\/tiles\/hex\/[^/]+\/)\{z\}\/\{x\}\/\{y\}\.pbf$/);
+    return m ? `${m[1]}metadata.json` : null;
+}
+
 /**
  * Named 3-stop color palettes for hex-layer fill-color ramps.
  *   viridis — sequential, perceptually uniform (default)

app/map-tools.js

@@ -1,4 +1,70 @@
 import { validateChartSpec } from './chart-renderer.js';
+import { metadataUrlFromTileUrl } from './hex-layer-helpers.js';
+
+/**
+ * Whether a value_stats object is usable for building a hex color ramp (#276):
+ * an object with a non-empty `by_res` map.
+ */
+function isUsableStats(vs) {
+    return !!(vs && typeof vs === 'object' && vs.by_res && Object.keys(vs.by_res).length > 0);
+}
+
+/**
+ * Resolve a hex layer's color-scale metadata (value_column, value_stats, bounds,
+ * layer_name) for add_hex_tile_layer (#276).
+ *
+ * The server already computed these and serves them by content hash, so the LLM
+ * should not have to transcribe the large value_stats blob into tool args (where
+ * weak models corrupt it — the failure that reopened #276). This prefers usable
+ * values the caller supplied, otherwise fetches the sidecar
+ * (metadataUrlFromTileUrl) and fills the gaps. If the fetch fails it uses
+ * whatever the caller did supply, and returns `{ error }` only when neither
+ * source yields the fields the renderer needs — never a silent blank layer.
+ */
+async function resolveHexMetadata(args) {
+    let valueColumn = args.value_column;
+    let valueStats = args.value_stats;
+    let bounds = (Array.isArray(args.bounds) && args.bounds.length === 4) ? args.bounds : undefined;
+    let layerName = args.layer_name;
+
+    // Fast path: the caller already supplied everything the renderer needs — no
+    // network round-trip, and back-compat for manual/programmatic callers.
+    if (isUsableStats(valueStats) && bounds && valueColumn) {
+        return { valueColumn, valueStats, bounds, layerName };
+    }
+
+    const metaUrl = metadataUrlFromTileUrl(args.tile_url);
+    if (metaUrl && typeof fetch === 'function') {
+        try {
+            const resp = await fetch(metaUrl);
+            if (resp.ok) {
+                const meta = await resp.json();
+                valueColumn = valueColumn || meta.value_columns?.[0];
+                if (!isUsableStats(valueStats)) valueStats = meta.value_stats?.[valueColumn];
+                if (!bounds) {
+                    bounds = (Array.isArray(meta.bounds) && meta.bounds.length === 4) ? meta.bounds : undefined;
+                }
+                layerName = layerName || meta.layer_name;
+            }
+        } catch { /* fall through to whatever the caller supplied */ }
+    }
+
+    // One clear error covering any remaining gap — never a silent blank layer.
+    // All three gaps share a root cause: the by-hash fetch didn't deliver and
+    // nothing usable was passed explicitly.
+    if (!valueColumn || !isUsableStats(valueStats) || !bounds) {
+        const missing = [
+            !valueColumn && 'value_column',
+            !isUsableStats(valueStats) && 'value_stats',
+            !bounds && 'bounds',
+        ].filter(Boolean).join(', ');
+        return { error: `add_hex_tile_layer: could not resolve color-scale metadata (${missing}). `
+            + `These are normally fetched from ${metaUrl || 'the tile host'} by content hash; that fetch `
+            + `returned nothing usable (ensure the tile host serves metadata.json — mcp-data-server >= v0.8.6), `
+            + `and no usable values were passed explicitly.` };
+    }
+    return { valueColumn, valueStats, bounds, layerName };
+}
 
 /**
  * Map Tools - Local tool definitions for the LLM agent
@@ -399,18 +465,20 @@ Common use cases:
 
 Flow:
   1. Call \`register_hex_tiles\` (MCP) with SQL that returns (h3_index [, value1, ...]).
-  2. Pass its return fields directly into this tool — no extra min/max query needed; the server already computed \`value_stats\` per H3 resolution.
-
-Pass the following fields straight through from the register_hex_tiles return value:
-  - tile_url              ← tile_url_template
-  - value_column          ← one of value_columns (for agg="COUNT" this is "count")
-  - value_stats           ← value_stats[value_column]  (has { by_res: { "<res>": { min, max } } })
-  - bounds                ← bounds
-  - layer_name            ← layer_name (when present; defaults to "layer" otherwise)
+  2. Pass the returned \`tile_url\` to this tool. That is the ONLY required field.
+     The color-scale metadata (value_stats, bounds, value_column, layer_name) is
+     fetched automatically from the tile host by content hash — do NOT copy the
+     \`value_stats\` blob or \`bounds\` array into this call. Transcribing that large
+     nested object is error-prone and unnecessary; the server already has it.
+
+Optional inputs:
+  - value_column          which value_columns entry to color by (default: first; "count" for agg=COUNT)
+  - palette / opacity / display_name / fit_bounds    styling (see below)
+  - value_stats / bounds / layer_name    accepted as explicit overrides, but normally OMIT — they are fetched
   - format                ← format ("geojson" or "vector"; defaults to "vector")
   - geojson_url           ← geojson_url (REQUIRED when format="geojson"; ignored otherwise)
 
-ALWAYS pass \`format\` and (when present) \`geojson_url\` through. The server auto-selects GeoJSON for small/single-resolution tilesets and vector tiles otherwise; for GeoJSON the \`.pbf\` tile_url 404s, so the layer renders blank unless you also pass format="geojson" + geojson_url.
+For GeoJSON tilesets you MUST still pass format="geojson" + geojson_url from the register_hex_tiles return — those two are NOT in the fetched sidecar. The server auto-selects GeoJSON for small/single-resolution tilesets and vector tiles otherwise; for GeoJSON the \`.pbf\` tile_url 404s, so the layer renders blank unless you also pass format="geojson" + geojson_url.
 
 Hexes get finer as the user zooms in: the tile server's pyramid serves the appropriate H3 resolution for each zoom level automatically (vector format only). If the user wants a coarser overall view, re-run \`register_hex_tiles\` with the SQL projected to a coarser resolution by wrapping the first column in \`h3_cell_to_parent(<h3_col>, <target_res>)\` — the server auto-detects the H3 resolution from that column.
 
@@ -420,18 +488,18 @@ The returned layer_id can be used with show_layer / hide_layer / set_style / set
             inputSchema: {
                 type: 'object',
                 properties: {
-                    tile_url: { type: 'string', description: 'tile_url_template from register_hex_tiles' },
-                    value_column: { type: 'string', description: 'Which column from register_hex_tiles.value_columns to style by (e.g. "count" for agg=COUNT)' },
+                    tile_url: { type: 'string', description: 'tile_url_template from register_hex_tiles — the ONLY required field' },
+                    value_column: { type: 'string', description: 'Optional: which column from value_columns to style by (default: first; "count" for agg=COUNT)' },
                     value_stats: {
                         type: 'object',
-                        description: 'Per-resolution stats for value_column — pass register_hex_tiles.value_stats[value_column] directly. Shape: { by_res: { "<res>": { min, max } } }.'
+                        description: 'Optional override — normally OMIT. Fetched automatically by content hash. Shape if passed: { by_res: { "<res>": { min, max } } }.'
                     },
                     bounds: {
                         type: 'array',
                         items: { type: 'number' },
-                        description: '[w, s, e, n] from register_hex_tiles.bounds'
+                        description: 'Optional override — normally OMIT. Fetched automatically. [w, s, e, n].'
                     },
-                    layer_name: { type: 'string', description: 'MVT source-layer name from register_hex_tiles.layer_name (defaults to "layer" when omitted; ignored for format="geojson")' },
+                    layer_name: { type: 'string', description: 'Optional override — normally OMIT. Fetched automatically (defaults to "layer"; ignored for format="geojson").' },
                     format: {
                         type: 'string',
                         enum: ['vector', 'geojson'],
@@ -447,20 +515,22 @@ The returned layer_id can be used with show_layer / hide_layer / set_style / set
                     opacity: { type: 'number', description: 'Fill opacity 0..1 (default 0.7)' },
                     fit_bounds: { type: 'boolean', description: 'Fly the camera to fit bounds (default true)' },
                 },
-                required: ['tile_url', 'value_column', 'value_stats', 'bounds'],
+                required: ['tile_url'],
             },
-            execute: (args) => {
-                const displayName = args.display_name || `Hex: ${args.value_column}`;
+            execute: async (args) => {
+                const meta = await resolveHexMetadata(args);
+                if (meta.error) return JSON.stringify({ success: false, error: meta.error });
+                const displayName = args.display_name || `Hex: ${meta.valueColumn}`;
                 const result = mapManager.addHexTileLayer({
                     tileUrl: args.tile_url,
-                    valueColumn: args.value_column,
-                    valueStats: args.value_stats,
-                    bounds: args.bounds,
+                    valueColumn: meta.valueColumn,
+                    valueStats: meta.valueStats,
+                    bounds: meta.bounds,
                     palette: args.palette || 'viridis',
                     opacity: args.opacity ?? 0.7,
                     displayName,
                     fitBounds: args.fit_bounds !== false,
-                    layerName: args.layer_name,
+                    layerName: meta.layerName,
                     format: args.format,
                     geojsonUrl: args.geojson_url,
                 });

test/hex-layer-helpers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { extractHashFromUrl, rewriteValueColumn } from '../app/hex-layer-helpers.js';
+import { extractHashFromUrl, rewriteValueColumn, metadataUrlFromTileUrl } from '../app/hex-layer-helpers.js';
 
 describe('extractHashFromUrl', () => {
   it('extracts hash from a valid MCP tile URL template', () => {
@@ -191,3 +191,22 @@ describe('rewriteValueColumn', () => {
     expect(replaced).toEqual([]);
   });
 });
+
+describe('metadataUrlFromTileUrl (#276)', () => {
+  it('swaps the /{z}/{x}/{y}.pbf suffix for metadata.json', () => {
+    expect(metadataUrlFromTileUrl(
+      'https://duckdb-mcp.nrp-nautilus.io/tiles/hex/abc123/{z}/{x}/{y}.pbf'))
+      .toBe('https://duckdb-mcp.nrp-nautilus.io/tiles/hex/abc123/metadata.json');
+  });
+
+  it('returns null for a non-hex-template URL', () => {
+    expect(metadataUrlFromTileUrl('https://h/tiles/hex/abc/6/10/24.pbf')).toBeNull();
+    expect(metadataUrlFromTileUrl('https://h/other/abc/{z}/{x}/{y}.pbf')).toBeNull();
+    expect(metadataUrlFromTileUrl('not a url')).toBeNull();
+  });
+
+  it('returns null for non-string input', () => {
+    expect(metadataUrlFromTileUrl(null)).toBeNull();
+    expect(metadataUrlFromTileUrl(undefined)).toBeNull();
+  });
+});

test/map-tools.test.js

@@ -564,3 +564,92 @@ describe('createMapTools smoke test', () => {
         expect(setFilter.inputSchema.properties.filter.items).toBeDefined();
     });
 });
+
+describe('add_hex_tile_layer — fetch color-scale metadata by hash (#276)', () => {
+    afterEach(() => { vi.restoreAllMocks(); delete global.fetch; });
+
+    const META = {
+        finest_res: 8, min_res: 2, agg: 'AVG', zoom_offset: 2,
+        value_columns: ['conserved_hw_frac'],
+        value_stats: { conserved_hw_frac: {
+            by_res: { '2': { min: 0.46, max: 9.45 }, '8': { min: 0, max: 49 } },
+            suggested_scale: 'linear',
+        } },
+        layer_name: 'layer',
+        bounds: [-124.4, 32.5, -114.3, 42.1],
+        feature_count_finest: 216305,
+    };
+    const TILE_URL = 'https://duckdb-mcp.nrp-nautilus.io/tiles/hex/abc123/{z}/{x}/{y}.pbf';
+
+    const getTool = () => {
+        const mapManager = { addHexTileLayer: vi.fn(() => ({ success: true, layer_id: 'hex-abc123' })) };
+        const tool = createMapTools(mapManager, { records: new Map() }).find(t => t.name === 'add_hex_tile_layer');
+        return { tool, mapManager };
+    };
+
+    it('requires only tile_url', () => {
+        const { tool } = getTool();
+        expect(tool.inputSchema.required).toEqual(['tile_url']);
+    });
+
+    it('fetches metadata.json by hash and forwards the resolved fields', async () => {
+        global.fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => META });
+        const { tool, mapManager } = getTool();
+
+        const out = JSON.parse(await tool.execute({ tile_url: TILE_URL }));
+
+        expect(global.fetch).toHaveBeenCalledWith('https://duckdb-mcp.nrp-nautilus.io/tiles/hex/abc123/metadata.json');
+        expect(mapManager.addHexTileLayer).toHaveBeenCalledWith(expect.objectContaining({
+            tileUrl: TILE_URL,
+            valueColumn: 'conserved_hw_frac',
+            valueStats: META.value_stats.conserved_hw_frac,
+            bounds: META.bounds,
+            layerName: 'layer',
+        }));
+        expect(out.success).toBe(true);
+    });
+
+    it('honors a value_column override while still fetching stats for it', async () => {
+        const meta = { ...META, value_columns: ['count', 'conserved_hw_frac'],
+            value_stats: { ...META.value_stats, count: { by_res: { '8': { min: 1, max: 99 } } } } };
+        global.fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => meta });
+        const { tool, mapManager } = getTool();
+
+        await tool.execute({ tile_url: TILE_URL, value_column: 'count' });
+
+        expect(mapManager.addHexTileLayer).toHaveBeenCalledWith(expect.objectContaining({
+            valueColumn: 'count',
+            valueStats: meta.value_stats.count,
+        }));
+    });
+
+    it('uses caller-supplied values without fetching (fast path / back-compat)', async () => {
+        global.fetch = vi.fn();
+        const { tool, mapManager } = getTool();
+        const stats = { by_res: { '8': { min: 0, max: 49 } } };
+
+        await tool.execute({ tile_url: TILE_URL, value_column: 'count', value_stats: stats, bounds: [1, 2, 3, 4] });
+
+        expect(global.fetch).not.toHaveBeenCalled();
+        expect(mapManager.addHexTileLayer).toHaveBeenCalledWith(expect.objectContaining({
+            valueColumn: 'count', valueStats: stats, bounds: [1, 2, 3, 4],
+        }));
+    });
+
+    it('errors clearly (no silent blank layer) when the fetch fails and nothing was provided', async () => {
+        global.fetch = vi.fn().mockResolvedValue({ ok: false, status: 404, json: async () => ({}) });
+        const { tool, mapManager } = getTool();
+
+        const out = JSON.parse(await tool.execute({ tile_url: TILE_URL }));
+
+        expect(out.success).toBe(false);
+        expect(out.error).toMatch(/value_stats/);
+        expect(mapManager.addHexTileLayer).not.toHaveBeenCalled();
+    });
+
+    it('does not force the model to transcribe value_stats in its description', () => {
+        const { tool } = getTool();
+        expect(tool.description).toMatch(/fetched automatically/i);
+        expect(tool.description).toMatch(/do NOT copy/i);
+    });
+});