@honua/mcp-server 0.0.6-alpha.0

package/README.md

@@ -0,0 +1,42 @@
+# `@honua/mcp-server`
+
+Model Context Protocol (MCP) server for Honua geospatial feature services.
+
+This package exposes a focused MCP surface for discovery and query workflows on top of Honua's FeatureServer APIs.
+
+## Requirements
+
+- Node.js `>=20`
+- A reachable Honua server URL
+
+## Environment Variables
+
+- `HONUA_BASE_URL` (required): absolute Honua base URL, for example `https://honua.example.com`
+- `HONUA_TRANSPORT` (optional): `grpc-web` (default) or `rest`
+- `HONUA_API_KEY` (optional): admin/API key when your deployment requires it
+- `HONUA_TIMEOUT_MS` (optional): request timeout in milliseconds (default `30000`)
+- `HONUA_RETRY_MAX_RETRIES` (optional): retry attempts for transient failures (default `2`)
+
+When `HONUA_API_KEY` is configured, use `https://` for non-localhost servers.
+
+## Run Locally
+
+```bash
+npm install
+npm run build
+HONUA_BASE_URL="https://honua.example.com" HONUA_TRANSPORT="grpc-web" node dist/src/index.js
+```
+
+## MCP Tools
+
+- `honua_list_services`
+- `honua_describe_layer`
+- `honua_query_features`
+- `honua_count_features`
+- `honua_get_extent`
+- `honua_statistics`
+
+## MCP Resources
+
+- `honua://services`
+- `honua://services/{encodedServiceId}/layers/{layerId}`

package/dist/src/helpers.d.ts

@@ -0,0 +1,17 @@
+import type { EsriGeometryType, EsriSpatialRel } from "@honua/sdk-js";
+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): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+export declare function metadataErrorText(): string;
+export declare function encodeServiceId(serviceId: string): string;
+export declare function decodeServiceId(encoded: string): string;
+export declare function parseLayerId(value: string): number;
+export declare function mapWithConcurrency<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMtE,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,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

@@ -0,0 +1,93 @@
+const MAX_LIMIT = 2000;
+const DEFAULT_LIMIT = 100;
+const METADATA_ERROR_MESSAGE = "Failed to fetch service metadata.";
+export const GEOMETRY_TYPES = [
+    "esriGeometryPoint",
+    "esriGeometryPolyline",
+    "esriGeometryPolygon",
+    "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);
+}
+export function resolveGeometryType(geometry, geometryType) {
+    if (geometryType) {
+        return geometryType;
+    }
+    if (!geometry) {
+        return undefined;
+    }
+    if ("xmin" in geometry && "xmax" in geometry && "ymin" in geometry && "ymax" in geometry) {
+        return "esriGeometryEnvelope";
+    }
+    if ("x" in geometry && "y" in geometry) {
+        return "esriGeometryPoint";
+    }
+    if (Array.isArray(geometry.rings)) {
+        return "esriGeometryPolygon";
+    }
+    if (Array.isArray(geometry.paths)) {
+        return "esriGeometryPolyline";
+    }
+    if (Array.isArray(geometry.points)) {
+        return "esriGeometryMultipoint";
+    }
+    return undefined;
+}
+export function jsonText(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+export function metadataErrorText() {
+    return METADATA_ERROR_MESSAGE;
+}
+export function encodeServiceId(serviceId) {
+    return encodeURIComponent(serviceId);
+}
+export function decodeServiceId(encoded) {
+    try {
+        return decodeURIComponent(encoded);
+    }
+    catch {
+        throw new Error(`Invalid encoded serviceId: "${encoded}"`);
+    }
+}
+export function parseLayerId(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`Invalid layerId: "${value}"`);
+    }
+    return Number.parseInt(value, 10);
+}
+export async function mapWithConcurrency(items, concurrency, fn) {
+    if (concurrency < 1 || !Number.isFinite(concurrency)) {
+        throw new Error(`Invalid concurrency value: ${concurrency}`);
+    }
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length || 1) }, async () => {
+        while (true) {
+            const index = cursor;
+            cursor += 1;
+            if (index >= items.length) {
+                return;
+            }
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { HonuaClient } from "@honua/sdk-js";
+import type { HonuaTransport } from "@honua/sdk-js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface RuntimeOptions {
+    baseUrl: string;
+    apiKey: string | undefined;
+    transport: HonuaTransport;
+    timeoutMs: number;
+    retryMaxRetries: number;
+}
+export declare const SERVER_VERSION: string;
+export declare function resolveRuntimeOptions(env: NodeJS.ProcessEnv): RuntimeOptions;
+export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClient;
+export declare function createServer(client: HonuaClient): McpServer;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;AAYtF,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;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,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,aA8D/C"}

package/dist/src/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { HonuaClient } from "@honua/sdk-js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as layerSchemaResource from "./resources/layer-schema.js";
+import * as servicesResource from "./resources/services.js";
+import * as countFeatures from "./tools/count-features.js";
+import * as describeLayer from "./tools/describe-layer.js";
+import * as getExtent from "./tools/get-extent.js";
+import * as listServices from "./tools/list-services.js";
+import * as queryFeatures from "./tools/query-features.js";
+import * as statistics from "./tools/statistics.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_SERVER_VERSION = "0.0.3-alpha.0";
+export const SERVER_VERSION = resolveServerVersion();
+function resolveServerVersion() {
+    try {
+        const packageJsonPath = new URL("../../package.json", import.meta.url);
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
+            return packageJson.version;
+        }
+    }
+    catch {
+        // Fall back to a static version if package metadata is unavailable.
+    }
+    return DEFAULT_SERVER_VERSION;
+}
+function parsePositiveInteger(env, name, defaultValue) {
+    const raw = env[name];
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    const normalized = raw.trim();
+    if (!/^\d+$/.test(normalized)) {
+        throw new Error(`${name} must be a positive integer, received "${raw}"`);
+    }
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`${name} must be a positive integer, received "${raw}"`);
+    }
+    return parsed;
+}
+function parseNonNegativeInteger(env, name, defaultValue) {
+    const raw = env[name];
+    if (raw === undefined) {
+        return defaultValue;
+    }
+    const normalized = raw.trim();
+    if (!/^\d+$/.test(normalized)) {
+        throw new Error(`${name} must be a non-negative integer, received "${raw}"`);
+    }
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`${name} must be a non-negative integer, received "${raw}"`);
+    }
+    return parsed;
+}
+function isLoopbackHost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+export function resolveRuntimeOptions(env) {
+    const baseUrl = env.HONUA_BASE_URL;
+    if (!baseUrl) {
+        throw new Error("HONUA_BASE_URL environment variable is required.");
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`HONUA_BASE_URL must be a valid absolute URL: ${baseUrl}`);
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error(`HONUA_BASE_URL must use http or https: ${baseUrl}`);
+    }
+    const apiKey = env.HONUA_API_KEY;
+    if (apiKey && parsedUrl.protocol === "http:" && !isLoopbackHost(parsedUrl.hostname)) {
+        throw new Error("HONUA_API_KEY over non-local HTTP is not allowed. Use HTTPS, or use localhost for local development.");
+    }
+    const rawTransportInput = env.HONUA_TRANSPORT ?? "grpc-web";
+    const normalizedTransport = rawTransportInput.trim().toLowerCase();
+    const transport = normalizedTransport === "grpc-web" || normalizedTransport === "grpc" || normalizedTransport === "grcp"
+        ? "grpc-web"
+        : normalizedTransport === "rest"
+            ? "rest"
+            : undefined;
+    if (!transport) {
+        throw new Error(`HONUA_TRANSPORT must be "grpc-web" (aliases: "grpc", "grcp") or "rest", received "${rawTransportInput}"`);
+    }
+    const timeoutMs = parsePositiveInteger(env, "HONUA_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+    const retryMaxRetries = parseNonNegativeInteger(env, "HONUA_RETRY_MAX_RETRIES", DEFAULT_MAX_RETRIES);
+    return {
+        baseUrl: parsedUrl.toString(),
+        apiKey,
+        transport,
+        timeoutMs,
+        retryMaxRetries,
+    };
+}
+export function createClientFromEnv(env = process.env) {
+    const options = resolveRuntimeOptions(env);
+    return new HonuaClient({
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        transport: options.transport,
+        timeoutMs: options.timeoutMs,
+        retry: options.retryMaxRetries > 0 ? { maxRetries: options.retryMaxRetries } : undefined,
+    });
+}
+export function createServer(client) {
+    const server = new McpServer({
+        name: "honua",
+        version: SERVER_VERSION,
+    });
+    // ── Tools ──────────────────────────────────────────────────────
+    server.tool("honua_list_services", "Discover all available feature services. Set includeDetails=true for descriptions, layer counts, and spatial references.", listServices.schema.shape, async (args) => listServices.execute(client, listServices.schema.parse(args)));
+    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_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)));
+    // ── 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));
+    return server;
+}
+async function main() {
+    const client = createClientFromEnv();
+    const server = createServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/src/resources/layer-schema.d.ts

@@ -0,0 +1,10 @@
+import type { HonuaClient } from "@honua/sdk-js";
+export declare const uriTemplate = "honua://services/{encodedServiceId}/layers/{layerId}";
+export declare function read(client: HonuaClient, encodedServiceId: string, layerId: string): Promise<{
+    contents: {
+        uri: string;
+        mimeType: "application/json";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=layer-schema.d.ts.map

package/dist/src/resources/layer-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-schema.d.ts","sourceRoot":"","sources":["../../../src/resources/layer-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,eAAO,MAAM,WAAW,yDAAyD,CAAC;AAElF,wBAAsB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;;;;;;GA4BxF"}

package/dist/src/resources/layer-schema.js

@@ -0,0 +1,27 @@
+import { decodeServiceId, parseLayerId } from "../helpers.js";
+export const uriTemplate = "honua://services/{encodedServiceId}/layers/{layerId}";
+export async function read(client, encodedServiceId, layerId) {
+    const serviceId = decodeServiceId(encodedServiceId);
+    const layerIdNum = parseLayerId(layerId);
+    const meta = await client.getLayerMetadata(serviceId, layerIdNum);
+    const schema = {
+        id: meta.id,
+        name: meta.name,
+        description: meta.description ?? null,
+        geometryType: meta.geometryType ?? null,
+        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type, alias: f.alias ?? f.name })),
+        extent: meta.extent ?? null,
+        spatialReference: meta.spatialReference ?? null,
+        relationships: meta.relationships ?? [],
+    };
+    const uri = `honua://services/${encodedServiceId}/layers/${layerId}`;
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(schema, null, 2),
+            },
+        ],
+    };
+}

package/dist/src/resources/services.d.ts

@@ -0,0 +1,10 @@
+import type { HonuaClient } from "@honua/sdk-js";
+export declare const uri = "honua://services";
+export declare function read(client: HonuaClient): Promise<{
+    contents: {
+        uri: string;
+        mimeType: "application/json";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=services.d.ts.map

package/dist/src/resources/services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../../src/resources/services.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGjD,eAAO,MAAM,GAAG,qBAAqB,CAAC;AAItC,wBAAsB,IAAI,CAAC,MAAM,EAAE,WAAW;;;;;;GAoC7C"}

package/dist/src/resources/services.js

@@ -0,0 +1,39 @@
+import { encodeServiceId, mapWithConcurrency, metadataErrorText } from "../helpers.js";
+export const uri = "honua://services";
+const METADATA_CONCURRENCY = 8;
+export async function read(client) {
+    const response = await client.listServices();
+    const featureServices = (response.services ?? []).filter((s) => s.type === "FeatureServer");
+    const catalog = await mapWithConcurrency(featureServices, METADATA_CONCURRENCY, async (s) => {
+        try {
+            const meta = await client.getFeatureServiceMetadata(s.name);
+            return {
+                serviceId: s.name,
+                encodedServiceId: encodeServiceId(s.name),
+                type: s.type,
+                layers: meta.layers ?? [],
+                tables: meta.tables ?? [],
+                metadataError: null,
+            };
+        }
+        catch {
+            return {
+                serviceId: s.name,
+                encodedServiceId: encodeServiceId(s.name),
+                type: s.type,
+                layers: [],
+                tables: [],
+                metadataError: metadataErrorText(),
+            };
+        }
+    });
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(catalog, null, 2),
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    serviceId: z.ZodString;
+    layerId: z.ZodNumber;
+    where: z.ZodOptional<z.ZodString>;
+    geometry: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    geometryType: z.ZodOptional<z.ZodEnum<["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"]>>;
+    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within"]>>;
+}, "strip", z.ZodTypeAny, {
+    serviceId: string;
+    layerId: number;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+}, {
+    serviceId: string;
+    layerId: number;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=count-features.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { GEOMETRY_TYPES, 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"),
+    where: z.string().optional().describe("SQL WHERE clause, e.g. \"status = 'active'\""),
+    geometry: z.record(z.unknown()).optional().describe("Esri JSON geometry for spatial filter"),
+    geometryType: z
+        .enum(GEOMETRY_TYPES)
+        .optional()
+        .describe("Esri geometry type. If omitted, inferred from geometry when possible."),
+    spatialRel: z
+        .enum(["intersects", "contains", "within"])
+        .optional()
+        .describe("Spatial relationship (default: intersects)"),
+});
+export async function execute(client, input) {
+    const response = (await client.queryFeatures({
+        serviceId: input.serviceId,
+        layerId: input.layerId,
+        where: input.where,
+        geometry: input.geometry,
+        geometryType: resolveGeometryType(input.geometry, input.geometryType),
+        spatialRel: mapSpatialRel(input.spatialRel),
+        returnGeometry: false,
+        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)) {
+        throw new Error("Count query did not return a numeric count.");
+    }
+    return jsonText({ count });
+}

package/dist/src/tools/describe-layer.d.ts

@@ -0,0 +1,20 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    serviceId: z.ZodString;
+    layerId: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    serviceId: string;
+    layerId: number;
+}, {
+    serviceId: string;
+    layerId: number;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=describe-layer.d.ts.map

package/dist/src/tools/describe-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-layer.d.ts","sourceRoot":"","sources":["../../../src/tools/describe-layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;EAGjB,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;;;;;GAa9D"}

package/dist/src/tools/describe-layer.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { jsonText } 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"),
+});
+export async function execute(client, input) {
+    const meta = await client.getLayerMetadata(input.serviceId, input.layerId);
+    return jsonText({
+        id: meta.id,
+        name: meta.name,
+        description: meta.description ?? null,
+        geometryType: meta.geometryType ?? null,
+        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type, alias: f.alias ?? f.name })),
+        extent: meta.extent ?? null,
+        spatialReference: meta.spatialReference ?? null,
+        relationships: meta.relationships ?? [],
+    });
+}

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

@@ -0,0 +1,32 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    serviceId: z.ZodString;
+    layerId: z.ZodNumber;
+    where: z.ZodOptional<z.ZodString>;
+    geometry: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    geometryType: z.ZodOptional<z.ZodEnum<["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"]>>;
+    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within"]>>;
+}, "strip", z.ZodTypeAny, {
+    serviceId: string;
+    layerId: number;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+}, {
+    serviceId: string;
+    layerId: number;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=get-extent.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { GEOMETRY_TYPES, 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"),
+    where: z.string().optional().describe("SQL WHERE clause"),
+    geometry: z.record(z.unknown()).optional().describe("Esri JSON geometry for spatial filter"),
+    geometryType: z
+        .enum(GEOMETRY_TYPES)
+        .optional()
+        .describe("Esri geometry type. If omitted, inferred from geometry when possible."),
+    spatialRel: z
+        .enum(["intersects", "contains", "within"])
+        .optional()
+        .describe("Spatial relationship (default: intersects)"),
+});
+export async function execute(client, input) {
+    const response = (await client.queryFeatures({
+        serviceId: input.serviceId,
+        layerId: input.layerId,
+        where: input.where,
+        geometry: input.geometry,
+        geometryType: resolveGeometryType(input.geometry, input.geometryType),
+        spatialRel: mapSpatialRel(input.spatialRel),
+        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;
+    const hasExtent = Object.prototype.hasOwnProperty.call(response, "extent");
+    if (!hasExtent) {
+        // Some backends can return count-only payloads for empty extent queries.
+        if (count !== undefined) {
+            return jsonText({ extent: null, count });
+        }
+        throw new Error("Extent query did not return an extent payload.");
+    }
+    let extent;
+    if (response.extent === null) {
+        extent = null;
+    }
+    else if (typeof response.extent === "object") {
+        extent = response.extent;
+    }
+    else {
+        throw new Error("Extent query returned an invalid extent payload.");
+    }
+    return jsonText({ extent, count });
+}

package/dist/src/tools/list-services.d.ts

@@ -0,0 +1,17 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    includeDetails: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    includeDetails: boolean;
+}, {
+    includeDetails?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=list-services.d.ts.map

package/dist/src/tools/list-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-services.d.ts","sourceRoot":"","sources":["../../../src/tools/list-services.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;EAQjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAI3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;GAgC9D"}

package/dist/src/tools/list-services.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { jsonText, mapWithConcurrency, metadataErrorText } from "../helpers.js";
+export const schema = z.object({
+    includeDetails: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Fetch service metadata (description, layer count, spatial reference). Slower due to per-service requests."),
+});
+const METADATA_CONCURRENCY = 8;
+export async function execute(client, input) {
+    const response = await client.listServices();
+    const services = (response.services ?? []).filter((s) => s.type === "FeatureServer");
+    if (!input.includeDetails) {
+        return jsonText(services.map((s) => ({ serviceId: s.name, type: s.type })));
+    }
+    const detailed = await mapWithConcurrency(services, METADATA_CONCURRENCY, async (s) => {
+        try {
+            const meta = await client.getFeatureServiceMetadata(s.name);
+            return {
+                serviceId: s.name,
+                type: s.type,
+                description: meta.serviceDescription ?? null,
+                layerCount: (meta.layers?.length ?? 0) + (meta.tables?.length ?? 0),
+                spatialReference: meta.spatialReference ?? null,
+                metadataError: null,
+            };
+        }
+        catch {
+            return {
+                serviceId: s.name,
+                type: s.type,
+                description: null,
+                layerCount: null,
+                spatialReference: null,
+                metadataError: metadataErrorText(),
+            };
+        }
+    });
+    return jsonText(detailed);
+}

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

@@ -0,0 +1,47 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    serviceId: z.ZodString;
+    layerId: z.ZodNumber;
+    where: z.ZodOptional<z.ZodString>;
+    outFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    geometry: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    geometryType: z.ZodOptional<z.ZodEnum<["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"]>>;
+    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within"]>>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    returnGeometry: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    serviceId: string;
+    layerId: number;
+    returnGeometry: boolean;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+    outFields?: string[] | undefined;
+    orderBy?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, {
+    serviceId: string;
+    layerId: number;
+    where?: string | undefined;
+    geometry?: Record<string, unknown> | undefined;
+    geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | undefined;
+    outFields?: string[] | undefined;
+    orderBy?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    returnGeometry?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=query-features.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { GEOMETRY_TYPES, clampLimit, 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"),
+    where: z.string().optional().describe('SQL WHERE clause, e.g. "population > 50000"'),
+    outFields: z.array(z.string()).optional().describe("Fields to return; defaults to all"),
+    geometry: z.record(z.unknown()).optional().describe("Esri JSON geometry for spatial filter"),
+    geometryType: z
+        .enum(GEOMETRY_TYPES)
+        .optional()
+        .describe("Esri geometry type. If omitted, inferred from geometry when possible."),
+    spatialRel: z
+        .enum(["intersects", "contains", "within"])
+        .optional()
+        .describe("Spatial relationship (default: intersects)"),
+    orderBy: z.string().optional().describe('Sort order, e.g. "name ASC"'),
+    limit: z.number().int().positive().optional().describe("Max features to return (default 100, max 2000)"),
+    offset: z.number().int().nonnegative().optional().describe("Number of features to skip (for pagination)"),
+    returnGeometry: z.boolean().optional().default(false).describe("Include geometry in results (default: false)"),
+});
+export async function execute(client, input) {
+    const response = await client.queryFeatures({
+        serviceId: input.serviceId,
+        layerId: input.layerId,
+        where: input.where,
+        outFields: input.outFields ?? "*",
+        geometry: input.geometry,
+        geometryType: resolveGeometryType(input.geometry, input.geometryType),
+        spatialRel: mapSpatialRel(input.spatialRel),
+        orderByFields: input.orderBy,
+        resultRecordCount: clampLimit(input.limit),
+        resultOffset: input.offset,
+        returnGeometry: input.returnGeometry,
+    });
+    const features = response.features ?? [];
+    return jsonText({
+        returnedCount: features.length,
+        features: features.map((f) => ({
+            attributes: f.attributes,
+            ...(input.returnGeometry && f.geometry ? { geometry: f.geometry } : {}),
+        })),
+        exceededTransferLimit: response.exceededTransferLimit ?? false,
+        objectIdFieldName: response.objectIdFieldName ?? null,
+        geometryType: response.geometryType ?? null,
+        spatialReference: response.spatialReference ?? null,
+    });
+}

package/dist/src/tools/statistics.d.ts

@@ -0,0 +1,32 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+export declare const schema: z.ZodObject<{
+    serviceId: z.ZodString;
+    layerId: z.ZodNumber;
+    statisticType: z.ZodEnum<["count", "sum", "avg", "min", "max", "stddev"]>;
+    onField: z.ZodString;
+    groupBy: z.ZodOptional<z.ZodString>;
+    where: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    serviceId: string;
+    layerId: number;
+    statisticType: "count" | "sum" | "avg" | "min" | "max" | "stddev";
+    onField: string;
+    where?: string | undefined;
+    groupBy?: string | undefined;
+}, {
+    serviceId: string;
+    layerId: number;
+    statisticType: "count" | "sum" | "avg" | "min" | "max" | "stddev";
+    onField: string;
+    where?: string | undefined;
+    groupBy?: string | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=statistics.d.ts.map

package/dist/src/tools/statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../src/tools/statistics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;EAOjB,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;;;;;GAuB9D"}

package/dist/src/tools/statistics.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { jsonText } 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"),
+    statisticType: z.enum(["count", "sum", "avg", "min", "max", "stddev"]).describe("The aggregate function to compute"),
+    onField: z.string().describe("The field to compute the statistic on"),
+    groupBy: z.string().optional().describe("Field to group results by"),
+    where: z.string().optional().describe("SQL WHERE clause to filter features"),
+});
+export async function execute(client, input) {
+    const outStatisticFieldName = `${input.statisticType}_${input.onField}`;
+    const response = await client.queryFeatures({
+        serviceId: input.serviceId,
+        layerId: input.layerId,
+        where: input.where ?? "1=1",
+        outStatistics: [
+            {
+                statisticType: input.statisticType,
+                onStatisticField: input.onField,
+                outStatisticFieldName,
+            },
+        ],
+        groupByFieldsForStatistics: input.groupBy,
+        returnGeometry: false,
+    });
+    const features = response.features ?? [];
+    return jsonText({
+        statistics: features.map((f) => ({ attributes: f.attributes })),
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@honua/mcp-server",
+  "version": "0.0.6-alpha.0",
+  "description": "MCP server for Honua geospatial feature services",
+  "type": "module",
+  "bin": {
+    "honua-mcp": "dist/src/index.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist coverage",
+    "build": "npm run clean --silent && tsc -p tsconfig.json",
+    "prepack": "npm run build --silent",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build --silent && vitest run --coverage",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome lint src/ test/",
+    "lint:fix": "biome lint --write src/ test/",
+    "format": "biome format src/ test/",
+    "format:fix": "biome format --write src/ test/",
+    "check": "biome check src/ test/",
+    "check:fix": "biome check --write src/ test/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "@honua/sdk-js": "^0.0.6-alpha.0"
+  },
+  "devDependencies": {
+    "@honua/sdk-js": "file:..",
+    "@biomejs/biome": "1.9.4",
+    "@types/node": "^24.3.1",
+    "@vitest/coverage-v8": "^4.0.16",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}