@showmeonmap/mcp 0.4.0 → 0.5.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) 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.
 
 Every tool returns a **three-channel envelope**:
 

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

@@ -209,6 +209,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 +264,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) => ({
@@ -1025,6 +1029,107 @@ 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.'),
+        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, 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 } : {}),
+            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);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, analyzedPlan, rationale);
+        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 +1667,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 +1679,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 +1698,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.5.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",