@showmeonmap/mcp 0.3.2 → 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

@@ -72,6 +72,18 @@ export const MCP_TOOL_META = {
         long_running: false,
         rationale: 'Adds a new derived layer; original layer untouched.',
     },
+    focus_area: {
+        requires_confirmation: false,
+        destructive: false,
+        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

@@ -207,6 +207,12 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
         })),
         ...(extras.outOfScope ? { outOfScope: extras.outOfScope } : {}),
         ...(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) {
@@ -240,6 +246,7 @@ const INVALID_INPUT_HINTS = {
     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.',
+    focus_area: 'Required: map_id, layerId, areaRef ({kind:"corridor", street, from?, to?} | {kind:"place", name} | {kind:"aroundIntersection", street, cross}), rationale. Optional: mode (filter|select|clip). Pass NAMES — the server resolves geometry from OSM.',
     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).',
@@ -257,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) => ({
@@ -500,7 +507,7 @@ const READ_ONLY_TOOLS = new Set([
 ]);
 // Tools that reach external/open-world data sources, vs operating purely on
 // already-loaded workspace state.
-const OPEN_WORLD_TOOLS = new Set(['build_map', 'mutate_map', 'add_layer', 'add_fusion_layer']);
+const OPEN_WORLD_TOOLS = new Set(['build_map', 'mutate_map', 'add_layer', 'add_fusion_layer', 'focus_area']);
 // Mutating-but-idempotent setters: re-applying the same call converges to the
 // same state (unlike append-style build_map / add_annotation / tag / undo).
 const IDEMPOTENT_SETTERS = new Set([
@@ -958,6 +965,171 @@ export function createServer(opts) {
         };
         return toContent(await applyOp(map_id, op));
     }));
+    const focusAreaAreaRefShape = z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('place'), name: z.string().min(1) }),
+        z.object({
+            kind: z.literal('corridor'),
+            street: z.string().min(1),
+            from: z.string().min(1).optional(),
+            to: z.string().min(1).optional(),
+            bufferMeters: z.number().min(30).max(1000).optional(),
+        }),
+        z.object({
+            kind: z.literal('aroundIntersection'),
+            street: z.string().min(1),
+            cross: z.string().min(1),
+            radiusMeters: z.number().min(50).max(5000).optional(),
+        }),
+    ]);
+    const focusAreaShape = {
+        map_id: z.string().min(1),
+        layerId: z.string().min(1),
+        areaRef: focusAreaAreaRefShape,
+        mode: z
+            .enum(['filter', 'select', 'clip'])
+            .optional()
+            .describe('filter (default): hide features outside, reversible. select: copy matches into a new layer. clip: new layer with geometry trimmed at the boundary.'),
+        rationale: rationaleSchema,
+    };
+    registerTool('focus_area', {
+        title: 'Focus a layer on a named area',
+        description: 'Refine an existing layer to a NAMED area the server resolves from OpenStreetMap — a street corridor ("Broadway from Arbutus Street to Main Street"), a place ("Mount Pleasant"), or an intersection surroundings. Pass names only, never coordinates; unresolvable names return a clarification with real nearby candidates instead of guessed geometry. Emits ordinary undoable ops (filter / new layer + camera) and a grounded summary like "kept 37 of 150 features". Costs 1 credit when a mutation lands; clarifications are refunded.',
+        inputSchema: focusAreaShape,
+    }, withValidation('focus_area', focusAreaShape, async ({ map_id, layerId, areaRef, mode, rationale }) => {
+        const entry = await store.get(map_id);
+        if (!entry)
+            throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
+        logRationale('focus_area', map_id, rationale, { opKind: `focus_area:${areaRef.kind ?? 'unknown'}:${mode ?? 'filter'}` });
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/focus-area', {
+            workspace: entry.workspace,
+            layerId,
+            areaRef,
+            ...(mode ? { mode } : {}),
+            rationale,
+        }));
+        if (!resp.ok) {
+            throw new Error(`focus_area failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+        }
+        // Honest resolver failure: nothing changed; surface the clarification.
+        if (resp.mutated === false) {
+            return toContent(envelope(baseUrl, map_id, entry.workspace, entry.mapPlan, undefined, { ...(resp.clarification ? { clarification: resp.clarification } : {}) }));
+        }
+        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 focusedPlan = (resp.mapPlan ?? entry.mapPlan);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, focusedPlan, rationale);
+        return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), focusedPlan, undefined, {
+            ...(resp.opsApplied ? { opsApplied: resp.opsApplied } : {}),
+            ...(resp.contextAnswer ? { contextAnswer: resp.contextAnswer } : {}),
+            ...(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),
@@ -1495,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)',
@@ -1506,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,
@@ -1525,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,13 +50,14 @@ 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.                                          |
 | `renameLayer`        | `{ oldLayerId, newLayerId }` — re-keys filters. newLayerId must be unique (incl. tombstones).         |
 | `restyleLayer`       | `{ layerId, color?: string, opacity?: number }` — within-palette style change.                         |
 | `subsetToSelection`  | `{ sourceLayerId, newLayerId, selection: GeoJSONPolygon, inheritStyle?: boolean }`                    |
+| `clipLayer`          | `{ sourceLayerId, newLayerId, clip: GeoJSONPolygon, inheritStyle?: boolean }` — new layer with geometry TRIMMED at the clip boundary (crossing lines keep only their inside span; polygons intersected; outside features dropped). Requires an inline-geojson source. Prefer the `focus_area` tool for NAMED areas — it resolves streets/places server-side so you never hand-build the polygon. |
 | `setCamera`          | `{ camera: CameraPlan }` — latest setCamera op wins on replay.                                          |
 | `setBasemap`         | `{ basemap: 'light'\|'dark'\|'streets'\|'satellite'\|'engineering' }`                                 |
 | `setTime`            | `{ field, rangeStart, rangeEnd, format?: 'unix_ms'\|'iso'\|'integer' }`                                |
@@ -92,8 +93,9 @@ exceeds the GPU's expressiveness (e.g. spatial `within`).
 ### Spatial predicates
 
 ```ts
-{ op: 'within', geometry: { type: 'Polygon', coordinates: [[ [lng,lat], ... ]] } }
+{ op: 'within', geometry: { type: 'Polygon', coordinates: [[ [lng,lat], ... ]] } }   // feature ENTIRELY inside
 { op: 'intersects', layerId: 'country_borders' }                  // intersect with another layer's geometry
+{ op: 'intersects', geometry: { type: 'Polygon', coordinates: [[ ... ]] } }          // intersect an inline polygon — keeps features crossing the boundary (e.g. a street-corridor focus); pass EXACTLY ONE of layerId | geometry
 { op: 'withinDistance', center: [lng, lat], meters: 5000 }
 { op: 'bbox', box: [west, south, east, north] }
 ```

package/package.json

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