@showmeonmap/mcp 0.2.0 → 0.3.0

package/dist/tools.js

@@ -394,6 +394,33 @@ async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query) {
         /* best-effort — a share-save failure never fails the build */
     }
 }
+// MCP tool annotations — safety hints every tool advertises so clients can
+// reason about read-only vs mutating vs destructive behavior (and the model
+// picks tools correctly). `destructiveHint` derives from MCP_TOOL_META (the
+// single source of truth, kept in sync with the agent-side meta); the rest
+// from a small intent classification.
+const READ_ONLY_TOOLS = new Set([
+    'get_state', 'query_features', 'select_within', 'correlate_layers',
+    'export_workspace', 'export_layer_data', 'export_image', 'report_blocker',
+]);
+// 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']);
+// 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([
+    'set_camera', 'set_time', 'clear_filters', 'rename_layer', 'restyle_layer',
+    'remove_layer', 'remove_annotation',
+]);
+function toolAnnotations(name) {
+    const readOnly = READ_ONLY_TOOLS.has(name);
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: MCP_TOOL_META[name]?.destructive ?? false,
+        idempotentHint: readOnly || IDEMPOTENT_SETTERS.has(name),
+        openWorldHint: OPEN_WORLD_TOOLS.has(name),
+    };
+}
 export function createServer(opts) {
     const baseUrl = opts.baseUrl;
     const apiKey = opts.apiKey;
@@ -402,6 +429,11 @@ export function createServer(opts) {
         name: opts.name ?? 'showmeonmap',
         version: opts.version ?? '0.1.0',
     });
+    // Stamp MCP annotations onto every tool from the central classification so we
+    // don't thread them through 24 registerTool call sites. `title` mirrors the
+    // tool's own title; any inline annotations a call sets win over the defaults.
+    const baseRegisterTool = server.registerTool.bind(server);
+    const registerTool = (name, config, cb) => baseRegisterTool(name, { ...config, annotations: { title: config.title, ...toolAnnotations(name), ...config.annotations } }, cb);
     // -------------------------------------------------------------------------
     // Resource: workspace-ops-spec
     // -------------------------------------------------------------------------
@@ -463,7 +495,7 @@ export function createServer(opts) {
             .describe('Natural language: "coffee shops in Tokyo", "GDP by country", "volcanoes in Indonesia", etc.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('build_map', {
+    registerTool('build_map', {
         title: 'Build a map',
         description: 'Create a new workspace from a natural-language query. Returns a map_id you can pass to mutate_map or get_state for follow-up actions. ' +
             'For the full Op catalog and predicate grammar that downstream tools (mutate_map, filter_layer, etc.) accept, fetch the MCP resource at showmeonmap://docs/workspace-ops-spec — do NOT guess the shapes.',
@@ -503,7 +535,7 @@ export function createServer(opts) {
             .describe('e.g., "filter to where magnitude is greater than 5", "change basemap to dark"'),
         rationale: rationaleSchema,
     };
-    server.registerTool('mutate_map', {
+    registerTool('mutate_map', {
         title: 'Mutate a map',
         description: 'Apply a natural-language instruction to an existing workspace. Valid mutations: filter a layer, remove a layer, change camera, change basemap. For ambiguous instructions the tool emits a clarification field. For unrelated instructions it emits outOfScope — build a new map in that case. ' +
             'For the full Op catalog and predicate grammar, fetch the MCP resource showmeonmap://docs/workspace-ops-spec.',
@@ -540,7 +572,7 @@ export function createServer(opts) {
         map_id: z.string().min(1),
         rationale: rationaleSchema,
     };
-    server.registerTool('get_state', {
+    registerTool('get_state', {
         title: 'Read map state',
         description: 'Return the current workspace, map plan, and active filters for a given map_id.',
         inputSchema: getStateShape,
@@ -627,7 +659,7 @@ export function createServer(opts) {
             '"comparison" = a layer added to compare against another; ' +
             '"other" = none of the above.'),
     };
-    server.registerTool('add_layer', {
+    registerTool('add_layer', {
         title: 'Add a layer (direct)',
         description: 'Append a fully-constructed LayerPlan to an existing workspace without going through NL. ' +
             'Pass the same shape the workspace pipeline emits — { id, title, source, viz, geometry, ... }. ' +
@@ -656,7 +688,7 @@ export function createServer(opts) {
         new_layer_id: z.string().optional(),
         rationale: rationaleSchema,
     };
-    server.registerTool('add_fusion_layer', {
+    registerTool('add_fusion_layer', {
         title: 'Add bivariate fusion layer',
         description: 'Spatially join two existing layers and add a new layer that ' +
             'encodes both values per region as a 3x3 bivariate choropleth. ' +
@@ -707,7 +739,7 @@ export function createServer(opts) {
         value_field_b: z.string().optional(),
         rationale: rationaleSchema,
     };
-    server.registerTool('correlate_layers', {
+    registerTool('correlate_layers', {
         title: 'Compute correlation between two layers',
         description: 'Spatially join two existing workspace layers and return the ' +
             'Pearson correlation coefficient r, sample size n, two-sided ' +
@@ -770,7 +802,7 @@ export function createServer(opts) {
             '"preview-data" = exploratory peek; ' +
             '"other" = none of the above.'),
     };
-    server.registerTool('filter_layer', {
+    registerTool('filter_layer', {
         title: 'Filter a layer (direct)',
         description: 'Narrow a layer to features matching a structured predicate. `append:true` (default) conjoins ' +
             'with any existing filter; `append:false` replaces the chain.',
@@ -808,7 +840,7 @@ export function createServer(opts) {
             .describe('Default true. false emits a new layer with minimal default styling.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('select_within', {
+    registerTool('select_within', {
         title: 'Subset a layer to a polygon selection',
         description: 'Create a new layer containing the source layer\'s features that lie within the supplied ' +
             'polygon. The source layer is untouched. Useful for "show me only the X inside this ' +
@@ -841,7 +873,7 @@ export function createServer(opts) {
             .describe('Default 100, max 1000. Response sets `truncated:true` when clipped.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('query_features', {
+    registerTool('query_features', {
         title: 'Query features from a layer (read-only)',
         description: 'Evaluate a predicate against a layer\'s inline features and return the matching subset. ' +
             'No Op is emitted and the workspace is not mutated. Handy for introspection ("how many X ' +
@@ -889,7 +921,7 @@ export function createServer(opts) {
             'returns a needs_confirmation envelope. Layer ids are tombstoned — once removed, ' +
             'the same id cannot be re-added later in this workspace.'),
     };
-    server.registerTool('remove_layer', {
+    registerTool('remove_layer', {
         title: 'Remove a layer (direct, destructive)',
         description: 'Drop a layer from the workspace by id. Strict: removing an already-removed ' +
             'or never-added layer fails. Layer ids do NOT recycle — a removed id cannot be ' +
@@ -917,7 +949,7 @@ export function createServer(opts) {
             'returns a needs_confirmation envelope. Wiping a filter chain is recoverable ' +
             'via undo, but autonomous agents lack a UI surface to confirm intent.'),
     };
-    server.registerTool('clear_filters', {
+    registerTool('clear_filters', {
         title: 'Clear all filters on a layer (direct, gated)',
         description: 'Wipe every predicate currently applied to a layer\'s filter chain, making ' +
             'every source feature visible again. Inverse of filter_layer. No-op on layers ' +
@@ -939,7 +971,7 @@ export function createServer(opts) {
         newLayerId: z.string().min(1).describe('New id. Must be unique within the workspace.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('rename_layer', {
+    registerTool('rename_layer', {
         title: 'Rename a layer (direct)',
         description: 'Change a layer\'s id from oldLayerId to newLayerId. Re-keys any existing filter ' +
             'chain and preserves insertion order among sibling layers. Strict: newLayerId must ' +
@@ -971,7 +1003,7 @@ export function createServer(opts) {
             .describe('0 (transparent) to 1 (opaque).'),
         rationale: rationaleSchema,
     };
-    server.registerTool('restyle_layer', {
+    registerTool('restyle_layer', {
         title: 'Restyle a layer (direct)',
         description: 'Adjust a layer\'s color and/or opacity. Within-palette changes only — the ' +
             'renderer silently ignores fields the current viz variant doesn\'t support. ' +
@@ -1029,7 +1061,7 @@ export function createServer(opts) {
         camera: cameraPlanSchema,
         rationale: rationaleSchema,
     };
-    server.registerTool('set_camera', {
+    registerTool('set_camera', {
         title: 'Set the map camera (direct)',
         description: 'Override the workspace camera. Latest set_camera op wins during replay. ' +
             'Two modes: `fitBounds` with a [w,s,e,n] bbox (plus optional padding/animateMs), ' +
@@ -1061,7 +1093,7 @@ export function createServer(opts) {
             .describe('How rangeStart/rangeEnd encode time. Default: unix_ms at render time.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('set_time', {
+    registerTool('set_time', {
         title: 'Set the time window (direct)',
         description: 'Override the current time-range filter. Latest set_time op wins during replay. ' +
             'Use for "filter to 2020-2024" or "show only the last 7 days" intents. Not yet ' +
@@ -1090,7 +1122,7 @@ export function createServer(opts) {
             .describe('Checkpoint label, e.g. "before EV layer added" or "v1.0".'),
         rationale: rationaleSchema,
     };
-    server.registerTool('tag', {
+    registerTool('tag', {
         title: 'Save a named checkpoint (direct)',
         description: 'Label the current workspace state with a user-supplied name. The label is ' +
             'mirrored into workspace.meta.tags so UIs can render a named-revision history. ' +
@@ -1119,7 +1151,7 @@ export function createServer(opts) {
             .describe('Optional CSS color for the marker + label.'),
         rationale: rationaleSchema,
     };
-    server.registerTool('add_annotation', {
+    registerTool('add_annotation', {
         title: 'Place an annotation on the map (direct)',
         description: 'Add a user-placed label at a specific coordinate. Annotations are independent of ' +
             'layers and live in their own id namespace. Strict: the id must not already be in ' +
@@ -1146,7 +1178,7 @@ export function createServer(opts) {
         annotationId: z.string().min(1),
         rationale: rationaleSchema,
     };
-    server.registerTool('remove_annotation', {
+    registerTool('remove_annotation', {
         title: 'Remove an annotation (direct)',
         description: 'Drop a previously-placed annotation by id. Strict: removing an already-removed ' +
             'or never-placed id fails. After removal, the id CAN be re-used by a later ' +
@@ -1193,7 +1225,7 @@ export function createServer(opts) {
         map_id: z.string().min(1),
         rationale: rationaleSchema,
     };
-    server.registerTool('export_workspace', {
+    registerTool('export_workspace', {
         title: 'Export the workspace JSON',
         description: 'Return the current workspace document (ops log + cursor + meta) plus the ' +
             'materialized mapPlan and layerFilters, in a shape suitable for save-to-file / ' +
@@ -1221,7 +1253,7 @@ export function createServer(opts) {
         format: z.enum(['csv', 'geojson']),
         rationale: rationaleSchema,
     };
-    server.registerTool('export_layer_data', {
+    registerTool('export_layer_data', {
         title: 'Export layer data',
         description: 'Export a single layer\'s features as a downloadable file. Returns ' +
             'a URL with Content-Disposition: attachment so the user\'s browser ' +
@@ -1242,7 +1274,7 @@ export function createServer(opts) {
         legend: z.boolean().default(true),
         rationale: rationaleSchema,
     };
-    server.registerTool('export_image', {
+    registerTool('export_image', {
         title: 'Export map as image',
         description: 'Returns a deep-link URL that opens the map in the user\'s browser ' +
             'and automatically triggers a PNG download. The user clicks the ' +
@@ -1281,7 +1313,7 @@ export function createServer(opts) {
             'returns a needs_confirmation envelope. Autonomous undo without user intent is ' +
             'a footgun — an agent that decides to "fix" something can erase prior work.'),
     };
-    server.registerTool('undo', {
+    registerTool('undo', {
         title: 'Undo the most recent op (gated)',
         description: 'Rewind the workspace cursor by one, re-materializing the state as it was before ' +
             'the last mutation. Does NOT delete any ops — redo will fast-forward. Calling ' +
@@ -1306,7 +1338,7 @@ export function createServer(opts) {
         map_id: z.string().min(1),
         rationale: rationaleSchema,
     };
-    server.registerTool('redo', {
+    registerTool('redo', {
         title: 'Redo a previously-undone op',
         description: 'Advance the workspace cursor by one toward the tail of the ops log, replaying ' +
             'the next op that was previously undone. Calling redo when the cursor is already ' +
@@ -1365,7 +1397,7 @@ export function createServer(opts) {
             .optional()
             .describe('Optional. A new tool, op, or schema field that would have unblocked you.'),
     };
-    server.registerTool('report_blocker', {
+    registerTool('report_blocker', {
         title: 'Report a blocker (agent feedback)',
         description: 'Tell the ShowMeOnMap team your agent hit something it could not accomplish — an ' +
             'unsupported intent, a missing tool, an unclear schema, an op that failed in a ' +

package/package.json

@@ -1,7 +1,7 @@
 {
   "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)",
+  "version": "0.3.0",
+  "description": "MCP server for ShowMeOnMap \u2014 geospatial visualization tools for any MCP-speaking agent (Claude Desktop, Cursor, Zed, ChatGPT Apps SDK)",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {