@showmeonmap/mcp 0.6.0 → 0.7.1

package/dist/nextActions.js

@@ -0,0 +1,340 @@
+/**
+ * build_map `next_actions` — state-aware, subject-aware follow-up hints.
+ *
+ * Until 2026-10-12 every build_map returned the same three constants
+ * ("Filter the layer to features where name is not empty", "Change the
+ * basemap to satellite", "Zoom the camera closer") whatever the map was. A
+ * live MCP test on three maps (M5+ earthquakes near Japan, California
+ * earthquakes, wildfires near Vancouver) showed all three were junk: every
+ * earthquake and fire detection HAS a name, the wildfire map was ALREADY on
+ * satellite, and the plan's own better follow-ups ("Smoke plume", "Air
+ * quality") never reached the caller. Agents learned to ignore the field.
+ *
+ * The rules this module enforces (pinned both directions in
+ * __tests__/tools/nextActions.test.ts):
+ *
+ *  - A filter hint names a field that exists on the layer AND varies across
+ *    its features, and its threshold/value comes from the features
+ *    themselves (a numeric threshold near the observed median, re-checked so
+ *    it keeps some features and drops some). Nothing is invented.
+ *  - Never suggest a state the map is already in (basemap already that
+ *    style, already zoomed close, already zoomed out).
+ *  - Surface the plan's own `followups` (handler + companion chips) — with
+ *    "this area" / "here" rewritten to the place in the caller's query,
+ *    because a fresh build_map has no "this area". When the place cannot be
+ *    read back out of the query, a region-neutral follow-up is dropped
+ *    rather than sent somewhere wrong.
+ *  - Nothing useful → `[]`. An empty list is a correct answer.
+ *
+ * Each hint is `{ label, argsTemplate, tool }`: `argsTemplate` is exactly
+ * the args (minus `map_id`) of `tool`, so it passes that tool's strict
+ * input validation as-is — `filter_layer` gets `{layerId, predicate}`,
+ * `mutate_map` gets `{instruction}`, `build_map` gets `{query}`.
+ */
+export const MAX_NEXT_ACTIONS = 3;
+const MAX_FILTER_HINTS = 2;
+const MAX_FOLLOWUP_HINTS = 2;
+// Measures worth thresholding when the layer itself does not name one
+// (valueField / filterConfig always qualify). Keys are normalized
+// (lower-case, alphanumerics only) so "Size (ha)" matches "sizeha".
+const KNOWN_MEASURES = [
+    'magnitude', 'mag', 'frp', 'brightness', 'sizeha', 'hectares', 'acres', 'areaha',
+    'containment', 'depth', 'significance', 'sig', 'population', 'pop',
+];
+// Measures where SMALLER is the notable end (shallow earthquakes do the damage).
+const LOWER_IS_NOTABLE = new Set(['depth']);
+// Categorical fields worth filtering, and the values that are the story when present.
+const KNOWN_CATEGORICAL = new Set([
+    'status', 'confidence', 'severity', 'alert', 'alertlevel', 'urgency', 'certainty', 'firestatus', 'stage',
+]);
+const SALIENT_VALUES = [
+    'out of control', 'active', 'high', 'h', 'extreme', 'severe', 'major', 'warning', 'emergency', 'red',
+];
+// Never a measure / filter dimension: coordinates (a coordinate column is
+// never a measure — CLAUDE.md), clocks, ids, links, free text.
+const EXCLUDED_FIELD = new RegExp('^(lat|latitude|lng|lon|long|longitude|x|y|easting|northing|' +
+    'time|timestamp|date|datetime|updated|hoursago|epoch|' +
+    'id|fid|objectid|gid|eventid|code|url|link|details|' +
+    'name|title|place|label|description|incident)$');
+function normKey(k) {
+    return k.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+function isInternalField(k) {
+    return k.startsWith('_');
+}
+function featuresOf(layer) {
+    const data = layer.source?.data;
+    if (!data || data.type !== 'FeatureCollection' || !Array.isArray(data.features))
+        return [];
+    return data.features.map((f) => (f && typeof f.properties === 'object' && f.properties ? f.properties : {}));
+}
+function layerName(layer) {
+    return (layer.title ?? layer.id ?? 'the layer').trim();
+}
+/** A threshold that reads cleanly AND still splits the observed values. */
+function niceThreshold(values, lowerIsNotable) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    const median = n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;
+    const allInt = sorted.every((v) => Number.isInteger(v));
+    const range = sorted[n - 1] - sorted[0];
+    const candidates = [];
+    if (allInt)
+        candidates.push(Math.round(median));
+    else if (range <= 20)
+        candidates.push(Math.round(median * 10) / 10);
+    else {
+        const mag = Math.pow(10, Math.floor(Math.log10(Math.abs(median) || 1)) - 1);
+        candidates.push(Math.round(median / mag) * mag);
+    }
+    candidates.push(median);
+    for (const raw of candidates) {
+        const t = Number(raw.toPrecision(6));
+        const kept = sorted.filter((v) => (lowerIsNotable ? v <= t : v >= t)).length;
+        if (kept > 0 && kept < n)
+            return { t, kept };
+    }
+    return null;
+}
+function collectFieldStats(props) {
+    const stats = new Map();
+    for (const p of props) {
+        for (const [k, v] of Object.entries(p)) {
+            if (v === null || v === undefined || v === '')
+                continue;
+            let s = stats.get(k);
+            if (!s) {
+                s = { key: k, numeric: [], strings: new Map() };
+                stats.set(k, s);
+            }
+            if (typeof v === 'number' && Number.isFinite(v))
+                s.numeric.push(v);
+            else if (typeof v === 'string')
+                s.strings.set(v, (s.strings.get(v) ?? 0) + 1);
+        }
+    }
+    return stats;
+}
+/** Data-derived filter_layer hints for one layer, best first. */
+function filterHintsForLayer(layer) {
+    const layerId = layer.id;
+    if (!layerId)
+        return [];
+    const props = featuresOf(layer);
+    const n = props.length;
+    if (n < 3)
+        return [];
+    const stats = collectFieldStats(props);
+    const name = layerName(layer);
+    const preferred = new Set();
+    if (layer.viz?.valueField)
+        preferred.add(layer.viz.valueField);
+    for (const fc of layer.filterConfig ?? [])
+        if (fc.field)
+            preferred.add(fc.field);
+    const eligible = (k) => !isInternalField(k) && !EXCLUDED_FIELD.test(normKey(k));
+    // ── numeric thresholds ────────────────────────────────────────────────
+    const numericFields = [...stats.values()]
+        .filter((s) => eligible(s.key))
+        .filter((s) => s.numeric.length >= Math.ceil(n * 0.8))
+        .filter((s) => new Set(s.numeric).size >= 3)
+        .filter((s) => preferred.has(s.key) || KNOWN_MEASURES.includes(normKey(s.key)))
+        .sort((a, b) => rank(a.key) - rank(b.key));
+    function rank(k) {
+        if (layer.viz?.valueField === k)
+            return -2;
+        if (preferred.has(k))
+            return -1;
+        return KNOWN_MEASURES.indexOf(normKey(k));
+    }
+    const preferredNumeric = [];
+    const otherNumeric = [];
+    const seenSignatures = new Set();
+    for (const s of numericFields) {
+        // A synthetic duplicate (e.g. `value` = magnitude for sizing) says nothing new.
+        const signature = s.numeric.join(',');
+        if (seenSignatures.has(signature))
+            continue;
+        seenSignatures.add(signature);
+        const lower = LOWER_IS_NOTABLE.has(normKey(s.key));
+        const th = niceThreshold(s.numeric, lower);
+        if (!th)
+            continue;
+        const op = lower ? 'lte' : 'gte';
+        const sym = lower ? '≤' : '≥';
+        (preferred.has(s.key) ? preferredNumeric : otherNumeric).push({
+            label: `Show only ${name} with ${s.key} ${sym} ${th.t} (${th.kept} of ${n} features)`,
+            argsTemplate: { layerId, predicate: { op, field: s.key, value: th.t } },
+            tool: 'filter_layer',
+        });
+    }
+    const categorical = [];
+    // ── categorical: a salient value that some, not all, features carry ──
+    for (const s of stats.values()) {
+        if (!eligible(s.key))
+            continue;
+        const isKnown = KNOWN_CATEGORICAL.has(normKey(s.key)) ||
+            (layer.filterConfig ?? []).some((fc) => fc.field === s.key && fc.kind === 'category');
+        if (!isKnown)
+            continue;
+        const totalStrings = [...s.strings.values()].reduce((a, b) => a + b, 0);
+        if (totalStrings < Math.ceil(n * 0.8) || s.strings.size < 2 || s.strings.size > 12)
+            continue;
+        const salient = SALIENT_VALUES
+            .map((sv) => [...s.strings.keys()].find((v) => v.trim().toLowerCase() === sv))
+            .find((v) => typeof v === 'string');
+        if (!salient)
+            continue;
+        const count = s.strings.get(salient) ?? 0;
+        if (count === 0 || count === totalStrings)
+            continue;
+        categorical.push({
+            label: `Show only ${name} where ${s.key} is "${salient}" (${count} of ${n} features)`,
+            argsTemplate: { layerId, predicate: { op: 'eq', field: s.key, value: salient } },
+            tool: 'filter_layer',
+        });
+        break;
+    }
+    // The layer's own encoded measure, then the story value of a status-like
+    // field, then other known measures.
+    return [...preferredNumeric, ...categorical, ...otherNumeric];
+}
+// ── plan follow-ups ────────────────────────────────────────────────────────
+const TIME_WINDOW_TAIL_RE = /(?:^|\s+)(?:(?:in|over|during|for|within|from|since)\s+)?(?:the\s+)?(?:(?:this|last|past|next|recent|previous|current|coming)\s+|\d+\s+)(?:\d+\s+)?(?:hour|hours|day|days|week|weeks|month|months|year|years|decade|decades)(?:\s+ago)?$/i;
+const SIMPLE_TIME_TAIL_RE = /\s+(?:(?:in|during|since|for)\s+)?(?:today|tonight|now|right now|recently|yesterday|(?:19|20)\d{2})$/i;
+const PRESENTATION_TAIL_RE = /,\s*(?:sized|colou?red|shown|styled|drawn|rendered|displayed|with|using|as|on)\b.*$/i;
+const LOCATION_PREP_RE = /\b(?:in|near|around|across|over|at|within)\s+/gi;
+const BAD_PLACE_START = /^(?:the\s+)?(?:past|last|this|next|recent|previous|current|coming|today|tonight|least|most)\b/i;
+/**
+ * The place a build_map query names, or null. Conservative on purpose: a
+ * wrong place is worse than no follow-up, so anything doubtful returns null.
+ *   "earthquakes above magnitude 5 near Japan this month" → "Japan"
+ *   "earthquakes in California in the past year"         → "California"
+ *   "active wildfires near Vancouver, British Columbia"   → "Vancouver, British Columbia"
+ */
+export function placeFromQuery(query) {
+    const q = (query ?? '').trim().replace(/[.?!]+$/, '');
+    for (const m of q.matchAll(LOCATION_PREP_RE)) {
+        let place = q.slice((m.index ?? 0) + m[0].length);
+        place = place.replace(PRESENTATION_TAIL_RE, '');
+        for (let i = 0; i < 3; i++) {
+            const before = place;
+            place = place.replace(TIME_WINDOW_TAIL_RE, '').replace(SIMPLE_TIME_TAIL_RE, '').trim();
+            if (place === before)
+                break;
+        }
+        if (!place || place.length > 60 || /\d/.test(place) || BAD_PLACE_START.test(place))
+            continue;
+        return place;
+    }
+    return null;
+}
+// Phrases that only mean something next to the map the user is looking at.
+const CONTEXT_PHRASE_RE = /\b(?:this area|this region|the area|here|nearby|on screen|current view|neighbou?ring)\b/i;
+function localizeMessage(message, place) {
+    if (!CONTEXT_PHRASE_RE.test(message))
+        return message;
+    if (!place)
+        return null;
+    const out = message
+        .replace(/\b(?:this area|this region|the area)\b/gi, place)
+        .replace(/\bhere\b/gi, `near ${place}`);
+    // "nearby" / "on screen" / "neighbouring" have no faithful rewrite — drop.
+    return CONTEXT_PHRASE_RE.test(out) ? null : out;
+}
+const MUTATION_RE = /^(?:filter|only show|show only|zoom|switch|change|set|remove|hide|colou?r|restyle|clear)\b/i;
+const BASEMAP_STYLES = ['satellite', 'dark', 'light', 'streets', 'engineering'];
+/** True when the hint would put the map into a state it is already in. */
+export function isRedundantWithState(text, plan) {
+    const t = text.toLowerCase();
+    const current = plan.basemap?.style?.toLowerCase();
+    const aboutBasemap = /\b(?:basemap|base map|map style|satellite (?:view|imagery|basemap|map))\b/.test(t) ||
+        /\b(?:switch|change|set)\s+(?:the\s+)?(?:map\s+)?to\s+(?:satellite|dark|light|streets|engineering)\b/.test(t);
+    if (current && aboutBasemap) {
+        const target = BASEMAP_STYLES.find((s) => new RegExp(`\\b${s}\\b`).test(t));
+        if (target && target === current)
+            return true;
+    }
+    const cam = plan.camera;
+    if (cam && /\bzoom\b/.test(t)) {
+        const zoom = typeof cam.zoom === 'number' ? cam.zoom : undefined;
+        const span = cam.mode === 'fitBounds' && Array.isArray(cam.bounds)
+            ? Math.max(Math.abs(cam.bounds[2] - cam.bounds[0]), Math.abs(cam.bounds[3] - cam.bounds[1]))
+            : undefined;
+        const close = (zoom !== undefined && zoom >= 12) || (span !== undefined && span <= 0.1);
+        const far = cam.mode === 'globalView' || (zoom !== undefined && zoom <= 2) || (span !== undefined && span >= 300);
+        if (/\bzoom\b(?:\s+\w+){0,3}?\s+(?:in|closer)\b/.test(t) && close)
+            return true;
+        if (/\bzoom\b(?:\s+\w+){0,3}?\s+out\b/.test(t) && far)
+            return true;
+    }
+    return false;
+}
+function followupHints(plan, query) {
+    const followups = Array.isArray(plan.followups) ? plan.followups : [];
+    if (!followups.length)
+        return [];
+    const place = placeFromQuery(query);
+    const hints = [];
+    const seen = new Set();
+    for (const f of followups) {
+        const message = typeof f?.message === 'string' ? f.message.trim() : '';
+        const label = typeof f?.label === 'string' && f.label.trim() ? f.label.trim() : message;
+        if (!message)
+            continue;
+        if (isRedundantWithState(`${label} ${message}`, plan))
+            continue;
+        if (MUTATION_RE.test(message)) {
+            if (seen.has(message.toLowerCase()))
+                continue;
+            seen.add(message.toLowerCase());
+            hints.push({ label, argsTemplate: { instruction: message }, tool: 'mutate_map' });
+            continue;
+        }
+        const localized = localizeMessage(message, place);
+        if (!localized || seen.has(localized.toLowerCase()))
+            continue;
+        seen.add(localized.toLowerCase());
+        hints.push({ label: `${label} — new map: "${localized}"`, argsTemplate: { query: localized }, tool: 'build_map' });
+    }
+    return hints;
+}
+/**
+ * next_actions for a freshly built map. `plan` must be the full-resolution
+ * MapPlan the API returned (features inline), `query` the build_map query.
+ */
+export function buildMapNextActions(plan, query) {
+    if (!plan)
+        return [];
+    const layers = (Array.isArray(plan.layers) ? plan.layers : []);
+    const subjectLayers = layers
+        .filter((l) => l && l.role !== 'context' && !l.hideFromLegend && !l.hiddenByDefault)
+        .map((l) => ({ layer: l, count: featuresOf(l).length }))
+        .filter((x) => x.count >= 3)
+        .sort((a, b) => b.count - a.count);
+    // Best hint from each of the busiest layers first (diversity), then a
+    // second hint from the busiest layer if room remains.
+    const perLayer = subjectLayers.map((x) => filterHintsForLayer(x.layer));
+    const filters = [];
+    for (const hs of perLayer)
+        if (hs[0] && filters.length < MAX_FILTER_HINTS)
+            filters.push(hs[0]);
+    for (const hs of perLayer) {
+        for (const h of hs.slice(1))
+            if (filters.length < MAX_FILTER_HINTS)
+                filters.push(h);
+    }
+    const follow = followupHints(plan, query).slice(0, MAX_FOLLOWUP_HINTS);
+    // Best data filter, then the plan's own follow-ups, then the rest — so a
+    // map that has both surfaces both.
+    const out = [...filters.slice(0, 1), ...follow, ...filters.slice(1)];
+    return out.filter((h) => !isRedundantWithState(h.label, plan)).slice(0, MAX_NEXT_ACTIONS);
+}
+/** mutate_map's server-suggested strings → mutate_map hints. */
+export function instructionHints(strings) {
+    return (strings ?? []).slice(0, MAX_NEXT_ACTIONS).map((label) => ({
+        label,
+        argsTemplate: { instruction: label },
+        tool: 'mutate_map',
+    }));
+}

package/dist/serverInstructions.js

@@ -0,0 +1,34 @@
+/**
+ * What Claude reads about ShowMeOnMap before choosing a tool.
+ *
+ * Real-host test (2026-10-06): asked "Show me earthquakes above magnitude 5
+ * near Japan this month" with ShowMeOnMap connected, Claude answered with its
+ * built-in place map and a web read of USGS — our tools were picked only when
+ * the user named the connector. The only signals it had were a build_map
+ * description that said "Create a new workspace from a natural-language
+ * query" and no server instructions at all: nothing about WHAT maps we make.
+ *
+ * Rules for this text and every tool description:
+ *   - Describe capability and data provenance accurately. Never tell the model
+ *     to prefer this server over other tools or to avoid them — the Claude
+ *     directory reviews descriptions for prompt injection, and the submission
+ *     pack commits that descriptions only state what each tool does
+ *     (`docs/launch/claude-directory-submission.md` §9). Pinned by
+ *     `__tests__/tools/serverInstructions.test.ts`.
+ *   - Claims must match what the pipeline does; no data source named here
+ *     that the server does not fetch.
+ */
+export const BUILD_MAP_DESCRIPTION = 'Make an interactive, data-driven map from a plain-language request, built from live public data with every value cited to its source. ' +
+    'Covers natural hazards (earthquakes, wildfires, volcanoes, tropical storms, floods), weather and air quality, ' +
+    'statistics by country, state or region (GDP, population, health, emissions — World Bank, Eurostat, US Census), ' +
+    'infrastructure and transit (railways, power plants, transit lines, roads), parks and terrain, and points of interest from OpenStreetMap. ' +
+    'The query carries the place, time window and any thresholds — "earthquakes above magnitude 5 near Japan this month", "GDP per capita across Europe" — and the server applies them itself. ' +
+    'Returns a shareable link and a map_id for follow-ups (mutate_map, filter_layer, get_state); in clients that support MCP Apps the map also renders interactively in the conversation. ' +
+    'The Op catalog and predicate grammar that downstream tools (mutate_map, filter_layer, etc.) accept are documented in the MCP resource showmeonmap://docs/workspace-ops-spec.';
+export const SERVER_INSTRUCTIONS = [
+    'ShowMeOnMap makes cartographic, data-driven maps. It fetches live public data (USGS, NASA FIRMS, NOAA, World Bank, Eurostat, US Census, OpenStreetMap and more), styles it with a legend, and cites every source on the map.',
+    'It suits requests where the answer is data on a map: natural hazards, statistics compared across regions, infrastructure and transit networks, environmental conditions, and spatial analysis (hot spots, zonal statistics, nearest neighbour, Census enrichment). It also keeps one map across several turns, so a map can be filtered, restyled or extended.',
+    'It is not a turn-by-turn directions service or a business-reviews directory.',
+    'Usage: call build_map once with the whole request, including place, time window and thresholds; it applies them itself, so a follow-up filter or camera call is only needed when the user asks for a change. Values that a source cannot supply are shown as unavailable, never estimated.',
+    'Building or changing a map spends the user\'s prepaid ShowMeOnMap credits; reading state and exporting are free.',
+].join('\n\n');

package/dist/sessionStoreD1.js

@@ -30,9 +30,16 @@
  * `maxSize` (default 1000) we delete the oldest rows by `last_seen_at`.
  * `toDrop = max(overflow, evictionBatch)` so a single sweep amortizes
  * to clear at least `evictionBatch` (default 50) rows when triggered,
- * avoiding running an eviction on every subsequent put. The cleanup
- * uses fire-and-forget semantics — a failed eviction never blocks
- * the put. The next put will retry.
+ * avoiding running an eviction on every subsequent put. The sweep runs
+ * in the background — the put does not wait for it, and a failed eviction
+ * never blocks or fails the put. The next put will retry.
+ *
+ * On Cloudflare Workers, un-registered background work is CANCELLED when the
+ * response returns, so a hosted caller must pass `waitUntil` (see the option)
+ * or the sweep — and the get-touch — may never finish. The COUNT(*) that
+ * gates each sweep is deliberately left on every put: it walks the
+ * last_seen_at index (≤ ~maxSize rows read), off the response path once
+ * registered, which is not worth a sampling scheme to shave.
  *
  * Independence
  * ------------
@@ -95,6 +102,19 @@ export function createD1SessionStore(d1, opts = {}) {
     const evictionBatch = opts.evictionBatch ?? 50;
     const onEvict = opts.onEvict;
     const ownerId = opts.ownerId ?? null;
+    const waitUntil = opts.waitUntil;
+    /** Run `work` in the background, registered with the runtime when we can be. */
+    function background(work) {
+        if (!waitUntil)
+            return;
+        try {
+            waitUntil(work);
+        }
+        catch {
+            // Runtime refused the registration (context already closed). The work
+            // is already running; it may or may not finish. Never fail the caller.
+        }
+    }
     // Tenancy predicate appended to every single-row accessor. When an owner is
     // set, a row matches only if its user_id equals that owner — which NULL
     // never does, so migration 0018's un-backfilled legacy rows fail CLOSED
@@ -105,7 +125,7 @@ export function createD1SessionStore(d1, opts = {}) {
     const scopeArgs = ownerId ? [ownerId] : [];
     /**
      * LRU sweep — best-effort. Counts rows, drops the oldest by last_seen_at
-     * if over capacity. Fire-and-forget: callers don't await this.
+     * if over capacity. Never rejects; callers hand it to background().
      */
     async function maybeEvict() {
         try {
@@ -161,12 +181,12 @@ export function createD1SessionStore(d1, opts = {}) {
                 return null;
             const entry = rowToEntry(row);
             // Touch last_seen_at so the LRU treats this as recently accessed.
-            // Fire-and-forget: a failed touch shouldn't break the read.
+            // Background: a failed touch shouldn't break or slow the read.
             const now = Date.now();
-            d1.prepare(`UPDATE mcp_sessions SET last_seen_at = ? WHERE id = ?${scope}`)
+            background(d1.prepare(`UPDATE mcp_sessions SET last_seen_at = ? WHERE id = ?${scope}`)
                 .bind(now, mapId, ...scopeArgs)
                 .run()
-                .catch(() => undefined);
+                .catch(() => undefined));
             entry.lastAccessed = now;
             return entry;
         },
@@ -200,7 +220,7 @@ export function createD1SessionStore(d1, opts = {}) {
             }
             // Best-effort LRU sweep. Don't await — a slow eviction must not block
             // the write that triggered it. Failures are absorbed inside maybeEvict.
-            void maybeEvict();
+            background(maybeEvict());
         },
         async delete(mapId) {
             // Owner-scoped, so a non-owner's delete silently affects zero rows