@showmeonmap/mcp 0.2.0

package/dist/workspaceOpsSpec.md

@@ -0,0 +1,250 @@
+# ShowMeOnMap Workspace Ops Spec (agent-facing)
+
+**URI:** `showmeonmap://docs/workspace-ops-spec`
+**Audience:** AI agents calling the ShowMeOnMap MCP server.
+**Purpose:** Give the calling agent every shape it needs to construct valid
+inputs to `mutate_map`, `filter_layer`, `add_layer`, `select_within`,
+`set_time`, `add_annotation`, etc. without guessing.
+
+If you are a calling agent and you are about to construct a structured
+predicate, a LayerPlan, or any other complex argument — read this first.
+Do **not** guess shapes; the renderer rejects malformed input with detail.
+
+---
+
+## Mental model
+
+A ShowMeOnMap workspace is an **append-only ops log** plus a `cursor`. Every
+mutation appends a typed Op. To render, the server folds the log up to the
+cursor (`materialize(workspace)`) into a `MapPlan`. Undo/redo move the cursor;
+they never delete ops. Tagging stamps a named checkpoint into `workspace.meta.tags`.
+
+You as the calling agent never construct ops by hand for `mutate_map` — that
+tool takes natural language. You **do** construct ops for the V2 direct-op
+tools (`add_layer`, `filter_layer`, `select_within`, `restyle_layer`,
+`set_time`, `tag`, `add_annotation`, etc.). Those POST a typed Op to the
+server's reducer without an LLM in the loop.
+
+Both surfaces require a `rationale` (≤300 chars) on every call: a short
+audit-log label stating the user-facing goal the call serves. The server
+cannot see your chat; the label is what keeps the ops-log traceable.
+
+---
+
+## Op catalog (what `materialize` understands)
+
+Every op carries common fields:
+
+```ts
+{
+  opId: uuid,           // assigned server-side if you go through MCP
+  turnId: uuid,         // shared across ops emitted in one user turn
+  emittedAt: ISO8601,
+  emittedBy: 'user' | 'agent' | 'system',
+  rationale?: string,   // ≤300 chars, optional in raw Op shape, required at MCP layer
+  kind: <one of below>,
+  args: { ... }
+}
+```
+
+| Op kind              | args                                                                                                  |
+| -------------------- | ----------------------------------------------------------------------------------------------------- |
+| `createWorkspace`    | `{ originalQuery?, shell: MapPlanShell }` — emitted by the server, never by you.                      |
+| `addLayer`           | `{ layerPlan: LayerPlan, intent?: string }` — see LayerPlan below.                                    |
+| `filterLayer`        | `{ layerId, predicate: Predicate, append?: boolean, intent?: string }` — see Predicate.               |
+| `removeLayer`        | `{ layerId }` — strict; double-remove rejected. Layer ids tombstone for the session.                   |
+| `clearFilters`       | `{ layerId }` — wipe predicate chain. Inverse of filterLayer.                                          |
+| `renameLayer`        | `{ oldLayerId, newLayerId }` — re-keys filters. newLayerId must be unique (incl. tombstones).         |
+| `restyleLayer`       | `{ layerId, color?: string, opacity?: number }` — within-palette style change.                         |
+| `subsetToSelection`  | `{ sourceLayerId, newLayerId, selection: GeoJSONPolygon, inheritStyle?: boolean }`                    |
+| `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' }`                                |
+| `addAnnotation`      | `{ annotation: { id, coords: [lng, lat], label?, color? } }` — annotation ids namespace separately.   |
+| `removeAnnotation`   | `{ annotationId }`                                                                                     |
+| `tag`                | `{ name }` — mirrored into `workspace.meta.tags`. Idempotent on duplicate.                             |
+
+---
+
+## Predicate grammar (Mongo-style tree)
+
+Predicates are recursive trees. Leaf nodes test one field; logical nodes
+combine children. The renderer transpiles to a MapLibre filter expression
+where possible, falls back to a Turf-based CPU filter where the predicate
+exceeds the GPU's expressiveness (e.g. spatial `within`).
+
+### Attribute predicates
+
+```ts
+{ op: 'eq',     field: 'category', value: 'cafe' }
+{ op: 'ne',     field: 'category', value: 'cafe' }
+{ op: 'gt',     field: 'magnitude', value: 5 }
+{ op: 'gte',    field: 'magnitude', value: 5 }
+{ op: 'lt',     field: 'depth_m', value: 100 }
+{ op: 'lte',    field: 'depth_m', value: 100 }
+{ op: 'in',     field: 'country', values: ['Japan','Indonesia','Philippines'] }
+{ op: 'nin',    field: 'country', values: ['Antarctica'] }
+{ op: 'regex',  field: 'name', pattern: '^Café', flags: 'i' }
+{ op: 'exists', field: 'wikidata_id', value: true }
+{ op: 'between', field: 'rating', min: 4, max: 5 }
+```
+
+### Spatial predicates
+
+```ts
+{ op: 'within', geometry: { type: 'Polygon', coordinates: [[ [lng,lat], ... ]] } }
+{ op: 'intersects', layerId: 'country_borders' }                  // intersect with another layer's geometry
+{ op: 'withinDistance', center: [lng, lat], meters: 5000 }
+{ op: 'bbox', box: [west, south, east, north] }
+```
+
+### Temporal predicates
+
+```ts
+{ op: 'before', field: 'date', value: '2025-01-01' }
+{ op: 'after',  field: 'date', value: '2020-01-01' }
+{ op: 'inRange', field: 'year', min: 2020, max: 2024 }
+```
+
+### Logical combinators
+
+```ts
+{ op: 'and', children: [<predicate>, <predicate>, ...] }
+{ op: 'or',  children: [<predicate>, <predicate>, ...] }
+{ op: 'not', child: <predicate> }
+```
+
+### Worked example
+
+> "Cafés rated 4+ within 2 km of [lng,lat]"
+
+```json
+{
+  "op": "and",
+  "children": [
+    { "op": "eq", "field": "category", "value": "cafe" },
+    { "op": "gte", "field": "rating", "value": 4 },
+    { "op": "withinDistance", "center": [-122.42, 37.77], "meters": 2000 }
+  ]
+}
+```
+
+---
+
+## LayerPlan (for `addLayer`)
+
+Minimum required fields:
+
+```ts
+{
+  id: string,                          // unique within workspace; tombstones on remove
+  title: string,                       // human-readable
+  geometry: 'point' | 'line' | 'polygon' | 'raster' | 'mixed',
+  source: LayerSource,                 // see below
+  viz: VizConfig,                      // see below
+  visible?: boolean,                   // default true
+  legend?: { label?: string, items?: Array<...> },
+}
+```
+
+### LayerSource shapes
+
+```ts
+// Inline GeoJSON
+{ kind: 'geojson', data: { type: 'FeatureCollection', features: [...] } }
+
+// External GeoJSON URL
+{ kind: 'geojson-url', url: string, attribution?: string }
+
+// Raster tiles (XYZ)
+{ kind: 'raster-tile', tileUrl: string, tileSize?: number, attribution?: string,
+  minzoom?: number, maxzoom?: number }
+
+// Vector tile source
+{ kind: 'vector-tile', tileUrl: string, sourceLayer: string, attribution?: string }
+```
+
+### Viz variants (must match geometry)
+
+```ts
+// point
+{ type: 'circle',   color?: string, valueField?: string, colorBy?: string, icon?: string }
+{ type: 'cluster',  clusterRadius?: number, color?: string }
+{ type: 'heatmap',  weight?: number, intensity?: number }
+// line
+{ type: 'line',     color?: string, width?: number }
+// polygon / fill
+{ type: 'fill',     color?: string, opacity?: number }
+{ type: 'choropleth', valueField: string, palette: string, classification?: 'quantile'|'jenks'|'equal' }
+// 3D
+{ type: 'extrusion', heightField: string, colorBy?: string }
+// raster
+{ type: 'raster',   opacity?: number }
+```
+
+Pass `viz` types that **match** the geometry (`circle`/`heatmap`/`cluster` →
+points; `line` → lines; `fill`/`choropleth`/`extrusion` → polygons;
+`raster` → raster). Mismatches are rejected.
+
+---
+
+## CameraPlan (for `setCamera`)
+
+```ts
+{
+  center: [lng, lat],
+  zoom: number,            // 0=world ... 22=building
+  bearing?: number,        // -180..180, 0 = north up
+  pitch?: number,          // 0..85, 0 = top-down
+  duration_ms?: number,    // animation duration
+}
+```
+
+---
+
+## Refusal & clarification surfaces (inside `mutate_map`)
+
+When you call `mutate_map` with NL, the response can carry one of three
+non-mutation signals. Treat them as structured affordances, not errors:
+
+- `outOfScope: { reason: string }` — instruction is unrelated to map state
+  (e.g. "what is the weather"). Do **not** retry; build a new map with
+  `build_map` instead.
+- `clarification: { question: string, candidates: string[] }` — instruction
+  is materially ambiguous (e.g. "remove it" with three candidate layers).
+  Surface the question + candidates back to your user; resend with the
+  disambiguated instruction.
+- `nextActions: string[]` — 2–3 concrete follow-ups tailored to the new
+  workspace state. Use as conversational suggestions to the user.
+
+The direct-op tools never emit these — they're a property of NL emission only.
+
+---
+
+## Common pitfalls
+
+- **Layer ids do not recycle.** Once `removeLayer` runs, that id is
+  tombstoned for the session. Re-use a different id.
+- **Annotation ids do recycle** — different namespace.
+- **`zoom` must be top-level** in any zoom-driven `step`/`interpolate` you
+  construct. Wrapping in arithmetic silently fails.
+- **`setBasemap` is enum-only** — five values exactly. Custom URLs go
+  through the `addLayer` raster-tile source.
+- **`promoteId: 'iso3'`** is the standard for choropleth feature-state
+  hover; provide it in the source if you're building per-country fills.
+- **Continuous scalar fields (UV, AQI, pollen, temperature, radiation)
+  must render as smooth rasters**, never as a point grid or MapLibre
+  `heatmap`. Use `raster-tile` source + `viz.type: 'raster'`. Hard rule.
+- **Default basemap water color** sits at `#aadaff` — tune fill opacity if
+  you need legibility on water-heavy regions.
+
+---
+
+## Versioning
+
+This spec describes **schema version 1** of the workspace ops log. The
+server returns `workspace.schemaVersion === 1`. Future changes will bump
+this and add an explicit migration path. If you see `schemaVersion > 1`,
+your snapshot of this resource may be stale — refetch.
+
+Last updated: 2026-04-25.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@showmeonmap/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for ShowMeOnMap — geospatial visualization tools for any MCP-speaking agent (Claude Desktop, Cursor, Zed, ChatGPT Apps SDK)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "showmeonmap-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp src/workspaceOpsSpec.md dist/workspaceOpsSpec.md && chmod +x dist/index.js",
+    "prepack": "npm run build",
+    "clean": "rm -rf dist",
+    "smoke": "node dist/index.js",
+    "test:unit": "node ../../scripts/run-mcp-unit-tests.mjs",
+    "test": "npm run test:unit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "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",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "maps",
+    "geospatial",
+    "showmeonmap",
+    "claude",
+    "cursor",
+    "zed"
+  ]
+}