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

package/dist/src/index.js

@@ -15,6 +15,7 @@ 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";
@@ -121,13 +122,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
@@ -145,23 +153,24 @@ 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)));
     // ── 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;
 }
 /* v8 ignore start -- live-process entry: wires the stdio transport to a real

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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"}

package/dist/src/neutral/filter.js

@@ -0,0 +1,271 @@
+import { geoJsonToEsri } from "@honua/sdk-js/geometry";
+import { z } from "zod";
+import { GEOMETRY_TYPES, resolveGeometryType } from "../helpers.js";
+/**
+ * PROTOCOL-NEUTRAL filter + geometry vocabulary for the MCP tool contract (#1005).
+ *
+ * The SDK's `Query.filter` is a typed semantic filter that compiles to
+ * GeoServices SQL-92, CQL2 (OGC API Features / STAC), FES 2.0 (WFS), OData
+ * `$filter`, and DuckDB SQL — and refuses, naming the construct and the
+ * protocol, when a target cannot express a construct exactly. Exposing it on
+ * the tool surface is what lets an agent write ONE filter and have it mean the
+ * same thing on every backend, instead of hand-writing Esri SQL.
+ *
+ * The wire shape here is a flattened projection of that AST: one `op`
+ * discriminator per node instead of the SDK's `kind` + `operator` pair, because
+ * a flat discriminated union is markedly easier for a model to emit correctly.
+ * {@link toQueryFilter} lowers it onto the canonical expression losslessly.
+ *
+ * Geometry is canonical **GeoJSON** (RFC 7946). Esri-JSON geometry is still
+ * accepted for compatibility with existing clients and is converted on the way
+ * in; nothing on the surface requires it.
+ */
+const scalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+/** Protocol-neutral spatial predicates (`QueryFilterSpatialPredicate`). */
+export const SPATIAL_PREDICATES = [
+    "intersects",
+    "contains",
+    "within",
+    "crosses",
+    "touches",
+    "overlaps",
+    "bbox-intersects",
+];
+const TEMPORAL_PREDICATES = ["before", "after", "during", "time-intersects"];
+/** GeoJSON geometry accepted anywhere a spatial constraint is expressed. */
+export const geoJsonGeometrySchema = z
+    .object({
+    type: z.enum(["Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon"]),
+    coordinates: z.array(z.unknown()),
+})
+    .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 const geometrySchema = z.record(z.unknown());
+export const bboxSchema = z
+    .array(z.number())
+    .length(4)
+    .describe("Bounding box [minX, minY, maxX, maxY]. Interpreted in the source CRS (WGS84 unless bboxSrid says otherwise).");
+/**
+ * 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 const filterSchema = z.lazy(() => z.union([
+    z.object({
+        op: z.enum(["and", "or"]),
+        args: z.array(filterSchema).min(1),
+    }),
+    z.object({ op: z.literal("not"), arg: filterSchema }),
+    z.object({
+        op: z.enum(["eq", "ne", "lt", "lte", "gt", "gte"]),
+        field: z.string().min(1),
+        value: scalarSchema,
+    }),
+    z.object({ op: z.literal("in"), field: z.string().min(1), values: z.array(scalarSchema).min(1) }),
+    z.object({
+        op: z.literal("between"),
+        field: z.string().min(1),
+        lower: scalarSchema,
+        upper: scalarSchema,
+    }),
+    z.object({ op: z.enum(["is-null", "is-not-null"]), field: z.string().min(1) }),
+    z.object({
+        op: z.literal("like"),
+        field: z.string().min(1),
+        pattern: z.string(),
+        caseSensitive: z.boolean().optional(),
+    }),
+    z.object({
+        op: z.enum(SPATIAL_PREDICATES),
+        geometry: geometrySchema.optional(),
+        bbox: z.array(z.number()).length(4).optional(),
+        field: z.string().optional(),
+        geometryType: z.enum(GEOMETRY_TYPES).optional(),
+    }),
+    z.object({
+        op: z.enum(TEMPORAL_PREDICATES),
+        field: z.string().min(1),
+        // An interval is a 2-element array rather than a JSON Schema tuple: the
+        // draft-07 tuple form (`items: [...]`) is invalid under 2020-12, and the
+        // certification harness validates advertised schemas under both dialects.
+        value: z.union([z.string(), z.array(z.string()).length(2)]),
+    }),
+]));
+export class FilterInputError extends Error {
+    code = "INVALID_FILTER";
+    constructor(message) {
+        super(message);
+        this.name = "FilterInputError";
+    }
+}
+function isGeoJsonGeometry(value) {
+    return typeof value.type === "string" && Array.isArray(value.coordinates);
+}
+/** Build an Esri envelope from a `[minX, minY, maxX, maxY]` bbox. */
+export function bboxToOperand(bbox, srid) {
+    const [xmin, ymin, xmax, ymax] = bbox;
+    const geometry = { xmin, ymin, xmax, ymax };
+    if (srid !== undefined) {
+        geometry.spatialReference = { wkid: srid };
+    }
+    return { geometry, geometryType: "esriGeometryEnvelope" };
+}
+/**
+ * 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 function toGeometryOperand(geometry, esriGeometryType, srid) {
+    if (isGeoJsonGeometry(geometry)) {
+        const converted = geoJsonToEsri(geometry, srid !== undefined ? { wkid: srid } : undefined);
+        if (!converted) {
+            throw new FilterInputError(`GeoJSON geometry of type "${String(geometry.type)}" could not be converted to a query geometry.`);
+        }
+        const asRecord = converted;
+        const geometryType = resolveGeometryType(asRecord, undefined);
+        if (!geometryType) {
+            throw new FilterInputError("Converted geometry has no recognizable geometry type.");
+        }
+        return { geometry: asRecord, geometryType };
+    }
+    const geometryType = resolveGeometryType(geometry, esriGeometryType);
+    if (!geometryType) {
+        throw new FilterInputError('geometry is neither GeoJSON (an object with "type" and "coordinates") nor a recognizable Esri-JSON geometry. Pass GeoJSON, a bbox, or an explicit geometryType.');
+    }
+    return { geometry, geometryType };
+}
+function spatialOperand(node) {
+    if (node.geometry && node.bbox) {
+        throw new FilterInputError(`filter node "${node.op}" carries both geometry and bbox; pass exactly one.`);
+    }
+    if (node.bbox) {
+        return bboxToOperand(node.bbox);
+    }
+    if (node.geometry) {
+        return toGeometryOperand(node.geometry, node.geometryType);
+    }
+    throw new FilterInputError(`filter node "${node.op}" requires either geometry (GeoJSON) or bbox.`);
+}
+function isSpatialOp(op) {
+    return SPATIAL_PREDICATES.includes(op);
+}
+function isTemporalOp(op) {
+    return TEMPORAL_PREDICATES.includes(op);
+}
+/** Lower the wire filter DSL onto the SDK's canonical typed filter expression. */
+export function toQueryFilter(node) {
+    switch (node.op) {
+        case "and":
+        case "or":
+            return { kind: "boolean", operator: node.op, args: node.args.map(toQueryFilter) };
+        case "not":
+            return { kind: "not", arg: toQueryFilter(node.arg) };
+        case "eq":
+        case "ne":
+        case "lt":
+        case "lte":
+        case "gt":
+        case "gte":
+            return {
+                kind: "comparison",
+                operator: node.op,
+                left: { kind: "property", name: node.field },
+                right: { kind: "literal", value: node.value },
+            };
+        case "in":
+            return {
+                kind: "list",
+                operator: "in",
+                operand: { kind: "property", name: node.field },
+                values: node.values.map((value) => ({ kind: "literal", value })),
+            };
+        case "between":
+            return {
+                kind: "range",
+                operator: "between",
+                operand: { kind: "property", name: node.field },
+                lower: { kind: "literal", value: node.lower },
+                upper: { kind: "literal", value: node.upper },
+            };
+        case "is-null":
+        case "is-not-null":
+            return { kind: "null", operator: node.op, operand: { kind: "property", name: node.field } };
+        case "like":
+            return {
+                kind: "pattern",
+                operator: "like",
+                operand: { kind: "property", name: node.field },
+                pattern: node.pattern,
+                ...(node.caseSensitive === undefined ? {} : { caseSensitive: node.caseSensitive }),
+            };
+        default:
+            break;
+    }
+    if (isSpatialOp(node.op)) {
+        const spatial = node;
+        return {
+            kind: "spatial",
+            operator: spatial.op,
+            geometry: spatialOperand(spatial),
+            ...(spatial.field ? { property: spatial.field } : {}),
+        };
+    }
+    if (isTemporalOp(node.op)) {
+        const temporal = node;
+        const value = temporal.value;
+        return {
+            kind: "temporal",
+            operator: temporal.op,
+            operand: { kind: "property", name: temporal.field },
+            value: typeof value === "string"
+                ? { kind: "temporal-literal", valueType: "instant", value }
+                : { kind: "temporal-literal", valueType: "interval", value: [value[0], value[1]] },
+        };
+    }
+    throw new FilterInputError(`unknown filter operator "${String(node.op)}".`);
+}
+/** Conjoin filter expressions; `undefined` when nothing was supplied. */
+export function andFilters(parts) {
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return { kind: "boolean", operator: "and", args: [...parts] };
+}
+/** Canonical time constraint accepted on the tool surface. */
+export const temporalSchema = z
+    .object({
+    instant: z.string().optional().describe("RFC 3339 instant, e.g. 2026-05-01T00:00:00Z."),
+    start: z.string().nullable().optional().describe("Interval start (null = open ended)."),
+    end: z.string().nullable().optional().describe("Interval end (null = open ended)."),
+    field: z
+        .string()
+        .optional()
+        .describe("Time column to constrain. Omit to target the source's own time dimension (GeoServices time=, OGC/STAC datetime=); OData, WFS, and GeoParquet require an explicit field."),
+})
+    .describe("Protocol-neutral time constraint: either `instant`, or `start`/`end` for an interval.");
+/** Lower the wire temporal input onto `Query.temporalFilter`. */
+export function toTemporalFilter(input) {
+    const field = input.field ? { field: input.field } : {};
+    if (input.instant !== undefined) {
+        if (input.start !== undefined || input.end !== undefined) {
+            throw new FilterInputError("temporal accepts either `instant` or `start`/`end`, not both.");
+        }
+        return { kind: "instant", instant: input.instant, ...field };
+    }
+    if (input.start === undefined && input.end === undefined) {
+        throw new FilterInputError("temporal requires `instant`, or at least one of `start` / `end`.");
+    }
+    return {
+        kind: "interval",
+        start: input.start ?? null,
+        end: input.end ?? null,
+        ...field,
+    };
+}