@showmeonmap/mcp 0.6.0 → 0.7.0

package/README.md

@@ -37,6 +37,8 @@ The server speaks standard MCP/stdio; it's a thin proxy to the ShowMeOnMap HTTP
 }
 ```
 
+**In Claude, no key at all:** add `https://showmeonmap.com/api/mcp` as a custom connector (Claude Code: `claude mcp add --transport http showmeonmap https://showmeonmap.com/api/mcp`, then `/mcp`). Claude signs you in with OAuth the first time it needs a map and bills your credits the same way; disconnect from the account menu → API keys → Connected apps.
+
 The hosted endpoint speaks streamable HTTP (stateless), is rate-limited to 30 requests/min per key, and works anywhere remote MCP servers do — Claude custom connectors, the OpenAI Responses API (`server_url`), Gemini managed agents (`mcp_server`), Cursor, Copilot Studio, Bedrock.
 
 ---
@@ -90,13 +92,16 @@ Ask Claude Desktop things like:
 
 ---
 
-## Tool surface (26 tools)
+## Tool surface (29 tools)
 
 **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`.
+**Saved workflows (3)**: `save_workflow`, `list_workflows`, `run_workflow`.
+
+**0.7.0** (everything merged since 0.6.0): the three workflow tools (with `batch` runs over a value list); `run_analysis` adds spatial join, merge/append, near and dissolve; `rationale` is optional on every tool; no tuple schemas (Claude dropped `set_camera` / `add_annotation`); fact-only tool descriptions; `export_layer_data` works on a saved map; share links store the features the map shows after `filter_layer` and its counts follow the filter; the server reports its real version; and an npm install no longer writes rationale logs into your `node_modules`.
 
 `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.
 
@@ -162,7 +167,7 @@ Spawns a fresh server process, exercises `initialize` → `tools/list` → every
 - **In-memory session cache.** `map_id` → workspace mapping lives in the server process; restarts lose state. Phase I-3 (in the parent repo's plan) wires D1 persistence so `shareable_url` actually resolves across sessions.
 - **No preview PNG.** The envelope's `shareable_url` points at the app's `/m/<id>` viewer, but workspaces aren't yet persisted in the gallery. Until I-3, share the raw structured response.
 - **stdio bin + hosted remote endpoint.** This package's bin is stdio; remote hosts use `https://showmeonmap.com/api/mcp` (streamable HTTP, stateless). The standalone Node HTTP entry (`packages/mcp-server/src/http.ts`) remains for self-hosting a checkout.
-- **Auth is per-user API keys** (`smo_live_…`, minted at showmeonmap.com). The key travels as a bearer on every backend call and bills the key's owner.
+- **Auth is a per-user bearer**: an API key (`smo_live_…`, minted at showmeonmap.com) or, on the hosted endpoint, an OAuth access token from Claude's sign-in. Either travels as a bearer on every backend call and bills its owner.
 
 ---
 

package/dist/fetchNoRedirect.js

@@ -0,0 +1,16 @@
+/**
+ * fetch() that refuses to follow redirects — portable to Cloudflare Workers,
+ * where this package also runs (the hosted /api/mcp route). The Workers
+ * runtime rejects `redirect: 'error'` outright, so every self-POST threw in
+ * production (build_map broken after #949, fixed 2026-09-28). Uses
+ * `redirect: 'manual'` and refuses any 3xx instead. Mirrors
+ * src/lib/http/fetchNoRedirect.ts (this package cannot import from the app).
+ */
+export async function fetchNoRedirect(input, init = {}) {
+    const response = await fetch(input, { ...init, redirect: 'manual' });
+    if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) {
+        void response.body?.cancel().catch(() => { });
+        throw new Error(`Refused to follow a redirect (HTTP ${response.status}) from ${new URL(input).pathname}`);
+    }
+    return response;
+}

package/dist/generalizeGeometry.js

@@ -0,0 +1,232 @@
+/**
+ * Generalize oversize line/polygon layers before a map enters the MCP session
+ * store. Design: docs/superpowers/specs/2026-10-06-mcp-geometry-generalization-design.md
+ *
+ * The global choropleth handlers inline 10m world-atlas geometry — EU-27 is
+ * 1.8 MB, the world 21 MB — and the hosted store keeps the whole workspace in
+ * ONE `mcp_sessions.workspace` cell, which D1 caps at 2 MB. "Map GDP per
+ * capita across Europe" therefore failed with SQLITE_TOOBIG in the first
+ * real-host Claude test (2026-10-06), and the EU-27 retry that did fit was
+ * over the card's ~850 KB budget ("too large to show here").
+ *
+ * Rules (pinned by __tests__/tools/generalizeGeometry.test.ts):
+ *   - only a layer whose serialized data exceeds LAYER_BUDGET (600 KB) is touched;
+ *   - points are never altered;
+ *   - no feature is dropped and no property value changes — only geometry;
+ *   - every ring keeps ≥ 4 points and stays closed;
+ *   - within a feature, parts/holes smaller than 3 × tolerance are dropped,
+ *     never the feature's largest part;
+ *   - the first rung of the ladder that fits wins (least simplification);
+ *   - a generalized layer says so: `_smo_generalized` on its data and a
+ *     legend subtitle suffix.
+ * Dependency-free: this package ships to npm with only the SDK and zod.
+ */
+/** Per-layer target. The card takes ~850 KB of layers per response (deferred
+ * layers load separately), and the world 10m choropleth fits at 0.1° (557 KB);
+ * 500 KB pushed it to 0.2° (≈ 22 km), visibly coarse. */
+export const LAYER_BUDGET = 600_000;
+export const WORKSPACE_CEILING = 1_800_000;
+/** Douglas–Peucker tolerances in degrees, tried after quantize-only (0). */
+export const TOLERANCES = [0, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2];
+export const SIMPLIFIED_NOTE = 'boundaries simplified for this view';
+function round4(n) {
+    return Math.round(n * 1e4) / 1e4;
+}
+/** Iterative Douglas–Peucker on an open or closed polyline. */
+function douglasPeucker(pts, tol) {
+    if (pts.length <= 2 || tol <= 0)
+        return pts;
+    const keep = new Uint8Array(pts.length);
+    keep[0] = 1;
+    keep[pts.length - 1] = 1;
+    const t2 = tol * tol;
+    const stack = [[0, pts.length - 1]];
+    while (stack.length) {
+        const [a, b] = stack.pop();
+        const [x1, y1] = pts[a];
+        const [x2, y2] = pts[b];
+        const dx = x2 - x1;
+        const dy = y2 - y1;
+        const len2 = dx * dx + dy * dy;
+        let maxD = 0;
+        let maxI = -1;
+        for (let i = a + 1; i < b; i++) {
+            const [x, y] = pts[i];
+            let t = len2 ? ((x - x1) * dx + (y - y1) * dy) / len2 : 0;
+            t = t < 0 ? 0 : t > 1 ? 1 : t;
+            const ex = x - x1 - t * dx;
+            const ey = y - y1 - t * dy;
+            const d = ex * ex + ey * ey;
+            if (d > maxD) {
+                maxD = d;
+                maxI = i;
+            }
+        }
+        if (maxD > t2 && maxI > 0) {
+            keep[maxI] = 1;
+            stack.push([a, maxI], [maxI, b]);
+        }
+    }
+    const out = [];
+    for (let i = 0; i < pts.length; i++)
+        if (keep[i])
+            out.push(pts[i]);
+    return out;
+}
+function extent(ring) {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of ring) {
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+    }
+    return Math.hypot(maxX - minX, maxY - minY);
+}
+function quantize(pts) {
+    const out = [];
+    for (const p of pts) {
+        const q = [round4(p[0]), round4(p[1]), ...p.slice(2)];
+        const prev = out[out.length - 1];
+        if (prev && prev[0] === q[0] && prev[1] === q[1])
+            continue;
+        out.push(q);
+    }
+    return out;
+}
+/** A closed ring with ≥ 4 points — falls back to a minimal closed ring from the original. */
+function simplifyRing(ring, tol) {
+    let s = douglasPeucker(quantize(ring), tol);
+    if (s.length && (s[0][0] !== s[s.length - 1][0] || s[0][1] !== s[s.length - 1][1]))
+        s = [...s, s[0]];
+    if (s.length >= 4)
+        return s;
+    if (ring.length < 4)
+        return ring;
+    const n = ring.length;
+    return [ring[0], ring[Math.floor(n / 3)], ring[Math.floor((2 * n) / 3)], ring[0]];
+}
+function simplifyPolygon(rings, tol, dropBelow) {
+    return rings
+        .filter((r, i) => i === 0 || dropBelow <= 0 || extent(r) >= dropBelow)
+        .map((r) => simplifyRing(r, tol));
+}
+function simplifyLine(line, tol) {
+    const s = douglasPeucker(quantize(line), tol);
+    return s.length >= 2 ? s : line;
+}
+function simplifyGeometry(g, tol) {
+    const dropBelow = 3 * tol;
+    const c = g.coordinates;
+    switch (g.type) {
+        case 'Polygon':
+            return { ...g, coordinates: simplifyPolygon(c, tol, dropBelow) };
+        case 'MultiPolygon': {
+            const polys = c;
+            const sizes = polys.map((p) => (p[0] ? extent(p[0]) : 0));
+            const largest = sizes.indexOf(Math.max(...sizes));
+            const kept = polys.filter((_, i) => i === largest || dropBelow <= 0 || sizes[i] >= dropBelow);
+            return { ...g, coordinates: kept.map((p) => simplifyPolygon(p, tol, dropBelow)) };
+        }
+        case 'LineString':
+            return { ...g, coordinates: simplifyLine(c, tol) };
+        case 'MultiLineString':
+            return { ...g, coordinates: c.map((l) => simplifyLine(l, tol)) };
+        default:
+            return g; // points and anything else are never altered
+    }
+}
+function hasShapeGeometry(fc) {
+    return fc.features.some((f) => /Polygon|LineString/.test(f.geometry?.type ?? ''));
+}
+function size(v) {
+    return JSON.stringify(v).length;
+}
+/**
+ * The least-simplified version of `fc` that fits `budget`, or null when it
+ * already fits / has no line or polygon geometry. Returns the last rung when
+ * nothing fits — the caller's ceiling check decides what happens then.
+ */
+export function generalizeCollection(fc, budget = LAYER_BUDGET, ladder = TOLERANCES) {
+    if (fc._smo_generalized || size(fc) <= budget || !hasShapeGeometry(fc))
+        return null;
+    let last = fc;
+    let lastTol = 0;
+    for (const tol of ladder) {
+        last = {
+            ...fc,
+            features: fc.features.map((f) => (f.geometry ? { ...f, geometry: simplifyGeometry(f.geometry, tol) } : f)),
+        };
+        lastTol = tol;
+        if (size(last) <= budget)
+            break;
+    }
+    return { data: { ...last, _smo_generalized: { toleranceDeg: lastTol } }, toleranceDeg: lastTol };
+}
+function isInlineCollection(layer) {
+    const d = layer.source?.data;
+    return !!d && d.type === 'FeatureCollection' && Array.isArray(d.features);
+}
+function withNote(subtitle) {
+    return typeof subtitle === 'string' && subtitle.trim()
+        ? `${subtitle} · ${SIMPLIFIED_NOTE}`
+        : SIMPLIFIED_NOTE.charAt(0).toUpperCase() + SIMPLIFIED_NOTE.slice(1);
+}
+/**
+ * Walk `root` (a workspace or a mapPlan) and generalize every oversize inline
+ * layer. Copy-on-write: unchanged branches are shared, `root` is never mutated.
+ */
+export function generalizeLayers(root, budget = LAYER_BUDGET) {
+    const generalized = [];
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            let changed = false;
+            const out = node.map((n) => {
+                const v = visit(n);
+                if (v !== n)
+                    changed = true;
+                return v;
+            });
+            return changed ? out : node;
+        }
+        if (!node || typeof node !== 'object')
+            return node;
+        const obj = node;
+        if (obj.source && isInlineCollection(obj)) {
+            const g = generalizeCollection(obj.source.data, budget);
+            if (!g)
+                return node;
+            generalized.push({
+                layerId: String(obj.id ?? ''),
+                ...(typeof obj.title === 'string' ? { title: obj.title } : {}),
+                toleranceDeg: g.toleranceDeg,
+            });
+            return { ...obj, subtitle: withNote(obj.subtitle), source: { ...obj.source, data: g.data } };
+        }
+        let changed = false;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            const nv = visit(v);
+            if (nv !== v)
+                changed = true;
+            out[k] = nv;
+        }
+        return changed ? out : node;
+    };
+    return { value: visit(root), generalized };
+}
+/** Approximate on-the-wire size of a stored value, in UTF-8 bytes. */
+export function storedBytes(v) {
+    return new TextEncoder().encode(JSON.stringify(v ?? null)).length;
+}
+/** "≈ 500 m" / "≈ 11 km" for a tolerance in degrees (1° ≈ 111 km). */
+export function describeTolerance(deg) {
+    if (deg <= 0)
+        return '≈ 10 m';
+    const m = deg * 111_000;
+    return m < 1000 ? `≈ ${Math.round(m / 100) * 100} m` : `≈ ${Math.round(m / 1000)} km`;
+}

package/dist/http.js

@@ -45,6 +45,7 @@ import { createServer as createHttpServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { randomUUID } from 'node:crypto';
 import { createServer as createMcpServer } from "./tools.js";
+import { PACKAGE_VERSION } from "./version.js";
 const BASE_URL = process.env.SHOWMEONMAP_BASE_URL ?? 'http://localhost:3000';
 const API_KEY = process.env.SHOWMEONMAP_API_KEY;
 const HTTP_PORT = Number(process.env.MCP_HTTP_PORT ?? 3333);
@@ -199,6 +200,7 @@ async function handleRequest(req, res) {
         baseUrl: BASE_URL,
         apiKey: API_KEY,
         sessionStore: SHARED_SESSION_STORE,
+        version: PACKAGE_VERSION,
     });
     await mcpServer.connect(transport);
     await transport.handleRequest(req, res, body);

package/dist/index.js

@@ -29,6 +29,7 @@
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from "./tools.js";
+import { PACKAGE_VERSION } from "./version.js";
 // Defaults to production so `npx @showmeonmap/mcp` works with only an API key.
 // Override with SHOWMEONMAP_BASE_URL=http://localhost:3000 for local dev.
 const BASE_URL = process.env.SHOWMEONMAP_BASE_URL ?? 'https://showmeonmap.com';
@@ -40,7 +41,7 @@ async function main() {
     // HTTP transport opts into D1 separately via http.ts. Callers can override
     // by injecting their own SessionStore into createServer if needed.
     const sessionStore = undefined;
-    const server = createServer({ baseUrl: BASE_URL, apiKey: API_KEY, sessionStore });
+    const server = createServer({ baseUrl: BASE_URL, apiKey: API_KEY, sessionStore, version: PACKAGE_VERSION });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write(`[showmeonmap-mcp] stdio ready · base=${BASE_URL}\n`);

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