@showmeonmap/mcp 0.5.0 → 0.6.0

package/README.md

@@ -100,7 +100,7 @@ Ask Claude Desktop things like:
 
 `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) 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.
+`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/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
@@ -456,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 = {};
@@ -473,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
@@ -1073,6 +1074,14 @@ export function createServer(opts) {
             .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', {
@@ -1089,7 +1098,7 @@ export function createServer(opts) {
             '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, rationale }) => {
+    }, 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.`);
@@ -1106,6 +1115,7 @@ export function createServer(opts) {
             ...(stats !== undefined ? { stats } : {}),
             ...(indicator !== undefined ? { indicator } : {}),
             ...(geoLevel !== undefined ? { geoLevel } : {}),
+            ...(annotate !== undefined ? { annotate } : {}),
             rationale,
         }));
         if (!resp.ok) {
@@ -1119,7 +1129,17 @@ export function createServer(opts) {
             lastAccessed: Date.now(),
         });
         const analyzedPlan = (resp.mapPlan ?? entry.mapPlan);
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, analyzedPlan, rationale);
+        // 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 } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showmeonmap/mcp",
-  "version": "0.5.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",