@honua/mcp-server 0.0.20-alpha.0 → 0.1.1-beta.0

package/README.md

@@ -1,45 +1,127 @@
 # `@honua/mcp-server`
 
-Model Context Protocol (MCP) server for Honua geospatial feature services.
+The **platform-free** Model Context Protocol (MCP) server for geospatial feature
+services. Point it at **any** public Esri FeatureServer or OGC API endpoint and it
+exposes discovery, query, and analysis workflows to any MCP client — with **zero**
+platform lock-in and no metering. Mapbox, CARTO, and Esri each ship an MCP server
+bound to their own platform; this one is bound to none.
 
-This package exposes a focused MCP surface for discovery and query workflows on top of Honua's FeatureServer APIs.
+**Release status: beta.** Tool contracts are certified against live and fixture
+targets on every release; remaining pre-1.0 work is hardening, not surface change.
 
-## Requirements
+Two modes:
 
-- Node.js `>=20`
-- A reachable Honua server URL
+- **Standalone (platform-free) — the front door.** The `honua-mcp` bin runs the
+  direct-SDK surface against any public FeatureServer/OGC endpoint. No Honua
+  server, no admin API, no `/mcp` catalog required.
+- **Honua-enhanced — the upgrade path.** The `honua-mcp-proxy` bin bridges a
+  Honua deployment's full `/mcp` operator catalog (planning, async jobs,
+  publishing) to stdio. Honua does **not** expose an AI/MCP feature-mutation tool
+  — AI operational data editing is not supported (honua-server ADR-0028).
 
-## Environment Variables
+## Requirements
 
-- `HONUA_BASE_URL` (required): absolute Honua base URL, for example `https://honua.example.com`
-- `HONUA_TRANSPORT` (optional): `grpc-web` (default) or `rest`
-- `HONUA_API_KEY` (optional): admin/API key when your deployment requires it
-- `HONUA_TIMEOUT_MS` (optional): request timeout in milliseconds (default `30000`)
-- `HONUA_RETRY_MAX_RETRIES` (optional): retry attempts for transient failures (default `2`)
+- Node.js `>=20`
+- Any reachable FeatureServer/OGC endpoint (public or Honua)
 
-When `HONUA_API_KEY` is configured, use `https://` for non-localhost servers.
+## Platform-free mode (any ArcGIS / OGC endpoint)
 
-## Run Locally
+Point `HONUA_BASE_URL` at any origin/folder that serves the standard GeoServices
+REST paths (`/rest/services`, `/FeatureServer/{id}/query`). Example — the public
+US Census 2020 apportionment FeatureServer on `services.arcgis.com`:
 
 ```bash
 npm install
 npm run build
-HONUA_BASE_URL="https://honua.example.com" HONUA_TRANSPORT="grpc-web" node dist/src/index.js
+HONUA_BASE_URL="https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" \
+  HONUA_TRANSPORT="rest" node dist/src/index.js
 ```
 
+Tools that require a Honua-only surface (server-side styling via OGC API – Styles,
+a `/rest/services` catalog) **degrade gracefully** on a plain endpoint: they
+return a structured result
+
+```json
+{ "available": false, "surface": "OGC API - Styles", "reason": "…", "guidance": "…" }
+```
+
+instead of crashing, hanging, or returning misleading empty data. This is the
+same skip-with-reason honesty the certification suite uses.
+
+## Environment Variables
+
+- `HONUA_BASE_URL` (required): absolute base URL — a public ArcGIS folder
+  (`https://services.arcgis.com/<org>/arcgis`) or a Honua deployment
+  (`https://honua.example.com`).
+- `HONUA_TRANSPORT` (optional): `grpc-web` (default, Honua deployments) or `rest`.
+  Use `rest` for plain public ArcGIS/OGC endpoints.
+- `HONUA_API_KEY` (optional): API key when your deployment requires it. Public
+  endpoints need none.
+- `HONUA_TIMEOUT_MS` (optional): request timeout in milliseconds (default `30000`)
+- `HONUA_RETRY_MAX_RETRIES` (optional): retry attempts for transient failures (default `2`)
+
+When `HONUA_API_KEY` is configured, use `https://` for non-localhost servers.
+
 ## MCP Tools
 
-- `honua_list_services`
+All read-only:
+
+- `honua_list_services` — discover services (degrades if the target has no catalog)
 - `honua_describe_layer`
 - `honua_query_features`
 - `honua_count_features`
 - `honua_get_extent`
 - `honua_statistics`
+- `honua_explain_capability_gap`
+- `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer
+
+Hosts that use signed safe-agent plans can import
+`@honua/mcp-server/agent-execution`. Its `createReadOnlyMcpAgentExecutor` binds
+one named read tool to `@honua/sdk-js/agent-safety`'s exact approved-operation,
+durable-audit, and signed-receipt path. It never enables wildcard dispatch or
+mutation on the standalone server. The descriptor requires a bounded exact name
+and a deterministic `countRows(result)` callback; missing or invalid row counts
+fail instead of being reported as zero.
+
+### Optional natural-language map-plan tools
+
+Embedded hosts with a map runtime, BYO-LLM callback, approval verifier, and
+atomic approval-use store can opt into two additional tools:
+
+- `proposeMapPlan` — compiles an instruction into an inspectable, content-addressed plan and never executes it.
+- `executeMapPlan` — accepts that plan plus a signed approval envelope and executes only after scope, signature,
+  expiry, single-use, cancellation, and plan-identity checks. The envelope is required for effects and for every
+  read step that names a `sourceId`; only non-source inspection may use read-only auto-execution.
+
+```ts
+import { createNlMapControlMcpHost, createServer } from "@honua/mcp-server";
+
+const nlMapControl = createNlMapControlMcpHost({
+  control: {
+    tools: { runtime },
+    llm: callYourModel,
+    approvalVerifier,
+    receiptSigner,
+  },
+  approvalUseConsumer, // host-owned atomic consume + verify callbacks
+  resolveAuthorizationScopes: (transportScopes) => transportScopes,
+});
+
+const server = createServer(honuaClient, { nlMapControl });
+```
+
+The callbacks are deliberately not inferred from environment variables: model
+transport, map authority, signing keys, and replay storage remain host-owned.
+The MCP response omits raw tool results and the original instruction from its
+execution receipt. Plans containing credential, cursor, or endpoint material
+are refused instead of returning a redacted plan that could no longer match its
+approval fingerprint.
 
 ## MCP Resources
 
 - `honua://services`
 - `honua://services/{encodedServiceId}/layers/{layerId}`
+- `honua://styles`, `honua://styles/{styleId}` — structured-unavailable on a plain FeatureServer
 
 ## Certification
 
@@ -72,9 +154,36 @@ npm run certify
 
 # CI entry points (also runnable locally):
 npm run test:certification            # gate: runs harness tests + certifier, exits non-zero on failure
+npm run test:certification:nl-map-control # gate: approval/scope/replay/cancellation/receipt security matrix
 npm run test:certification:artifact   # evidence: writes artifacts, always exits 0
 ```
 
+The certification test lane also hosts the optional NL tools over an in-memory
+MCP transport with a deterministic fixture completion and mock map runtime. It proves
+propose→approve→execute plus missing, expired, replayed, wrong-scope, tampered,
+cancelled, deterministic-receipt, and redaction cases without a model, API key,
+network service, or wall-clock dependency.
+
+### Platform-free certification lane
+
+A dedicated **standalone** target (`HONUA_MCP_CERT_TARGET=standalone`, or
+`--target standalone`) certifies the platform-free surface against an in-process
+fixture of a **plain public FeatureServer** — the recorded US Census 2020
+apportionment layer from `services.arcgis.com`, with **no** Honua surfaces. It
+proves the tools certify **green with honest skips** against a non-Honua endpoint:
+the data tools round-trip against real recorded data, the Honua-only style tools
+degrade to structured "not available" results, and the auth/mutation/job contracts
+skip-with-reason. Fixture-backed and deterministic — no network.
+
+```bash
+npm run certify:standalone            # platform-free cert (plain FeatureServer fixture)
+npm run test:certification:standalone # CI gate variant
+```
+
+The fixture is recorded by `scripts/record-census-fixtures.mjs` into
+`src/certification/census-data.ts`; the evaluator that replays it is verified for
+parity against the live recordings in `test/certification/census-fixture-client.test.ts`.
+
 Artifacts are written to the package root as
 `mcp-certification-results.json` and `mcp-certification-results.md` (gitignored;
 uploaded by CI). To certify against a **live** honua-server, set `HONUA_BASE_URL`
@@ -147,6 +256,23 @@ by CI) record the per-model scorecard. The CI gate asserts the deterministic
 control passes every scenario; live cross-model runs are recorded but
 informational.
 
+### Platform-free semantic corpus (`src/eval/standalone-corpus.ts`)
+
+The **standalone** corpus is 50+ scenarios run against the plain public
+FeatureServer fixture (the census layer) with **semantic** grading — not just tool
+trajectory. Each scenario asserts the *meaning* of the answer: correct feature
+counts (52 rows, 4 states with ≥20 seats), correct geographic facts (California is
+the most populous; Wyoming the least; the House totals 435 seats), correct tool
+selection for ambiguous asks (count vs. query vs. statistics), refusal /
+clarification behavior on ambiguous or unsupported requests, and anti-hallucination
+guards. Because the fixture replays real recorded data, a wrong number or a
+hallucinated place name fails. The grading taxonomy is documented in
+[`evals/README.md`](evals/README.md).
+
+```bash
+npm run eval:standalone       # deterministic control over the census fixture (offline)
+```
+
 ### Live lane (paid, manual only)
 
 The **operator corpus** (`src/eval/operator-corpus.ts`, 8 harder scenarios) is

package/certification/geospatial-mcp-schemas/PROVENANCE.md

@@ -5,11 +5,17 @@ machine-readable schemas from the open **geospatial-mcp** standard.
 
 - **Source repo:** https://github.com/honua-io/geospatial-mcp
 - **Source path:** `spec/schemas/`
-- **Source commit:** `54cbd49a6b8bf408024fe4d0316f79b8fa0534ab`
-  (`spec: align prose + served-family schemas to the honua-server /mcp grammar; harden strict manifest gate (#44)`)
-- **Schema index date:** `2026-07-01`
+- **Source commit:** `eb53989cc61c856261cf017b4b5a8e721317dc41`
+  (`feat: direct geoprocessing verbs (analysis profile) + geometryPrecision/maxInlineBytes (#55)`)
+- **Schema index date:** `2026-07-06`
 - **Dialect:** JSON Schema draft 2020-12
 
+> The pin is deliberately held at `eb53989` (pre geospatial-mcp#58): the #58
+> platform-ops schemas are marked implemented in the manifest but honua-server
+> does not serve those tools yet, so re-vendoring past #58 would introduce
+> conformance failures. The post-#58 bump is owned by honua-server#2555/#2566,
+> which implement the new tools and vendor their schemas together.
+
 ## Why vendored
 
 The MCP certification harness (`src/certification/`) must run deterministically
@@ -19,10 +25,12 @@ a known, reproducible revision and removes any cross-repo fetch at certify time.
 
 ## Refreshing
 
-To re-pin to a newer published revision, re-copy `spec/schemas/` from the
-`geospatial-mcp` repo at the desired tag/commit and update the source commit and
-index date above. Do not hand-edit individual schema files; the standard is owned
-upstream.
+To re-pin to a newer published revision, edit the **Source commit** SHA (and the
+index date) above, then run `scripts/sync-schemas.sh --write` from the repo root
+to re-copy `spec/schemas/` verbatim from that commit. Do not hand-edit individual
+schema files; the standard is owned upstream. The `schema-sync` CI workflow
+(`.github/workflows/schema-sync.yml`) runs `scripts/sync-schemas.sh` on every PR
+and fails on any byte difference from the pinned commit.
 
 ## Index
 

package/certification/geospatial-mcp-schemas/conformance/manifest.schema.json

@@ -23,6 +23,12 @@
         "isReferenceImplementation": {
           "type": "boolean",
           "description": "True only for the reference implementation named in /CONFORMANCE.md (Honua). Other implementations omit this or set it false."
+        },
+        "profiles": {
+          "type": "array",
+          "description": "Conformance profiles this implementation claims (default ['base'] when omitted). 'base' is the read-only floor; additive profiles such as 'mutation' require the implementation to advertise every tool the index assigns to that profile to reach FULL. See /CONFORMANCE.md §Conformance Profiles.",
+          "items": { "type": "string" },
+          "uniqueItems": true
         }
       }
     },

package/certification/geospatial-mcp-schemas/index.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "geospatial-mcp JSON Schema index",
-  "description": "Machine-readable map from standard MCP tool names and resource family URIs to their JSON Schema (draft 2020-12) files. 'standardName' is the bare taxonomy.md tool name; 'referenceToolName' is the name the reference implementation (Honua /mcp) advertises. 'implementationStatus' records whether the reference implementation ships the tool/resource family today (implemented) or whether it is a standard family not yet served by the reference (known-gap). For resources, 'implementationStatus' gates the FULL conformance level the same way it does for tools: a manifest must advertise every 'implemented' resource family to reach FULL; 'known-gap' families are reported as informational notes only.",
-  "date": "2026-07-01",
+  "description": "Machine-readable map from standard MCP tool names and resource family URIs to their JSON Schema (draft 2020-12) files. 'standardName' is the bare taxonomy.md tool name; 'referenceToolName' is the name the reference implementation (Honua /mcp) advertises. 'implementationStatus' records whether the reference implementation ships the tool/resource family today (implemented) or whether it is a standard family not yet served by the reference (known-gap). For resources, 'implementationStatus' gates the FULL conformance level the same way it does for tools: a manifest must advertise every 'implemented' resource family to reach FULL; 'known-gap' families are reported as informational notes only. 'profile' (optional; default 'base') assigns a tool to a conformance profile: 'base' tools are required for the base FULL verdict; tools in an additive profile such as 'mutation' are required for FULL only when a manifest declares that profile, and are otherwise reported as informational notes (see /CONFORMANCE.md §Conformance Profiles).",
+  "date": "2026-07-06",
   "dialect": "https://json-schema.org/draft/2020-12/schema",
   "tools": [
     {
@@ -58,17 +58,17 @@
     },
     {
       "standardName": "get_style",
-      "referenceToolName": null,
+      "referenceToolName": "honua_get_style",
       "family": "Style inspection",
       "schema": "tools/get_style.schema.json",
-      "implementationStatus": "known-gap"
+      "implementationStatus": "implemented"
     },
     {
       "standardName": "apply_style_preset",
-      "referenceToolName": null,
-      "family": "Map composition",
+      "referenceToolName": "honua_apply_style_preset",
+      "family": "Map composition (reference shape)",
       "schema": "tools/apply_style_preset.schema.json",
-      "implementationStatus": "known-gap"
+      "implementationStatus": "implemented"
     },
     {
       "standardName": "compose_mixed_protocol_map",
@@ -101,10 +101,11 @@
     },
     {
       "standardName": "publish_result",
-      "referenceToolName": null,
+      "referenceToolName": "honua_publish_result",
       "family": "Publishing",
       "schema": "tools/publish_result.schema.json",
-      "implementationStatus": "known-gap"
+      "implementationStatus": "implemented",
+      "notes": "honua_publish_result (honua-server#2482) promotes a completed analysis job's materialized FeatureLayer/Table artifact (sourceId = the job id) into a hosted published service + layer, routing through the same canonical service.publish promotion as honua_publish_service. The standard schema requires only sourceId; the reference tool adds honua extension selectors (artifactId / serviceName / layerName) under additionalProperties. Analyze / Publish Data (published_service) is implemented; Build App (deployment) promotion is deferred (honua-server#730/#732)."
     },
     {
       "standardName": "list_layers",
@@ -121,6 +122,15 @@
       "schema": "tools/query_features.schema.json",
       "implementationStatus": "implemented"
     },
+    {
+      "standardName": "edit_features",
+      "referenceToolName": null,
+      "family": "Feature editing",
+      "schema": "tools/edit_features.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "mutation",
+      "notes": "Sole member of the optional mutation conformance profile (docs/adr/0028-governed-feature-mutation.md). Governed transactional editing: an implementation must require an authenticated, authorized caller and authorize each edit type (insert/update/delete) independently. The reference implementation (Honua) does NOT serve this tool — Honua does not support AI operational data editing (honua-server ADR-0028, founder-reaffirmed 2026-07-06); its referenceToolName is null and its implementationStatus is known-gap. Base-profile (read-only) implementations conform without advertising this tool; it is required for FULL only when an adopter's manifest declares the mutation profile."
+    },
     {
       "standardName": "render_map",
       "referenceToolName": "honua_render_map",
@@ -135,6 +145,13 @@
       "schema": "tools/geocode_address.schema.json",
       "implementationStatus": "implemented"
     },
+    {
+      "standardName": "geocode_addresses",
+      "referenceToolName": "honua_geocode_addresses",
+      "family": "Analysis and geoprocessing (reference shape)",
+      "schema": "tools/geocode_addresses.schema.json",
+      "implementationStatus": "implemented"
+    },
     {
       "standardName": "solve_route",
       "referenceToolName": "honua_solve_route",
@@ -142,6 +159,60 @@
       "schema": "tools/solve_route.schema.json",
       "implementationStatus": "implemented"
     },
+    {
+      "standardName": "buffer_features",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/buffer_features.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb; member of the opt-in analysis conformance profile (docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Single-step buffer, an alternative to a plan_analysis/execute_plan Geoprocess step. The reference implementation does not ship a direct verb yet; required for FULL only when a manifest declares the analysis profile."
+    },
+    {
+      "standardName": "overlay_features",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/overlay_features.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb (analysis profile; docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Two-input overlay: intersect/union/difference/erase/clip. Not yet shipped by the reference; required for FULL only when a manifest declares the analysis profile."
+    },
+    {
+      "standardName": "summarize_statistics",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/summarize_statistics.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb (analysis profile; docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Group-by + statistics over a layer or a prior overlay/verb result. Not yet shipped by the reference; required for FULL only when a manifest declares the analysis profile."
+    },
+    {
+      "standardName": "reproject_features",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/reproject_features.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb (analysis profile; docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Reproject a dataset to a targetSrid; the sibling verbs also carry an optional outSrid output-CRS param. Not yet shipped by the reference; required for FULL only when a manifest declares the analysis profile."
+    },
+    {
+      "standardName": "join_features",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/join_features.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb (analysis profile; docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Attribute or spatial join of two datasets. Not yet shipped by the reference; required for FULL only when a manifest declares the analysis profile."
+    },
+    {
+      "standardName": "export_dataset",
+      "referenceToolName": null,
+      "family": "Analysis verbs",
+      "schema": "tools/export_dataset.schema.json",
+      "implementationStatus": "known-gap",
+      "profile": "analysis",
+      "notes": "Direct geoprocessing verb (analysis profile; docs/adr/0029-direct-geoprocessing-verbs.md, geospatial-mcp#53). Materialize a layer/result to a GeoJSON/GeoPackage/CSV/Parquet artifact. Advertised readOnlyHint:false (writes a new artifact) but non-destructive and not a mutation-profile tool. Not yet shipped by the reference; required for FULL only when a manifest declares the analysis profile."
+    },
     {
       "standardName": "cancel_job",
       "referenceToolName": "honua_cancel_job",
@@ -156,6 +227,14 @@
       "schema": "tools/propose_operation.schema.json",
       "implementationStatus": "implemented"
     },
+    {
+      "standardName": "ingest_dataset",
+      "referenceToolName": "honua_ingest_dataset",
+      "family": "Publishing",
+      "schema": "tools/ingest_dataset.schema.json",
+      "implementationStatus": "implemented",
+      "notes": "Publish Data ingest step of the reference implementation: inline CSV/GeoJSON to a catalog table whose {connectionId, schema, table} chains into publish_service. Closes the data-loading gap ahead of the standard's file/URL ingest contract."
+    },
     {
       "standardName": "publish_service",
       "referenceToolName": "honua_publish_service",

package/certification/geospatial-mcp-schemas/tools/apply_style_preset.schema.json

@@ -2,22 +2,26 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/apply_style_preset.schema.json",
   "title": "apply_style_preset inputSchema",
-  "description": "Argument shape for apply_style_preset (Analyze, Build App; returns the updated MapPackage). Applies a reusable StyleRef preset to a map package, optionally scoped to a binding. Responsibility-level; concrete styling field set finalizes upstream. See taxonomy.md §Map composition and resources.md §honua://styles/{style_id}.",
+  "description": "Argument shape for apply_style_preset. x-honua-reference-shape: this shape tracks the reference implementation (advertised name honua_apply_style_preset), which applies a reusable StyleRef preset (a catalog styleId) as the primary/default style of a published layer, persisting through the server OGC API – Styles authoring surface (ADR-0048) so subsequent render_map calls reflect it. The bare taxonomy responsibility (map-package composition) is described in taxonomy.md §Map composition; the reference implementation binds presets to published layers rather than to an in-memory MapPackage. Applying a preset never edits feature records (ADR-0028); it authors presentation metadata on the hosted service. See taxonomy.md §Map composition and resources.md §honua://styles.",
+  "x-honua-reference-shape": true,
   "type": "object",
   "additionalProperties": true,
-  "required": ["mapPackageId", "styleId"],
+  "required": ["serviceId", "layerId", "styleId"],
   "properties": {
-    "mapPackageId": {
+    "serviceId": {
       "type": "string",
-      "description": "Identifier (map_…) of the MapPackage to style."
+      "minLength": 1,
+      "description": "Published service identifier or name whose layer is being styled."
     },
-    "styleId": {
-      "type": "string",
-      "description": "StyleRef preset identifier (style_…) to apply."
+    "layerId": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Service-local layer index to apply the preset to."
     },
-    "targetBindingId": {
+    "styleId": {
       "type": "string",
-      "description": "Optional SourceBinding the preset is scoped to; applies map-wide when omitted."
+      "minLength": 1,
+      "description": "StyleRef preset identifier (style_…) to apply as the layer's primary/default style. Discover the available presets with get_style (no styleId lists honua://styles)."
     }
   }
 }

package/certification/geospatial-mcp-schemas/tools/buffer_features.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/buffer_features.schema.json",
+  "title": "buffer_features inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_buffer_features): buffer input features by a distance and return the buffer polygons. Use this for a single self-contained buffer step (\"buffer these roads by 500 m\"); for multi-step analysis with dependencies, clarification, and a packaged result, use plan_analysis + execute_plan instead. Member of the standard's opt-in **analysis** conformance profile (see /CONFORMANCE.md and docs/adr/0029-direct-geoprocessing-verbs.md). Long-running calls return an ExecutionJob handle (honua://jobs/{job_id}), pollable and cancelable via cancel_job; small/fast calls may return an inline result — the same handoff execute_plan uses. Advertised readOnlyHint: true (computes a derived result; mutates no server state). x-honua-reference-shape: the concrete source (serviceId/layerId, artifactId) spellings track the reference pipeline.",
+  "x-honua-reference-shape": true,
+  "type": "object",
+  "required": ["source", "distance"],
+  "properties": {
+    "source": {
+      "description": "Dataset to buffer: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId) from an earlier analysis job or verb.",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "distance": {
+      "type": "number",
+      "description": "Buffer distance in the given unit. Negative distances buffer inward for polygon inputs."
+    },
+    "unit": {
+      "type": "string",
+      "default": "meters",
+      "enum": ["meters", "kilometers", "feet", "miles", "nautical_miles", "degrees"],
+      "description": "Linear unit of distance."
+    },
+    "dissolve": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, overlapping buffers are dissolved into a single geometry; when false, one buffer per input feature is returned."
+    },
+    "where": {
+      "type": "string",
+      "description": "Optional attribute filter (ArcGIS/SQL WHERE clause) selecting which input features to buffer."
+    },
+    "outSrid": {
+      "type": "integer",
+      "description": "Output spatial reference (SRID/WKID) for the returned buffers; defaults to the source CRS. Buffer distances are always measured in the given unit regardless of outSrid."
+    }
+  },
+  "$defs": {
+    "layerRef": {
+      "type": "object",
+      "required": ["serviceId", "layerId"],
+      "additionalProperties": false,
+      "properties": {
+        "serviceId": { "type": "string", "minLength": 1, "description": "Published service identifier or name (from list_layers.serviceId or resolve_entity)." },
+        "layerId": { "type": "integer", "minimum": 0, "description": "Service-local layer index (from list_layers.layerId)." }
+      }
+    },
+    "artifactRef": {
+      "type": "object",
+      "required": ["artifactId"],
+      "additionalProperties": false,
+      "properties": {
+        "artifactId": { "type": "string", "minLength": 1, "description": "Identifier (artifact_…) of a prior-result ArtifactRef produced by an earlier analysis job or verb. See resources/artifact.schema.json." }
+      }
+    }
+  }
+}

package/certification/geospatial-mcp-schemas/tools/edit_features.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/edit_features.schema.json",
+  "title": "edit_features inputSchema",
+  "description": "Argument shape for the transactional feature-editing tool (advertised name honua_edit_features). edit_features is the sole member of the standard's **mutation** conformance profile (see /CONFORMANCE.md and docs/adr/0028-governed-feature-mutation.md): it applies adds/updates/deletes to a single published editable layer as one all-or-nothing transaction when rollbackOnFailure=true (the default). It is governed mutation, not autonomous mutation: an implementation MUST require an authenticated, authorized caller and MUST authorize each edit type independently (insert for adds, update for updates, delete for deletes), rejecting the whole request before any edit is applied if any required permission is missing. An implementation MAY be read-only and still conform to the base profile by not advertising this tool. x-honua-reference-shape: the concrete objectId/globalId/attributes spellings track the reference implementation's shared edit/transaction pipeline; see taxonomy.md §Feature editing (mutation profile).",
+  "x-honua-reference-shape": true,
+  "type": "object",
+  "required": ["serviceId", "layerId"],
+  "properties": {
+    "serviceId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Published service identifier or name (from list_layers.serviceId or resolve_entity)."
+    },
+    "layerId": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Service-local layer index of the editable layer (from list_layers.layerId)."
+    },
+    "srid": {
+      "type": "integer",
+      "default": 4326,
+      "description": "Spatial reference (SRID/WKID) of the input feature geometries."
+    },
+    "adds": {
+      "type": "array",
+      "description": "Features to insert. Requires insert authorization on the target layer. Object IDs are assigned by the store.",
+      "items": { "$ref": "#/$defs/editFeature" }
+    },
+    "updates": {
+      "type": "array",
+      "description": "Features to update. Requires update authorization on the target layer. Each MUST carry an objectId identifying the existing feature.",
+      "items": { "$ref": "#/$defs/editFeature" }
+    },
+    "deletes": {
+      "type": "array",
+      "description": "Object IDs of features to delete. Requires delete authorization on the target layer.",
+      "items": { "type": "integer" }
+    },
+    "rollbackOnFailure": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (the default), any failed edit rolls back the whole transaction (all-or-nothing) and the layer is left unchanged; when false, successful edits commit independently and per-edit failures are reported."
+    },
+    "returnEditResults": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true, per-edit results are returned; when false only the transaction summary is emitted."
+    }
+  },
+  "$defs": {
+    "editFeature": {
+      "type": "object",
+      "properties": {
+        "objectId": {
+          "type": "integer",
+          "description": "Object ID of the target feature. Required for updates; ignored for adds."
+        },
+        "globalId": {
+          "type": "string",
+          "description": "Optional global ID of the feature."
+        },
+        "geometry": {
+          "type": ["object", "null"],
+          "description": "RFC 7946 GeoJSON geometry object (e.g. {\"type\":\"Point\",\"coordinates\":[1,2]})."
+        },
+        "attributes": {
+          "type": "object",
+          "description": "Flat attribute name/value map applied to the feature."
+        }
+      }
+    }
+  }
+}