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

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

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/export_dataset.schema.json",
+  "title": "export_dataset inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_export_dataset): materialize a dataset — a published layer or a prior verb/job result — into a downloadable artifact in the requested format and return an ArtifactRef with a content locator. Use this for a single self-contained export step (\"export the intersect result as GeoPackage\"); for multi-step analysis with dependencies 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 referencing the produced artifact. Advertised readOnlyHint: false — it writes a new downloadable artifact — but non-destructive (it creates a new artifact and mutates no source records) and idempotent. It is NOT feature mutation and is not part of the mutation profile. x-honua-reference-shape: the concrete source (serviceId/layerId, artifactId) spellings track the reference pipeline.",
+  "x-honua-reference-shape": true,
+  "type": "object",
+  "required": ["source", "format"],
+  "properties": {
+    "source": {
+      "description": "Dataset to export: 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" }
+      ]
+    },
+    "format": {
+      "type": "string",
+      "enum": ["geojson", "geopackage", "csv", "parquet"],
+      "description": "Output format. geojson: RFC 7946 features. geopackage: OGC GeoPackage (.gpkg). csv: attribute rows (geometry as WKT when returnGeometry). parquet: (Geo)Parquet columnar."
+    },
+    "where": {
+      "type": "string",
+      "description": "Optional attribute filter (ArcGIS/SQL WHERE clause) selecting which features to export."
+    },
+    "outFields": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional attribute fields to include; omit for all fields."
+    },
+    "returnGeometry": {
+      "type": "boolean",
+      "default": true,
+      "description": "When false, export attributes only (no geometry). csv/parquet exports of attribute tables commonly set this false."
+    },
+    "outSrid": {
+      "type": "integer",
+      "description": "Output spatial reference (SRID/WKID) for exported geometries; defaults to the source CRS."
+    }
+  },
+  "$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/geocode_addresses.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/geocode_addresses.schema.json",
+  "title": "geocode_addresses inputSchema",
+  "description": "Argument shape for the analysis/geoprocessing batch geocode tool (advertised name honua_geocode_addresses). Resolves up to 100 freeform addresses in one call, returning one result per input in input order ({input, ok, location?, score?, error?}); a failed address surfaces per item without failing the batch. First step of the CSV-of-addresses workflow: geocode here, then load the coordinates with ingest_dataset and publish the table with publish_service. x-honua-reference-shape: this shape tracks the reference implementation.",
+  "x-honua-reference-shape": true,
+  "type": "object",
+  "required": ["addresses"],
+  "properties": {
+    "addresses": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 100,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Freeform single-line addresses to geocode, in the order results should be returned."
+    },
+    "countryCodes": {
+      "type": "string",
+      "description": "Optional comma-separated ISO 3166 country codes to restrict the search."
+    },
+    "outSrid": {
+      "type": "integer",
+      "default": 4326,
+      "description": "Spatial reference (SRID/WKID) for returned coordinates (x=longitude, y=latitude order). Defaults to 4326 (WGS84 lon/lat)."
+    },
+    "provider": {
+      "type": "string",
+      "description": "Optional preferred geocoding provider name."
+    }
+  }
+}

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

@@ -2,13 +2,23 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/get_style.schema.json",
   "title": "get_style inputSchema",
-  "description": "Argument shape for get_style (Analyze, Publish Data, Build App). Read-only style inspection: with styleId, resolves a single canonical StyleRef (style_id/title/encodings) from the server OGC API – Styles surface; without styleId, lists the available styles (honua://styles). Like every MCP tool it is read-only and never mutates server-side styles. See taxonomy.md §Style inspection and resources.md §honua://styles/{style_id}.",
+  "description": "Argument shape for get_style (Analyze, Publish Data, Build App). Read-only style inspection: with styleId, resolves a single canonical StyleRef (style_id/title/encodings) from the server OGC API – Styles surface; with serviceId+layerId (a reference-implementation convenience) resolves the primary/default StyleRef bound to that published layer; with none of these, lists the available styles (honua://styles). Like every MCP tool it is read-only and never mutates server-side styles. See taxonomy.md §Style inspection and resources.md §honua://styles.",
   "type": "object",
   "properties": {
     "styleId": {
       "type": "string",
       "minLength": 1,
-      "description": "StyleRef identifier (style_…) to resolve. When omitted, the tool lists the available styles (honua://styles)."
+      "description": "StyleRef identifier (style_…) to resolve. When omitted, the tool resolves the styleId bound to serviceId+layerId, or lists the available styles (honua://styles) when neither is given."
+    },
+    "serviceId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reference-implementation shape (honua_get_style): published service identifier or name. Paired with layerId, resolves that layer's primary/default StyleRef when styleId is omitted."
+    },
+    "layerId": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Reference-implementation shape (honua_get_style): service-local layer index. Paired with serviceId, resolves that layer's primary/default StyleRef when styleId is omitted."
     },
     "encoding": {
       "type": "string",
@@ -24,7 +34,7 @@
     },
     "includeStylesheet": {
       "type": "boolean",
-      "description": "When true and styleId is set, include the resolved stylesheet body (inlineBody) for the selected encoding; otherwise the StyleRef projection advertises derived encodings by reference (storageRef)."
+      "description": "When true and a single style resolves, include the resolved stylesheet body (inlineBody) for the selected encoding; otherwise the StyleRef projection advertises derived encodings by reference (storageRef)."
     }
   }
 }

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

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/ingest_dataset.schema.json",
+  "title": "ingest_dataset inputSchema",
+  "description": "Argument shape for the Publish Data ingest tool (advertised name honua_ingest_dataset). Loads a small inline dataset (CSV with a header row, or a GeoJSON FeatureCollection; 4 MB cap) into the reference implementation's catalog database as a table, returning the {connectionId, schema, table} triple plus row count and per-row errors so the result chains directly into publish_service. CSV point geometry comes from longitude/latitude columns (auto-detected or explicit), a WKT column, or a server-geocoded address column; coordinate order is lon/lat and the CRS defaults to EPSG:4326. x-honua-reference-shape: this shape tracks the reference implementation.",
+  "x-honua-reference-shape": true,
+  "type": "object",
+  "required": ["format", "data", "datasetName"],
+  "properties": {
+    "format": {
+      "type": "string",
+      "enum": ["csv", "geojson"],
+      "description": "Inline data format: \"csv\" (text with a header row) or \"geojson\" (a GeoJSON FeatureCollection document)."
+    },
+    "data": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The dataset content, inline. Capped at 4 MB; larger datasets use the implementation's out-of-band upload surface."
+    },
+    "datasetName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63,
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "description": "Target dataset/table name (letters, digits, underscores; must not start with a digit)."
+    },
+    "sourceSrid": {
+      "type": "integer",
+      "default": 4326,
+      "description": "Spatial reference (SRID/WKID) of the input coordinates; data is stored in EPSG:4326. Defaults to 4326 (WGS84 lon/lat)."
+    },
+    "longitudeColumn": {
+      "type": "string",
+      "description": "CSV only: explicit longitude (X) column name. Pair with latitudeColumn. When omitted, lon/lng/long/longitude/x is auto-detected."
+    },
+    "latitudeColumn": {
+      "type": "string",
+      "description": "CSV only: explicit latitude (Y) column name. Pair with longitudeColumn. When omitted, lat/latitude/y is auto-detected."
+    },
+    "addressColumn": {
+      "type": "string",
+      "description": "CSV only: column holding freeform addresses to geocode into point geometry server-side (up to 100 rows). Mutually exclusive with longitudeColumn/latitudeColumn."
+    }
+  }
+}

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

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/join_features.schema.json",
+  "title": "join_features inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_join_features): join a second dataset onto a target dataset — either an attribute join on matching key fields or a spatial join by geometric relationship — and return the joined features. Use this for a single self-contained join step (\"attach the demographics table to the tracts\", \"tag each incident with the county it falls in\"); for multi-step analysis with dependencies 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. 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": ["target", "join", "joinType"],
+  "properties": {
+    "target": {
+      "description": "Target (left) dataset whose features are kept and enriched: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId).",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "join": {
+      "description": "Join (right) dataset supplying attributes to append: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId).",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "joinType": {
+      "type": "string",
+      "enum": ["attribute", "spatial"],
+      "description": "attribute: match on equal key fields (targetField = joinField). spatial: match by geometric relationship (spatialRelationship)."
+    },
+    "targetField": {
+      "type": "string",
+      "description": "Attribute join only: key field on the target dataset. Required when joinType is attribute."
+    },
+    "joinField": {
+      "type": "string",
+      "description": "Attribute join only: key field on the join dataset matched against targetField. Required when joinType is attribute."
+    },
+    "spatialRelationship": {
+      "type": "string",
+      "enum": ["intersects", "contains", "within", "nearest"],
+      "description": "Spatial join only: geometric predicate relating a target feature to join features. Required when joinType is spatial."
+    },
+    "joinOperation": {
+      "type": "string",
+      "default": "one_to_one",
+      "enum": ["one_to_one", "one_to_many"],
+      "description": "one_to_one: one output row per target feature (matches aggregated per joinAggregation on conflict). one_to_many: one output row per matching pair."
+    },
+    "joinAggregation": {
+      "type": "string",
+      "enum": ["first", "count", "sum", "min", "max", "mean"],
+      "description": "one_to_one only: how to reduce multiple matches for a target feature. Defaults to an implementation-defined first-match when omitted."
+    }
+  },
+  "$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/overlay_features.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/overlay_features.schema.json",
+  "title": "overlay_features inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_overlay_features): compute a two-input topological overlay (intersect, union, difference, erase, or clip) and return the result features. Use this for a single self-contained overlay step (\"intersect the flood zones with the parcels\"); for multi-step analysis with dependencies 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. 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", "overlay", "operation"],
+  "properties": {
+    "source": {
+      "description": "Primary input dataset: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId).",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "overlay": {
+      "description": "Overlay dataset combined with source: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId).",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "operation": {
+      "type": "string",
+      "enum": ["intersect", "union", "difference", "erase", "clip"],
+      "description": "Overlay operation. intersect: geometry AND attributes of both where they overlap. union: full combination of both inputs. difference: source minus overlay (source attributes kept). erase: remove the overlay area from source. clip: cut source to the overlay boundary (source attributes only)."
+    },
+    "outSrid": {
+      "type": "integer",
+      "description": "Output spatial reference (SRID/WKID) for the returned overlay features; defaults to the source CRS."
+    }
+  },
+  "$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/query_features.schema.json

@@ -45,10 +45,30 @@
       "default": 100,
       "description": "Maximum number of features to return (capped at 1000)."
     },
+    "resultOffset": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Number of matching features to skip before returning results (pagination). Pair with limit to page mechanically through large result sets: when a response reports exceededTransferLimit=true, re-issue the same query with resultOffset set to the returned nextOffset until exceededTransferLimit is false."
+    },
+    "returnGeometry": {
+      "type": "boolean",
+      "default": true,
+      "description": "When false, features are returned without geometry (attribute-only rows). Use for attribute scans where returning geometry would waste the response/context budget."
+    },
+    "returnCountOnly": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, return only the matching feature count and no features. Use for cheap cardinality checks before deciding whether/how to page."
+    },
     "outSrid": {
       "type": "integer",
       "default": 4326,
       "description": "Output spatial reference (SRID/WKID) for returned geometries."
+    },
+    "geometryPrecision": {
+      "type": "integer",
+      "description": "Optional number of decimal places to round returned GeoJSON coordinates to, trading positional precision for a smaller response/context budget. A negative value returns full precision. When omitted, precision is implementation-defined; the reference implementation defaults to 6 (~0.1 m), which cuts coordinate payload roughly 12% at the default and far more for dense geometries. Standardized from the honua-server x-honua extension (geospatial-mcp#52)."
     }
   }
 }

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

@@ -50,6 +50,11 @@
       "type": "boolean",
       "default": false,
       "description": "Render a transparent background instead of an opaque one."
+    },
+    "maxInlineBytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional ceiling, in bytes, on inline base64 image content. When the rendered image is at or below this size it may be returned inline; above it, the tool returns a resource_link href to the image instead of inlining megabytes of PNG into model context. When omitted, inlining behavior is implementation-defined; the reference implementation defaults to returning a resource_link href rather than inlining. Standardized from the honua-server x-honua extension (geospatial-mcp#52)."
     }
   }
 }

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

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/reproject_features.schema.json",
+  "title": "reproject_features inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_reproject_features): reproject a whole dataset into a target spatial reference and return the reprojected features. Use this when reprojection is the goal (\"give me this layer in EPSG:3857\"); when you only need another verb's output in a particular CRS, prefer that verb's optional outSrid param instead of a second call. For multi-step analysis with dependencies 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. 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", "targetSrid"],
+  "properties": {
+    "source": {
+      "description": "Dataset to reproject: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId).",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "targetSrid": {
+      "type": "integer",
+      "description": "Target spatial reference (SRID/WKID) to reproject into. Required — it is the operation's defining parameter."
+    },
+    "sourceSrid": {
+      "type": "integer",
+      "description": "Spatial reference (SRID/WKID) of the input geometries; defaults to the dataset's declared CRS. Provide only to override a missing or incorrect source CRS."
+    },
+    "where": {
+      "type": "string",
+      "description": "Optional attribute filter (ArcGIS/SQL WHERE clause) selecting which input features to reproject."
+    }
+  },
+  "$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/summarize_statistics.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/tools/summarize_statistics.schema.json",
+  "title": "summarize_statistics inputSchema",
+  "description": "Direct geoprocessing verb (advertised name honua_summarize_statistics): compute summary statistics over a dataset, optionally grouped by attribute fields, and return the summary rows. Use this for a single self-contained summary step (\"total population by county\", \"mean parcel value by zoning\") over a layer or a prior overlay/verb result; for multi-step analysis with dependencies 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. 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", "statistics"],
+  "properties": {
+    "source": {
+      "description": "Dataset to summarize: EITHER a published layer (serviceId + layerId) OR a prior-result artifact (artifactId) such as an overlay_features or join_features result.",
+      "oneOf": [
+        { "$ref": "#/$defs/layerRef" },
+        { "$ref": "#/$defs/artifactRef" }
+      ]
+    },
+    "groupByFields": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Attribute fields to group by. Omit for a single summary row over all matching features."
+    },
+    "statistics": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Statistics to compute. Each entry names a statistic type and the field it is computed on.",
+      "items": {
+        "type": "object",
+        "required": ["statisticType", "onField"],
+        "additionalProperties": false,
+        "properties": {
+          "statisticType": {
+            "type": "string",
+            "enum": ["count", "sum", "min", "max", "mean", "stddev", "var"],
+            "description": "Aggregate to compute. count ignores onField values (counts rows)."
+          },
+          "onField": {
+            "type": "string",
+            "description": "Attribute field the statistic is computed on."
+          },
+          "outField": {
+            "type": "string",
+            "description": "Optional name for the output column; defaults to an implementation-defined name derived from statisticType and onField."
+          }
+        }
+      }
+    },
+    "where": {
+      "type": "string",
+      "description": "Optional attribute filter (ArcGIS/SQL WHERE clause) selecting which input features are summarized."
+    }
+  },
+  "$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/dist/src/agent-execution.d.ts

@@ -0,0 +1,16 @@
+import type { AgentOperationExecutorV1 } from "@honua/sdk-js/agent-safety";
+import type { JsonValue } from "@honua/sdk-js/query-planner";
+/** A named, read-only MCP tool handler adapted to the SDK approval boundary. */
+export interface ReadOnlyMcpAgentTool<TArguments> {
+    readonly name: string;
+    parse(parameters: JsonValue): TArguments;
+    execute(arguments_: TArguments, signal?: AbortSignal): Promise<unknown>;
+    /** Deterministically count logical rows/records in the returned MCP result. */
+    countRows(result: unknown): number;
+}
+/**
+ * Adapt a standalone MCP read tool without introducing a second approval or
+ * audit model. The SDK validates the exact tool/effect before this handler runs.
+ */
+export declare function createReadOnlyMcpAgentExecutor<TArguments>(tool: ReadOnlyMcpAgentTool<TArguments>): AgentOperationExecutorV1;
+//# sourceMappingURL=agent-execution.d.ts.map

package/dist/src/agent-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution.d.ts","sourceRoot":"","sources":["../../src/agent-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAE7D,gFAAgF;AAChF,MAAM,WAAW,oBAAoB,CAAC,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,UAAU,EAAE,SAAS,GAAG,UAAU,CAAC;IACzC,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EACvD,IAAI,EAAE,oBAAoB,CAAC,UAAU,CAAC,GACrC,wBAAwB,CA0B1B"}

package/dist/src/agent-execution.js

@@ -0,0 +1,46 @@
+/**
+ * Adapt a standalone MCP read tool without introducing a second approval or
+ * audit model. The SDK validates the exact tool/effect before this handler runs.
+ */
+export function createReadOnlyMcpAgentExecutor(tool) {
+    if (!tool || typeof tool !== "object")
+        throw new TypeError("MCP tool descriptor is required");
+    const name = dataProperty(tool, "name");
+    if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(name))
+        throw new TypeError("MCP tool name must be a bounded exact identifier");
+    const parse = callback(tool, "parse");
+    const execute = callback(tool, "execute");
+    const countRows = callback(tool, "countRows");
+    return Object.freeze({
+        tool: name,
+        effect: "read",
+        async execute(operation, _limits, signal) {
+            if (operation.tool !== name || operation.effect !== "read")
+                throw new TypeError("approved operation does not match the read-only MCP tool");
+            const arguments_ = parse(operation.parameters);
+            const result = await execute(arguments_, signal);
+            const rows = countRows(result);
+            if (!Number.isSafeInteger(rows) || rows < 0)
+                throw new TypeError("MCP tool row count must be a non-negative safe integer");
+            return { rows, value: result };
+        },
+    });
+}
+function dataProperty(input, key) {
+    let descriptor;
+    try {
+        descriptor = Reflect.getOwnPropertyDescriptor(input, key);
+    }
+    catch {
+        throw new TypeError(`MCP tool ${key} could not be safely captured`);
+    }
+    if (!descriptor || descriptor.get || descriptor.set)
+        throw new TypeError(`MCP tool ${key} must be a data property`);
+    return descriptor.value;
+}
+function callback(input, key) {
+    const value = dataProperty(input, key);
+    if (typeof value !== "function")
+        throw new TypeError(`MCP tool ${key} callback is required`);
+    return value.bind(input);
+}

package/dist/src/capability.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Platform-free capability degradation (issue #369).
+ *
+ * `@honua/mcp-server` runs in two modes: against a Honua-enhanced deployment
+ * (which exposes extra surfaces such as OGC API – Styles) and — the platform-free
+ * front door — against ANY plain public Esri FeatureServer / OGC endpoint that
+ * has none of those surfaces. A tool that depends on a Honua-only surface must
+ * NEVER crash, hang, or return misleading empty data on a plain target. Instead
+ * it detects the missing surface and reports a clear, structured "not available
+ * on this target" result — the same skip-with-reason honesty the certification
+ * suite uses.
+ *
+ * Probing helpers throw {@link CapabilityUnavailableError} when a surface is
+ * absent; the tool/resource layer catches it and returns
+ * {@link capabilityUnavailable}, a non-error tool result carrying
+ * `available: false` plus a human-readable reason.
+ */
+export declare class CapabilityUnavailableError extends Error {
+    readonly code = "CAPABILITY_UNAVAILABLE";
+    /** Human label of the missing surface, e.g. "OGC API - Styles". */
+    readonly surface: string;
+    /** Why the surface was judged unavailable (status / parse / shape). */
+    readonly reason: string;
+    constructor(surface: string, reason: string);
+}
+/** Machine-readable body of a graceful capability-degradation result. */
+export interface CapabilityUnavailablePayload {
+    available: false;
+    surface: string;
+    reason: string;
+    /** What a client can do instead on a plain public endpoint. */
+    guidance: string;
+}
+/**
+ * Build a structured "not available on this target" tool/resource result. The
+ * result is deliberately NOT an MCP error: a plain FeatureServer legitimately
+ * lacks the surface, so degradation is an honest, expected outcome — not a
+ * failure. Clients branch on `available === false`.
+ */
+export declare function capabilityUnavailablePayload(surface: string, reason: string, guidance: string): CapabilityUnavailablePayload;
+/** Convenience: the {@link capabilityUnavailablePayload} body wrapped as tool text content. */
+export declare function capabilityUnavailable(surface: string, reason: string, guidance: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+//# sourceMappingURL=capability.d.ts.map

package/dist/src/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/capability.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM5C;AAED,yEAAyE;AACzE,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,4BAA4B,CAE9B;AAED,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;;;;;EAEtF"}