@honua/mcp-server 0.0.10-alpha.0 → 0.0.20-alpha.0

package/dist/src/styles.js

@@ -0,0 +1,118 @@
+/**
+ * Thin read-only client over the server's OGC API – Styles surface
+ * (honua-server, ADR-0048):
+ *
+ *   GET /ogc/styles                     -> styles list   ({ styles: [{ id, title, links }], default? })
+ *   GET /ogc/styles/{styleId}/metadata  -> style metadata ({ id, title, description, keywords, license, version, links })
+ *   GET /ogc/styles/{styleId}           -> stylesheet body (MapLibre/Mapbox JSON by default; SLD via Accept)
+ *
+ * These helpers project the server responses into the geospatial-grpc
+ * `StyleRef` / `StyleEncoding` shape (style_id / title / encodings) so the MCP
+ * resource + `get_style` tool surface a single canonical style object.
+ *
+ * The MCP package only consumes the public {@link HonuaClient.pipelineFetch}
+ * request pipeline (auth / retry / timeout / interceptors) rather than a
+ * private route, matching the other `/ogc/*` consumers in the SDK.
+ *
+ * @module
+ */
+/** Default path prefix for the server's OGC API – Styles surface. */
+export const OGC_STYLES_PATH = "/ogc/styles";
+/** MapLibre / Mapbox style media type (server default stylesheet encoding). */
+export const MAPLIBRE_STYLE_MEDIA_TYPE = "application/vnd.mapbox.style+json";
+/** SLD 1.0 stylesheet media type. */
+export const SLD_10_MEDIA_TYPE = "application/vnd.ogc.sld+xml;version=1.0";
+/** SLD 1.1 stylesheet media type. */
+export const SLD_11_MEDIA_TYPE = "application/vnd.ogc.sld+xml;version=1.1";
+/**
+ * Stylesheet encodings the MCP surface understands, keyed by the canonical
+ * geospatial-grpc `StyleEncoding.encoding` identifier. The server
+ * content-negotiates these via the `Accept` header.
+ */
+export const STYLE_ENCODINGS = {
+    "mapbox-style": MAPLIBRE_STYLE_MEDIA_TYPE,
+    "sld-1.0.0": SLD_10_MEDIA_TYPE,
+    "sld-1.1.0": SLD_11_MEDIA_TYPE,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function getJson(client, path, accept) {
+    const response = await client.pipelineFetch("GET", path, { headers: { Accept: accept } });
+    return (await response.json());
+}
+function stylePath(styleId) {
+    return `${OGC_STYLES_PATH}/${encodeURIComponent(styleId)}`;
+}
+/** List available styles via `GET /ogc/styles`. */
+export async function listStyles(client) {
+    const body = await getJson(client, OGC_STYLES_PATH, "application/json");
+    if (!isRecord(body) || !Array.isArray(body.styles)) {
+        return { styles: [] };
+    }
+    const styles = [];
+    for (const entry of body.styles) {
+        if (isRecord(entry) && typeof entry.id === "string") {
+            styles.push({
+                id: entry.id,
+                ...(typeof entry.title === "string" ? { title: entry.title } : {}),
+                ...(Array.isArray(entry.links) ? { links: entry.links } : {}),
+            });
+        }
+    }
+    return {
+        styles,
+        ...(typeof body.default === "string" ? { default: body.default } : {}),
+        ...(Array.isArray(body.links) ? { links: body.links } : {}),
+    };
+}
+/** Fetch style metadata via `GET /ogc/styles/{styleId}/metadata`. */
+export async function getStyleMetadata(client, styleId) {
+    const body = await getJson(client, `${stylePath(styleId)}/metadata`, "application/json");
+    return body;
+}
+/**
+ * Fetch the MapLibre/Mapbox stylesheet body via `GET /ogc/styles/{styleId}`
+ * (content-negotiated to {@link MAPLIBRE_STYLE_MEDIA_TYPE}).
+ */
+export async function getMapLibreStylesheet(client, styleId) {
+    return getJson(client, stylePath(styleId), `${MAPLIBRE_STYLE_MEDIA_TYPE}, application/json;q=0.9`);
+}
+/** Coerce a free-form metadata `version` (string) into the numeric style_version, when possible. */
+function parseStyleVersion(version) {
+    if (version === undefined)
+        return null;
+    const parsed = Number.parseInt(version, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Resolve a single style into a `StyleRef` projection: fetch metadata and the
+ * canonical MapLibre stylesheet, and advertise the alternate SLD encodings by
+ * reference. The stylesheet base URL (`{baseUrl}/ogc/styles/{styleId}`) backs
+ * the `storageRef` for the by-reference encodings.
+ */
+export async function resolveStyleRef(client, styleId) {
+    const [metadata, maplibre] = await Promise.all([
+        getStyleMetadata(client, styleId).catch(() => null),
+        getMapLibreStylesheet(client, styleId),
+    ]);
+    const stylesheetUrl = `${client.serverBaseUrl}${stylePath(styleId)}`;
+    const encodings = [
+        {
+            encoding: "mapbox-style",
+            contentType: MAPLIBRE_STYLE_MEDIA_TYPE,
+            inlineBody: maplibre,
+        },
+        { encoding: "sld-1.0.0", contentType: SLD_10_MEDIA_TYPE, storageRef: stylesheetUrl },
+        { encoding: "sld-1.1.0", contentType: SLD_11_MEDIA_TYPE, storageRef: stylesheetUrl },
+    ];
+    const legendUrl = metadata?.links?.find((l) => l.rel === "preview")?.href ?? null;
+    return {
+        styleId,
+        title: metadata?.title ?? styleId,
+        description: metadata?.description ?? null,
+        styleVersion: parseStyleVersion(metadata?.version),
+        legendUrl,
+        encodings,
+    };
+}

package/dist/src/tools/apply-style-preset.d.ts

@@ -0,0 +1,27 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    styleId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    styleId: string;
+}, {
+    styleId: string;
+}>;
+export type Input = z.infer<typeof schema>;
+/**
+ * Resolve a style preset for client-side application. Returns the canonical
+ * `StyleRef` plus the MapLibre/Mapbox stylesheet body so an agent or downstream
+ * runtime can apply the preset to a map.
+ *
+ * This is a read-only inspection projection: it resolves and returns the
+ * preset's stylesheet but never mutates server state. Persisting a preset onto
+ * a map or published service stays with the typed gRPC execution layer per the
+ * MCP boundary (geospatial-mcp taxonomy / ADR-0028).
+ */
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=apply-style-preset.d.ts.map

package/dist/src/tools/apply-style-preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-style-preset.d.ts","sourceRoot":"","sources":["../../../src/tools/apply-style-preset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,MAAM;;;;;;EAEjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAa9D"}

package/dist/src/tools/apply-style-preset.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { jsonText } from "../helpers.js";
+import { resolveStyleRef } from "../styles.js";
+export const schema = z.object({
+    styleId: z.string().describe("Stable style identifier of the preset to resolve."),
+});
+/**
+ * Resolve a style preset for client-side application. Returns the canonical
+ * `StyleRef` plus the MapLibre/Mapbox stylesheet body so an agent or downstream
+ * runtime can apply the preset to a map.
+ *
+ * This is a read-only inspection projection: it resolves and returns the
+ * preset's stylesheet but never mutates server state. Persisting a preset onto
+ * a map or published service stays with the typed gRPC execution layer per the
+ * MCP boundary (geospatial-mcp taxonomy / ADR-0028).
+ */
+export async function execute(client, input) {
+    // `resolveStyleRef` already fetches the MapLibre stylesheet and inlines it on
+    // the `mapbox-style` encoding, so reuse that body instead of issuing a second
+    // identical GET /ogc/styles/{id}.
+    const styleRef = await resolveStyleRef(client, input.styleId);
+    const stylesheet = styleRef.encodings.find((e) => e.encoding === "mapbox-style")?.inlineBody ?? null;
+    return jsonText({
+        style: styleRef,
+        stylesheet,
+        application: "client-side",
+        note: "Apply this MapLibre stylesheet client-side. MCP does not mutate server state; persisting a preset to a map or service uses the gRPC execution layer.",
+    });
+}

package/dist/src/tools/count-features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"count-features.d.ts","sourceRoot":"","sources":["../../../src/tools/count-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAajB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAoB9D"}
+{"version":3,"file":"count-features.d.ts","sourceRoot":"","sources":["../../../src/tools/count-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAajB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAqB9D"}

package/dist/src/tools/count-features.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { GEOMETRY_TYPES, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
+import { GEOMETRY_TYPES, coerceCount, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
 export const schema = z.object({
     serviceId: z.string().describe("The feature service ID"),
     layerId: z.number().int().nonnegative().describe("The layer ID within the service"),
@@ -26,9 +26,10 @@ export async function execute(client, input) {
         outFields: "OBJECTID",
         extraParams: { returnCountOnly: true },
     }));
-    const hasCount = Object.prototype.hasOwnProperty.call(response, "count");
-    const count = response.count;
-    if (!hasCount || typeof count !== "number" || !Number.isFinite(count)) {
+    // The default grpc-web transport returns very large counts as a string to
+    // preserve precision beyond Number.MAX_SAFE_INTEGER; accept both forms.
+    const count = coerceCount(response.count);
+    if (count === undefined) {
         throw new Error("Count query did not return a numeric count.");
     }
     return jsonText({ count });

package/dist/src/tools/get-extent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-extent.d.ts","sourceRoot":"","sources":["../../../src/tools/get-extent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAajB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAmC9D"}
+{"version":3,"file":"get-extent.d.ts","sourceRoot":"","sources":["../../../src/tools/get-extent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAajB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAoC9D"}

package/dist/src/tools/get-extent.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { GEOMETRY_TYPES, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
+import { GEOMETRY_TYPES, coerceCount, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
 export const schema = z.object({
     serviceId: z.string().describe("The feature service ID"),
     layerId: z.number().int().nonnegative().describe("The layer ID within the service"),
@@ -25,8 +25,9 @@ export async function execute(client, input) {
         returnGeometry: false,
         extraParams: { returnExtentOnly: true },
     }));
-    const hasCount = Object.prototype.hasOwnProperty.call(response, "count");
-    const count = hasCount && typeof response.count === "number" && Number.isFinite(response.count) ? response.count : undefined;
+    // Accept large counts returned as strings by the grpc-web transport (chosen
+    // to preserve precision beyond Number.MAX_SAFE_INTEGER) as well as numbers.
+    const count = coerceCount(response.count);
     const hasExtent = Object.prototype.hasOwnProperty.call(response, "extent");
     if (!hasExtent) {
         // Some backends can return count-only payloads for empty extent queries.
@@ -39,7 +40,8 @@ export async function execute(client, input) {
     if (response.extent === null) {
         extent = null;
     }
-    else if (typeof response.extent === "object") {
+    else if (typeof response.extent === "object" && !Array.isArray(response.extent)) {
+        // A JSON array is `typeof "object"` but is not a valid extent envelope.
         extent = response.extent;
     }
     else {

package/dist/src/tools/get-style.d.ts

@@ -0,0 +1,24 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    styleId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    styleId?: string | undefined;
+}, {
+    styleId?: string | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+/**
+ * Resolve a style from the server's OGC API – Styles surface. With a `styleId`,
+ * returns the canonical `StyleRef` projection (style_id / title / description /
+ * style_version / encodings / legend_url), with the MapLibre stylesheet inlined.
+ * Without a `styleId`, returns the styles catalog so an agent can discover what
+ * is available.
+ */
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=get-style.d.ts.map

package/dist/src/tools/get-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-style.d.ts","sourceRoot":"","sources":["../../../src/tools/get-style.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,MAAM;;;;;;EAEjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAe9D"}

package/dist/src/tools/get-style.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { jsonText } from "../helpers.js";
+import { listStyles, resolveStyleRef } from "../styles.js";
+export const schema = z.object({
+    styleId: z.string().optional().describe("Stable style identifier. Omit to list the styles available on the server."),
+});
+/**
+ * Resolve a style from the server's OGC API – Styles surface. With a `styleId`,
+ * returns the canonical `StyleRef` projection (style_id / title / description /
+ * style_version / encodings / legend_url), with the MapLibre stylesheet inlined.
+ * Without a `styleId`, returns the styles catalog so an agent can discover what
+ * is available.
+ */
+export async function execute(client, input) {
+    if (!input.styleId) {
+        const list = await listStyles(client);
+        return jsonText({
+            styles: list.styles.map((entry) => ({
+                styleId: entry.id,
+                title: entry.title ?? entry.id,
+                uri: `honua://styles/${encodeURIComponent(entry.id)}`,
+            })),
+            default: list.default ?? null,
+        });
+    }
+    const styleRef = await resolveStyleRef(client, input.styleId);
+    return jsonText(styleRef);
+}

package/dist/src/tools/query-features.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-features.d.ts","sourceRoot":"","sources":["../../../src/tools/query-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GA4B9D"}
+{"version":3,"file":"query-features.d.ts","sourceRoot":"","sources":["../../../src/tools/query-features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GA+B9D"}

package/dist/src/tools/query-features.js

@@ -24,7 +24,10 @@ export async function execute(client, input) {
         serviceId: input.serviceId,
         layerId: input.layerId,
         where: input.where,
-        outFields: input.outFields ?? "*",
+        // An empty array is a natural "no specific fields" from an agent, but Esri
+        // FeatureServer treats an empty outFields as "OBJECTID only". Coerce both
+        // missing and empty to "*" so all fields are returned.
+        outFields: input.outFields && input.outFields.length > 0 ? input.outFields : "*",
         geometry: input.geometry,
         geometryType: resolveGeometryType(input.geometry, input.geometryType),
         spatialRel: mapSpatialRel(input.spatialRel),

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@honua/mcp-server",
-  "version": "0.0.10-alpha.0",
+  "version": "0.0.20-alpha.0",
   "description": "MCP server for Honua geospatial feature services",
   "type": "module",
   "bin": {
-    "honua-mcp": "dist/src/index.js"
+    "honua-mcp": "dist/src/index.js",
+    "honua-mcp-proxy": "dist/src/proxy.js"
   },
   "scripts": {
     "clean": "rm -rf dist coverage",
@@ -14,6 +15,14 @@
     "test": "npm run build --silent && vitest run --coverage",
     "test:unit": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "certify": "npm run build --silent && node dist/src/certification/cli.js",
+    "test:certification": "npm run build --silent && vitest run test/certification && node dist/src/certification/cli.js",
+    "test:certification:artifact": "npm run build --silent && node dist/src/certification/cli.js --artifact-only",
+    "eval": "npm run build --silent && node dist/src/eval/cli.js",
+    "eval:offline": "npm run build --silent && node dist/src/eval/cli.js --offline",
+    "eval:live": "npm run build --silent && node dist/src/eval/cli.js --corpus operator --artifact-only",
+    "test:eval": "npm run build --silent && vitest run test/eval && node dist/src/eval/cli.js --offline",
+    "test:eval:artifact": "npm run build --silent && node dist/src/eval/cli.js --artifact-only",
     "lint": "biome lint src/ test/",
     "lint:fix": "biome lint --write src/ test/",
     "format": "biome format src/ test/",
@@ -22,15 +31,20 @@
     "check:fix": "biome check --write src/ test/"
   },
   "dependencies": {
+    "@aws-sdk/client-bedrock-runtime": "^3.901.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.20.0",
     "zod": "^3.24.0"
   },
+  "overrides": {
+    "hono": "^4.12.21"
+  },
   "peerDependencies": {
-    "@honua/sdk-js": "^0.0.10-alpha.0"
+    "@honua/sdk-js": "^0.0.20-alpha.0"
   },
   "devDependencies": {
-    "@honua/sdk-js": "file:..",
     "@biomejs/biome": "1.9.4",
+    "@honua/sdk-js": "file:..",
     "@types/node": "^24.3.1",
     "@vitest/coverage-v8": "^4.0.16",
     "typescript": "^5.9.2",
@@ -38,6 +52,7 @@
   },
   "files": [
     "dist/src",
+    "certification/geospatial-mcp-schemas",
     "README.md"
   ],
   "engines": {