@showmeonmap/mcp 0.3.1 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @showmeonmap/mcp
 
-[Model Context Protocol](https://modelcontextprotocol.io/) server for [ShowMeOnMap](https://github.com/FrankAIUser/showmeonmap). Lets any MCP-speaking agent — Claude Desktop, Cursor, Zed, Windsurf, ChatGPT Apps SDK, custom LangGraph / CrewAI / Autogen agents — build and mutate geospatial maps over a typed tool surface.
+[Model Context Protocol](https://modelcontextprotocol.io/) server for [ShowMeOnMap](https://showmeonmap.com). Lets any MCP-speaking agent — Claude Desktop, Cursor, Zed, Windsurf, ChatGPT Apps SDK, custom LangGraph / CrewAI / Autogen agents — build and mutate geospatial maps over a typed tool surface.
 
-**Spec:** `docs/superpowers/specs/2026-04-17-mcp-server-design.md` (in the parent repo).
+**Docs & keys:** https://showmeonmap.com/developers · Design spec: `docs/superpowers/specs/2026-04-17-mcp-server-design.md` (internal).
 
 ---
 

package/dist/http.js

@@ -13,9 +13,12 @@
  *   - Mcp-Session-Id header   — opaque per-session id returned on init
  *
  * Auth (baseline): single shared bearer token via MCP_HTTP_AUTH_TOKEN env var.
- * If set, every request must include `Authorization: Bearer <token>`. If
- * unset the server runs open — fine for localhost dev, unacceptable for a
- * public deployment.
+ * Every request must include `Authorization: Bearer <token>`. With no token
+ * set the server FAILS CLOSED and refuses everything; running without auth is
+ * possible but has to be requested explicitly with MCP_HTTP_ALLOW_OPEN=1.
+ *
+ * Binds 127.0.0.1 by default — override with MCP_HTTP_HOST (audit F8: it used
+ * to bind every interface while logging loopback).
  *
  * Run:
  *   MCP_HTTP_AUTH_TOKEN=dev npx tsx packages/mcp-server/src/http.ts
@@ -47,6 +50,27 @@ const API_KEY = process.env.SHOWMEONMAP_API_KEY;
 const HTTP_PORT = Number(process.env.MCP_HTTP_PORT ?? 3333);
 const AUTH_TOKEN = process.env.MCP_HTTP_AUTH_TOKEN;
 const ENDPOINT_PATH = '/mcp';
+/**
+ * Bind LOOPBACK by default (audit F8).
+ *
+ * `server.listen(port, cb)` with no host binds every interface, while the
+ * startup log said `http://127.0.0.1:…`. A developer running this on café or
+ * coworking wifi therefore had a process reachable at `http://<laptop-ip>:3333/mcp`
+ * from the whole LAN, and believed the log saying otherwise. That process holds
+ * `SHOWMEONMAP_API_KEY`, so a stranger could drive `/api/workspace/new` — burning
+ * the developer's credits — and write `/api/maps` as them.
+ *
+ * Override deliberately (containers, LAN testing) with MCP_HTTP_HOST=0.0.0.0.
+ * The log below prints the host actually bound, so it can never disagree again.
+ */
+const HTTP_HOST = process.env.MCP_HTTP_HOST ?? '127.0.0.1';
+/**
+ * Open mode must be ASKED FOR (audit F8). `isAuthorized` returned true whenever
+ * `MCP_HTTP_AUTH_TOKEN` was unset, i.e. auth failed OPEN — and unset was the
+ * documented dev default, so the safe-looking path was the unauthenticated one.
+ * Now an unset token is a hard refusal unless this flag says otherwise.
+ */
+const ALLOW_OPEN = process.env.MCP_HTTP_ALLOW_OPEN === '1';
 /**
  * Default to the in-memory store. Production deployments running under a
  * Cloudflare Worker (where a D1 binding exists) should construct their
@@ -71,9 +95,12 @@ const SHARED_SESSION_STORE = undefined;
 // transport.
 const transports = new Map();
 // ── Auth check ────────────────────────────────────────────────────────
-function isAuthorized(req) {
+export function isAuthorized(req) {
+    // Fails CLOSED with no token. Open mode is still available for local dev,
+    // but you have to say MCP_HTTP_ALLOW_OPEN=1 — the point is that nobody ends
+    // up unauthenticated by simply not setting something.
     if (!AUTH_TOKEN)
-        return true; // open mode
+        return ALLOW_OPEN;
     const hdr = req.headers['authorization'];
     if (typeof hdr !== 'string')
         return false;
@@ -180,13 +207,27 @@ const server = createHttpServer((req, res) => {
     handleRequest(req, res).catch((err) => {
         process.stderr.write(`[showmeonmap-mcp-http] unhandled: ${err instanceof Error ? err.stack : String(err)}\n`);
         if (!res.headersSent) {
-            writeJson(res, 500, { error: 'internal', message: err.message });
+            // Generic string only — an internal exception can carry D1 table/column
+            // names, and this handler is reachable before auth resolves. Matches the
+            // house pattern applied to the workspace routes (audit F13). The detail
+            // still reaches the operator via stderr above.
+            writeJson(res, 500, { error: 'internal', message: 'internal error' });
         }
     });
 });
-server.listen(HTTP_PORT, () => {
-    const authStatus = AUTH_TOKEN ? 'bearer-auth enabled' : 'OPEN (no auth — dev only)';
-    process.stderr.write(`[showmeonmap-mcp-http] listening on http://127.0.0.1:${HTTP_PORT}${ENDPOINT_PATH} · base=${BASE_URL} · ${authStatus}\n`);
+server.listen(HTTP_PORT, HTTP_HOST, () => {
+    // Report the host actually bound, never a hardcoded one — the previous log
+    // claimed 127.0.0.1 while listening on every interface, and that gap is what
+    // made F8 dangerous rather than merely wrong.
+    const authStatus = AUTH_TOKEN
+        ? 'bearer-auth enabled'
+        : ALLOW_OPEN
+            ? 'OPEN (MCP_HTTP_ALLOW_OPEN=1 — no auth)'
+            : 'REFUSING ALL REQUESTS (set MCP_HTTP_AUTH_TOKEN, or MCP_HTTP_ALLOW_OPEN=1 for local dev)';
+    process.stderr.write(`[showmeonmap-mcp-http] listening on http://${HTTP_HOST}:${HTTP_PORT}${ENDPOINT_PATH} · base=${BASE_URL} · ${authStatus}\n`);
+    if (HTTP_HOST !== '127.0.0.1' && HTTP_HOST !== 'localhost' && !AUTH_TOKEN) {
+        process.stderr.write(`[showmeonmap-mcp-http] ⚠️  bound to ${HTTP_HOST} with NO bearer token — this process holds SHOWMEONMAP_API_KEY and anyone who can reach this port can spend its credits\n`);
+    }
 });
 // Graceful shutdown — close every live session so clients see DELETE, not a socket hangup.
 async function shutdown() {

package/dist/sessionStoreD1.js

@@ -94,6 +94,15 @@ export function createD1SessionStore(d1, opts = {}) {
     const maxSize = opts.maxSize ?? 1000;
     const evictionBatch = opts.evictionBatch ?? 50;
     const onEvict = opts.onEvict;
+    const ownerId = opts.ownerId ?? null;
+    // 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
+    // rather than being readable by whoever asks first. When no owner is set
+    // (stdio: one process, one user) the predicate degrades to a no-op and the
+    // SQL is byte-identical to what shipped before.
+    const scope = ownerId ? ' AND user_id = ?' : '';
+    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.
@@ -143,17 +152,19 @@ export function createD1SessionStore(d1, opts = {}) {
             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)
+            WHERE id = ?${scope}`)
+                .bind(mapId, ...scopeArgs)
                 .first();
+            // A row owned by someone else is indistinguishable from one that does
+            // not exist — no existence oracle for another tenant's map ids.
             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)
+            d1.prepare(`UPDATE mcp_sessions SET last_seen_at = ? WHERE id = ?${scope}`)
+                .bind(now, mapId, ...scopeArgs)
                 .run()
                 .catch(() => undefined);
             entry.lastAccessed = now;
@@ -161,25 +172,45 @@ export function createD1SessionStore(d1, opts = {}) {
         },
         async put(mapId, entry) {
             const row = entryToRow(mapId, entry);
-            // UPSERT — D1 supports ON CONFLICT(id) DO UPDATE.
-            await d1
+            // UPSERT — D1 supports ON CONFLICT(id) DO UPDATE, including the optional
+            // WHERE on the DO UPDATE arm. That WHERE is the whole tenancy guard on
+            // the write path: if the id already belongs to a different owner the
+            // update arm matches nothing, so a cross-tenant overwrite is impossible
+            // ATOMICALLY, without a read-then-write race.
+            const result = await d1
                 .prepare(`INSERT INTO mcp_sessions
-             (id, workspace_id, workspace, map_plan, layer_filters, created_at, last_seen_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?)
+             (id, user_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)
+             last_seen_at  = excluded.last_seen_at
+           ${ownerId ? 'WHERE mcp_sessions.user_id = ?' : ''}`)
+                .bind(row.id, ownerId, row.workspace_id, row.workspace, row.map_plan, row.layer_filters, row.created_at, row.last_seen_at, ...scopeArgs)
                 .run();
+            // A refused DO UPDATE reports zero changes and would otherwise look
+            // exactly like a successful write — the caller would go on to report a
+            // saved workspace that was never saved. Make it loud. This is the
+            // silent-failure shape this repo has been bitten by repeatedly; an
+            // unwritable session must not be indistinguishable from a written one.
+            if (ownerId && (result.meta?.changes ?? 0) === 0) {
+                throw new Error(`mcp session ${mapId} belongs to another account (write refused)`);
+            }
             // 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();
+            // Owner-scoped, so a non-owner's delete silently affects zero rows
+            // rather than destroying someone else's session. No error here on
+            // purpose: delete is idempotent by contract, and "already gone" and
+            // "not yours" should look the same to a caller who owns neither.
+            await d1
+                .prepare(`DELETE FROM mcp_sessions WHERE id = ?${scope}`)
+                .bind(mapId, ...scopeArgs)
+                .run();
         },
         async size() {
             const row = await d1

package/dist/toolMeta.js

@@ -72,6 +72,12 @@ 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.',
+    },
     query_features: {
         requires_confirmation: false,
         destructive: false,

package/dist/tools.js

@@ -193,7 +193,9 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
         map_id: mapId,
         version: opsCount,
         structured: compactStructured(workspace, mapPlan),
-        shareable_url: `${baseUrl}/m/${mapId}`,
+        ...(extras.shareUnpersisted
+            ? { share_status: 'not_persisted' }
+            : { shareable_url: `${baseUrl}/m/${mapId}` }),
         metadata: {
             title: mapPlan?.title,
             layer_count: layerCount,
@@ -205,6 +207,8 @@ 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 } : {}),
     };
 }
 function toContent(obj) {
@@ -238,6 +242,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).',
@@ -350,6 +355,14 @@ async function apiFetch(baseUrl, apiKey, path, body) {
         body: JSON.stringify(body),
     });
     const text = await resp.text();
+    // A non-2xx is a FAILURE even when the body is valid JSON — /api/maps
+    // returns a JSON error body for its IP rate-limit 429, which parsed
+    // "successfully" here and made a failed share-store write look like a
+    // success (one of four parallel build_map calls lost its map this way,
+    // 2026-08-01).
+    if (!resp.ok) {
+        throw new Error(`${path} ${resp.status}: ${text.slice(0, 200)}`);
+    }
     try {
         return JSON.parse(text);
     }
@@ -368,31 +381,116 @@ async function apiFetch(baseUrl, apiKey, path, body) {
  * `version`, so /m/[id] rehydrates it faithfully. NEVER throws — a failed
  * share must not fail the build/mutation.
  */
+// ── share-blob compaction ──────────────────────────────────────────────────
+// /api/maps caps blobs at 5 MB. A fusion map's inline world geometry is
+// 16.5 MB MEASURED (2026-08-01) — the persist POST was rejected with
+// "blob too large" on every attempt and the old code swallowed it, which is
+// how the same map vanished twice while its siblings persisted. Recipe
+// mirrors build-statistical-goldens + saveMapSnapshot: ring decimation,
+// largest-polygons-only, 4-decimal coordinates (~11 m — invisible at the
+// zooms a snapshot serves; the /m/ page offers "Re-run live" for full
+// fidelity), and a property whitelist of base fields + whatever the layer's
+// own viz reads.
+const SHARE_MAX_VERTICES_PER_RING = 60;
+const SHARE_MAX_POLYS_PER_MULTI = 3;
+const SHARE_MAX_FEATURES_PER_LAYER = 2000;
+const SHARE_BASE_KEEP_PROPS = new Set(['value', 'name', 'iso3', 'label', '_dataVintage']);
+function roundCoord(n) {
+    return Math.round(n * 10_000) / 10_000;
+}
+function decimateRing(ring) {
+    const rounded = ring.map(([x, y]) => [roundCoord(x), roundCoord(y)]);
+    if (rounded.length <= SHARE_MAX_VERTICES_PER_RING)
+        return rounded;
+    const out = [];
+    for (let i = 0; i < SHARE_MAX_VERTICES_PER_RING; i++) {
+        out.push(rounded[Math.floor((i * (rounded.length - 1)) / (SHARE_MAX_VERTICES_PER_RING - 1))]);
+    }
+    return out;
+}
+function ringArea(ring) {
+    let area = 0;
+    for (let i = 0; i < ring.length - 1; i++) {
+        area += ring[i][0] * ring[i + 1][1] - ring[i + 1][0] * ring[i][1];
+    }
+    return Math.abs(area / 2);
+}
+function compactGeometry(geom) {
+    if (geom?.type === 'Polygon') {
+        return { ...geom, coordinates: geom.coordinates.map(decimateRing) };
+    }
+    if (geom?.type === 'MultiPolygon') {
+        const polys = [...geom.coordinates]
+            .sort((a, b) => ringArea(b[0]) - ringArea(a[0]))
+            .slice(0, SHARE_MAX_POLYS_PER_MULTI);
+        return { ...geom, coordinates: polys.map((poly) => poly.map(decimateRing)) };
+    }
+    if (geom?.type === 'LineString') {
+        return { ...geom, coordinates: decimateRing(geom.coordinates) };
+    }
+    if (geom?.type === 'MultiLineString') {
+        return { ...geom, coordinates: geom.coordinates.map(decimateRing) };
+    }
+    if (geom?.type === 'Point') {
+        const [x, y] = geom.coordinates;
+        return { ...geom, coordinates: [roundCoord(x), roundCoord(y)] };
+    }
+    return geom;
+}
+/** Base whitelist + every field name the layer's viz reads + `_smo_*`
+ *  internals (tooltip/popup dispatch). Exported for tests. */
+export function compactFeatureCollection(fc, viz) {
+    const keep = new Set(SHARE_BASE_KEEP_PROPS);
+    for (const [k, v] of Object.entries(viz ?? {})) {
+        if (typeof v === 'string' && /(Field|^field[A-Z])/.test(k))
+            keep.add(v);
+    }
+    const features = (fc.features ?? []).slice(0, SHARE_MAX_FEATURES_PER_LAYER).map((f) => ({
+        ...f,
+        geometry: compactGeometry(f.geometry),
+        properties: Object.fromEntries(Object.entries(f.properties ?? {}).filter(([k]) => keep.has(k) || k.startsWith('_smo_'))),
+    }));
+    return { type: fc.type ?? 'FeatureCollection', features };
+}
 async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query) {
     if (!mapPlan || !Array.isArray(mapPlan.layers))
-        return;
-    try {
-        const geojsonLayers = {};
-        const strippedLayers = mapPlan.layers.map((raw) => {
-            const layer = raw;
-            if (layer?.source?.kind === 'geojson' && layer.source.data && layer.id) {
-                geojsonLayers[layer.id] = layer.source.data;
-                return { ...layer, source: { ...layer.source, data: undefined } };
+        return false;
+    const geojsonLayers = {};
+    const strippedLayers = mapPlan.layers.map((raw) => {
+        const layer = raw;
+        if (layer?.source?.kind === 'geojson' && layer.source.data && layer.id) {
+            geojsonLayers[layer.id] = compactFeatureCollection(layer.source.data, layer.viz);
+            return { ...layer, source: { ...layer.source, data: undefined } };
+        }
+        return layer;
+    });
+    const title = mapPlan.title ?? mapPlan.layers[0]?.title ?? 'Untitled Map';
+    const body = {
+        id: mapId,
+        title,
+        query,
+        blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1 },
+        isPublic: true,
+    };
+    // Two attempts: the second exists for exactly the failure that lost a map
+    // live — parallel build_map calls tripping /api/maps' burst rate limit.
+    // A share-save failure still never fails the BUILD, but it must never be
+    // silent either, and the caller decides whether to hand out the URL.
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            await apiFetch(baseUrl, apiKey, '/api/maps', body);
+            return true;
+        }
+        catch (err) {
+            if (attempt === 1) {
+                await new Promise((r) => setTimeout(r, 400));
+                continue;
             }
-            return layer;
-        });
-        const title = mapPlan.title ?? mapPlan.layers[0]?.title ?? 'Untitled Map';
-        await apiFetch(baseUrl, apiKey, '/api/maps', {
-            id: mapId,
-            title,
-            query,
-            blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1 },
-            isPublic: true,
-        });
-    }
-    catch {
-        /* best-effort — a share-save failure never fails the build */
+            console.warn(`[mcp] share-store write FAILED for map ${mapId} after retry — ` +
+                `the /m/ link would be dead, omitting it: ${err instanceof Error ? err.message : err}`);
+        }
     }
+    return false;
 }
 // MCP tool annotations — safety hints every tool advertises so clients can
 // reason about read-only vs mutating vs destructive behavior (and the model
@@ -405,7 +503,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([
@@ -524,8 +622,8 @@ export function createServer(opts) {
             'Zoom the camera closer',
         ];
         // Persist to the shareable store so the returned /m/<mapId> link renders.
-        await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, query);
-        return toContent(envelope(baseUrl, mapId, resp.workspace, resp.mapPlan, nextActions));
+        const shared = await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, query);
+        return toContent(envelope(baseUrl, mapId, resp.workspace, resp.mapPlan, nextActions, shared ? {} : { shareUnpersisted: true }));
     }));
     const mutateMapShape = {
         map_id: z.string().min(1).describe('map_id from a prior build_map call'),
@@ -565,8 +663,11 @@ export function createServer(opts) {
         });
         const mutMapPlan = (resp.mapPlan ?? entry.mapPlan);
         // Update the shareable /m/<map_id> map so the link reflects the mutation.
-        await persistShareableMap(baseUrl, apiKey, map_id, mutMapPlan, instruction);
-        return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), mutMapPlan, resp.nextActions, resp.clarification ? { clarification: resp.clarification } : {}));
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, mutMapPlan, instruction);
+        return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), mutMapPlan, resp.nextActions, {
+            ...(resp.clarification ? { clarification: resp.clarification } : {}),
+            ...(shared ? {} : { shareUnpersisted: true }),
+        }));
     }));
     const getStateShape = {
         map_id: z.string().min(1),
@@ -612,8 +713,8 @@ export function createServer(opts) {
         });
         const opMapPlan = (resp.mapPlan ?? entry.mapPlan);
         // Update the shareable /m/<map_id> map so the link reflects the mutation.
-        await persistShareableMap(baseUrl, apiKey, map_id, opMapPlan, opMapPlan?.title ?? '');
-        return envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), opMapPlan, undefined);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, opMapPlan, opMapPlan?.title ?? '');
+        return envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), opMapPlan, undefined, shared ? {} : { shareUnpersisted: true });
     }
     /**
      * Shared op-header builder — every direct-op tool fills these fields.
@@ -860,6 +961,70 @@ 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 queryFeaturesShape = {
         map_id: z.string().min(1),
         layerId: z.string().min(1),
@@ -1218,8 +1383,8 @@ export function createServer(opts) {
         });
         const rematPlan = resp.mapPlan;
         // Keep the shareable /m/<map_id> map in sync after undo/redo.
-        await persistShareableMap(baseUrl, apiKey, map_id, rematPlan, rematPlan?.title ?? '');
-        return envelope(baseUrl, map_id, workspace, rematPlan, undefined);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, rematPlan, rematPlan?.title ?? '');
+        return envelope(baseUrl, map_id, workspace, rematPlan, undefined, shared ? {} : { shareUnpersisted: true });
     }
     const exportWorkspaceShape = {
         map_id: z.string().min(1),
@@ -1258,8 +1423,9 @@ export function createServer(opts) {
         description: 'Export a single layer\'s features as a downloadable file. Returns ' +
             'a URL with Content-Disposition: attachment so the user\'s browser ' +
             'downloads it. CSV drops geometry beyond a (lng, lat) centroid — ' +
-            'for full polygon/line geometry, use format: "geojson". URL is ' +
-            'valid for 24 hours. Required: map_id, layer_id, format, rationale.',
+            'for full polygon/line geometry, use format: "geojson". The URL is an ' +
+            'unguessable capability link that does NOT expire — treat it as ' +
+            'shareable-forever, not temporary. Required: map_id, layer_id, format, rationale.',
         inputSchema: exportLayerDataShape,
     }, withValidation('export_layer_data', exportLayerDataShape, async ({ map_id, layer_id, format, rationale }) => {
         logRationale('export_layer_data', map_id, rationale);

package/dist/workspaceOpsSpec.md

@@ -57,6 +57,7 @@ Every op carries common fields:
 | `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.1",
+  "version": "0.4.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",
@@ -24,7 +24,7 @@
     "test": "npm run test:unit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
@@ -32,12 +32,7 @@
     "typescript": "^5.4.0"
   },
   "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/FrankAIUser/showmeonmap.git",
-    "directory": "packages/mcp-server"
-  },
-  "homepage": "https://github.com/FrankAIUser/showmeonmap/tree/main/packages/mcp-server#readme",
+  "homepage": "https://showmeonmap.com/developers",
   "keywords": [
     "mcp",
     "model-context-protocol",