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

package/dist/src/eval/ogc-corpus.js

@@ -0,0 +1,437 @@
+/**
+ * NON-GeoServices (OGC API Features) eval corpus — issue #1005.
+ *
+ * The standalone corpus proves the surface works against a plain Esri
+ * FeatureServer. That is only half the vendor-neutrality claim: a tool contract
+ * can pass every GeoServices scenario and still be Esri-shaped. This corpus runs
+ * the same catalog against a plain **OGC API Features** endpoint — recorded from
+ * the public pygeoapi demo (`src/certification/ogc-data.ts`), the pinned
+ * `ogc-features` target in `config/live-conformance-endpoints.v1.json` — where
+ * nothing Esri exists: no `/rest/services`, no `serviceId`, no `layerId`.
+ *
+ * Every scenario addresses data with the protocol-neutral
+ * `ogc-features:<collectionId>` reference and filters with the typed semantic
+ * filter, a `bbox`, or a canonical temporal predicate. Grading is SEMANTIC, on
+ * anchors verified against the recorded data:
+ *
+ *   obs   (5 observations): avg(value)=96.14  max=103.5  stn_id=2147 => 2 rows
+ *                           value>95 => 2     2001-01-01..2004-01-01 => 3 rows
+ *                           bbox(-80,42,-78,44) => 2 rows
+ *   utah_city_locations (31 cities): sum(POP_2000)=354212  max=105166 (Provo)
+ *                           CO_SEAT='yes' => 1   POP_2000>100000 => 1
+ *
+ * Two scenarios grade HONESTY rather than data: OGC API Features has no
+ * server-side aggregation and no server-side extent operation, so those answers
+ * must arrive carrying an explicit degradation reason; and a CQL2 spatial
+ * predicate the endpoint does not publish must come back as a structured
+ * capability refusal, never as an empty feature list.
+ *
+ * Selected via `HONUA_EVAL_CORPUS=ogc` / `--corpus ogc`; the runner swaps in the
+ * OGC fixture client for this corpus (see `runner.ts`).
+ */
+const OBS = "ogc-features:obs";
+const CITIES = "ogc-features:utah_city_locations";
+export const OGC_CORPUS = [
+    // ── Protocol-neutral discovery ───────────────────────────────────────────
+    {
+        id: "ogc-discover-sources",
+        title: "Discover sources on an endpoint with no GeoServices catalog",
+        category: "discovery",
+        prompt: "What data can I query at this endpoint? List the sources and how I address them.",
+        criteria: {
+            requiredTools: ["honua_list_sources"],
+            answerMustInclude: ["ogc-features:obs", "ogc-features:utah_city_locations"],
+        },
+        script: [{ tool: "honua_list_sources", args: {} }],
+    },
+    {
+        id: "ogc-discover-geoservices-absent",
+        title: "The GeoServices family is reported absent, not as 'no data'",
+        category: "degradation",
+        prompt: "Does this endpoint publish any Esri feature services? Be honest if it does not.",
+        criteria: {
+            requiredTools: ["honua_list_sources"],
+            answerMustInclude: ["geoservices", "ogc-features:obs"],
+            answerMustMatch: ['"available":\\s*false'],
+        },
+        script: [{ tool: "honua_list_sources", args: {} }],
+    },
+    // ── Schema grounding ─────────────────────────────────────────────────────
+    {
+        id: "ogc-describe-collection",
+        title: "Inspect an OGC collection's schema before querying",
+        category: "grounding",
+        prompt: "Show me the fields on the observations collection before I query it.",
+        criteria: {
+            requiredTools: ["honua_describe_layer"],
+            answerMustInclude: ["stn_id", "value", "ogc-features"],
+        },
+        script: [{ tool: "honua_describe_layer", args: { source: OBS } }],
+    },
+    {
+        id: "ogc-describe-capabilities",
+        title: "Report the capabilities the protocol actually advertises",
+        category: "grounding",
+        prompt: "What can I actually do with the observations collection — can I aggregate on the server?",
+        criteria: {
+            requiredTools: ["honua_describe_layer"],
+            answerMustInclude: ["capabilities", "query"],
+            answerMustNotInclude: ['"queryAggregate"'],
+        },
+        script: [{ tool: "honua_describe_layer", args: { source: OBS } }],
+    },
+    // ── Counting through numberMatched ───────────────────────────────────────
+    {
+        id: "ogc-count-all",
+        title: "Count every record in an OGC collection",
+        category: "count",
+        prompt: "How many observations are there? Just the number.",
+        criteria: {
+            requiredTools: ["honua_count_features"],
+            forbiddenTools: ["honua_query_features"],
+            answerMustMatch: ['"count":\\s*5'],
+        },
+        script: [{ tool: "honua_count_features", args: { source: OBS } }],
+    },
+    {
+        id: "ogc-count-typed-filter",
+        title: "Count with the typed semantic filter (compiled to CQL2)",
+        category: "count",
+        prompt: "How many observations came from station 2147?",
+        criteria: {
+            requiredTools: ["honua_count_features"],
+            answerMustMatch: ['"count":\\s*2'],
+        },
+        script: [
+            {
+                tool: "honua_count_features",
+                args: { source: OBS, filter: { op: "eq", field: "stn_id", value: 2147 } },
+            },
+        ],
+    },
+    {
+        id: "ogc-count-county-seat",
+        title: "Count with a string equality filter",
+        category: "count",
+        prompt: "How many of these Utah cities are county seats?",
+        criteria: {
+            requiredTools: ["honua_count_features"],
+            answerMustMatch: ['"count":\\s*1'],
+        },
+        script: [
+            {
+                tool: "honua_count_features",
+                args: { source: CITIES, filter: { op: "eq", field: "CO_SEAT", value: "yes" } },
+            },
+        ],
+    },
+    // ── Typed filter + ordering ──────────────────────────────────────────────
+    {
+        id: "ogc-filter-and-sort",
+        title: "Filter and sort with the protocol-neutral vocabulary",
+        category: "query",
+        prompt: "Show me the observations with a value above 95, highest first.",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustMatch: ["103.5", '"returnedCount":\\s*2'],
+        },
+        script: [
+            {
+                tool: "honua_query_features",
+                args: {
+                    source: OBS,
+                    filter: { op: "gt", field: "value", value: 95 },
+                    orderBy: [{ field: "value", direction: "desc" }],
+                },
+            },
+        ],
+    },
+    {
+        id: "ogc-filter-compound",
+        title: "Compound AND filter over an OGC collection",
+        category: "query",
+        prompt: "Which observations from station 2147 have a value under 100?",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustMatch: ["93.5", '"returnedCount":\\s*1'],
+            answerMustNotInclude: ["103.5"],
+        },
+        script: [
+            {
+                tool: "honua_query_features",
+                args: {
+                    source: OBS,
+                    filter: {
+                        op: "and",
+                        args: [
+                            { op: "eq", field: "stn_id", value: 2147 },
+                            { op: "lt", field: "value", value: 100 },
+                        ],
+                    },
+                },
+            },
+        ],
+    },
+    {
+        id: "ogc-filter-largest-city",
+        title: "Find the largest city with a typed filter",
+        category: "reasoning",
+        prompt: "Which of these Utah cities had more than 100,000 people in 2000?",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustMatch: ["105166", '"returnedCount":\\s*1'],
+        },
+        script: [
+            {
+                tool: "honua_query_features",
+                args: { source: CITIES, filter: { op: "gt", field: "POP_2000", value: 100000 } },
+            },
+        ],
+    },
+    // ── Canonical geometry + temporal predicates ─────────────────────────────
+    {
+        id: "ogc-bbox-filter",
+        title: "Spatial filter through the canonical bbox",
+        category: "query",
+        prompt: "Which observations fall inside the box from -80,42 to -78,44? Include their geometry.",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustMatch: ['"returnedCount":\\s*2', '"geometryFormat":\\s*"geojson"'],
+            answerMustInclude: ["Point"],
+        },
+        script: [
+            {
+                tool: "honua_query_features",
+                args: { source: OBS, bbox: [-80, 42, -78, 44], returnGeometry: true },
+            },
+        ],
+    },
+    {
+        id: "ogc-temporal-interval",
+        title: "Canonical temporal interval on the collection time dimension",
+        category: "query",
+        prompt: "How many observations were recorded between 2001 and the start of 2004?",
+        criteria: {
+            requiredTools: ["honua_count_features"],
+            answerMustMatch: ['"count":\\s*3'],
+        },
+        script: [
+            {
+                tool: "honua_count_features",
+                args: { source: OBS, temporal: { start: "2001-01-01T00:00:00Z", end: "2004-01-01T00:00:00Z" } },
+            },
+        ],
+    },
+    {
+        id: "ogc-temporal-field",
+        title: "Canonical temporal predicate bound to an explicit field",
+        category: "query",
+        prompt: "Count the observations whose datetime column falls in 2001 through 2003.",
+        criteria: {
+            requiredTools: ["honua_count_features"],
+            answerMustMatch: ['"count":\\s*3'],
+        },
+        script: [
+            {
+                tool: "honua_count_features",
+                args: {
+                    source: OBS,
+                    temporal: { start: "2001-01-01T00:00:00Z", end: "2004-01-01T00:00:00Z", field: "datetime" },
+                },
+            },
+        ],
+    },
+    // ── Aggregation with honest degradation ──────────────────────────────────
+    {
+        id: "ogc-aggregate-sum",
+        title: "Aggregate over a protocol with no server-side aggregation",
+        category: "analysis",
+        prompt: "What is the total 2000 population across these Utah cities?",
+        criteria: {
+            requiredTools: ["honua_statistics"],
+            answerMustInclude: ["sum_POP_2000"],
+            answerMustMatch: ["354212"],
+        },
+        script: [{ tool: "honua_statistics", args: { source: CITIES, statisticType: "sum", onField: "POP_2000" } }],
+    },
+    {
+        id: "ogc-aggregate-degradation-reported",
+        title: "Client-side aggregation is reported, not passed off as server-side",
+        category: "degradation",
+        prompt: "Average the observation values, and tell me whether the server computed that or you did.",
+        criteria: {
+            requiredTools: ["honua_statistics"],
+            answerMustInclude: ["degraded", "queryAggregate", "client-side"],
+            answerMustMatch: ["96.14"],
+        },
+        script: [{ tool: "honua_statistics", args: { source: OBS, statisticType: "avg", onField: "value" } }],
+    },
+    {
+        id: "ogc-aggregate-grouped",
+        title: "Grouped aggregation across an OGC collection",
+        category: "analysis",
+        prompt: "Break the Utah cities down by whether they are county seats and count each group.",
+        criteria: {
+            requiredTools: ["honua_statistics"],
+            answerMustInclude: ["CO_SEAT"],
+            answerMustMatch: ['"count_POP_2000":\\s*30', '"count_POP_2000":\\s*1'],
+        },
+        script: [
+            {
+                tool: "honua_statistics",
+                args: { source: CITIES, statisticType: "count", onField: "POP_2000", groupBy: ["CO_SEAT"] },
+            },
+        ],
+    },
+    // ── Extent with honest provenance ────────────────────────────────────────
+    {
+        id: "ogc-extent-declared",
+        title: "Extent comes from the declared collection extent, and says so",
+        category: "degradation",
+        prompt: "What area do these Utah cities cover?",
+        criteria: {
+            requiredTools: ["honua_get_extent"],
+            answerMustInclude: ["declared-extent"],
+            answerMustMatch: ["-112.108489"],
+        },
+        script: [{ tool: "honua_get_extent", args: { source: CITIES } }],
+    },
+    // ── Capability honesty ───────────────────────────────────────────────────
+    {
+        id: "ogc-spatial-predicate-refused",
+        title: "An inexpressible spatial predicate refuses instead of returning nothing",
+        category: "degradation",
+        prompt: "Find the observations strictly within this polygon. If this endpoint cannot do that, say so — do not tell me there are none.",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustInclude: ["Part 3"],
+            answerMustNotInclude: ['"returnedCount": 0'],
+        },
+        script: [
+            {
+                tool: "honua_query_features",
+                args: {
+                    source: OBS,
+                    filter: {
+                        op: "within",
+                        geometry: {
+                            type: "Polygon",
+                            coordinates: [
+                                [
+                                    [-80, 42],
+                                    [-78, 42],
+                                    [-78, 44],
+                                    [-80, 44],
+                                    [-80, 42],
+                                ],
+                            ],
+                        },
+                    },
+                },
+            },
+        ],
+    },
+    {
+        id: "ogc-bad-source-reference",
+        title: "A malformed source reference is refused with the accepted forms",
+        category: "grounding",
+        prompt: "Query the collection called 'observations-2024' on this server.",
+        criteria: {
+            requiredTools: ["honua_query_features"],
+            answerMustInclude: ["invalid_source_reference", "ogc-features:<collectionId>"],
+        },
+        script: [{ tool: "honua_query_features", args: { source: "observations-2024" } }],
+    },
+    {
+        id: "ogc-style-unavailable",
+        title: "Styling degrades honestly on an OGC endpoint too",
+        category: "degradation",
+        prompt: "List the map styles this endpoint publishes.",
+        criteria: {
+            requiredTools: ["honua_get_style"],
+            answerMustInclude: ["OGC API - Styles"],
+            answerMustMatch: ['"available":\\s*false'],
+        },
+        script: [{ tool: "honua_get_style", args: {} }],
+    },
+    {
+        id: "ogc-capability-gap-explained",
+        title: "Explain the aggregation gap for the OGC protocol",
+        category: "grounding",
+        prompt: "Can OGC API Features aggregate on the server? If not, what should I do instead?",
+        criteria: {
+            requiredTools: ["honua_explain_capability_gap"],
+            answerMustInclude: ["explanation"],
+        },
+        script: [
+            {
+                tool: "honua_explain_capability_gap",
+                args: { capability: "queryAggregate", protocol: "ogc-features" },
+            },
+        ],
+    },
+    // ── Multi-step workflows ─────────────────────────────────────────────────
+    {
+        id: "ogc-discover-describe-query",
+        title: "Discover → describe → query, end to end, with zero Esri vocabulary",
+        category: "multi-step",
+        prompt: "I don't know this endpoint. Find a source, inspect its schema, then show me its highest-value observation.",
+        criteria: {
+            requiredTools: ["honua_list_sources", "honua_describe_layer", "honua_query_features"],
+            expectedToolSequence: ["honua_list_sources", "honua_describe_layer", "honua_query_features"],
+            answerMustMatch: ["103.5"],
+        },
+        script: [
+            { tool: "honua_list_sources", args: {} },
+            { tool: "honua_describe_layer", args: { source: OBS } },
+            {
+                tool: "honua_query_features",
+                args: { source: OBS, orderBy: [{ field: "value", direction: "desc" }], limit: 1 },
+            },
+        ],
+    },
+    {
+        id: "ogc-count-then-list",
+        title: "Check cardinality, then fetch the matching records",
+        category: "multi-step",
+        prompt: "How many observations exceed 95, and which are they?",
+        criteria: {
+            requiredTools: ["honua_count_features", "honua_query_features"],
+            expectedToolSequence: ["honua_count_features", "honua_query_features"],
+            answerMustMatch: ['"count":\\s*2', "99.9"],
+        },
+        script: [
+            {
+                tool: "honua_count_features",
+                args: { source: OBS, filter: { op: "gt", field: "value", value: 95 } },
+            },
+            {
+                tool: "honua_query_features",
+                args: { source: OBS, filter: { op: "gt", field: "value", value: 95 } },
+            },
+        ],
+    },
+    // ── Ambiguity / refusal ──────────────────────────────────────────────────
+    {
+        id: "ogc-clarify-which-collection",
+        title: "Ambiguous 'the data' → clarify which collection",
+        category: "clarification",
+        prompt: "Show me the data from this server.",
+        criteria: { requiredTools: [], expectClarification: true },
+        script: [],
+        clarify: {
+            question: "Which collection would you like — the observations (ogc-features:obs) or the Utah city locations (ogc-features:utah_city_locations)?",
+        },
+    },
+    {
+        id: "ogc-refuse-write",
+        title: "Read-only endpoint → refuse an edit",
+        category: "clarification",
+        prompt: "Set every observation value to 100 and save it.",
+        criteria: { requiredTools: [], expectClarification: true },
+        script: [],
+        clarify: {
+            question: "This MCP surface is read-only, so I can't write features to this OGC API Features endpoint. Would you like me to query or aggregate the observations instead?",
+        },
+    },
+];

package/dist/src/eval/runner.d.ts

@@ -23,6 +23,12 @@ export interface RunEvalOptions {
      * Defaults to true when `HONUA_EVAL_CORPUS=standalone`.
      */
     forceStandaloneSurface?: boolean;
+    /**
+     * Use the NON-GeoServices fixture surface (a plain OGC API Features endpoint,
+     * recorded pygeoapi collections) instead of either Honua/Esri fixture. Implies
+     * offline. Defaults to true when `HONUA_EVAL_CORPUS=ogc` (issue #1005).
+     */
+    forceOgcSurface?: boolean;
 }
 export declare function runEval(options?: RunEvalOptions): Promise<EvalReport>;
 //# sourceMappingURL=runner.d.ts.map

package/dist/src/eval/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/eval/runner.ts"],"names":[],"mappings":"AAUA,OAAO,EAAiB,KAAK,UAAU,EAAkB,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAmC,MAAM,YAAY,CAAC;AAEzF;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AA+FD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiD/E"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/eval/runner.ts"],"names":[],"mappings":"AAWA,OAAO,EAAiB,KAAK,UAAU,EAAkB,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAmC,MAAM,YAAY,CAAC;AAEzF;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA4GD,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkD/E"}

package/dist/src/eval/runner.js

@@ -2,10 +2,11 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { createStandaloneFixtureClient } from "../certification/census-fixture-client.js";
 import { createFixtureClient } from "../certification/fixture-client.js";
+import { createOgcFixtureClient } from "../certification/ogc-fixture-client.js";
 import { createServer } from "../index.js";
 import { readNegotiatedProtocolVersion, resolveSuiteGitSha } from "../provenance.js";
 import { connectUpstream, resolveProxyOptions } from "../proxy.js";
-import { isStandaloneCorpus, resolveCorpus } from "./corpus.js";
+import { isOgcCorpus, isStandaloneCorpus, resolveCorpus } from "./corpus.js";
 import { resolveDrivers } from "./drivers/index.js";
 import { grade } from "./grade.js";
 import { assembleReport } from "./report.js";
@@ -17,8 +18,12 @@ function isTruthy(value) {
     const v = value.trim().toLowerCase();
     return v.length > 0 && v !== "0" && v !== "false" && v !== "no" && v !== "off";
 }
-async function connectSurface(env, forceOffline, standalone) {
-    const live = !forceOffline && !standalone && typeof env.HONUA_MCP_REMOTE_URL === "string" && env.HONUA_MCP_REMOTE_URL.length > 0;
+async function connectSurface(env, forceOffline, standalone, ogc) {
+    const live = !forceOffline &&
+        !standalone &&
+        !ogc &&
+        typeof env.HONUA_MCP_REMOTE_URL === "string" &&
+        env.HONUA_MCP_REMOTE_URL.length > 0;
     if (live) {
         const options = resolveProxyOptions(env);
         // The live lane authenticates via the proxy's real credential headers — no
@@ -41,7 +46,11 @@ async function connectSurface(env, forceOffline, standalone) {
             },
         };
     }
-    const fixtureClient = standalone ? createStandaloneFixtureClient() : createFixtureClient();
+    const fixtureClient = ogc
+        ? createOgcFixtureClient()
+        : standalone
+            ? createStandaloneFixtureClient()
+            : createFixtureClient();
     const server = createServer(fixtureClient);
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({ name: "honua-mcp-eval", version: "1.0.0" });
@@ -50,7 +59,11 @@ async function connectSurface(env, forceOffline, standalone) {
     return {
         client,
         backend: "fixture",
-        mcpTransport: standalone ? "in-memory (standalone FeatureServer fixture)" : "in-memory",
+        mcpTransport: ogc
+            ? "in-memory (standalone OGC API Features fixture)"
+            : standalone
+                ? "in-memory (standalone FeatureServer fixture)"
+                : "in-memory",
         auth: "none",
         close: async () => {
             await client.close().catch(() => { });
@@ -86,8 +99,9 @@ export async function runEval(options = {}) {
     const corpus = options.corpus ?? resolveCorpus(env);
     const drivers = options.drivers ?? resolveDrivers({ env });
     const standalone = options.forceStandaloneSurface ?? isStandaloneCorpus(env);
-    const forceOffline = options.forceOffline ?? standalone;
-    const surface = await connectSurface(env, forceOffline, standalone);
+    const ogc = options.forceOgcSurface ?? isOgcCorpus(env);
+    const forceOffline = options.forceOffline ?? (standalone || ogc);
+    const surface = await connectSurface(env, forceOffline, standalone, ogc);
     try {
         const listed = await surface.client.listTools();
         const tools = listed.tools.map((t) => ({

package/dist/src/helpers.d.ts

@@ -1,6 +1,12 @@
-import type { EsriGeometryType, EsriSpatialRel } from "@honua/sdk-js/honua";
+import type { EsriGeometryType } from "@honua/sdk-js/honua";
+/**
+ * Esri geometry-type tags.
+ *
+ * These are the SDK's canonical geometry-operand tags, not part of the tool
+ * contract: the tool surface takes GeoJSON (see `neutral/filter.ts`) and only
+ * accepts these to disambiguate Esri-JSON geometry sent by legacy clients.
+ */
 export declare const GEOMETRY_TYPES: readonly ["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"];
-export declare function mapSpatialRel(rel: string | undefined): EsriSpatialRel | undefined;
 export declare function clampLimit(limit: number | undefined): number;
 export declare function resolveGeometryType(geometry: Record<string, unknown> | undefined, geometryType: EsriGeometryType | undefined): EsriGeometryType | undefined;
 export declare function jsonText(result: unknown): {
@@ -10,17 +16,6 @@ export declare function jsonText(result: unknown): {
     }>;
 };
 export declare function metadataErrorText(): string;
-/**
- * Coerce a feature `count` from a query response into a usable value.
- *
- * The default `grpc-web` transport returns counts via `toSafeNumberOrString`,
- * which yields a **string** when the proto count exceeds
- * `Number.MAX_SAFE_INTEGER` (chosen specifically to avoid precision loss). Both
- * a finite `number` and a numeric `string` are valid counts; anything else
- * (non-finite numbers, non-numeric strings, missing values) returns
- * `undefined`.
- */
-export declare function coerceCount(value: unknown): number | string | undefined;
 export declare function encodeServiceId(serviceId: string): string;
 export declare function decodeServiceId(encoded: string): string;
 export declare function parseLayerId(value: string): number;

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM5E,eAAO,MAAM,cAAc,iIAMjB,CAAC;AAQX,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAKjF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,gBAAgB,GAAG,SAAS,CA8B9B;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAE5F;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,iIAMjB,CAAC;AAEX,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,gBAAgB,GAAG,SAAS,CA8B9B;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAE5F;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}

package/dist/src/helpers.js

@@ -1,6 +1,13 @@
 const MAX_LIMIT = 2000;
 const DEFAULT_LIMIT = 100;
 const METADATA_ERROR_MESSAGE = "Failed to fetch service metadata.";
+/**
+ * Esri geometry-type tags.
+ *
+ * These are the SDK's canonical geometry-operand tags, not part of the tool
+ * contract: the tool surface takes GeoJSON (see `neutral/filter.ts`) and only
+ * accepts these to disambiguate Esri-JSON geometry sent by legacy clients.
+ */
 export const GEOMETRY_TYPES = [
     "esriGeometryPoint",
     "esriGeometryPolyline",
@@ -8,19 +15,6 @@ export const GEOMETRY_TYPES = [
     "esriGeometryEnvelope",
     "esriGeometryMultipoint",
 ];
-const SPATIAL_REL_MAP = {
-    intersects: "esriSpatialRelIntersects",
-    contains: "esriSpatialRelContains",
-    within: "esriSpatialRelWithin",
-};
-export function mapSpatialRel(rel) {
-    if (!rel)
-        return undefined;
-    const mapped = SPATIAL_REL_MAP[rel];
-    if (!mapped)
-        throw new Error(`Unknown spatialRel "${rel}". Expected: intersects, contains, within`);
-    return mapped;
-}
 export function clampLimit(limit) {
     const n = limit ?? DEFAULT_LIMIT;
     return Math.min(Math.max(1, n), MAX_LIMIT);
@@ -55,28 +49,6 @@ export function jsonText(result) {
 export function metadataErrorText() {
     return METADATA_ERROR_MESSAGE;
 }
-/**
- * Coerce a feature `count` from a query response into a usable value.
- *
- * The default `grpc-web` transport returns counts via `toSafeNumberOrString`,
- * which yields a **string** when the proto count exceeds
- * `Number.MAX_SAFE_INTEGER` (chosen specifically to avoid precision loss). Both
- * a finite `number` and a numeric `string` are valid counts; anything else
- * (non-finite numbers, non-numeric strings, missing values) returns
- * `undefined`.
- */
-export function coerceCount(value) {
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? value : undefined;
-    }
-    if (typeof value === "string") {
-        // Accept canonical base-10 integer strings (optionally signed). These are
-        // the large-count representation the grpc adapter emits to preserve
-        // precision beyond Number.MAX_SAFE_INTEGER.
-        return /^-?\d+$/.test(value.trim()) ? value.trim() : undefined;
-    }
-    return undefined;
-}
 export function encodeServiceId(serviceId) {
     return encodeURIComponent(serviceId);
 }

package/dist/src/index.d.ts

@@ -22,13 +22,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

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;AAe7F,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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aAsGlF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}