@showmeonmap/mcp 0.4.0 → 0.6.0

package/README.md

@@ -90,10 +90,17 @@ Ask Claude Desktop things like:
 
 ---
 
-## Tool surface (24 tools)
+## Tool surface (26 tools)
 
-**V1 — natural-language tools (3)**: `build_map`, `mutate_map`, `get_state`.
-**V2 — direct-op tools (18)**: `add_layer`, `filter_layer`, `clear_filters`, `remove_layer`, `rename_layer`, `restyle_layer`, `set_camera`, `set_time`, `set_basemap`, `select_within`, `subset_to_selection`, `query_features`, `add_annotation`, `remove_annotation`, `tag`, `undo`, `redo`, `report_blocker`.
+**Workspace lifecycle (6)**: `build_map`, `mutate_map`, `get_state`, `export_workspace`, `undo`, `redo`.
+**Direct ops (14)**: `add_layer`, `filter_layer`, `select_within`, `focus_area`, `query_features`, `remove_layer`, `clear_filters`, `rename_layer`, `restyle_layer`, `set_camera`, `set_time`, `tag`, `add_annotation`, `remove_annotation`.
+**Multi-source analysis (3)**: `add_fusion_layer`, `correlate_layers`, `run_analysis`.
+**Export (2)**: `export_layer_data`, `export_image`.
+**Feedback channel (1)**: `report_blocker`.
+
+`focus_area` (0.4.0) refines an existing map to a **named** area — no coordinates required. Pass a `layerId` plus an `areaRef` (`{kind:'corridor', street, from?, to?}`, `{kind:'place', name}`, or `{kind:'aroundIntersection', street, cross}`) and the server resolves the real geometry from OpenStreetMap, then applies one of three `mode`s: `filter` (hide non-matching), `select` (extract to a new layer), or `clip` (geometrically trim — lines are split at the boundary). The reply carries a grounded `contextAnswer` such as `"kept 37 of 150 features"`. A resolver miss returns a `clarification` with real nearby candidates rather than a guessed location.
+
+`run_analysis` (0.5.0; knobs below 0.6.0) computes a spatial analysis server-side and appends the finished, honestly-legended result as a new layer + camera. `analysis: 'hotspot'` runs **Getis-Ord Gi\***: hot/cold significance classes (99/95/90%, Benjamini-Hochberg FDR-corrected) on a numeric `valueField`, or on hex-binned point density when `valueField` is omitted (fishnet with zero cells, auto-grown under a stated cap). The reply carries a grounded `memo` + `stats` payload (Moran's I, class counts, significant share) — every number is computed, never generated — plus `resultLayerId` and a `contextAnswer` like `"Found 12 hot and 0 cold features among n=72"`. "No significant clustering" is a finding that keeps the map (and the credit); typed failures (unknown layer, too few features, the 10,000-feature cap) are refunded. `analysis: 'zonal'` aggregates a point layer into polygon zones — an existing zone layer (`zoneLayerId`) or a generated h3 hex fishnet (`zones: {kind:'h3', resolution?}`) — as count/sum/mean/min/max per zone, rendered as a quantile choropleth where a zone with zero features and a zone the data never reaches are DIFFERENT legend classes. `analysis: 'enrich'` joins a US Census ACS indicator (`median_household_income`, `median_home_value`, `median_rent`, … or a raw variable code) onto each feature by tract/county/state containment — unmatched features stay null, never zero-filled, and the joined column carries the indicator's human name. In all analyses the result replaces its input layer(s) (undoable; original attributes preserved or aggregated as stated in the memo). The catalog grows behind this one tool. Two opt-in knobs (0.6.0): `annotate: true` places ONE callout annotation at the analysis's headline feature (hottest cluster / top zone / highest joined value — label text only from computed values; no headline → no annotation), and `story: true` persists the shared map with a 2-step story rail (the grounded `contextAnswer` as overview + the memo as an analysis step that isolates the result layer at its real extent) so the `/m/` link opens as a guided read.
 
 Every tool returns a **three-channel envelope**:
 

package/dist/storyDraft.js

@@ -0,0 +1,106 @@
+/**
+ * MCP-side story drafting — the "MCP export knob" deferred from PR-C3
+ * (spec 2026-08-15 §PR-C3, ledger 11; shipped 0.6.0).
+ *
+ * `run_analysis({ story: true })` persists the shared map with a
+ * 2-step story: an overview step carrying the grounded one-line
+ * contextAnswer, and an analysis step carrying the grounded memo,
+ * isolating the result layer and framing its REAL extent. The same two
+ * iron rules as the web drafter (src/lib/share/story.ts — this package
+ * is self-contained, so the invariants are restated, not imported):
+ *
+ * 1. GROUNDED TEXT ONLY — bodies are the contextAnswer and memo the
+ *    analysis just computed, verbatim (markdown chrome stripped, long
+ *    memos clamped at a whitespace boundary — a verbatim prefix, never
+ *    a rewrite). Missing either text → no story (a 1-step story is
+ *    worse than none; /m/'s render guard rejects < 2 steps anyway).
+ * 2. NEVER INVENT GEOMETRY — the analysis step's camera is the bbox of
+ *    the result layer's own features; no features → no camera.
+ */
+/** /m/'s isValidStory caps bodies at 4000 chars — clamp the memo to a
+ *  verbatim prefix at a whitespace boundary rather than get rejected. */
+const MAX_BODY = 4000;
+/** Strip markdown chrome (headings, bold/italic markers, backticks) —
+ *  the story rail renders plain text; the words are untouched. */
+export function markdownToPlain(md) {
+    return md
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function clampBody(text) {
+    if (text.length <= MAX_BODY)
+        return text;
+    const cut = text.lastIndexOf(' ', MAX_BODY - 2);
+    return `${text.slice(0, cut > MAX_BODY / 2 ? cut : MAX_BODY - 2).trimEnd()}…`;
+}
+function bboxOfFeatures(features) {
+    let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
+    let seen = false;
+    const walk = (g) => {
+        if (!Array.isArray(g))
+            return;
+        if (g.length >= 2 && typeof g[0] === 'number' && typeof g[1] === 'number') {
+            if (Number.isFinite(g[0]) && Number.isFinite(g[1])) {
+                seen = true;
+                if (g[0] < w)
+                    w = g[0];
+                if (g[0] > e)
+                    e = g[0];
+                if (g[1] < s)
+                    s = g[1];
+                if (g[1] > n)
+                    n = g[1];
+            }
+            return;
+        }
+        for (const child of g)
+            walk(child);
+    };
+    for (const f of features) {
+        walk(f?.geometry?.coordinates);
+    }
+    if (!seen)
+        return null;
+    if (w === e) {
+        w -= 0.05;
+        e += 0.05;
+    }
+    if (s === n) {
+        s -= 0.05;
+        n += 0.05;
+    }
+    return [w, s, e, n];
+}
+/** Null when the run lacks the grounded material for BOTH steps. */
+export function buildAnalysisStory(input) {
+    const overviewBody = input.contextAnswer?.trim();
+    const memoBody = input.memo ? markdownToPlain(input.memo) : '';
+    if (!overviewBody || !memoBody)
+        return null;
+    const layers = Array.isArray(input.plan?.layers) ? input.plan.layers : [];
+    const resultLayer = input.resultLayerId
+        ? layers.find((l) => String(l?.id) === input.resultLayerId)
+        : undefined;
+    const bounds = resultLayer?.source?.kind === 'geojson' && Array.isArray(resultLayer.source.data?.features)
+        ? bboxOfFeatures(resultLayer.source.data.features)
+        : null;
+    return {
+        version: 1,
+        steps: [
+            {
+                title: input.plan?.title?.trim() || 'Overview',
+                body: clampBody(overviewBody),
+            },
+            {
+                title: resultLayer?.title?.trim() || 'Analysis',
+                body: clampBody(memoBody),
+                ...(bounds ? { camera: { bounds } } : {}),
+                ...(input.resultLayerId ? { visibleLayerIds: [input.resultLayerId] } : {}),
+            },
+        ],
+    };
+}

package/dist/toolMeta.js

@@ -78,6 +78,12 @@ export const MCP_TOOL_META = {
         long_running: false,
         rationale: 'Filters or derives a layer to a server-resolved named area; reversible via undo/clear_filters.',
     },
+    run_analysis: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Appends a computed analysis layer; original layer untouched; reversible via undo/remove_layer.',
+    },
     query_features: {
         requires_confirmation: false,
         destructive: false,

package/dist/tools.js

@@ -22,6 +22,7 @@ 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";
+import { buildAnalysisStory } from "./storyDraft.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
@@ -209,6 +210,10 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
         ...(extras.clarification ? { clarification: extras.clarification } : {}),
         ...(extras.opsApplied ? { opsApplied: extras.opsApplied } : {}),
         ...(extras.contextAnswer ? { contextAnswer: extras.contextAnswer } : {}),
+        ...(extras.resultLayerId ? { resultLayerId: extras.resultLayerId } : {}),
+        ...(extras.memo ? { memo: extras.memo } : {}),
+        ...(extras.stats ? { stats: extras.stats } : {}),
+        ...(extras.note ? { note: extras.note } : {}),
     };
 }
 function toContent(obj) {
@@ -260,7 +265,7 @@ const INVALID_INPUT_HINTS = {
     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.',
+    report_blocker: 'Required: what_i_was_trying, what_i_tried, where_i_got_stuck, rationale. Optional: map_id, suggested_capability.',
 };
 function buildInvalidInputResponse(toolName, error) {
     const issues = error.issues.map((iss) => ({
@@ -452,7 +457,7 @@ export function compactFeatureCollection(fc, viz) {
     }));
     return { type: fc.type ?? 'FeatureCollection', features };
 }
-async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query) {
+async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query, story) {
     if (!mapPlan || !Array.isArray(mapPlan.layers))
         return false;
     const geojsonLayers = {};
@@ -469,7 +474,7 @@ async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query) {
         id: mapId,
         title,
         query,
-        blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1 },
+        blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1, ...(story ? { story } : {}) },
         isPublic: true,
     };
     // Two attempts: the second exists for exactly the failure that lost a map
@@ -1025,6 +1030,126 @@ export function createServer(opts) {
             ...(shared ? {} : { shareUnpersisted: true }),
         }));
     }));
+    const runAnalysisShape = {
+        map_id: z.string().min(1),
+        analysis: z
+            .enum(['hotspot', 'zonal', 'enrich'])
+            .describe("Which analysis to run. 'hotspot' = Getis-Ord Gi* with FDR-corrected significance classes. 'zonal' = aggregate a point layer into polygon zones (count/sum/mean/min/max choropleth). 'enrich' = join a US Census indicator onto each feature by containment (tract/county/state)."),
+        layerId: z.string().min(1).describe('The workspace layer to analyze (geojson-backed; the point source for zonal).'),
+        valueField: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Numeric property to analyze. hotspot: omit on point layers for incident-DENSITY mode (hex-binned counts). zonal: omit for count-only aggregation.'),
+        k: z.number().int().min(3).max(24).optional().describe('hotspot only: nearest neighbors per feature (default 8).'),
+        hexMeters: z
+            .number()
+            .min(100)
+            .max(50_000)
+            .optional()
+            .describe('hotspot density mode only: hex cell spacing in meters (default auto from the data extent).'),
+        zoneLayerId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('zonal only: an existing polygon layer to aggregate into. Provide EXACTLY ONE of zoneLayerId or zones.'),
+        zones: z
+            .object({ kind: z.literal('h3'), resolution: z.number().int().min(3).max(10).optional() })
+            .strict()
+            .optional()
+            .describe('zonal only: generate an h3 hex fishnet over the source extent instead of using a zone layer (resolution 3-10, default auto). Provide EXACTLY ONE of zoneLayerId or zones.'),
+        stats: z
+            .array(z.enum(['count', 'sum', 'mean', 'min', 'max']))
+            .min(1)
+            .max(5)
+            .optional()
+            .describe('zonal only: which statistics to attach per zone (default: count, plus sum/mean/min/max when valueField is set).'),
+        indicator: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe("enrich only (required there): a US Census ACS preset id (e.g. 'median_household_income', 'median_home_value', 'median_rent') or a raw ACS variable code (e.g. 'B19013_001E')."),
+        geoLevel: z
+            .enum(['state', 'county', 'tract'])
+            .optional()
+            .describe('enrich only: containment geography (default tract). Tract/county fetch only the states the data touches, capped at 3 — filter first or use state for wider layers.'),
+        annotate: z
+            .boolean()
+            .optional()
+            .describe('Opt-in: place ONE callout annotation at the headline feature (hottest cluster / top zone / highest value). Label text comes only from computed values.'),
+        story: z
+            .boolean()
+            .optional()
+            .describe('Opt-in: persist the shared map with a 2-step story rail (grounded overview + analysis memo isolating the result layer) — the /m/ link opens with it.'),
+        rationale: rationaleSchema,
+    };
+    registerTool('run_analysis', {
+        title: 'Run a spatial analysis on a layer',
+        description: 'Compute a spatial analysis server-side and append the finished, honestly-legended result ' +
+            'as a new layer + camera; the result REPLACES its input layer(s) (undoable). hotspot = ' +
+            'Getis-Ord Gi*: hot/cold significance classes (99/95/90%, Benjamini-Hochberg FDR-corrected) ' +
+            'on a numeric field, or on hex-binned point density when valueField is omitted. zonal = ' +
+            'aggregate points into polygon zones (an existing zone layer OR a generated h3 fishnet): ' +
+            'count/sum/mean/min/max per zone as a quantile choropleth where zero and no-data are ' +
+            'distinct classes. enrich = join a US Census ACS indicator (median income, home value, ' +
+            'rent, …) onto each feature by tract/county/state containment — unmatched features stay ' +
+            'null, never zero-filled. Returns a grounded memo + stats payload — every number is computed, ' +
+            'never generated; findings keep the map. Costs 1 credit when the result lands; typed ' +
+            'failures (unknown layer, too few features, >10,000-feature cap) are refunded.',
+        inputSchema: runAnalysisShape,
+    }, withValidation('run_analysis', runAnalysisShape, async ({ map_id, analysis, layerId, valueField, k, hexMeters, zoneLayerId, zones, stats, indicator, geoLevel, annotate, story, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('run_analysis', map_id, rationale, { opKind: `run_analysis:${analysis}` });
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/run-analysis', {
+            workspace: entry.workspace,
+            analysis,
+            layerId,
+            ...(valueField !== undefined ? { valueField } : {}),
+            ...(k !== undefined ? { k } : {}),
+            ...(hexMeters !== undefined ? { hexMeters } : {}),
+            ...(zoneLayerId !== undefined ? { zoneLayerId } : {}),
+            ...(zones !== undefined ? { zones } : {}),
+            ...(stats !== undefined ? { stats } : {}),
+            ...(indicator !== undefined ? { indicator } : {}),
+            ...(geoLevel !== undefined ? { geoLevel } : {}),
+            ...(annotate !== undefined ? { annotate } : {}),
+            rationale,
+        }));
+        if (!resp.ok) {
+            throw new Error(`run_analysis 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 analyzedPlan = (resp.mapPlan ?? entry.mapPlan);
+        // Story knob (0.6.0): draft from the just-computed grounded material,
+        // BEFORE persist strips inline data (the bbox needs the features).
+        const storyDraft = story === true
+            ? buildAnalysisStory({
+                plan: analyzedPlan,
+                contextAnswer: resp.contextAnswer,
+                memo: resp.memo,
+                resultLayerId: resp.resultLayerId,
+            })
+            : null;
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, analyzedPlan, rationale, storyDraft);
+        return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), analyzedPlan, undefined, {
+            ...(resp.opsApplied ? { opsApplied: resp.opsApplied } : {}),
+            ...(resp.contextAnswer ? { contextAnswer: resp.contextAnswer } : {}),
+            ...(resp.resultLayerId ? { resultLayerId: resp.resultLayerId } : {}),
+            ...(resp.memo ? { memo: resp.memo } : {}),
+            ...(resp.stats ? { stats: resp.stats } : {}),
+            ...(resp.note ? { note: resp.note } : {}),
+            ...(shared ? {} : { shareUnpersisted: true }),
+        }));
+    }));
     const queryFeaturesShape = {
         map_id: z.string().min(1),
         layerId: z.string().min(1),
@@ -1562,6 +1687,7 @@ export function createServer(opts) {
             .max(300)
             .optional()
             .describe('Optional. A new tool, op, or schema field that would have unblocked you.'),
+        rationale: rationaleSchema,
     };
     registerTool('report_blocker', {
         title: 'Report a blocker (agent feedback)',
@@ -1573,11 +1699,11 @@ export function createServer(opts) {
             '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 }) => {
+    }, withValidation('report_blocker', reportBlockerShape, async ({ map_id, what_i_was_trying, what_i_tried, where_i_got_stuck, suggested_capability, rationale }) => {
         // 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' });
+        logRationale('report_blocker', map_id ?? null, `BLOCKER: ${what_i_was_trying} — stuck: ${where_i_got_stuck} (${rationale})`, { opKind: 'reportBlocker' });
         const resp = (await apiFetch(baseUrl, apiKey, '/api/agent/report-blocker', {
             ...(map_id ? { map_id } : {}),
             what_i_was_trying,
@@ -1592,6 +1718,7 @@ export function createServer(opts) {
         return toContent({
             ok: true,
             message: `Blocker recorded — thanks. Recorded at ${resp.recorded_at ?? new Date().toISOString()}.`,
+            ...(resp.sink ? { sink: resp.sink } : {}),
         });
     }));
     // ── JSON Schema draft normalization (2026-07-16) ─────────────────────────

package/dist/workspaceOpsSpec.md

@@ -50,7 +50,7 @@ Every op carries common fields:
 | Op kind              | args                                                                                                  |
 | -------------------- | ----------------------------------------------------------------------------------------------------- |
 | `createWorkspace`    | `{ originalQuery?, shell: MapPlanShell }` — emitted by the server, never by you.                      |
-| `addLayer`           | `{ layerPlan: LayerPlan, intent?: string }` — see LayerPlan below.                                    |
+| `addLayer`           | `{ layerPlan: LayerPlan, intent?: string }` — see LayerPlan below. For computed ANALYSIS layers (Gi* hot spots, zonal-statistics choropleths, census enrichment), prefer the `run_analysis` tool — the server computes, classes, and legends the result honestly and replaces the input layer(s), undoably. |
 | `filterLayer`        | `{ layerId, predicate: Predicate, append?: boolean, intent?: string }` — see Predicate.               |
 | `removeLayer`        | `{ layerId }` — strict; double-remove rejected. Layer ids tombstone for the session.                   |
 | `clearFilters`       | `{ layerId }` — wipe predicate chain. Inverse of filterLayer.                                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showmeonmap/mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "mcpName": "com.showmeonmap/maps",
   "description": "MCP server for ShowMeOnMap \u2014 geospatial visualization tools for any MCP-speaking agent (Claude Desktop, Cursor, Zed, ChatGPT Apps SDK)",
   "type": "module",