@showmeonmap/mcp 0.2.0

package/dist/sessionStoreD1.js

@@ -0,0 +1,191 @@
+/**
+ * D1-backed SessionStore for the ShowMeOnMap MCP server (Wave 4 / Task C3,
+ * 2026-04-27).
+ *
+ * Why this exists
+ * ---------------
+ * The default store (createMemorySessionStore in tools.ts) is a per-process
+ * Map. Sessions evaporate on Worker restart and can't be shared across
+ * horizontally-scaled instances. createD1SessionStore swaps the backing
+ * store for a Cloudflare D1 binding so a session opened on one Worker can
+ * be served by any other.
+ *
+ * Schema
+ * ------
+ * Migration: migrations/0006_mcp_sessions.sql
+ *
+ *     CREATE TABLE mcp_sessions (
+ *       id            TEXT PRIMARY KEY,
+ *       workspace_id  TEXT,
+ *       workspace     TEXT NOT NULL,   -- JSON Workspace
+ *       map_plan      TEXT,            -- JSON MapPlan
+ *       layer_filters TEXT,            -- JSON Record<layerId, Predicate>
+ *       created_at    INTEGER NOT NULL,
+ *       last_seen_at  INTEGER NOT NULL
+ *     );
+ *
+ * LRU eviction
+ * ------------
+ * Best-effort. On every `put` we count rows; if the count exceeds
+ * `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.
+ *
+ * Independence
+ * ------------
+ * This file deliberately does NOT import from src/lib/db/d1Client. The
+ * MCP package has its own tsconfig with rootDir=./src and is published
+ * standalone; pulling in main-app modules would break the build. Instead
+ * we declare a minimal D1Database shape inline that matches both
+ * @cloudflare/workers-types and the main app's d1Client binding.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function rowToEntry(row) {
+    return {
+        workspace: JSON.parse(row.workspace),
+        mapPlan: row.map_plan ? JSON.parse(row.map_plan) : null,
+        layerFilters: row.layer_filters
+            ? JSON.parse(row.layer_filters)
+            : {},
+        createdAt: row.created_at,
+        lastAccessed: row.last_seen_at,
+    };
+}
+function entryToRow(id, entry) {
+    // Best-effort extraction of the workspace's own id for cross-table joins.
+    // Not a FK — the D1 row may persist after the canonical workspaces row is
+    // gone, and that's fine for a hot cache.
+    let workspaceId = null;
+    const ws = entry.workspace;
+    if (ws && typeof ws === 'object' && typeof ws.workspaceId === 'string') {
+        workspaceId = ws.workspaceId;
+    }
+    // mapPlan can blow past the D1 500KB row cap. If JSON.stringify throws
+    // RangeError or the result is huge we drop it; the next get will trigger
+    // a re-materialize on the API side. workspace itself stays — it's the
+    // ops log, which is small.
+    let mapPlanJson = null;
+    if (entry.mapPlan != null) {
+        try {
+            const candidate = JSON.stringify(entry.mapPlan);
+            if (candidate.length < 400_000)
+                mapPlanJson = candidate;
+        }
+        catch {
+            // Stringify failed (circular ref?). Leave null.
+        }
+    }
+    return {
+        id,
+        workspace_id: workspaceId,
+        workspace: JSON.stringify(entry.workspace ?? null),
+        map_plan: mapPlanJson,
+        layer_filters: JSON.stringify(entry.layerFilters ?? {}),
+        created_at: entry.createdAt,
+        last_seen_at: entry.lastAccessed,
+    };
+}
+export function createD1SessionStore(d1, opts = {}) {
+    const maxSize = opts.maxSize ?? 1000;
+    const evictionBatch = opts.evictionBatch ?? 50;
+    const onEvict = opts.onEvict;
+    /**
+     * LRU sweep — best-effort. Counts rows, drops the oldest by last_seen_at
+     * if over capacity. Fire-and-forget: callers don't await this.
+     */
+    async function maybeEvict() {
+        try {
+            const countRow = await d1
+                .prepare(`SELECT COUNT(*) AS n FROM mcp_sessions`)
+                .first();
+            const count = countRow?.n ?? 0;
+            if (count <= maxSize)
+                return;
+            // Drop at least the overflow; bump up to evictionBatch so we amortize
+            // the cost of running an eviction sweep. Concretely: count=4, maxSize=3,
+            // evictionBatch=2 → toDrop = max(1, 2) = 2 (lands at count=2).
+            const overflow = count - maxSize;
+            const toDrop = Math.max(overflow, evictionBatch);
+            // Identify the N oldest, then delete by id (DELETE ... ORDER BY LIMIT
+            // is not portable across all D1 versions; this two-step is safe).
+            const oldest = await d1
+                .prepare(`SELECT id FROM mcp_sessions ORDER BY last_seen_at ASC LIMIT ?`)
+                .bind(toDrop)
+                .all();
+            const ids = oldest.results.map((r) => r.id);
+            if (!ids.length)
+                return;
+            // Single DELETE with IN-list keeps the round-trip count low even on
+            // larger eviction batches. D1 has no documented limit on IN-list size
+            // beyond the SQL statement length cap, which we are nowhere near at
+            // batches of <1000 ids.
+            const placeholders = ids.map(() => '?').join(',');
+            const result = await d1
+                .prepare(`DELETE FROM mcp_sessions WHERE id IN (${placeholders})`)
+                .bind(...ids)
+                .run();
+            if (onEvict)
+                onEvict({ deleted: result.meta.changes ?? ids.length });
+        }
+        catch (err) {
+            // Eviction is best-effort — never let it bubble out of put().
+            if (onEvict)
+                onEvict({ deleted: 0, error: err });
+        }
+    }
+    return {
+        async get(mapId) {
+            const row = await d1
+                .prepare(`SELECT id, workspace_id, workspace, map_plan, layer_filters, created_at, last_seen_at
+             FROM mcp_sessions
+            WHERE id = ?`)
+                .bind(mapId)
+                .first();
+            if (!row)
+                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.
+            const now = Date.now();
+            d1.prepare(`UPDATE mcp_sessions SET last_seen_at = ? WHERE id = ?`)
+                .bind(now, mapId)
+                .run()
+                .catch(() => undefined);
+            entry.lastAccessed = now;
+            return entry;
+        },
+        async put(mapId, entry) {
+            const row = entryToRow(mapId, entry);
+            // UPSERT — D1 supports ON CONFLICT(id) DO UPDATE.
+            await d1
+                .prepare(`INSERT INTO mcp_sessions
+             (id, workspace_id, workspace, map_plan, layer_filters, created_at, last_seen_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             workspace_id  = excluded.workspace_id,
+             workspace     = excluded.workspace,
+             map_plan      = excluded.map_plan,
+             layer_filters = excluded.layer_filters,
+             last_seen_at  = excluded.last_seen_at`)
+                .bind(row.id, row.workspace_id, row.workspace, row.map_plan, row.layer_filters, row.created_at, row.last_seen_at)
+                .run();
+            // 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();
+        },
+        async delete(mapId) {
+            await d1.prepare(`DELETE FROM mcp_sessions WHERE id = ?`).bind(mapId).run();
+        },
+        async size() {
+            const row = await d1
+                .prepare(`SELECT COUNT(*) AS n FROM mcp_sessions`)
+                .first();
+            return row?.n ?? 0;
+        },
+    };
+}

package/dist/toolMeta.js

@@ -0,0 +1,182 @@
+/**
+ * Tool confirmation metadata — MCP package mirror of
+ * `src/core/agent/tools/meta.ts` in the parent repo.
+ *
+ * Why a mirror and not a direct import:
+ *   The MCP server (`@showmeonmap/mcp`) is npm-publishable from
+ *   `packages/mcp-server`. Its `tsconfig.json` has `rootDir: ./src`
+ *   so it can ship a clean `dist/` independent of the parent. Reaching
+ *   up into `../../src/core/agent/tools/meta.ts` would force the package
+ *   to depend on the parent repo's source layout, breaking the
+ *   publishable boundary.
+ *
+ * Sync invariant:
+ *   The agent-side meta file is the source of truth. A unit test in
+ *   `src/core/agent/tools/__tests__/meta.test.ts` (parent repo) asserts
+ *   the gated tool names and required-confirmation flags here match
+ *   the canonical TOOL_META map. If this file drifts, that test fails.
+ *
+ * Only the subset MCP actually needs lives here — the gating helpers
+ * for `withConfirmation` + the long-running flag for selected tools.
+ */
+/**
+ * Mirror of the MCP-side entries from src/core/agent/tools/meta.ts.
+ * Keep ordering + key set aligned with the canonical map.
+ */
+export const MCP_TOOL_META = {
+    build_map: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: true,
+        rationale: 'Bootstraps a workspace via /api/workspace/new; runs the full pipeline.',
+    },
+    mutate_map: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: true,
+        rationale: 'Append-only NL mutation; runs Claude tool-use loop on /api/workspace/mutate.',
+    },
+    get_state: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Read-only session-store lookup.',
+    },
+    add_layer: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Append-only LayerPlan insertion via apply-op; reversible with undo.',
+    },
+    add_fusion_layer: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: true,
+        rationale: 'Spatial join + Pearson r; multi-second on country-scale layers.',
+    },
+    correlate_layers: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Pure read of pre-joined layer pair; no mutation, no credit charged.',
+    },
+    filter_layer: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Append-only predicate; reversible with clear_filters or undo.',
+    },
+    select_within: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Adds a new derived layer; original layer untouched.',
+    },
+    query_features: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Read-only predicate evaluation against an existing layer.',
+    },
+    remove_layer: {
+        requires_confirmation: true,
+        destructive: true,
+        long_running: false,
+        rationale: 'Layer ids are tombstoned and CANNOT be re-added later in the same workspace. Effect is permanent within the session.',
+    },
+    clear_filters: {
+        requires_confirmation: true,
+        destructive: false,
+        long_running: false,
+        rationale: 'Recoverable via undo, but autonomous agents lack a UI surface to confirm intent. Gate at the wire layer instead.',
+    },
+    rename_layer: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Rekeys layer id but preserves data; reversible by renaming back.',
+    },
+    restyle_layer: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Cosmetic patch on viz fields; reversible.',
+    },
+    set_camera: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Camera-only op; no data mutation.',
+    },
+    set_time: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Binds a temporal window; reversible by emitting another setTime.',
+    },
+    tag: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Mirrors a string into workspace.meta.tags; append-only.',
+    },
+    add_annotation: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Append-only pin; reversible with remove_annotation.',
+    },
+    remove_annotation: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Annotations are not tombstoned; same id can be re-added.',
+    },
+    export_workspace: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Read-only export of workspace + mapPlan as JSON.',
+    },
+    export_layer_data: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: true,
+        rationale: 'Serializes layer + uploads to R2 with 24h TTL; network-bound.',
+    },
+    export_image: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Returns a pre-signed image URL; rendering is async upstream.',
+    },
+    undo: {
+        requires_confirmation: true,
+        destructive: false,
+        long_running: false,
+        rationale: 'Autonomous undo without user intent is a footgun: an agent that decides to "fix" something can erase the user\'s prior work.',
+    },
+    redo: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Re-applies a previously undone op; reversible by undoing again.',
+    },
+    report_blocker: {
+        requires_confirmation: false,
+        destructive: false,
+        long_running: false,
+        rationale: 'Append-only NDJSON write to the agent-blockers feedback channel.',
+    },
+};
+export function getMcpToolMeta(toolName) {
+    return MCP_TOOL_META[toolName];
+}
+export function mcpRequiresConfirmation(toolName) {
+    return MCP_TOOL_META[toolName]?.requires_confirmation ?? false;
+}
+export function mcpGatedToolNames() {
+    return Object.entries(MCP_TOOL_META)
+        .filter(([, meta]) => meta.requires_confirmation)
+        .map(([name]) => name);
+}