feat: render_map_tool — single visualization primitive (server-side refs)

[mattpodwysocki]

Architecture B: data tools + one visualization primitive

Refactors MCP App rendering. Instead of every map-producing tool declaring its own iframe, there's now one tool — render_map_tool — that takes a MapAppPayload and renders it. Every other geo tool stores the payload server-side and returns a small ref on structuredContent; the LLM passes refs through.

Why: MCP App hosts (Claude Desktop today) only fully render the iframe for the last tool in a chained sequence. Intermediate tools render as failed cards even when their JSON-RPC returned isError: false. Funneling all rendering through one terminal tool sidesteps this — render_map_tool is always last by design.

The payload format

type MapAppPayload = {
  summary?: string;
  layers: Array<{
    id: string;
    type: 'fill' | 'line' | 'circle' | 'symbol';
    data: Feature | FeatureCollection;
    paint?: Record<string, unknown>;   // pass-through to addLayer
    layout?: Record<string, unknown>;
  }>;
  markers?: Array<{
    coordinates: [number, number];
    style?: 'pin' | 'numbered' | 'start' | 'end';
    label?: string; color?: string; popup?: string;
  }>;
  legend?: Array<{ label: string; color: string; opacity?: number }>;
  camera?: { center?: [...]; zoom?: number; bounds?: [[...],[...]] };
};

Thin pass-through to Mapbox Style spec — anything expressible in GL JS is expressible in the payload.

Flow

User: "Directions from Foo Coffee to Bar Coffee"
  ↓
LLM calls search_and_geocode_tool   → text + structuredContent.mapboxRender.ref
LLM calls search_and_geocode_tool   → text + structuredContent.mapboxRender.ref
LLM calls directions_tool           → text + structuredContent.mapboxRender.ref
LLM calls render_map_tool({ payload_refs: [r1, r2, r3] })  → MAP RENDERS

Data-tool calls are pure data exchanges. Only the terminal render_map_tool opens an iframe. The iframe fetches the merged payload via resources/read mapbox://temp/map-payload-<uuid> and draws it.

Why server-side refs

Initial implementation passed the full payload inline in the tool result. Two problems surfaced:

1. Latency. Round-trip times of 20-30s for chained tool calls — the LLM was serializing ~300KB of GeoJSON through its own context just to hand back to the iframe.
2. Claude Desktop content trimming. When the inline iframe HTML pushed the response past Claude Desktop's per-tool size threshold (~160KB), the host replaced content[] with "Tool result too large for context". The iframe shipped, but it had nothing to render.

Server-side refs fix both: the payload lives on the server keyed by UUID, the tool result carries only the URI, and the iframe reads it back via standard resources/read. Total roundtrip is a handful of KB.

Why the sentinel text

Claude Desktop strips structuredContent entirely from the postMessage it forwards to MCP App iframes (we verified this with a diagnostic dump). It also deduplicates iframes by URI across a chained call sequence, only fully rendering the last one.

So in addition to setting structuredContent.mapboxRender.ref, each data tool also embeds the ref in content[0].text tagged with a sentinel [[MAPBOX_RENDER_REF]] <uri>. The iframe extracts via either path — structuredContent for spec-compliant hosts, sentinel regex for Claude Desktop.

The render_map_tool description tells the LLM to call it at the end of any chain with the collected refs.

What landed

• Single primitive: render_map_tool (src/tools/render-map-tool/). Takes payload_refs: string[], optional inline overrides, renders the merged result.
• Single shared iframe template: mapAppHtml.ts. Renders any MapAppPayload. Reads ref from structuredContent or content-sentinel, then resources/read.
• Single shared MCP App resource: MapAppUIResource at ui://mapbox/map-app/index.html. Targeted only by render_map_tool's meta.ui.resourceUri.
• Server-side payload store: storeMapPayload(payload) → mapbox://temp/map-payload-<uuid> with TTL. resolveMapPayloadRef(uri) reads back. mergeMapPayloads([...]) for compositing.
• Per-tool payload builders: pure functions in each tool. Stash payload, attach ref to structuredContent, append renderHint(ref) to text.
• Polyline decoded tool-side so the iframe only sees GeoJSON.

What's removed

• @mcp-ui/server dependency and all inline createUIResource emissions
• enableMcpUi config, ENABLE_MCP_UI env var, --disable-mcp-ui flag
• meta.ui.resourceUri from every data tool (only render_map_tool declares it now)
• DirectionsAppUIResource + directionsAppHtml.ts
• The MAP_APP_FLAVORS URI-disambiguation scheme (single URI now, funneled through render tool)

Customer story

"Mapbox MCP gives you geo data primitives + one visualization primitive. Compose them like LEGO."

Other devs building MCP servers with their own logistics, telemetry, or sensor tools can plug into render_map_tool directly — they emit a MapAppPayload, the Mapbox renderer draws it.

Test plan

• 741 tests passing across 60 files (npm test)
• Build, lint, prettier all clean
• Per-tool render coverage: directions, isochrone, optimization, search_and_geocode, category_search, map_matching, ground_location, union, intersect, difference. Each test verifies structuredContent.mapboxRender.ref is set, render hint references the ref in text output, and resolveMapPayloadRef() returns the expected layers/markers/legend shape.
• Visual verification in Claude Desktop:
  • DC → NYC directions (chained geocode + directions)
  • Search "Find Blue Bottle Coffee" standalone
  • Polygon ops (union/intersect/difference) chained with map render

🤖 Generated with Claude Code