@honua/mcp-server 0.1.2-beta.0 → 0.1.8-beta.0

package/dist/src/index.d.ts

@@ -3,7 +3,10 @@ import { HonuaClient } from "@honua/sdk-js";
 import type { HonuaTransport } from "@honua/sdk-js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type NlMapControlMcpHost } from "./nl-map-control.js";
+import type { ControlPlaneCommandMcpHost } from "./tools/control-plane-command.js";
 export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
+export { CONTROL_PLANE_COMMAND_TOOL_PREFIX, controlPlaneCommandToolName, controlPlaneCommandToolSchema, registerControlPlaneCommandTools, } from "./tools/control-plane-command.js";
+export type { ControlPlaneCommandMcpHost } from "./tools/control-plane-command.js";
 export type { CreateNlMapControlMcpHostOptions, McpNlMapExecutionResponse, McpNlMapPlanResponse, McpNlMapReceipt, NlMapControlMcpHost, NlMapControlMcpRequestContext, } from "./nl-map-control.js";
 export interface RuntimeOptions {
     baseUrl: string;
@@ -15,6 +18,13 @@ export interface RuntimeOptions {
 export interface CreateServerOptions {
     /** Optional BYO-LLM/map-runtime host for the experimental NL map-plan tools. */
     readonly nlMapControl?: NlMapControlMcpHost;
+    /**
+     * Optional control-plane command runtime. When supplied, the server also
+     * publishes one generated thin adapter per shared command (see
+     * {@link registerControlPlaneCommandTools}). Omitted by default so the
+     * standalone catalog stays platform-free and read-only.
+     */
+    readonly controlPlaneCommands?: ControlPlaneCommandMcpHost;
 }
 export declare const SERVER_VERSION: string;
 export declare function resolveRuntimeOptions(env: NodeJS.ProcessEnv): RuntimeOptions;
@@ -22,13 +32,20 @@ export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClien
 /**
  * The PLATFORM-FREE standalone MCP surface (issue #369).
  *
- * This is the direct-SDK operator surface: nine read-only geospatial tools wired
- * straight onto `@honua/sdk-js`, which speaks plain Esri GeoServices / OGC API
- * over standard REST paths (`/rest/services`, `/FeatureServer/{id}/query`, …).
- * Point it at ANY public FeatureServer / OGC endpoint (e.g. a `services.arcgis.com`
- * FeatureServer) with ZERO Honua-server assumptions — no admin API, no `/healthz`,
- * no `/mcp` catalog. This is what the `honua-mcp` bin runs (see {@link runStandalone}),
- * and what the platform-free certification lane + eval corpus exercise.
+ * This is the direct-SDK operator surface: ten read-only geospatial tools wired
+ * straight onto `@honua/sdk-js`. Point it at ANY public FeatureServer / OGC API /
+ * STAC / WFS / OData endpoint with ZERO Honua-server assumptions — no admin API,
+ * no `/healthz`, no `/mcp` catalog. This is what the `honua-mcp` bin runs (see
+ * {@link runStandalone}), and what the platform-free certification lanes + eval
+ * corpora exercise.
+ *
+ * The tool contract is PROTOCOL-NEUTRAL (issue #1005): sources are addressed by
+ * a `<protocol>:<address>` reference (`honua_list_sources` emits them), filters
+ * are the SDK's typed semantic filter, geometry is GeoJSON, and execution goes
+ * through the canonical `Dataset`/`Source`/`Query`/`Result` contract so one call
+ * means the same thing on every protocol. The GeoServices `serviceId`/`layerId`
+ * pair is still accepted as a deprecated compatibility input; no tool schema
+ * requires an Esri-only field.
  *
  * Tools that need a Honua-only surface (server-side styling via OGC API – Styles,
  * a `/rest/services` catalog) degrade gracefully on a plain target: they return a
@@ -39,13 +56,24 @@ export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClien
  * mutation, jobs, and publishing — is a superset reached over streamable-HTTP and
  * mirrored to stdio by `honua-mcp-proxy` ({@link runProxy}); it requires a Honua
  * deployment. Standalone is the front door; the proxy is the upgrade path.
+ * Local installation is intentionally absent from this catalog and is exposed
+ * only by {@link createBootstrapServer}.
+ *
+ * Control-plane MUTATION is likewise absent by default, and when a host does
+ * enable it ({@link CreateServerOptions.controlPlaneCommands}) MCP does not get
+ * a workflow of its own: the tools are generated from the shared command
+ * catalog in `@honua/sdk-js/control-plane`, so an MCP invocation and the
+ * equivalent `honua` CLI, Studio, or direct-JS invocation share one
+ * implementation and one receipt `auditKey`.
  */
 export declare function createServer(client: HonuaClient, options?: CreateServerOptions): McpServer;
+/** Bootstrap-only MCP surface for a laptop that does not have Honua yet. */
+export declare function createBootstrapServer(): McpServer;
 /**
  * Run the platform-free standalone server end-to-end over stdio.
  *
  * Builds a `HonuaClient` from the environment (`HONUA_BASE_URL` + optional
- * transport/auth) and exposes {@link createServer} — the nine read-only tools —
+ * transport/auth) and exposes {@link createServer} — the ten read-only tools —
  * to a stdio MCP client (Claude Desktop / Claude Code / any MCP agent). Point
  * `HONUA_BASE_URL` at any public FeatureServer/OGC endpoint; no Honua server is
  * required. For the Honua-enhanced `/mcp` catalog, use `honua-mcp-proxy` instead.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAGtF,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,qBAAqB,CAAC;AAc7F,OAAO,EACL,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;CAC7C;AAMD,eAAO,MAAM,cAAc,QAAyB,CAAC;AA2DrD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,CAgD5E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CASrF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aA6FlF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAGtF,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,qBAAqB,CAAC;AAM7F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAanF,OAAO,EACL,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,2BAA2B,EAC3B,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,YAAY,EACV,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,cAAc,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,0BAA0B,CAAC;CAC5D;AAMD,eAAO,MAAM,cAAc,QAAyB,CAAC;AA2DrD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,CAgD5E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CASrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aAoHlF;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}

package/dist/src/index.js

@@ -8,16 +8,21 @@ import { registerNlMapControlMcpTools } from "./nl-map-control.js";
 import * as layerSchemaResource from "./resources/layer-schema.js";
 import * as servicesResource from "./resources/services.js";
 import * as stylesResource from "./resources/styles.js";
+import * as adminInstallLocal from "./tools/admin-install-local.js";
 import * as applyStylePreset from "./tools/apply-style-preset.js";
+import * as controlPlaneCommand from "./tools/control-plane-command.js";
 import * as countFeatures from "./tools/count-features.js";
 import * as describeLayer from "./tools/describe-layer.js";
+import * as docsSearch from "./tools/docs-search.js";
 import * as explainCapabilityGap from "./tools/explain-capability-gap.js";
 import * as getExtent from "./tools/get-extent.js";
 import * as getStyle from "./tools/get-style.js";
 import * as listServices from "./tools/list-services.js";
+import * as listSources from "./tools/list-sources.js";
 import * as queryFeatures from "./tools/query-features.js";
 import * as statistics from "./tools/statistics.js";
 export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
+export { CONTROL_PLANE_COMMAND_TOOL_PREFIX, controlPlaneCommandToolName, controlPlaneCommandToolSchema, registerControlPlaneCommandTools, } from "./tools/control-plane-command.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_SERVER_VERSION = "0.0.3-alpha.0";
@@ -121,13 +126,20 @@ export function createClientFromEnv(env = process.env) {
 /**
  * The PLATFORM-FREE standalone MCP surface (issue #369).
  *
- * This is the direct-SDK operator surface: nine read-only geospatial tools wired
- * straight onto `@honua/sdk-js`, which speaks plain Esri GeoServices / OGC API
- * over standard REST paths (`/rest/services`, `/FeatureServer/{id}/query`, …).
- * Point it at ANY public FeatureServer / OGC endpoint (e.g. a `services.arcgis.com`
- * FeatureServer) with ZERO Honua-server assumptions — no admin API, no `/healthz`,
- * no `/mcp` catalog. This is what the `honua-mcp` bin runs (see {@link runStandalone}),
- * and what the platform-free certification lane + eval corpus exercise.
+ * This is the direct-SDK operator surface: ten read-only geospatial tools wired
+ * straight onto `@honua/sdk-js`. Point it at ANY public FeatureServer / OGC API /
+ * STAC / WFS / OData endpoint with ZERO Honua-server assumptions — no admin API,
+ * no `/healthz`, no `/mcp` catalog. This is what the `honua-mcp` bin runs (see
+ * {@link runStandalone}), and what the platform-free certification lanes + eval
+ * corpora exercise.
+ *
+ * The tool contract is PROTOCOL-NEUTRAL (issue #1005): sources are addressed by
+ * a `<protocol>:<address>` reference (`honua_list_sources` emits them), filters
+ * are the SDK's typed semantic filter, geometry is GeoJSON, and execution goes
+ * through the canonical `Dataset`/`Source`/`Query`/`Result` contract so one call
+ * means the same thing on every protocol. The GeoServices `serviceId`/`layerId`
+ * pair is still accepted as a deprecated compatibility input; no tool schema
+ * requires an Esri-only field.
  *
  * Tools that need a Honua-only surface (server-side styling via OGC API – Styles,
  * a `/rest/services` catalog) degrade gracefully on a plain target: they return a
@@ -138,6 +150,15 @@ export function createClientFromEnv(env = process.env) {
  * mutation, jobs, and publishing — is a superset reached over streamable-HTTP and
  * mirrored to stdio by `honua-mcp-proxy` ({@link runProxy}); it requires a Honua
  * deployment. Standalone is the front door; the proxy is the upgrade path.
+ * Local installation is intentionally absent from this catalog and is exposed
+ * only by {@link createBootstrapServer}.
+ *
+ * Control-plane MUTATION is likewise absent by default, and when a host does
+ * enable it ({@link CreateServerOptions.controlPlaneCommands}) MCP does not get
+ * a workflow of its own: the tools are generated from the shared command
+ * catalog in `@honua/sdk-js/control-plane`, so an MCP invocation and the
+ * equivalent `honua` CLI, Studio, or direct-JS invocation share one
+ * implementation and one receipt `auditKey`.
  */
 export function createServer(client, options = {}) {
     const server = new McpServer({
@@ -145,25 +166,41 @@ export function createServer(client, options = {}) {
         version: SERVER_VERSION,
     });
     // ── Tools ──────────────────────────────────────────────────────
-    server.tool("honua_list_services", "Discover all available feature services on any FeatureServer folder. Set includeDetails=true for descriptions, layer counts, and spatial references. Degrades gracefully when the target has no service catalog.", listServices.schema.shape, async (args) => listServices.execute(client, listServices.schema.parse(args)));
+    server.tool("honua_list_sources", 'Discover queryable sources on this endpoint, across protocols. Returns protocol-neutral `<protocol>:<address>` source references (e.g. "ogc-features:hotels", "geoservices-feature-service:Parks/0") to pass verbatim to the query tools, plus each source\'s capabilities. Each protocol family degrades independently with a reason.', listSources.schema.shape, async (args) => listSources.execute(client, listSources.schema.parse(args)));
+    server.tool("honua_list_services", "[GeoServices-specific; prefer honua_list_sources] Discover feature services on a FeatureServer folder. Set includeDetails=true for descriptions, layer counts, and spatial references. Degrades gracefully when the target has no service catalog.", listServices.schema.shape, async (args) => listServices.execute(client, listServices.schema.parse(args)));
     if (options.nlMapControl) {
         registerNlMapControlMcpTools(server, options.nlMapControl);
     }
-    server.tool("honua_describe_layer", "Get full schema for a layer — fields, geometry type, extent, relationships.", describeLayer.schema.shape, async (args) => describeLayer.execute(client, describeLayer.schema.parse(args)));
-    server.tool("honua_query_features", "Query features with attribute filters, spatial filters, field selection, and pagination. returnGeometry defaults to false to save tokens.", queryFeatures.schema.shape, async (args) => queryFeatures.execute(client, queryFeatures.schema.parse(args)));
+    server.tool("honua_describe_layer", "Describe a source: its protocol, the capabilities it actually supports, field schema, geometry type, and extent. Address it with `source` (from honua_list_sources); the serviceId/layerId pair is deprecated but still accepted.", describeLayer.schema.shape, async (args) => describeLayer.execute(client, describeLayer.schema.parse(args)));
+    server.tool("honua_query_features", "Query features from any supported protocol. Address the source with `source`; filter with the typed protocol-neutral `filter`, a GeoJSON `geometry` or `bbox` plus `spatialRel`, and `temporal`. returnGeometry defaults to false to save tokens. A construct the backing protocol cannot express returns a structured capability error, never a silently empty result.", queryFeatures.schema.shape, async (args) => queryFeatures.execute(client, queryFeatures.schema.parse(args)));
     server.tool("honua_count_features", "Count features matching a filter without returning data. Use before querying to check cardinality.", countFeatures.schema.shape, async (args) => countFeatures.execute(client, countFeatures.schema.parse(args)));
     server.tool("honua_get_extent", "Get the spatial bounding box of features matching a filter.", getExtent.schema.shape, async (args) => getExtent.execute(client, getExtent.schema.parse(args)));
-    server.tool("honua_statistics", "Compute aggregate statistics (count, sum, avg, min, max, stddev) on a field, optionally grouped.", statistics.schema.shape, async (args) => statistics.execute(client, statistics.schema.parse(args)));
+    server.tool("honua_statistics", "Compute aggregate statistics (count, sum, avg, min, max, stddev, var) on a field, optionally grouped. Protocols without server-side aggregation answer client-side and report the degradation.", statistics.schema.shape, async (args) => statistics.execute(client, statistics.schema.parse(args)));
     server.tool("honua_explain_capability_gap", "Explain whether a source/protocol supports a capability and suggest a safe fallback when it does not.", explainCapabilityGap.schema.shape, async (args) => explainCapabilityGap.execute(client, explainCapabilityGap.schema.parse(args)));
     server.tool("honua_get_style", "Resolve a style from a server's OGC API – Styles surface. Pass styleId for the canonical StyleRef (style_id, title, encodings incl. inlined MapLibre); omit it to list available styles. On a plain FeatureServer with no styling surface, reports a structured 'not available on this target' result.", getStyle.schema.shape, async (args) => getStyle.execute(client, getStyle.schema.parse(args)));
     server.tool("honua_apply_style_preset", "Resolve a style preset and its MapLibre stylesheet for client-side application. Read-only: returns the stylesheet to apply locally; it does not mutate server state. Degrades gracefully on a target with no styling surface.", applyStylePreset.schema.shape, async (args) => applyStylePreset.execute(client, applyStylePreset.schema.parse(args)));
+    if (options.controlPlaneCommands) {
+        // Thin adapters generated from the shared command catalog. Registered last
+        // so the platform-free read-only surface keeps its stable tool order.
+        controlPlaneCommand.registerControlPlaneCommandTools(server, options.controlPlaneCommands);
+    }
+    server.tool("honua_docs_search", "Answer a Honua documentation question from the local versioned documentation corpus (llms-full.txt), returning ranked excerpts with a source-file and release-version citation for each hit. Local and offline: reads committed docs, never the network. Use it before guessing at an API, a CLI flag, or a contract. Reports a structured 'not available' result when the corpus is not present in this installation.", docsSearch.schema.shape, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => docsSearch.execute(client, docsSearch.schema.parse(args)));
     // ── Resources ──────────────────────────────────────────────────
-    server.resource("services-catalog", servicesResource.uri, async (uri) => servicesResource.read(client));
-    server.resource("layer-schema", new ResourceTemplate(layerSchemaResource.uriTemplate, { list: undefined }), async (uri, params) => layerSchemaResource.read(client, params.encodedServiceId, params.layerId));
-    server.resource("styles-catalog", stylesResource.uri, async (uri) => stylesResource.readCatalog(client));
-    server.resource("style", new ResourceTemplate(stylesResource.uriTemplate, { list: undefined }), async (uri, params) => stylesResource.read(client, params.styleId));
+    server.resource("services-catalog", servicesResource.uri, async (_uri) => servicesResource.read(client));
+    server.resource("layer-schema", new ResourceTemplate(layerSchemaResource.uriTemplate, { list: undefined }), async (_uri, params) => layerSchemaResource.read(client, params.encodedServiceId, params.layerId));
+    server.resource("styles-catalog", stylesResource.uri, async (_uri) => stylesResource.readCatalog(client));
+    server.resource("style", new ResourceTemplate(stylesResource.uriTemplate, { list: undefined }), async (_uri, params) => stylesResource.read(client, params.styleId));
     return server;
 }
+/** Bootstrap-only MCP surface for a laptop that does not have Honua yet. */
+export function createBootstrapServer() {
+    const server = new McpServer({ name: "honua-bootstrap", version: SERVER_VERSION });
+    registerLocalInstallTool(server);
+    return server;
+}
+function registerLocalInstallTool(server) {
+    server.tool("honua_admin_install_local", "Install the manifest-pinned Honua Server, PostGIS, and Redis on this laptop, wait for readiness, bootstrap a scoped admin key, and write proxy MCP configuration. Requires confirm=true.", adminInstallLocal.schema.shape, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }, async (args) => adminInstallLocal.execute(adminInstallLocal.schema.parse(args)));
+}
 /* v8 ignore start -- live-process entry: wires the stdio transport to a real
    SDK client against HONUA_BASE_URL; exercised by running the bin, not unit tests.
    The unit-testable logic (option resolution, client construction, server wiring)
@@ -172,14 +209,14 @@ export function createServer(client, options = {}) {
  * Run the platform-free standalone server end-to-end over stdio.
  *
  * Builds a `HonuaClient` from the environment (`HONUA_BASE_URL` + optional
- * transport/auth) and exposes {@link createServer} — the nine read-only tools —
+ * transport/auth) and exposes {@link createServer} — the ten read-only tools —
  * to a stdio MCP client (Claude Desktop / Claude Code / any MCP agent). Point
  * `HONUA_BASE_URL` at any public FeatureServer/OGC endpoint; no Honua server is
  * required. For the Honua-enhanced `/mcp` catalog, use `honua-mcp-proxy` instead.
  */
 export async function runStandalone(env = process.env) {
-    const client = createClientFromEnv(env);
-    const server = createServer(client);
+    const bootstrapOnly = env.HONUA_MCP_BOOTSTRAP === "1" || env.HONUA_MCP_BOOTSTRAP === "true";
+    const server = bootstrapOnly ? createBootstrapServer() : createServer(createClientFromEnv(env));
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/src/neutral/errors.d.ts

@@ -0,0 +1,73 @@
+import { HonuaCapabilityNotSupportedError } from "@honua/sdk-js";
+/**
+ * CAPABILITY HONESTY on the tool surface (#1005).
+ *
+ * The SDK's contract is that a capability gap throws
+ * `HonuaCapabilityNotSupportedError` rather than returning empty data. That
+ * guarantee is worthless if the MCP layer swallows the throw and hands the
+ * model an empty feature list — the model would report "no features match"
+ * for what is actually "this protocol cannot express that request".
+ *
+ * So every capability refusal becomes an explicit `isError` tool result
+ * carrying a machine-actionable `code`, the refused capability/construct, the
+ * protocol that refused it, and — for real capability identifiers — the same
+ * explanation `honua_explain_capability_gap` would give, including what to do
+ * instead. Degradations that DID produce an answer travel the other channel,
+ * `Result.degraded`, and are reported alongside the data.
+ */
+/**
+ * `kind` values come from the vendored geospatial-mcp `GeoprocessingError`
+ * taxonomy — the standard forbids a parallel MCP-local error vocabulary, so a
+ * capability refusal is an `ExecutionFailed` (a well-formed request the target
+ * cannot run) and a bad argument is a `ValidationFailed`. The precise reason
+ * travels in the envelope's machine-actionable `code` plus the typed fields.
+ */
+export type ToolErrorKind = "ValidationFailed" | "ExecutionFailed";
+export interface ToolErrorViolation {
+    readonly code: string;
+    readonly message: string;
+    readonly fieldPath?: string;
+}
+export interface ToolErrorPayload {
+    readonly code: string;
+    readonly error: {
+        readonly kind: ToolErrorKind;
+        readonly message: string;
+        readonly capability?: string;
+        readonly protocol?: string;
+        readonly source?: string;
+        readonly guidance?: string;
+        readonly explanation?: unknown;
+        readonly violations?: readonly ToolErrorViolation[];
+    };
+}
+/** Build the structured payload for a capability refusal. */
+export declare function capabilityErrorPayload(error: HonuaCapabilityNotSupportedError): ToolErrorPayload;
+/** Build the structured payload for an invalid tool argument. */
+export declare function validationErrorPayload(code: string, message: string, violations?: readonly ToolErrorViolation[]): ToolErrorPayload;
+/**
+ * Wrap a payload as an `isError` MCP tool result.
+ *
+ * The payload rides in both channels: `structuredContent` for clients (and the
+ * certification error-shape contract) that branch on machine-readable fields,
+ * and the text block for models that only read text.
+ */
+export declare function toolErrorResult(payload: ToolErrorPayload): {
+    structuredContent: Record<string, unknown>;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+/** Map any thrown value onto a structured tool-error payload. */
+export declare function toToolErrorPayload(error: unknown): ToolErrorPayload;
+/**
+ * Run a tool body, converting capability refusals and argument-validation
+ * failures into structured `isError` results. Anything else is rethrown so a
+ * genuine transport/server fault is not disguised as a data answer.
+ */
+export declare function withCapabilityHonesty<T extends {
+    content: unknown;
+}>(run: () => Promise<T>): Promise<T | ReturnType<typeof toolErrorResult>>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/neutral/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/neutral/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,eAAe,CAAC;AASjE;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;KACrD,CAAC;CACH;AAUD,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gCAAgC,GAAG,gBAAgB,CAkChG;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,SAAS,kBAAkB,EAAwB,GAC9D,gBAAgB,CAKlB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB;uBAGZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;EAGnE;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CA4BnE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,SAAS;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACxE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAcjD"}

package/dist/src/neutral/errors.js

@@ -0,0 +1,112 @@
+import { HonuaCapabilityNotSupportedError } from "@honua/sdk-js";
+import { explainHonuaCapabilityGap } from "@honua/sdk-js/agent-tools";
+import { CAPABILITIES, PROTOCOLS } from "@honua/sdk-js/contract";
+import { z } from "zod";
+import { jsonText } from "../helpers.js";
+import { FilterInputError } from "./filter.js";
+import { SourceRefError } from "./source-ref.js";
+function isKnownCapability(value) {
+    return CAPABILITIES.includes(value);
+}
+function isKnownProtocol(value) {
+    return PROTOCOLS.includes(value);
+}
+/** Build the structured payload for a capability refusal. */
+export function capabilityErrorPayload(error) {
+    // Filter refusals name a construct (`filter.spatial.multiple`) rather than a
+    // registry capability; only real capability identifiers can be explained
+    // against the protocol capability registry.
+    const explanation = isKnownCapability(error.capability) && (error.protocol === undefined || isKnownProtocol(error.protocol))
+        ? explainHonuaCapabilityGap({
+            capability: error.capability,
+            ...(isKnownProtocol(error.protocol) ? { protocol: error.protocol } : {}),
+            ...(error.sourceId ? { sourceId: error.sourceId } : {}),
+        })
+        : undefined;
+    return {
+        code: "capability_not_supported",
+        error: {
+            kind: "ExecutionFailed",
+            message: error.message,
+            capability: error.capability,
+            protocol: error.protocol,
+            ...(error.sourceId ? { source: error.sourceId } : {}),
+            violations: [
+                {
+                    code: "capability_not_supported",
+                    message: error.message,
+                    fieldPath: error.capability.startsWith("filter.") ? "filter" : "source",
+                },
+            ],
+            guidance: explanation?.suggestedAction ??
+                "This protocol cannot express the request exactly. Re-issue it against a source whose protocol advertises the capability, or restate the request within what this protocol supports — do not treat this as an empty result.",
+            ...(explanation ? { explanation } : {}),
+        },
+    };
+}
+/** Build the structured payload for an invalid tool argument. */
+export function validationErrorPayload(code, message, violations = [{ code, message }]) {
+    return {
+        code,
+        error: { kind: "ValidationFailed", message, violations },
+    };
+}
+/**
+ * Wrap a payload as an `isError` MCP tool result.
+ *
+ * The payload rides in both channels: `structuredContent` for clients (and the
+ * certification error-shape contract) that branch on machine-readable fields,
+ * and the text block for models that only read text.
+ */
+export function toolErrorResult(payload) {
+    return {
+        ...jsonText(payload),
+        structuredContent: payload,
+        isError: true,
+    };
+}
+/** Map any thrown value onto a structured tool-error payload. */
+export function toToolErrorPayload(error) {
+    if (error instanceof HonuaCapabilityNotSupportedError) {
+        return capabilityErrorPayload(error);
+    }
+    if (error instanceof SourceRefError) {
+        const code = error.code.toLowerCase();
+        return validationErrorPayload(code, error.message, [{ code, message: error.message, fieldPath: "source" }]);
+    }
+    if (error instanceof FilterInputError) {
+        const code = error.code.toLowerCase();
+        return validationErrorPayload(code, error.message, [{ code, message: error.message, fieldPath: "filter" }]);
+    }
+    if (error instanceof z.ZodError) {
+        return validationErrorPayload("invalid_arguments", "Tool arguments failed validation.", error.issues.map((issue) => ({
+            code: issue.code,
+            message: issue.message,
+            fieldPath: issue.path.join("."),
+        })));
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        code: "tool_execution_failed",
+        error: { kind: "ExecutionFailed", message, violations: [{ code: "tool_execution_failed", message }] },
+    };
+}
+/**
+ * Run a tool body, converting capability refusals and argument-validation
+ * failures into structured `isError` results. Anything else is rethrown so a
+ * genuine transport/server fault is not disguised as a data answer.
+ */
+export async function withCapabilityHonesty(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof HonuaCapabilityNotSupportedError ||
+            error instanceof SourceRefError ||
+            error instanceof FilterInputError ||
+            error instanceof z.ZodError) {
+            return toolErrorResult(toToolErrorPayload(error));
+        }
+        throw error;
+    }
+}

package/dist/src/neutral/filter.d.ts

@@ -0,0 +1,108 @@
+import type { QueryFilterExpression, QueryFilterGeometryOperand, QueryTemporalFilter } from "@honua/sdk-js/contract";
+import { z } from "zod";
+import { GEOMETRY_TYPES } from "../helpers.js";
+/** Protocol-neutral spatial predicates (`QueryFilterSpatialPredicate`). */
+export declare const SPATIAL_PREDICATES: readonly ["intersects", "contains", "within", "crosses", "touches", "overlaps", "bbox-intersects"];
+declare const TEMPORAL_PREDICATES: readonly ["before", "after", "during", "time-intersects"];
+/** GeoJSON geometry accepted anywhere a spatial constraint is expressed. */
+export declare const geoJsonGeometrySchema: z.ZodObject<{
+    type: z.ZodEnum<["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"]>;
+    coordinates: z.ZodArray<z.ZodUnknown, "many">;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    type: z.ZodEnum<["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"]>;
+    coordinates: z.ZodArray<z.ZodUnknown, "many">;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    type: z.ZodEnum<["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"]>;
+    coordinates: z.ZodArray<z.ZodUnknown, "many">;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * A geometry operand: GeoJSON (canonical) or Esri-JSON (accepted for
+ * compatibility). Kept as a loose record so an Esri envelope / rings payload
+ * from an existing client still validates.
+ */
+export declare const geometrySchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const bboxSchema: z.ZodArray<z.ZodNumber, "many">;
+export type FilterNode = {
+    op: "and" | "or";
+    args: FilterNode[];
+} | {
+    op: "not";
+    arg: FilterNode;
+} | {
+    op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
+    field: string;
+    value: string | number | boolean | null;
+} | {
+    op: "in";
+    field: string;
+    values: (string | number | boolean | null)[];
+} | {
+    op: "between";
+    field: string;
+    lower: string | number | boolean | null;
+    upper: string | number | boolean | null;
+} | {
+    op: "is-null" | "is-not-null";
+    field: string;
+} | {
+    op: "like";
+    field: string;
+    pattern: string;
+    caseSensitive?: boolean;
+} | {
+    op: (typeof SPATIAL_PREDICATES)[number];
+    geometry?: Record<string, unknown>;
+    bbox?: number[];
+    field?: string;
+    geometryType?: (typeof GEOMETRY_TYPES)[number];
+} | {
+    op: (typeof TEMPORAL_PREDICATES)[number];
+    field: string;
+    value: string | string[];
+};
+/**
+ * Recursive zod schema for {@link FilterNode}. `z.lazy` keeps `and`/`or`/`not`
+ * genuinely recursive; zod-to-json-schema emits it as a `$ref`, which stays
+ * well-formed JSON Schema for MCP clients and for the certification harness.
+ */
+export declare const filterSchema: z.ZodType<FilterNode>;
+export declare class FilterInputError extends Error {
+    readonly code = "INVALID_FILTER";
+    constructor(message: string);
+}
+/** Build an Esri envelope from a `[minX, minY, maxX, maxY]` bbox. */
+export declare function bboxToOperand(bbox: readonly number[], srid?: number): QueryFilterGeometryOperand;
+/**
+ * Normalize a geometry input onto the canonical geometry operand.
+ *
+ * GeoJSON is the documented input; Esri-JSON is accepted so existing clients
+ * keep working. The canonical operand is Esri-shaped inside the SDK — that is
+ * an SDK implementation detail, not part of this tool contract.
+ */
+export declare function toGeometryOperand(geometry: Record<string, unknown>, esriGeometryType?: (typeof GEOMETRY_TYPES)[number], srid?: number): QueryFilterGeometryOperand;
+/** Lower the wire filter DSL onto the SDK's canonical typed filter expression. */
+export declare function toQueryFilter(node: FilterNode): QueryFilterExpression;
+/** Conjoin filter expressions; `undefined` when nothing was supplied. */
+export declare function andFilters(parts: readonly QueryFilterExpression[]): QueryFilterExpression | undefined;
+/** Canonical time constraint accepted on the tool surface. */
+export declare const temporalSchema: z.ZodObject<{
+    instant: z.ZodOptional<z.ZodString>;
+    start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    end: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    field: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    field?: string | undefined;
+    instant?: string | undefined;
+    start?: string | null | undefined;
+    end?: string | null | undefined;
+}, {
+    field?: string | undefined;
+    instant?: string | undefined;
+    start?: string | null | undefined;
+    end?: string | null | undefined;
+}>;
+export type TemporalInput = z.infer<typeof temporalSchema>;
+/** Lower the wire temporal input onto `Query.temporalFilter`. */
+export declare function toTemporalFilter(input: TemporalInput): QueryTemporalFilter;
+export {};
+//# sourceMappingURL=filter.d.ts.map

package/dist/src/neutral/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/neutral/filter.ts"],"names":[],"mappings":"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"}