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

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

@@ -1,19 +1,110 @@
 import { z } from "zod";
 import { jsonText } from "../helpers.js";
+import { withCapabilityHonesty } from "../neutral/errors.js";
+import { ogcLayoutFor, resolveSource, sourceRefFields } from "../neutral/source-ref.js";
+/**
+ * `honua_describe_layer` — protocol-neutral source description (#1005).
+ *
+ * The envelope is the same for every protocol: the neutral source reference,
+ * its protocol, the capabilities the runtime will actually honor, and a field
+ * schema. Where the schema comes from is protocol-specific (GeoServices layer
+ * metadata, an OGC collection + its queryables); the shape the agent reads is
+ * not. Protocols with no metadata document report `schemaAvailable: false`
+ * with a reason instead of an empty field list, which would read as "this
+ * source has no attributes".
+ */
 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"),
+    ...sourceRefFields,
 });
-export async function execute(client, input) {
-    const meta = await client.getLayerMetadata(input.serviceId, input.layerId);
-    return jsonText({
-        id: meta.id,
-        name: meta.name,
+async function describeGeoServices(client, resolved) {
+    const { serviceId, layerId } = resolved.descriptor.locator;
+    const meta = await client.getLayerMetadata(serviceId, layerId);
+    return {
+        name: meta.name ?? null,
         description: meta.description ?? null,
         geometryType: meta.geometryType ?? null,
-        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type, alias: f.alias ?? f.name })),
+        fields: (meta.fields ?? []).map((f) => ({ name: f.name, type: f.type ?? null, alias: f.alias ?? f.name })),
         extent: meta.extent ?? null,
         spatialReference: meta.spatialReference ?? null,
         relationships: meta.relationships ?? [],
+        schemaAvailable: true,
+    };
+}
+function bboxToExtent(bbox) {
+    if (!bbox || bbox.length < 4)
+        return null;
+    const [xmin, ymin, xmax, ymax] = bbox;
+    return { xmin, ymin, xmax, ymax };
+}
+async function describeOgcCollection(client, resolved) {
+    const collectionId = resolved.descriptor.locator.collectionId;
+    const layout = await ogcLayoutFor(client, resolved.ref.layout);
+    const request = { collectionId, ...(layout ? { layout } : {}) };
+    const meta = resolved.descriptor.protocol === "ogc-records"
+        ? await client.getOgcRecordCollection(request)
+        : await client.getOgcCollection(request);
+    let fields = [];
+    let schemaAvailable = true;
+    let schemaReason;
+    try {
+        const queryables = await client.getOgcQueryables(request);
+        fields = Object.entries(queryables.properties ?? {}).map(([name, property]) => ({
+            name,
+            type: property.type ?? null,
+            alias: property.title ?? name,
+        }));
+        if (fields.length === 0) {
+            schemaAvailable = false;
+            schemaReason = "the collection advertises no queryable properties.";
+        }
+    }
+    catch (error) {
+        schemaAvailable = false;
+        schemaReason = `queryables are not published by this endpoint: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    const temporal = meta.extent?.temporal?.interval?.[0];
+    return {
+        name: meta.title ?? meta.id ?? collectionId,
+        description: meta.description ?? null,
+        geometryType: null,
+        fields,
+        extent: bboxToExtent(meta.extent?.spatial?.bbox?.[0]),
+        spatialReference: meta.extent?.spatial?.crs ?? meta.crs?.[0] ?? null,
+        relationships: [],
+        ...(temporal ? { timeField: null } : {}),
+        schemaAvailable,
+        ...(schemaReason ? { schemaReason } : {}),
+    };
+}
+function describeFromDescriptorOnly(resolved) {
+    return {
+        name: resolved.ref.address,
+        description: null,
+        geometryType: null,
+        fields: [],
+        extent: null,
+        spatialReference: null,
+        relationships: [],
+        schemaAvailable: false,
+        schemaReason: `protocol "${resolved.descriptor.protocol}" publishes no schema document this server can read without a discovery pass; query the source and inspect the returned attributes instead.`,
+    };
+}
+export async function execute(client, input) {
+    return withCapabilityHonesty(async () => {
+        const resolved = resolveSource(client, input);
+        const protocol = resolved.descriptor.protocol;
+        const envelope = protocol === "geoservices-feature-service" || protocol === "geoservices-map-service" || protocol === "grpc"
+            ? await describeGeoServices(client, resolved)
+            : protocol === "ogc-features" || protocol === "ogc-records"
+                ? await describeOgcCollection(client, resolved)
+                : describeFromDescriptorOnly(resolved);
+        return jsonText({
+            source: resolved.ref.ref,
+            protocol,
+            capabilities: [...resolved.source.capabilities].sort(),
+            ...envelope,
+            // Retained for clients written against the pre-#1005 shape.
+            id: resolved.descriptor.locator.layerId ?? resolved.ref.address,
+        });
     });
 }

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

@@ -1,26 +1,77 @@
 import type { HonuaClient } from "@honua/sdk-js";
 import { z } from "zod";
+/**
+ * `honua_get_extent` — protocol-neutral bounding box (#1005).
+ *
+ * Runs the canonical `Source.queryExtent()`. Protocols with no server-side
+ * extent operation (OGC API Features, STAC, OData) answer from the collection's
+ * declared extent under the degraded capability policy, and say so; protocols
+ * that cannot answer at all refuse with a structured capability error.
+ */
 export declare const schema: z.ZodObject<{
-    serviceId: z.ZodString;
-    layerId: z.ZodNumber;
+    filter: z.ZodOptional<z.ZodType<import("../neutral/filter.js").FilterNode, z.ZodTypeDef, import("../neutral/filter.js").FilterNode>>;
     where: z.ZodOptional<z.ZodString>;
+    bbox: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    bboxSrid: z.ZodOptional<z.ZodNumber>;
     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"]>>;
+    spatialRel: z.ZodOptional<z.ZodEnum<["intersects", "contains", "within", "crosses", "touches", "overlaps", "bbox-intersects"]>>;
+    temporal: z.ZodOptional<z.ZodObject<{
+        instant: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        end: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        field: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }, {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    }>>;
+    source: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"]>>;
+    serviceId: z.ZodOptional<z.ZodString>;
+    layerId: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    serviceId: string;
-    layerId: number;
-    where?: string | undefined;
+    filter?: import("../neutral/filter.js").FilterNode | undefined;
+    serviceId?: string | undefined;
     geometry?: Record<string, unknown> | undefined;
+    bbox?: number[] | undefined;
     geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
-    spatialRel?: "intersects" | "contains" | "within" | undefined;
-}, {
-    serviceId: string;
-    layerId: number;
+    temporal?: {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    } | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
     where?: string | undefined;
+    bboxSrid?: number | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | "crosses" | "touches" | "overlaps" | "bbox-intersects" | undefined;
+}, {
+    filter?: import("../neutral/filter.js").FilterNode | undefined;
+    serviceId?: string | undefined;
     geometry?: Record<string, unknown> | undefined;
+    bbox?: number[] | undefined;
     geometryType?: "esriGeometryPoint" | "esriGeometryPolyline" | "esriGeometryPolygon" | "esriGeometryEnvelope" | "esriGeometryMultipoint" | undefined;
-    spatialRel?: "intersects" | "contains" | "within" | undefined;
+    temporal?: {
+        field?: string | undefined;
+        instant?: string | undefined;
+        start?: string | null | undefined;
+        end?: string | null | undefined;
+    } | undefined;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    layerId?: number | undefined;
+    source?: string | undefined;
+    where?: string | undefined;
+    bboxSrid?: number | undefined;
+    spatialRel?: "intersects" | "contains" | "within" | "crosses" | "touches" | "overlaps" | "bbox-intersects" | undefined;
 }>;
 export type Input = z.infer<typeof schema>;
 export declare function execute(client: HonuaClient, input: Input): Promise<{
@@ -28,5 +79,12 @@ export declare function execute(client: HonuaClient, input: Input): Promise<{
         type: "text";
         text: string;
     }>;
+} | {
+    structuredContent: Record<string, unknown>;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
 }>;
 //# sourceMappingURL=get-extent.d.ts.map

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;;;;;GAoC9D"}
+{"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;AAMxB;;;;;;;GAOG;AACH,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;;;;;;;;;;;;GAgB9D"}

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

@@ -1,51 +1,33 @@
 import { z } from "zod";
-import { GEOMETRY_TYPES, coerceCount, jsonText, mapSpatialRel, resolveGeometryType } from "../helpers.js";
+import { jsonText } from "../helpers.js";
+import { withCapabilityHonesty } from "../neutral/errors.js";
+import { queryFilterFields, toQuery } from "../neutral/query.js";
+import { resolveSource, sourceRefFields } from "../neutral/source-ref.js";
+/**
+ * `honua_get_extent` — protocol-neutral bounding box (#1005).
+ *
+ * Runs the canonical `Source.queryExtent()`. Protocols with no server-side
+ * extent operation (OGC API Features, STAC, OData) answer from the collection's
+ * declared extent under the degraded capability policy, and say so; protocols
+ * that cannot answer at all refuse with a structured capability error.
+ */
 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)"),
+    ...sourceRefFields,
+    ...queryFilterFields,
 });
 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 },
-    }));
-    // 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.
-        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" && !Array.isArray(response.extent)) {
-        // A JSON array is `typeof "object"` but is not a valid extent envelope.
-        extent = response.extent;
-    }
-    else {
-        throw new Error("Extent query returned an invalid extent payload.");
-    }
-    return jsonText({ extent, count });
+    return withCapabilityHonesty(async () => {
+        const resolved = resolveSource(client, input);
+        const query = toQuery(input, { protocol: resolved.descriptor.protocol, paginate: false });
+        const { extent, count } = await resolved.source.queryExtent(query);
+        return jsonText({
+            source: resolved.ref.ref,
+            protocol: resolved.descriptor.protocol,
+            extent: extent ?? null,
+            count: count ?? null,
+            // An extent that did not come from a server-side extent operation is an
+            // honest, but weaker, answer; name the capability so the caller can tell.
+            extentCapability: resolved.source.capabilities.has("queryExtent") ? "server" : "declared-extent",
+        });
+    });
 }

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

@@ -1,5 +1,12 @@
 import type { HonuaClient } from "@honua/sdk-js";
 import { z } from "zod";
+/**
+ * `honua_list_services` — the GeoServices-specific service catalog.
+ *
+ * Retained for existing clients; `honua_list_sources` is the protocol-neutral
+ * replacement (#1005), because "what services are under /rest/services?" is a
+ * question only an Esri endpoint can answer.
+ */
 export declare const schema: z.ZodObject<{
     includeDetails: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {

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

@@ -1 +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;;;;;GA+C9D"}
+{"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;;;;;;GAMG;AACH,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;;;;;GA+C9D"}

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

@@ -1,5 +1,12 @@
 import { z } from "zod";
 import { jsonText, mapWithConcurrency, metadataErrorText } from "../helpers.js";
+/**
+ * `honua_list_services` — the GeoServices-specific service catalog.
+ *
+ * Retained for existing clients; `honua_list_sources` is the protocol-neutral
+ * replacement (#1005), because "what services are under /rest/services?" is a
+ * question only an Esri endpoint can answer.
+ */
 export const schema = z.object({
     includeDetails: z
         .boolean()
@@ -22,7 +29,7 @@ export async function execute(client, input) {
             catalogAvailable: false,
             services: [],
             reason: `service catalog is not available on this target: ${err instanceof Error ? err.message : String(err)}`,
-            guidance: "No /rest/services directory here. Call honua_describe_layer / honua_query_features with a known serviceId and layerId, or point the base URL at an ArcGIS folder that lists services.",
+            guidance: "No /rest/services directory here — this tool only sees a GeoServices catalog. Call honua_list_sources, which probes every protocol family this endpoint may publish (OGC API Features included) and returns protocol-neutral source references.",
         });
     }
     const services = (response.services ?? []).filter((s) => s.type === "FeatureServer");

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

@@ -0,0 +1,44 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { z } from "zod";
+/**
+ * `honua_list_sources` — protocol-neutral discovery (#1005).
+ *
+ * `honua_list_services` answers a GeoServices-only question ("what is in
+ * `/rest/services`?"). This tool answers the neutral one — "what sources can I
+ * query here, and how do I address them?" — and emits the exact
+ * `<protocol>:<address>` references every other tool accepts, so an agent never
+ * has to construct one.
+ *
+ * Each protocol family is probed independently and degrades on its own: an
+ * endpoint that serves OGC collections but has no `/rest/services` directory
+ * reports the GeoServices family as unavailable-with-reason and still returns
+ * its OGC sources. A family that is absent is never reported as "no sources".
+ */
+export declare const schema: z.ZodObject<{
+    protocol: z.ZodDefault<z.ZodOptional<z.ZodEnum<["auto", "geoservices", "ogc-features", "ogc-records"]>>>;
+    layout: z.ZodOptional<z.ZodEnum<["honua-facade", "ogc-api", "auto", "stac-api", "stac-static"]>>;
+    maxServices: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    protocol: "ogc-features" | "ogc-records" | "geoservices" | "auto";
+    maxServices: number;
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+}, {
+    layout?: "honua-facade" | "ogc-api" | "auto" | "stac-api" | "stac-static" | undefined;
+    protocol?: "ogc-features" | "ogc-records" | "geoservices" | "auto" | undefined;
+    maxServices?: number | undefined;
+}>;
+export type Input = z.infer<typeof schema>;
+export declare function execute(client: HonuaClient, input: Input): Promise<{
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+} | {
+    structuredContent: Record<string, unknown>;
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}>;
+//# sourceMappingURL=list-sources.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-sources.d.ts","sourceRoot":"","sources":["../../../src/tools/list-sources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;EAoBjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AA6F3C,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;GAkC9D"}

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

@@ -0,0 +1,138 @@
+import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract";
+import { z } from "zod";
+import { jsonText, mapWithConcurrency } from "../helpers.js";
+import { withCapabilityHonesty } from "../neutral/errors.js";
+import { SOURCE_LAYOUTS, ogcLayoutFor } from "../neutral/source-ref.js";
+/**
+ * `honua_list_sources` — protocol-neutral discovery (#1005).
+ *
+ * `honua_list_services` answers a GeoServices-only question ("what is in
+ * `/rest/services`?"). This tool answers the neutral one — "what sources can I
+ * query here, and how do I address them?" — and emits the exact
+ * `<protocol>:<address>` references every other tool accepts, so an agent never
+ * has to construct one.
+ *
+ * Each protocol family is probed independently and degrades on its own: an
+ * endpoint that serves OGC collections but has no `/rest/services` directory
+ * reports the GeoServices family as unavailable-with-reason and still returns
+ * its OGC sources. A family that is absent is never reported as "no sources".
+ */
+export const schema = z.object({
+    protocol: z
+        .enum(["auto", "geoservices", "ogc-features", "ogc-records"])
+        .optional()
+        .default("auto")
+        .describe("Restrict discovery to one protocol family. `auto` (default) probes every family this server can list."),
+    layout: z
+        .enum(SOURCE_LAYOUTS)
+        .optional()
+        .describe('Endpoint layout for the OGC families: "honua-facade" (default) or "ogc-api"/"auto" for a third-party OGC API root.'),
+    maxServices: z
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .default(25)
+        .describe("Maximum GeoServices services expanded into per-layer sources (each costs one metadata request)."),
+});
+const METADATA_CONCURRENCY = 8;
+function capabilitiesFor(protocol) {
+    return [...PROTOCOL_DEFAULT_CAPABILITIES[protocol]].sort();
+}
+async function discoverGeoServices(client, maxServices) {
+    let response;
+    try {
+        response = await client.listServices();
+    }
+    catch (err) {
+        return {
+            available: false,
+            reason: `no GeoServices catalog on this target: ${err instanceof Error ? err.message : String(err)}`,
+            sources: [],
+        };
+    }
+    const services = (response.services ?? []).filter((s) => s.type === "FeatureServer" || s.type === "MapServer");
+    const expanded = services.slice(0, maxServices);
+    const perService = await mapWithConcurrency(expanded, METADATA_CONCURRENCY, async (service) => {
+        const protocol = service.type === "MapServer" ? "geoservices-map-service" : "geoservices-feature-service";
+        try {
+            const meta = await client.getFeatureServiceMetadata(service.name);
+            const layers = [...(meta.layers ?? []), ...(meta.tables ?? [])];
+            return layers.map((layer) => ({
+                source: `${protocol}:${service.name}/${layer.id}`,
+                protocol,
+                title: layer.name ?? null,
+                capabilities: capabilitiesFor(protocol),
+            }));
+        }
+        catch {
+            // The service exists but its metadata is unreadable; still emit the
+            // conventional layer-0 reference rather than dropping the service.
+            return [
+                {
+                    source: `${protocol}:${service.name}/0`,
+                    protocol,
+                    title: service.name,
+                    capabilities: capabilitiesFor(protocol),
+                },
+            ];
+        }
+    });
+    return { available: true, sources: perService.flat() };
+}
+async function discoverOgc(client, family, layout) {
+    try {
+        const resolved = await ogcLayoutFor(client, layout);
+        const request = resolved ? { layout: resolved } : {};
+        const response = family === "ogc-records"
+            ? await client.listOgcRecordCollections(request)
+            : await client.listOgcCollections(request);
+        return {
+            available: true,
+            sources: (response.collections ?? []).map((collection) => ({
+                source: `${family}:${collection.id}`,
+                protocol: family,
+                title: collection.title ?? collection.id,
+                capabilities: capabilitiesFor(family),
+            })),
+        };
+    }
+    catch (err) {
+        return {
+            available: false,
+            reason: `no ${family} collections on this target: ${err instanceof Error ? err.message : String(err)}`,
+            sources: [],
+        };
+    }
+}
+export async function execute(client, input) {
+    return withCapabilityHonesty(async () => {
+        const families = {};
+        if (input.protocol === "auto" || input.protocol === "geoservices") {
+            families.geoservices = await discoverGeoServices(client, input.maxServices);
+        }
+        if (input.protocol === "auto" || input.protocol === "ogc-features") {
+            families["ogc-features"] = await discoverOgc(client, "ogc-features", input.layout);
+        }
+        if (input.protocol === "ogc-records") {
+            families["ogc-records"] = await discoverOgc(client, "ogc-records", input.layout);
+        }
+        const sources = Object.values(families).flatMap((family) => family.sources);
+        return jsonText({
+            sources,
+            sourceCount: sources.length,
+            families: Object.fromEntries(Object.entries(families).map(([name, outcome]) => [
+                name,
+                {
+                    available: outcome.available,
+                    ...(outcome.reason ? { reason: outcome.reason } : {}),
+                    count: outcome.sources.length,
+                },
+            ])),
+            guidance: sources.length > 0
+                ? "Pass a `source` value verbatim to honua_describe_layer / honua_query_features / honua_count_features / honua_get_extent / honua_statistics."
+                : 'No source catalog is published here. Address a known source directly, e.g. source="ogc-features:<collectionId>", "stac:<collectionId>", "wfs:<typeName>", "odata:<entitySet>", or "geoservices-feature-service:<serviceId>/<layerId>".',
+        });
+    });
+}