@showmeonmap/mcp 0.2.0

package/dist/tools.js

@@ -0,0 +1,1443 @@
+/**
+ * Shared tool implementations for the ShowMeOnMap MCP server.
+ *
+ * Pulled out of index.ts so both the stdio transport (index.ts) and the
+ * HTTP/SSE transport (http.ts) can register the same tool surface without
+ * duplicating the handler bodies. Exports:
+ *
+ *   - createServer({ baseUrl, apiKey, sessionStore? })
+ *     returns a configured McpServer with build_map, mutate_map, get_state
+ *     already registered. Caller attaches whichever transport they want.
+ *
+ *   - sessionStore helpers: createMemorySessionStore() gives the default
+ *     LRU-in-memory behavior used by the stdio prototype. HTTP callers
+ *     will eventually swap this for a D1-backed store once Phase I-3 ships.
+ *
+ * Spec: docs/superpowers/specs/2026-04-17-mcp-server-design.md
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, mkdirSync, appendFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { MCP_TOOL_META, mcpRequiresConfirmation } from "./toolMeta.js";
+// -----------------------------------------------------------------------------
+// Agent-facing spec resource (Teddy Riker, "Designing for Agents" §2,
+// 2026-04-23). Loaded once at module init from a sibling .md file. Tool
+// descriptions for build_map / mutate_map / add_layer / filter_layer point
+// agents at this resource so they fetch shapes (predicate grammar, LayerPlan
+// fields, refusal surfaces) at the moment of need instead of guessing.
+// -----------------------------------------------------------------------------
+const WORKSPACE_OPS_SPEC_URI = 'showmeonmap://docs/workspace-ops-spec';
+const WORKSPACE_OPS_SPEC_TEXT = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return readFileSync(resolve(here, 'workspaceOpsSpec.md'), 'utf8');
+    }
+    catch (err) {
+        process.stderr.write(`[showmeonmap-mcp] WARN: failed to load workspaceOpsSpec.md: ${err instanceof Error ? err.message : String(err)}\n`);
+        return '# Workspace ops spec not available — please update the MCP server.\n';
+    }
+})();
+// -----------------------------------------------------------------------------
+// NDJSON rationale sink — `reports/mcp-rationale/YYYY-MM-DD.ndjson`.
+// -----------------------------------------------------------------------------
+// Article §3.1: rationale is only useful if it sticks around. Stderr alone is
+// transient — the launcher (Claude Desktop, Cursor, etc.) controls what
+// happens to it. We additionally append every tool call to a per-day NDJSON
+// file alongside the existing `reports/agent-blockers/` sink so the same
+// pattern applies to both feedback channels.
+//
+// Path is resolved relative to THIS module so we land in the repo regardless
+// of how the user invoked the MCP server (cwd is unspecified for stdio
+// children). All filesystem writes are best-effort: a failed append never
+// breaks a tool call. Date is UTC to match the agent-blockers route.
+// -----------------------------------------------------------------------------
+const MCP_RATIONALE_DIR = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // tools.ts sits at packages/mcp-server/src/. Climb three levels
+        // (src → mcp-server → packages → <repo>) to land at <repo>/reports/
+        // mcp-rationale, alongside the agent-blockers sink and the
+        // *.seed.ndjson committed for clustering passes. Previously climbed
+        // only two levels and wrote to packages/reports/mcp-rationale,
+        // which was gitignored and invisible to the audit pipeline (gap #1
+        // in the 2026-05-01 agent-design pattern pass).
+        return resolve(here, '..', '..', '..', 'reports', 'mcp-rationale');
+    }
+    catch {
+        return null;
+    }
+})();
+function ymdUtc(d) {
+    return [
+        d.getUTCFullYear(),
+        String(d.getUTCMonth() + 1).padStart(2, '0'),
+        String(d.getUTCDate()).padStart(2, '0'),
+    ].join('-');
+}
+function appendRationaleNdjson(rec) {
+    if (!MCP_RATIONALE_DIR)
+        return;
+    try {
+        mkdirSync(MCP_RATIONALE_DIR, { recursive: true });
+        const file = resolve(MCP_RATIONALE_DIR, `${ymdUtc(new Date(rec.ts))}.ndjson`);
+        appendFileSync(file, JSON.stringify(rec) + '\n', 'utf8');
+    }
+    catch {
+        // Best-effort — a tool call must never fail because the disk is full or
+        // the dir is unwriteable. Stderr line above already carries the info.
+    }
+}
+export function asSessionId(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError('SessionId: expected non-empty string');
+    }
+    return value;
+}
+export function createMemorySessionStore(maxSize = 256) {
+    const cache = new Map();
+    return {
+        async get(mapId) {
+            const e = cache.get(asSessionId(mapId));
+            if (!e)
+                return null;
+            e.lastAccessed = Date.now();
+            return e;
+        },
+        async put(mapId, entry) {
+            const key = asSessionId(mapId);
+            cache.set(key, entry);
+            if (cache.size > maxSize) {
+                let oldestId = null;
+                let oldestAt = Infinity;
+                for (const [id, e] of cache) {
+                    if (e.lastAccessed < oldestAt) {
+                        oldestAt = e.lastAccessed;
+                        oldestId = id;
+                    }
+                }
+                if (oldestId)
+                    cache.delete(oldestId);
+            }
+        },
+        async delete(mapId) {
+            cache.delete(asSessionId(mapId));
+        },
+        async size() {
+            return cache.size;
+        },
+    };
+}
+// ── Tool-result compaction (1MB cap, 2026-07-16) ────────────────────────────
+// The tool-result channel on claude.ai / Claude Desktop is capped at ~1MB.
+// Fully-hydrated layers — notably build_map's own `smo_earthquakes_plates`
+// tectonic-plate overlay, large regardless of match count — blow past it, so
+// the `map_id` never reaches the caller (real failure, first Claude Desktop
+// dogfood). `structured` is the REASONING channel: the agent needs to know
+// what layers exist, their viz, and how many features — NOT the raw geometry.
+// The full data lives server-side and renders via `shareable_url` (/m/[id])
+// and `export_layer_data` (returns a URL, never inline bytes).
+//
+// summarizeGeoData walks the structure and replaces every GeoJSON
+// FeatureCollection with a compact summary, preserving all other fields
+// (layer ids, titles, viz, op kinds, cursor) that agents and tests rely on.
+const MAX_STRUCTURED_BYTES = 900_000;
+function summarizeGeoData(node) {
+    if (Array.isArray(node))
+        return node.map(summarizeGeoData);
+    if (node && typeof node === 'object') {
+        const rec = node;
+        if (rec.type === 'FeatureCollection' && Array.isArray(rec.features)) {
+            const feats = rec.features;
+            const geometryTypes = Array.from(new Set(feats.map((f) => f?.geometry?.type).filter((t) => typeof t === 'string')));
+            return { type: 'FeatureCollection', _smo_compacted: true, feature_count: feats.length, geometry_types: geometryTypes };
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(rec))
+            out[k] = summarizeGeoData(v);
+        return out;
+    }
+    return node;
+}
+function compactStructured(workspace, mapPlan) {
+    const compacted = summarizeGeoData({ workspace, mapPlan });
+    // Safety net: if a non-FeatureCollection heavy blob still pushes us near the
+    // cap, degrade to minimal layer stubs so map_id ALWAYS returns. Full data
+    // remains at shareable_url + export_layer_data.
+    try {
+        if (JSON.stringify(compacted).length > MAX_STRUCTURED_BYTES) {
+            const stubs = Array.isArray(mapPlan?.layers)
+                ? mapPlan.layers.map((l) => {
+                    const layer = l;
+                    return { id: layer.id, title: layer.title, viz: layer.viz, _smo_truncated: true };
+                })
+                : [];
+            return {
+                workspace: { cursor: workspace?.cursor, _smo_truncated: true },
+                mapPlan: { title: mapPlan?.title, layers: stubs, _smo_truncated: true },
+            };
+        }
+    }
+    catch {
+        /* stringify blew up — return the compacted best-effort */
+    }
+    return compacted;
+}
+function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras = {}) {
+    const layerCount = Array.isArray(mapPlan?.layers) ? mapPlan.layers.length : 0;
+    const opsCount = Array.isArray(workspace?.opsLog) ? workspace.opsLog.length : 0;
+    return {
+        ok: true,
+        map_id: mapId,
+        version: opsCount,
+        structured: compactStructured(workspace, mapPlan),
+        shareable_url: `${baseUrl}/m/${mapId}`,
+        metadata: {
+            title: mapPlan?.title,
+            layer_count: layerCount,
+            last_updated: new Date().toISOString(),
+        },
+        next_actions: (nextActionStrings ?? []).slice(0, 3).map((label) => ({
+            label,
+            argsTemplate: { instruction: label },
+        })),
+        ...(extras.outOfScope ? { outOfScope: extras.outOfScope } : {}),
+        ...(extras.clarification ? { clarification: extras.clarification } : {}),
+    };
+}
+function toContent(obj) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Runtime input validation (W1/C2, 2026-04-27)
+// ---------------------------------------------------------------------------
+// The MCP SDK runs `safeParseAsync` against `inputSchema` at the wire layer
+// (server/mcp.js :: validateToolInput), but two gaps slip through:
+//
+//   1. `z.object(shape)` defaults to passthrough — unknown keys are silently
+//      kept. We want strict rejection so an agent that hallucinates a
+//      `radiusField` (or any other dead key) gets a self-correctable error
+//      instead of a silently-ignored argument.
+//   2. Direct handler invocations (the unit-test harness, future internal
+//      callers) bypass the SDK's wire-layer validation entirely.
+//
+// `withValidation` closes both gaps. Each tool registers its raw zod-shape
+// inputSchema as before (keeps the SDK happy) AND wraps its handler in a
+// strict-object validator. On failure we return a structured `invalid_input`
+// envelope (isError:true + content[].text JSON) so the calling agent can
+// self-correct.
+// ---------------------------------------------------------------------------
+const INVALID_INPUT_HINTS = {
+    build_map: 'Required: query (string, ≥1 char), rationale (string, 1–300 chars). No other fields accepted.',
+    mutate_map: 'Required: map_id, instruction, rationale. No other fields accepted.',
+    get_state: 'Required: map_id, rationale. No other fields accepted.',
+    add_layer: 'Required: map_id, layerPlan (object), rationale. Optional: intent (enum). No other fields accepted.',
+    filter_layer: 'Required: map_id, layerId, predicate (object), rationale. Optional: append (boolean), intent (enum).',
+    select_within: 'Required: map_id, sourceLayerId, newLayerId, selection ({type:Polygon|MultiPolygon, coordinates}), rationale. Optional: inheritStyle.',
+    query_features: 'Required: map_id, layerId, predicate (object), rationale. Optional: limit (1–1000 integer).',
+    remove_layer: 'Required: map_id, layerId, rationale, confirmed:true (destructive — layer ids are tombstoned).',
+    clear_filters: 'Required: map_id, layerId, rationale, confirmed:true (sensitive — autonomous filter wipe).',
+    rename_layer: 'Required: map_id, oldLayerId, newLayerId, rationale.',
+    restyle_layer: 'Required: map_id, layerId, rationale. Optional: color (string), opacity (0–1).',
+    set_camera: 'Required: map_id, camera (mode:fitBounds|flyTo with required fields), rationale.',
+    set_time: 'Required: map_id, field, rangeStart (number), rangeEnd (number), rationale. Optional: format (unix_ms|iso|integer).',
+    tag: 'Required: map_id, name, rationale.',
+    add_annotation: 'Required: map_id, id, coords ([lng,lat]), rationale. Optional: label, color.',
+    remove_annotation: 'Required: map_id, annotationId, rationale.',
+    export_workspace: 'Required: map_id, rationale.',
+    export_layer_data: 'Required: map_id, layer_id, rationale, format ("csv" or "geojson"). No other fields accepted.',
+    export_image: 'Required: map_id, rationale. Optional: format ("png" default | "jpeg" | "pdf"), legend (boolean default true). No other fields accepted.',
+    add_fusion_layer: 'Required: map_id, layer_a_id, layer_b_id, rationale. Optional: value_field_a, value_field_b, new_layer_id. Mode is locked to "bivariate" in v1. No other fields accepted.',
+    correlate_layers: 'Required: map_id, layer_a_id, layer_b_id, rationale. Optional: value_field_a, value_field_b. Pure read — no layer added, no credit charged. No other fields accepted.',
+    undo: 'Required: map_id, rationale, confirmed:true (sensitive — autonomous undo can erase prior work).',
+    redo: 'Required: map_id, rationale.',
+    report_blocker: 'Required: what_i_was_trying, what_i_tried, where_i_got_stuck. Optional: map_id, suggested_capability.',
+};
+function buildInvalidInputResponse(toolName, error) {
+    const issues = error.issues.map((iss) => ({
+        path: iss.path,
+        code: iss.code,
+        message: iss.message,
+    }));
+    const payload = {
+        error: 'invalid_input',
+        tool: toolName,
+        issues,
+        hint: INVALID_INPUT_HINTS[toolName] ?? 'Check the tool schema and remove unknown keys.',
+    };
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+/**
+ * Wrap a tool handler in a strict-object zod validator. Returns the
+ * `invalid_input` envelope on parse failure; otherwise hands the parsed
+ * data to the inner handler.
+ *
+ * The MCP SDK's `inputSchema` config field still receives the same raw
+ * shape so its wire-layer validation continues to work. This wrapper is
+ * the second layer that catches direct invocations and adds
+ * unknown-key rejection (`.strict()`).
+ *
+ * Typing: we accept any return type from the inner handler (the SDK's
+ * CallToolResult union is broader than what we emit) and merge it with
+ * the InvalidInputEnvelope branch. The cast at the bottom keeps the
+ * SDK's strict overload happy without silently widening the schema —
+ * the runtime parser is the source of truth.
+ */
+function withValidation(toolName, shape, handler) {
+    const parser = z.object(shape).strict();
+    return ((args, extra) => {
+        const parsed = parser.safeParse(args);
+        if (!parsed.success) {
+            return buildInvalidInputResponse(toolName, parsed.error);
+        }
+        return handler(parsed.data, extra);
+    });
+}
+function buildNeedsConfirmationResponse(toolName) {
+    const meta = MCP_TOOL_META[toolName];
+    const payload = {
+        error: 'needs_confirmation',
+        tool: toolName,
+        message: 'This tool is marked destructive or sensitive. Re-call with confirmed:true to proceed.',
+        meta: {
+            destructive: meta?.destructive ?? false,
+            requires_confirmation: meta?.requires_confirmation ?? true,
+            rationale: meta?.rationale,
+        },
+    };
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+    };
+}
+/**
+ * Wrap a (post-validation) tool handler so that gated tools require
+ * `confirmed: true`. Composes outside `withValidation` — the inner
+ * handler never sees the `confirmed` field (it has fulfilled its
+ * gating purpose by the time we delegate).
+ */
+function withConfirmation(toolName, handler) {
+    // Non-gated tools: pass through untouched. Avoids any per-call overhead.
+    if (!mcpRequiresConfirmation(toolName)) {
+        return handler;
+    }
+    return ((args, extra) => {
+        if (args?.confirmed !== true) {
+            return buildNeedsConfirmationResponse(toolName);
+        }
+        // Strip `confirmed` so downstream handlers + telemetry don't see it.
+        // We keep the rest of the args intact. We use a destructuring rest
+        // pattern + intentional throwaway binding for the dropped key.
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { confirmed, ...rest } = args;
+        return handler(rest, extra);
+    });
+}
+async function apiFetch(baseUrl, apiKey, path, body) {
+    const resp = await fetch(`${baseUrl}${path}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await resp.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${path} returned non-JSON (status ${resp.status}): ${text.slice(0, 200)}`);
+    }
+}
+/**
+ * Persist the map to the shareable `maps` store (best-effort) so the returned
+ * `shareable_url` (/m/<mapId>) actually renders — without this the workspace
+ * lives only in the MCP session cache and the /m/ viewer 404s. Saved under the
+ * WORKSPACE id so the envelope link resolves unchanged, public=link-reachable
+ * (unlisted), attributed to the key owner via the forwarded bearer. The blob
+ * mirrors the web save shape (src/lib/share/saveMapSnapshot.ts): mapPlan with
+ * geojson `source.data` stripped + a `geojsonLayers` map keyed by layer id +
+ * `version`, so /m/[id] rehydrates it faithfully. NEVER throws — a failed
+ * share must not fail the build/mutation.
+ */
+async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query) {
+    if (!mapPlan || !Array.isArray(mapPlan.layers))
+        return;
+    try {
+        const geojsonLayers = {};
+        const strippedLayers = mapPlan.layers.map((raw) => {
+            const layer = raw;
+            if (layer?.source?.kind === 'geojson' && layer.source.data && layer.id) {
+                geojsonLayers[layer.id] = layer.source.data;
+                return { ...layer, source: { ...layer.source, data: undefined } };
+            }
+            return layer;
+        });
+        const title = mapPlan.title ?? mapPlan.layers[0]?.title ?? 'Untitled Map';
+        await apiFetch(baseUrl, apiKey, '/api/maps', {
+            id: mapId,
+            title,
+            query,
+            blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1 },
+            isPublic: true,
+        });
+    }
+    catch {
+        /* best-effort — a share-save failure never fails the build */
+    }
+}
+export function createServer(opts) {
+    const baseUrl = opts.baseUrl;
+    const apiKey = opts.apiKey;
+    const store = opts.sessionStore ?? createMemorySessionStore();
+    const server = new McpServer({
+        name: opts.name ?? 'showmeonmap',
+        version: opts.version ?? '0.1.0',
+    });
+    // -------------------------------------------------------------------------
+    // Resource: workspace-ops-spec
+    // -------------------------------------------------------------------------
+    // Notion-style "fetch the spec at the moment of need" pattern (Teddy Riker,
+    // "Designing for Agents" §2, 2026-04-23). Tool descriptions reference this
+    // URI so calling agents pull shapes from us rather than guessing.
+    // -------------------------------------------------------------------------
+    server.registerResource('workspace-ops-spec', WORKSPACE_OPS_SPEC_URI, {
+        title: 'ShowMeOnMap workspace ops spec',
+        description: 'Predicate grammar, LayerPlan shape, Op catalog, refusal surfaces, and common pitfalls for ShowMeOnMap. Fetch this before constructing structured arguments to filter_layer / add_layer / select_within / set_time / mutate_map.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: WORKSPACE_OPS_SPEC_TEXT,
+            },
+        ],
+    }));
+    // -------------------------------------------------------------------------
+    // Shared `rationale` schema + stderr logger.
+    // ---------------------------------------------------------------------------
+    // Required on every MCP tool per Teddy Riker's "Designing for Agents"
+    // (2026-04-23 §3.1). Hoisted here so the very first registerTool call below
+    // can reference it (TS would otherwise flag use-before-declaration).
+    // ---------------------------------------------------------------------------
+    const rationaleSchema = z
+        .string()
+        .min(1)
+        .max(300)
+        .describe('Short audit-log label (≤300 chars) stating the user-facing goal this call serves, e.g. "add wildfire layer for the user\'s California query". Required on every call. Stored in the operations log so map edits stay traceable — we never see your chat history.');
+    /**
+     * Log a tool call's rationale (and any op-shaped extras) to BOTH stderr
+     * and the per-day NDJSON sink. Every tool calls this — direct-op tools
+     * also emit an Op carrying the same rationale on `OpBase.rationale`, so
+     * the NDJSON is the unified observability stream and the ops log is the
+     * authoritative state.
+     *
+     * `extra.intent` lands in the NDJSON for filter_layer / add_layer.
+     * `extra.opKind` lands in the NDJSON when this call emits a typed Op.
+     */
+    function logRationale(toolName, mapId, rationale, extra) {
+        const safe = rationale.replace(/[\r\n\t]+/g, ' ').slice(0, 300);
+        process.stderr.write(`[mcp:rationale] tool=${toolName} mapId=${mapId ?? '-'} rationale="${safe}"${extra?.intent ? ` intent=${extra.intent}` : ''}${extra?.opKind ? ` op=${extra.opKind}` : ''}\n`);
+        appendRationaleNdjson({
+            ts: new Date().toISOString(),
+            tool: toolName,
+            ...(mapId ? { map_id: mapId } : {}),
+            rationale: safe,
+            ...(extra?.intent ? { intent: extra.intent } : {}),
+            ...(extra?.opKind ? { op_kind: extra.opKind } : {}),
+        });
+    }
+    const buildMapShape = {
+        query: z
+            .string()
+            .min(1)
+            .describe('Natural language: "coffee shops in Tokyo", "GDP by country", "volcanoes in Indonesia", etc.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('build_map', {
+        title: 'Build a map',
+        description: 'Create a new workspace from a natural-language query. Returns a map_id you can pass to mutate_map or get_state for follow-up actions. ' +
+            'For the full Op catalog and predicate grammar that downstream tools (mutate_map, filter_layer, etc.) accept, fetch the MCP resource at showmeonmap://docs/workspace-ops-spec — do NOT guess the shapes.',
+        inputSchema: buildMapShape,
+    }, withValidation('build_map', buildMapShape, async ({ query, rationale }) => {
+        logRationale('build_map', null, rationale);
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/new', {
+            message: query,
+            stream: false,
+            rationale,
+        }));
+        if (resp.type !== 'visualization' || !resp.workspace) {
+            throw new Error(`build_map failed: ${JSON.stringify(resp.error ?? resp.message ?? resp).slice(0, 300)}`);
+        }
+        const mapId = asSessionId(resp.workspace.workspaceId ?? randomUUID());
+        await store.put(mapId, {
+            workspace: resp.workspace,
+            mapPlan: resp.mapPlan ?? null,
+            layerFilters: {},
+            createdAt: Date.now(),
+            lastAccessed: Date.now(),
+        });
+        const nextActions = [
+            'Filter the layer to features where name is not empty',
+            'Change the basemap to satellite',
+            'Zoom the camera closer',
+        ];
+        // Persist to the shareable store so the returned /m/<mapId> link renders.
+        await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, query);
+        return toContent(envelope(baseUrl, mapId, resp.workspace, resp.mapPlan, nextActions));
+    }));
+    const mutateMapShape = {
+        map_id: z.string().min(1).describe('map_id from a prior build_map call'),
+        instruction: z
+            .string()
+            .min(1)
+            .describe('e.g., "filter to where magnitude is greater than 5", "change basemap to dark"'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('mutate_map', {
+        title: 'Mutate a map',
+        description: 'Apply a natural-language instruction to an existing workspace. Valid mutations: filter a layer, remove a layer, change camera, change basemap. For ambiguous instructions the tool emits a clarification field. For unrelated instructions it emits outOfScope — build a new map in that case. ' +
+            'For the full Op catalog and predicate grammar, fetch the MCP resource showmeonmap://docs/workspace-ops-spec.',
+        inputSchema: mutateMapShape,
+    }, withValidation('mutate_map', mutateMapShape, async ({ map_id, instruction, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('mutate_map', map_id, rationale);
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/mutate', {
+            workspace: entry.workspace,
+            instruction,
+            rationale,
+        }));
+        if (!resp.ok) {
+            throw new Error(`mutate_map failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        if (resp.outOfScope && (!resp.opsEmitted || resp.opsEmitted.length === 0)) {
+            return toContent(envelope(baseUrl, map_id, entry.workspace, entry.mapPlan, resp.nextActions, { outOfScope: resp.outOfScope }));
+        }
+        await store.put(map_id, {
+            workspace: resp.workspace ?? entry.workspace,
+            mapPlan: resp.mapPlan ?? entry.mapPlan,
+            layerFilters: resp.layerFilters ?? {},
+            createdAt: entry.createdAt,
+            lastAccessed: Date.now(),
+        });
+        const mutMapPlan = (resp.mapPlan ?? entry.mapPlan);
+        // Update the shareable /m/<map_id> map so the link reflects the mutation.
+        await persistShareableMap(baseUrl, apiKey, map_id, mutMapPlan, instruction);
+        return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), mutMapPlan, resp.nextActions, resp.clarification ? { clarification: resp.clarification } : {}));
+    }));
+    const getStateShape = {
+        map_id: z.string().min(1),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('get_state', {
+        title: 'Read map state',
+        description: 'Return the current workspace, map plan, and active filters for a given map_id.',
+        inputSchema: getStateShape,
+    }, withValidation('get_state', getStateShape, async ({ map_id, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('get_state', map_id, rationale);
+        return toContent(envelope(baseUrl, map_id, entry.workspace, entry.mapPlan, undefined));
+    }));
+    // ===========================================================================
+    // V2 direct-op tools (spec §4, 2026-04-17 MCP design)
+    // ---------------------------------------------------------------------------
+    // These skip the NL roundtrip that mutate_map needs. Strong-model callers
+    // construct a typed Op or predicate and we apply it via the reducer directly.
+    // Each calls POST /api/workspace/apply-op (write) or /api/workspace/
+    // query-features (read). Shared envelope shape with v1 tools.
+    // ===========================================================================
+    /** Shared helper — POST a constructed Op and fold the result into the store. */
+    async function applyOp(map_id, op) {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/apply-op', {
+            workspace: entry.workspace,
+            op,
+        }));
+        if (!resp.ok) {
+            throw new Error(`apply-op failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        await store.put(map_id, {
+            workspace: resp.workspace ?? entry.workspace,
+            mapPlan: resp.mapPlan ?? entry.mapPlan,
+            layerFilters: resp.layerFilters ?? {},
+            createdAt: entry.createdAt,
+            lastAccessed: Date.now(),
+        });
+        const opMapPlan = (resp.mapPlan ?? entry.mapPlan);
+        // Update the shareable /m/<map_id> map so the link reflects the mutation.
+        await persistShareableMap(baseUrl, apiKey, map_id, opMapPlan, opMapPlan?.title ?? '');
+        return envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), opMapPlan, undefined);
+    }
+    /**
+     * Shared op-header builder — every direct-op tool fills these fields.
+     * `rationale` is required at the MCP tool layer (Teddy Riker, "Designing for
+     * Agents" §3.1, 2026-04-23) and passed straight through to OpBase.rationale.
+     */
+    function opHeader(rationale, emittedBy = 'agent') {
+        return {
+            opId: randomUUID(),
+            turnId: randomUUID(),
+            emittedAt: new Date().toISOString(),
+            emittedBy,
+            rationale,
+        };
+    }
+    // --- predicate schema (shared by filter_layer + query_features) ------------
+    // Keeping this structural — the server re-validates via the zod predicate
+    // schema, so the MCP-facing shape can be liberal to avoid client-side
+    // schema drift.
+    const predicateInputSchema = z
+        .record(z.string(), z.unknown())
+        .describe('Predicate in the Mongo-shape grammar. Examples: {op:"eq",field:"category",value:"cafe"}, ' +
+        '{op:"gt",field:"magnitude",value:5}, {op:"within",geometry:{type:"Polygon",coordinates:[...]}}, ' +
+        '{op:"and",children:[...]}. See docs/superpowers/specs/2026-04-17-workspace-ops-log-design.md §6.');
+    const addLayerShape = {
+        map_id: z.string().min(1).describe('map_id from a prior build_map call'),
+        layerPlan: z
+            .record(z.string(), z.unknown())
+            .describe('Full LayerPlan object. Must include id, title, source, viz, geometry.'),
+        rationale: rationaleSchema,
+        // intent hint (article §3.3) — optional mental-model marker so we
+        // can later route / telemeter based on what the calling agent
+        // believed it was doing. Calling agents that don't know which
+        // value to send can omit it; we never reject for missing intent.
+        intent: z
+            .enum(['primary-data', 'context-overlay', 'reference-boundary', 'annotation', 'comparison', 'other'])
+            .optional()
+            .describe('Optional. Which mental model is this add_layer operating under? ' +
+            '"primary-data" = the layer the user actually asked to see; ' +
+            '"context-overlay" = supporting data layered on top of a primary; ' +
+            '"reference-boundary" = admin/geo boundary used as a backdrop; ' +
+            '"annotation" = caller-placed callout / pin layer; ' +
+            '"comparison" = a layer added to compare against another; ' +
+            '"other" = none of the above.'),
+    };
+    server.registerTool('add_layer', {
+        title: 'Add a layer (direct)',
+        description: 'Append a fully-constructed LayerPlan to an existing workspace without going through NL. ' +
+            'Pass the same shape the workspace pipeline emits — { id, title, source, viz, geometry, ... }. ' +
+            'Prefer this when you already have a structured plan; otherwise use mutate_map. ' +
+            'For the full LayerPlan and Op spec, fetch the MCP resource showmeonmap://docs/workspace-ops-spec.',
+        inputSchema: addLayerShape,
+    }, withValidation('add_layer', addLayerShape, async ({ map_id, layerPlan, rationale, intent }) => {
+        logRationale('add_layer', map_id, rationale, { opKind: 'addLayer', ...(intent ? { intent } : {}) });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'addLayer',
+            args: {
+                layerPlan,
+                ...(intent ? { intent } : {}),
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const addFusionLayerShape = {
+        map_id: z.string().min(1),
+        layer_a_id: z.string().min(1),
+        layer_b_id: z.string().min(1),
+        mode: z.literal('bivariate').default('bivariate'),
+        value_field_a: z.string().optional(),
+        value_field_b: z.string().optional(),
+        new_layer_id: z.string().optional(),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('add_fusion_layer', {
+        title: 'Add bivariate fusion layer',
+        description: 'Spatially join two existing layers and add a new layer that ' +
+            'encodes both values per region as a 3x3 bivariate choropleth. ' +
+            'Both layers must already exist in the workspace (call build_map ' +
+            'or add_layer first). Auto-detects the numeric value field from ' +
+            'each layer\'s viz config; pass value_field_a / value_field_b to ' +
+            'override. Returns the new layer_id, correlation r, and ' +
+            'matched-feature count. Required: map_id, layer_a_id, ' +
+            'layer_b_id, rationale.',
+        inputSchema: addFusionLayerShape,
+    }, withValidation('add_fusion_layer', addFusionLayerShape, async ({ map_id, layer_a_id, layer_b_id, value_field_a, value_field_b, new_layer_id, rationale, }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('add_fusion_layer', map_id, rationale, { opKind: 'addLayer' });
+        const data = await apiFetch(baseUrl, apiKey, '/api/workspace/apply-fusion-op', {
+            workspace: entry.workspace,
+            sourceLayerA: layer_a_id,
+            sourceLayerB: layer_b_id,
+            ...(value_field_a ? { valueFieldA: value_field_a } : {}),
+            ...(value_field_b ? { valueFieldB: value_field_b } : {}),
+            ...(new_layer_id ? { newLayerId: new_layer_id } : {}),
+            header: { rationale },
+        });
+        if (!data.ok) {
+            throw new Error(`add_fusion_layer failed: ${data.error?.kind ?? 'unknown'} — ${data.error?.reason ?? data.error?.message ?? 'no detail'}`);
+        }
+        await store.put(map_id, {
+            workspace: data.workspace,
+            mapPlan: data.mapPlan,
+            layerFilters: data.layerFilters ?? {},
+            createdAt: entry.createdAt,
+            lastAccessed: Date.now(),
+        });
+        return toContent({
+            ok: true,
+            layer_id: data.layer_id,
+            correlation: data.correlation,
+            matchedCount: data.matchedCount,
+            outliers: data.outliers,
+        });
+    }));
+    const correlateLayersShape = {
+        map_id: z.string().min(1),
+        layer_a_id: z.string().min(1),
+        layer_b_id: z.string().min(1),
+        value_field_a: z.string().optional(),
+        value_field_b: z.string().optional(),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('correlate_layers', {
+        title: 'Compute correlation between two layers',
+        description: 'Spatially join two existing workspace layers and return the ' +
+            'Pearson correlation coefficient r, sample size n, two-sided ' +
+            'p-value approximation, plus human-readable strength and ' +
+            'direction labels. Pure read — no layer is added, no op is ' +
+            'committed, no credit charge. Use this when you want a numeric ' +
+            'answer without rendering; use add_fusion_layer when the user ' +
+            'wants the visualization. Required: map_id, layer_a_id, ' +
+            'layer_b_id, rationale.',
+        inputSchema: correlateLayersShape,
+    }, withValidation('correlate_layers', correlateLayersShape, async ({ map_id, layer_a_id, layer_b_id, value_field_a, value_field_b, rationale, }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('correlate_layers', map_id, rationale);
+        const data = await apiFetch(baseUrl, apiKey, '/api/workspace/correlate-layers', {
+            workspace: entry.workspace,
+            sourceLayerA: layer_a_id,
+            sourceLayerB: layer_b_id,
+            ...(value_field_a ? { valueFieldA: value_field_a } : {}),
+            ...(value_field_b ? { valueFieldB: value_field_b } : {}),
+        });
+        if (!data.ok) {
+            throw new Error(`correlate_layers failed: ${data.error?.kind ?? 'unknown'} — ${data.error?.reason ?? data.error?.message ?? 'no detail'}`);
+        }
+        // Pure read — do NOT update the session-store entry. Subsequent
+        // get_state / mutate_map calls see the same workspace they would
+        // have seen before this call.
+        return toContent({
+            ok: true,
+            r: data.r,
+            n: data.n,
+            pValue: data.pValue,
+            matchedCount: data.matchedCount,
+            strength: data.strength,
+            direction: data.direction,
+            outliers: data.outliers,
+        });
+    }));
+    const filterLayerShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1).describe('id of the layer to filter'),
+        predicate: predicateInputSchema,
+        append: z
+            .boolean()
+            .optional()
+            .describe('Default true. false replaces the layer\'s existing filter chain.'),
+        rationale: rationaleSchema,
+        // intent hint (article §3.3) — optional mental-model marker so we
+        // can later route / telemeter based on what the calling agent
+        // believed it was doing. Calling agents that don't know which
+        // value to send can omit it; we never reject for missing intent.
+        intent: z
+            .enum(['narrow', 'isolate-outliers', 'compare-subset', 'preview-data', 'other'])
+            .optional()
+            .describe('Optional. Which mental model is this filter operating under? ' +
+            '"narrow" = generic shrink-the-set; ' +
+            '"isolate-outliers" = pull out anomalies for inspection; ' +
+            '"compare-subset" = pre-step before a side-by-side compare; ' +
+            '"preview-data" = exploratory peek; ' +
+            '"other" = none of the above.'),
+    };
+    server.registerTool('filter_layer', {
+        title: 'Filter a layer (direct)',
+        description: 'Narrow a layer to features matching a structured predicate. `append:true` (default) conjoins ' +
+            'with any existing filter; `append:false` replaces the chain.',
+        inputSchema: filterLayerShape,
+    }, withValidation('filter_layer', filterLayerShape, async ({ map_id, layerId, predicate, append, rationale, intent }) => {
+        logRationale('filter_layer', map_id, rationale, { opKind: 'filterLayer', ...(intent ? { intent } : {}) });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'filterLayer',
+            args: {
+                layerId,
+                predicate,
+                ...(typeof append === 'boolean' ? { append } : {}),
+                ...(intent ? { intent } : {}),
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const selectWithinShape = {
+        map_id: z.string().min(1),
+        sourceLayerId: z.string().min(1),
+        newLayerId: z
+            .string()
+            .min(1)
+            .describe('Id for the new layer. Must not already be in use in this workspace.'),
+        selection: z
+            .object({
+            type: z.enum(['Polygon', 'MultiPolygon']),
+            coordinates: z.array(z.any()),
+        })
+            .describe('GeoJSON Polygon or MultiPolygon in [lng,lat] coordinate order.'),
+        inheritStyle: z
+            .boolean()
+            .optional()
+            .describe('Default true. false emits a new layer with minimal default styling.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('select_within', {
+        title: 'Subset a layer to a polygon selection',
+        description: 'Create a new layer containing the source layer\'s features that lie within the supplied ' +
+            'polygon. The source layer is untouched. Useful for "show me only the X inside this ' +
+            'country/bbox/hand-drawn shape."',
+        inputSchema: selectWithinShape,
+    }, withValidation('select_within', selectWithinShape, async ({ map_id, sourceLayerId, newLayerId, selection, inheritStyle, rationale }) => {
+        logRationale('select_within', map_id, rationale, { opKind: 'subsetToSelection' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'subsetToSelection',
+            args: {
+                sourceLayerId,
+                newLayerId,
+                selection,
+                ...(typeof inheritStyle === 'boolean' ? { inheritStyle } : {}),
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const queryFeaturesShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1),
+        predicate: predicateInputSchema,
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .max(1000)
+            .optional()
+            .describe('Default 100, max 1000. Response sets `truncated:true` when clipped.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('query_features', {
+        title: 'Query features from a layer (read-only)',
+        description: 'Evaluate a predicate against a layer\'s inline features and return the matching subset. ' +
+            'No Op is emitted and the workspace is not mutated. Handy for introspection ("how many X ' +
+            'match Y?") before deciding whether to filter, subset, or build a new layer.',
+        inputSchema: queryFeaturesShape,
+    }, withValidation('query_features', queryFeaturesShape, async ({ map_id, layerId, predicate, limit, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('query_features', map_id, rationale);
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/query-features', {
+            workspace: entry.workspace,
+            layerId,
+            predicate,
+            ...(typeof limit === 'number' ? { limit } : {}),
+        }));
+        if (!resp.ok) {
+            throw new Error(`query_features failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        return toContent({
+            ok: true,
+            map_id,
+            layerId,
+            totalMatched: resp.totalMatched ?? 0,
+            truncated: resp.truncated ?? false,
+            features: resp.features ?? [],
+        });
+    }));
+    // ===========================================================================
+    // V2 direct-op tools — catalog completion (remaining 8 ops).
+    // ---------------------------------------------------------------------------
+    // Same pattern as add_layer / filter_layer / select_within — each wraps a
+    // single Op kind, constructs it with opHeader(), and ships through
+    // /api/workspace/apply-op. These exist so strong-model callers can skip
+    // the NL roundtrip for any op in the spec catalog.
+    // ===========================================================================
+    const removeLayerShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1),
+        rationale: rationaleSchema,
+        confirmed: z
+            .boolean()
+            .optional()
+            .describe('Set to true to confirm this destructive action. If omitted or false, the call ' +
+            'returns a needs_confirmation envelope. Layer ids are tombstoned — once removed, ' +
+            'the same id cannot be re-added later in this workspace.'),
+    };
+    server.registerTool('remove_layer', {
+        title: 'Remove a layer (direct, destructive)',
+        description: 'Drop a layer from the workspace by id. Strict: removing an already-removed ' +
+            'or never-added layer fails. Layer ids do NOT recycle — a removed id cannot be ' +
+            're-added later in the same workspace. ' +
+            'GATED: this tool is destructive. Pass confirmed:true to proceed; otherwise ' +
+            'a needs_confirmation envelope is returned.',
+        inputSchema: removeLayerShape,
+    }, withValidation('remove_layer', removeLayerShape, withConfirmation('remove_layer', async ({ map_id, layerId, rationale }) => {
+        logRationale('remove_layer', map_id, rationale, { opKind: 'removeLayer' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'removeLayer',
+            args: { layerId },
+        };
+        return toContent(await applyOp(map_id, op));
+    })));
+    const clearFiltersShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1),
+        rationale: rationaleSchema,
+        confirmed: z
+            .boolean()
+            .optional()
+            .describe('Set to true to confirm this sensitive action. If omitted or false, the call ' +
+            'returns a needs_confirmation envelope. Wiping a filter chain is recoverable ' +
+            'via undo, but autonomous agents lack a UI surface to confirm intent.'),
+    };
+    server.registerTool('clear_filters', {
+        title: 'Clear all filters on a layer (direct, gated)',
+        description: 'Wipe every predicate currently applied to a layer\'s filter chain, making ' +
+            'every source feature visible again. Inverse of filter_layer. No-op on layers ' +
+            'that have no existing filter. ' +
+            'GATED: pass confirmed:true to proceed; otherwise a needs_confirmation envelope is returned.',
+        inputSchema: clearFiltersShape,
+    }, withValidation('clear_filters', clearFiltersShape, withConfirmation('clear_filters', async ({ map_id, layerId, rationale }) => {
+        logRationale('clear_filters', map_id, rationale, { opKind: 'clearFilters' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'clearFilters',
+            args: { layerId },
+        };
+        return toContent(await applyOp(map_id, op));
+    })));
+    const renameLayerShape = {
+        map_id: z.string().min(1),
+        oldLayerId: z.string().min(1),
+        newLayerId: z.string().min(1).describe('New id. Must be unique within the workspace.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('rename_layer', {
+        title: 'Rename a layer (direct)',
+        description: 'Change a layer\'s id from oldLayerId to newLayerId. Re-keys any existing filter ' +
+            'chain and preserves insertion order among sibling layers. Strict: newLayerId must ' +
+            'not already be in use (current OR tombstoned) in this workspace. Subsequent ops ' +
+            'must reference the layer by its new id.',
+        inputSchema: renameLayerShape,
+    }, withValidation('rename_layer', renameLayerShape, async ({ map_id, oldLayerId, newLayerId, rationale }) => {
+        logRationale('rename_layer', map_id, rationale, { opKind: 'renameLayer' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'renameLayer',
+            args: { oldLayerId, newLayerId },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const restyleLayerShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1),
+        color: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('CSS color string: hex (#RRGGBB), rgb/rgba, or named color.'),
+        opacity: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe('0 (transparent) to 1 (opaque).'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('restyle_layer', {
+        title: 'Restyle a layer (direct)',
+        description: 'Adjust a layer\'s color and/or opacity. Within-palette changes only — the ' +
+            'renderer silently ignores fields the current viz variant doesn\'t support. ' +
+            'Pass at least one of color / opacity; passing neither is an accepted no-op.',
+        inputSchema: restyleLayerShape,
+    }, withValidation('restyle_layer', restyleLayerShape, async ({ map_id, layerId, color, opacity, rationale }) => {
+        logRationale('restyle_layer', map_id, rationale, { opKind: 'restyleLayer' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'restyleLayer',
+            args: {
+                layerId,
+                ...(typeof color === 'string' ? { color } : {}),
+                ...(typeof opacity === 'number' ? { opacity } : {}),
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    // CameraPlan mirrors src/lib/types/mapPlan.ts :: CameraPlan. Keeping the
+    // discriminated union local to the tool — the reducer re-validates
+    // structurally (workspace.ts declares args.camera as z.unknown) so this
+    // schema is purely a client-side shape hint.
+    const cameraPlanSchema = z.discriminatedUnion('mode', [
+        z.object({
+            mode: z.literal('fitBounds'),
+            bounds: z
+                .tuple([z.number(), z.number(), z.number(), z.number()])
+                .describe('[west, south, east, north] bbox in WGS84 degrees.'),
+            padding: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Pixel padding around the bbox. Default is the renderer default.'),
+            animateMs: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Animation duration in ms. 0 = instant jump.'),
+        }),
+        z.object({
+            mode: z.literal('flyTo'),
+            center: z.tuple([z.number(), z.number()]).describe('[lng, lat] in WGS84.'),
+            zoom: z.number(),
+            pitch: z.number().optional().describe('Tilt in degrees, 0-60.'),
+            bearing: z.number().optional().describe('Rotation in degrees, 0-360.'),
+            animateMs: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe('Animation duration in ms. 0 = instant jump.'),
+        }),
+    ]);
+    const setCameraShape = {
+        map_id: z.string().min(1),
+        camera: cameraPlanSchema,
+        rationale: rationaleSchema,
+    };
+    server.registerTool('set_camera', {
+        title: 'Set the map camera (direct)',
+        description: 'Override the workspace camera. Latest set_camera op wins during replay. ' +
+            'Two modes: `fitBounds` with a [w,s,e,n] bbox (plus optional padding/animateMs), ' +
+            'or `flyTo` with [lng,lat] center + zoom (plus optional pitch/bearing/animateMs). ' +
+            'Use for "zoom to Japan", "center on Paris at z=10", or finishing a drill-down ' +
+            'after filter_layer. Equivalent to the camera move mutate_map would emit, but ' +
+            'skips the NL roundtrip.',
+        inputSchema: setCameraShape,
+    }, withValidation('set_camera', setCameraShape, async ({ map_id, camera, rationale }) => {
+        logRationale('set_camera', map_id, rationale, { opKind: 'setCamera' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'setCamera',
+            args: { camera },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const setTimeShape = {
+        map_id: z.string().min(1),
+        field: z
+            .string()
+            .min(1)
+            .describe('Feature property carrying the time value (e.g. "date", "year", "timestamp").'),
+        rangeStart: z.number().describe('Inclusive lower bound of the visible window.'),
+        rangeEnd: z.number().describe('Inclusive upper bound of the visible window.'),
+        format: z
+            .enum(['unix_ms', 'iso', 'integer'])
+            .optional()
+            .describe('How rangeStart/rangeEnd encode time. Default: unix_ms at render time.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('set_time', {
+        title: 'Set the time window (direct)',
+        description: 'Override the current time-range filter. Latest set_time op wins during replay. ' +
+            'Use for "filter to 2020-2024" or "show only the last 7 days" intents. Not yet ' +
+            'consumed by the renderer — the UI drives the slider directly — but the value is ' +
+            'captured in the ops log and queryable via get_state.',
+        inputSchema: setTimeShape,
+    }, withValidation('set_time', setTimeShape, async ({ map_id, field, rangeStart, rangeEnd, format, rationale }) => {
+        logRationale('set_time', map_id, rationale, { opKind: 'setTime' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'setTime',
+            args: {
+                field,
+                rangeStart,
+                rangeEnd,
+                ...(format ? { format } : {}),
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const tagShape = {
+        map_id: z.string().min(1),
+        name: z
+            .string()
+            .min(1)
+            .describe('Checkpoint label, e.g. "before EV layer added" or "v1.0".'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('tag', {
+        title: 'Save a named checkpoint (direct)',
+        description: 'Label the current workspace state with a user-supplied name. The label is ' +
+            'mirrored into workspace.meta.tags so UIs can render a named-revision history. ' +
+            'Tagging the same label twice is idempotent — no error, no duplicate entry.',
+        inputSchema: tagShape,
+    }, withValidation('tag', tagShape, async ({ map_id, name, rationale }) => {
+        logRationale('tag', map_id, rationale, { opKind: 'tag' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'tag',
+            args: { name },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const addAnnotationShape = {
+        map_id: z.string().min(1),
+        id: z.string().min(1).describe('Stable id for this annotation — caller-supplied.'),
+        coords: z
+            .tuple([z.number(), z.number()])
+            .describe('[lng, lat] in WGS84.'),
+        label: z.string().optional().describe('Optional text rendered at the point.'),
+        color: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Optional CSS color for the marker + label.'),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('add_annotation', {
+        title: 'Place an annotation on the map (direct)',
+        description: 'Add a user-placed label at a specific coordinate. Annotations are independent of ' +
+            'layers and live in their own id namespace. Strict: the id must not already be in ' +
+            'use by another CURRENTLY-placed annotation (removed ids can be recycled).',
+        inputSchema: addAnnotationShape,
+    }, withValidation('add_annotation', addAnnotationShape, async ({ map_id, id, coords, label, color, rationale }) => {
+        logRationale('add_annotation', map_id, rationale, { opKind: 'addAnnotation' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'addAnnotation',
+            args: {
+                annotation: {
+                    id,
+                    coords: coords,
+                    ...(label ? { label } : {}),
+                    ...(color ? { color } : {}),
+                },
+            },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    const removeAnnotationShape = {
+        map_id: z.string().min(1),
+        annotationId: z.string().min(1),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('remove_annotation', {
+        title: 'Remove an annotation (direct)',
+        description: 'Drop a previously-placed annotation by id. Strict: removing an already-removed ' +
+            'or never-placed id fails. After removal, the id CAN be re-used by a later ' +
+            'add_annotation (unlike layer ids, which are tombstoned for the session).',
+        inputSchema: removeAnnotationShape,
+    }, withValidation('remove_annotation', removeAnnotationShape, async ({ map_id, annotationId, rationale }) => {
+        logRationale('remove_annotation', map_id, rationale, { opKind: 'removeAnnotation' });
+        const op = {
+            ...opHeader(rationale),
+            kind: 'removeAnnotation',
+            args: { annotationId },
+        };
+        return toContent(await applyOp(map_id, op));
+    }));
+    // ===========================================================================
+    // V1 completion — export + undo + redo.
+    // ---------------------------------------------------------------------------
+    // Export is read-only; undo/redo manipulate the workspace cursor without
+    // modifying the ops log, then re-materialize via /api/workspace/materialize
+    // so the caller sees the refreshed mapPlan for the rewound state.
+    // ===========================================================================
+    /** Shared helper — re-materialize a workspace at whatever cursor it carries. */
+    async function rematerialize(map_id, workspace) {
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/materialize', {
+            workspace,
+        }));
+        if (!resp.ok) {
+            throw new Error(`materialize failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        const entry = await store.get(map_id);
+        await store.put(map_id, {
+            workspace,
+            mapPlan: resp.mapPlan ?? null,
+            layerFilters: resp.layerFilters ?? {},
+            createdAt: entry?.createdAt ?? Date.now(),
+            lastAccessed: Date.now(),
+        });
+        const rematPlan = resp.mapPlan;
+        // Keep the shareable /m/<map_id> map in sync after undo/redo.
+        await persistShareableMap(baseUrl, apiKey, map_id, rematPlan, rematPlan?.title ?? '');
+        return envelope(baseUrl, map_id, workspace, rematPlan, undefined);
+    }
+    const exportWorkspaceShape = {
+        map_id: z.string().min(1),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('export_workspace', {
+        title: 'Export the workspace JSON',
+        description: 'Return the current workspace document (ops log + cursor + meta) plus the ' +
+            'materialized mapPlan and layerFilters, in a shape suitable for save-to-file / ' +
+            'share-by-URL / inspection. Pure read — no mutation, no credit charge. Use ' +
+            'this when you want the full raw state for serialization; use get_state when ' +
+            'you want the compact envelope for display.',
+        inputSchema: exportWorkspaceShape,
+    }, withValidation('export_workspace', exportWorkspaceShape, async ({ map_id, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('export_workspace', map_id, rationale);
+        return toContent({
+            ok: true,
+            map_id,
+            workspace: entry.workspace,
+            mapPlan: entry.mapPlan,
+            layerFilters: entry.layerFilters,
+            exportedAt: new Date().toISOString(),
+        });
+    }));
+    const exportLayerDataShape = {
+        map_id: z.string().min(1),
+        layer_id: z.string().min(1),
+        format: z.enum(['csv', 'geojson']),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('export_layer_data', {
+        title: 'Export layer data',
+        description: 'Export a single layer\'s features as a downloadable file. Returns ' +
+            'a URL with Content-Disposition: attachment so the user\'s browser ' +
+            'downloads it. CSV drops geometry beyond a (lng, lat) centroid — ' +
+            'for full polygon/line geometry, use format: "geojson". URL is ' +
+            'valid for 24 hours. Required: map_id, layer_id, format, rationale.',
+        inputSchema: exportLayerDataShape,
+    }, withValidation('export_layer_data', exportLayerDataShape, async ({ map_id, layer_id, format, rationale }) => {
+        logRationale('export_layer_data', map_id, rationale);
+        const data = await apiFetch(baseUrl, apiKey, '/api/export/layer-data', {
+            map_id, layer_id, format, rationale,
+        });
+        return toContent({ ok: true, ...data });
+    }));
+    const exportImageShape = {
+        map_id: z.string().min(1),
+        format: z.enum(['png', 'jpeg', 'pdf']).default('png'),
+        legend: z.boolean().default(true),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('export_image', {
+        title: 'Export map as image',
+        description: 'Returns a deep-link URL that opens the map in the user\'s browser ' +
+            'and automatically triggers a PNG download. The user clicks the ' +
+            'link, the browser renders the map at full resolution with the ' +
+            'legend composited (if legend: true), and the file downloads. ' +
+            'There is no server-side rendering; the user\'s browser is the ' +
+            'renderer. Required: map_id, rationale. Optional: format (png ' +
+            'default), legend (true default).',
+        inputSchema: exportImageShape,
+    }, withValidation('export_image', exportImageShape, async ({ map_id, format, legend, rationale }) => {
+        logRationale('export_image', map_id, rationale);
+        // Auto-share check — guarantees /m/[id] resolves.
+        try {
+            await apiFetch(baseUrl, apiKey, '/api/export/ensure-shared', { map_id, rationale });
+        }
+        catch (err) {
+            // Surface as a soft warning; the URL still composes, but the user
+            // may get a 404 if the workspace isn't shareable yet.
+            console.warn('[export_image] ensure-shared failed:', err);
+        }
+        const url = `${baseUrl}/m/${encodeURIComponent(map_id)}?autoExport=${format}&legend=${legend ? 'on' : 'off'}`;
+        return toContent({
+            ok: true,
+            format,
+            url,
+            note: 'Open this URL in a browser to download the image.',
+        });
+    }));
+    const undoShape = {
+        map_id: z.string().min(1),
+        rationale: rationaleSchema,
+        confirmed: z
+            .boolean()
+            .optional()
+            .describe('Set to true to confirm this sensitive action. If omitted or false, the call ' +
+            'returns a needs_confirmation envelope. Autonomous undo without user intent is ' +
+            'a footgun — an agent that decides to "fix" something can erase prior work.'),
+    };
+    server.registerTool('undo', {
+        title: 'Undo the most recent op (gated)',
+        description: 'Rewind the workspace cursor by one, re-materializing the state as it was before ' +
+            'the last mutation. Does NOT delete any ops — redo will fast-forward. Calling ' +
+            'undo at the workspace genesis (cursor === 0, only the CreateWorkspace op is in ' +
+            'scope) is a no-op that surfaces an error rather than silently doing nothing. ' +
+            'GATED: pass confirmed:true to proceed; otherwise a needs_confirmation envelope is returned.',
+        inputSchema: undoShape,
+    }, withValidation('undo', undoShape, withConfirmation('undo', async ({ map_id, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('undo', map_id, rationale);
+        const ws = entry.workspace;
+        const currentCursor = typeof ws.cursor === 'number' ? ws.cursor : 0;
+        if (currentCursor <= 0) {
+            throw new Error('Nothing to undo — cursor is already at workspace genesis.');
+        }
+        const undone = { ...ws, cursor: currentCursor - 1 };
+        return toContent(await rematerialize(map_id, undone));
+    })));
+    const redoShape = {
+        map_id: z.string().min(1),
+        rationale: rationaleSchema,
+    };
+    server.registerTool('redo', {
+        title: 'Redo a previously-undone op',
+        description: 'Advance the workspace cursor by one toward the tail of the ops log, replaying ' +
+            'the next op that was previously undone. Calling redo when the cursor is already ' +
+            'at the tail (no undone ops to fast-forward) fails rather than silently no-op. ' +
+            'Note: any new op applied via apply-op / mutate-map after an undo truncates the ' +
+            'redo tail (standard edit-stack semantics).',
+        inputSchema: redoShape,
+    }, withValidation('redo', redoShape, async ({ map_id, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('redo', map_id, rationale);
+        const ws = entry.workspace;
+        const opsLen = Array.isArray(ws.opsLog) ? ws.opsLog.length : 0;
+        const currentCursor = typeof ws.cursor === 'number' ? ws.cursor : 0;
+        if (currentCursor >= opsLen - 1) {
+            throw new Error('Nothing to redo — cursor is already at the end of the ops log.');
+        }
+        const redone = { ...ws, cursor: currentCursor + 1 };
+        return toContent(await rematerialize(map_id, redone));
+    }));
+    // ===========================================================================
+    // Agent feedback loop (article §3.2)
+    // ---------------------------------------------------------------------------
+    // Standalone tool that a calling agent uses to file "I'm stuck" reports.
+    // No map_id required (an agent stuck *before* any map is built must still
+    // be able to report). Persists to reports/agent-blockers/YYYY-MM-DD.ndjson
+    // via POST /api/agent/report-blocker. Returns a friendly envelope — no
+    // need to mimic build_map's three-channel shape.
+    // ===========================================================================
+    const reportBlockerShape = {
+        map_id: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Optional. The map_id you were working on, if any.'),
+        what_i_was_trying: z
+            .string()
+            .min(1)
+            .max(500)
+            .describe('High-level intent in one or two sentences. e.g. "merge two filtered choropleths into a fused bivariate map".'),
+        what_i_tried: z
+            .string()
+            .min(1)
+            .max(1000)
+            .describe('Which tools / inputs you attempted, in order. Be specific — tool name + key arg shape is ideal.'),
+        where_i_got_stuck: z
+            .string()
+            .min(1)
+            .max(500)
+            .describe('The specific failure: what came back, what was missing, why you could not proceed.'),
+        suggested_capability: z
+            .string()
+            .min(1)
+            .max(300)
+            .optional()
+            .describe('Optional. A new tool, op, or schema field that would have unblocked you.'),
+    };
+    server.registerTool('report_blocker', {
+        title: 'Report a blocker (agent feedback)',
+        description: 'Tell the ShowMeOnMap team your agent hit something it could not accomplish — an ' +
+            'unsupported intent, a missing tool, an unclear schema, an op that failed in a ' +
+            'confusing way. Use this when build_map / mutate_map / a direct-op tool returns ' +
+            'something you cannot recover from, OR when you would have wanted a different tool ' +
+            'to exist. Records the report to a server-side log; does not unblock the current ' +
+            'session, but feeds future capability work. No map_id required — file the report ' +
+            'even if no map was built.',
+        inputSchema: reportBlockerShape,
+    }, withValidation('report_blocker', reportBlockerShape, async ({ map_id, what_i_was_trying, what_i_tried, where_i_got_stuck, suggested_capability }) => {
+        // Mirror to the rationale NDJSON so the May-1 clustering pass sees a
+        // unified stream of "what did agents try, where did they get stuck".
+        // The agent-blockers route persists the full record separately.
+        logRationale('report_blocker', map_id ?? null, `BLOCKER: ${what_i_was_trying} — stuck: ${where_i_got_stuck}`, { opKind: 'reportBlocker' });
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/agent/report-blocker', {
+            ...(map_id ? { map_id } : {}),
+            what_i_was_trying,
+            what_i_tried,
+            where_i_got_stuck,
+            ...(suggested_capability ? { suggested_capability } : {}),
+            source: 'mcp',
+        }));
+        if (!resp.ok) {
+            throw new Error(`report_blocker failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        return toContent({
+            ok: true,
+            message: `Blocker recorded — thanks. Recorded at ${resp.recorded_at ?? new Date().toISOString()}.`,
+        });
+    }));
+    // ── JSON Schema draft normalization (2026-07-16) ─────────────────────────
+    // zod-to-json-schema (inside the SDK) stamps every tool's inputSchema with a
+    // draft-07 `$schema` header. The Anthropic API validates tool schemas as
+    // draft 2020-12 and REJECTS the draft-07 header ("tools.N.custom.input_
+    // schema: JSON schema is invalid. It must match JSON Schema draft 2020-12"),
+    // which breaks EVERY live client (Claude Desktop, the OpenAI Responses API,
+    // …). The MCP wire layer never validates this, so the protocol roundtrip
+    // tests pass while real clients fail. Strip the header on the way out — a
+    // schema with no `$schema` defaults to 2020-12, which validates. Done at the
+    // transport boundary so all three entrypoints (stdio, standalone HTTP, and
+    // the app's /api/mcp route) are covered by this one shared factory.
+    const stripDraftSchema = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const el of node)
+                stripDraftSchema(el);
+            return;
+        }
+        const rec = node;
+        delete rec.$schema;
+        for (const v of Object.values(rec))
+            stripDraftSchema(v);
+    };
+    const originalConnect = server.connect.bind(server);
+    server.connect = ((transport) => {
+        const t = transport;
+        const originalSend = t.send?.bind(t);
+        if (originalSend) {
+            t.send = (message, options) => {
+                const tools = message?.result?.tools;
+                if (Array.isArray(tools)) {
+                    for (const tool of tools) {
+                        const tt = tool;
+                        stripDraftSchema(tt.inputSchema);
+                        stripDraftSchema(tt.outputSchema);
+                    }
+                }
+                return originalSend(message, options);
+            };
+        }
+        return originalConnect(transport);
+    });
+    return server;
+}