@honua/mcp-server 0.0.20-alpha.0 → 0.1.1-beta.0

package/dist/src/capability.js

@@ -0,0 +1,44 @@
+import { jsonText } from "./helpers.js";
+/**
+ * Platform-free capability degradation (issue #369).
+ *
+ * `@honua/mcp-server` runs in two modes: against a Honua-enhanced deployment
+ * (which exposes extra surfaces such as OGC API – Styles) and — the platform-free
+ * front door — against ANY plain public Esri FeatureServer / OGC endpoint that
+ * has none of those surfaces. A tool that depends on a Honua-only surface must
+ * NEVER crash, hang, or return misleading empty data on a plain target. Instead
+ * it detects the missing surface and reports a clear, structured "not available
+ * on this target" result — the same skip-with-reason honesty the certification
+ * suite uses.
+ *
+ * Probing helpers throw {@link CapabilityUnavailableError} when a surface is
+ * absent; the tool/resource layer catches it and returns
+ * {@link capabilityUnavailable}, a non-error tool result carrying
+ * `available: false` plus a human-readable reason.
+ */
+export class CapabilityUnavailableError extends Error {
+    code = "CAPABILITY_UNAVAILABLE";
+    /** Human label of the missing surface, e.g. "OGC API - Styles". */
+    surface;
+    /** Why the surface was judged unavailable (status / parse / shape). */
+    reason;
+    constructor(surface, reason) {
+        super(`${surface} is not available on this target: ${reason}`);
+        this.name = "CapabilityUnavailableError";
+        this.surface = surface;
+        this.reason = reason;
+    }
+}
+/**
+ * Build a structured "not available on this target" tool/resource result. The
+ * result is deliberately NOT an MCP error: a plain FeatureServer legitimately
+ * lacks the surface, so degradation is an honest, expected outcome — not a
+ * failure. Clients branch on `available === false`.
+ */
+export function capabilityUnavailablePayload(surface, reason, guidance) {
+    return { available: false, surface, reason, guidance };
+}
+/** Convenience: the {@link capabilityUnavailablePayload} body wrapped as tool text content. */
+export function capabilityUnavailable(surface, reason, guidance) {
+    return jsonText(capabilityUnavailablePayload(surface, reason, guidance));
+}

package/dist/src/certification/census-data.d.ts

@@ -0,0 +1,33 @@
+export interface CensusRow {
+    OBJECTID: number;
+    NAME: string;
+    STUSPS: string;
+    Total_Pop_2020: number | null;
+    Seats_2020: number | null;
+}
+/** The public FeatureServer this fixture was recorded from. */
+export declare const CENSUS_ENDPOINT = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0";
+/** Service id (as it appears under /rest/services) for the recorded service. */
+export declare const CENSUS_SERVICE_ID = "2020_Census_State_Apportionment";
+/** Human layer name as advertised by the live layer metadata. */
+export declare const CENSUS_LAYER_NAME = "States 2020 Apportionment - U.S. House of Representatives Seats";
+/** Recorded layer extent (Web Mercator, wkid 102100). */
+export declare const CENSUS_EXTENT: {
+    readonly xmin: -19942592.3656;
+    readonly ymin: 2024070.8216000013;
+    readonly xmax: 20012846.037699997;
+    readonly ymax: 11523911.845299996;
+    readonly spatialReference: {
+        readonly wkid: 102100;
+        readonly latestWkid: 3857;
+    };
+};
+/** Recorded field list for layer 0 (all 22 fields, verbatim). */
+export declare const CENSUS_FIELDS: ReadonlyArray<{
+    name: string;
+    type: string;
+    alias: string;
+}>;
+/** All 52 recorded rows (attribute-only; geometry omitted to keep the fixture small). */
+export declare const CENSUS_ROWS: ReadonlyArray<CensusRow>;
+//# sourceMappingURL=census-data.d.ts.map

package/dist/src/certification/census-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"census-data.d.ts","sourceRoot":"","sources":["../../../src/certification/census-data.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAG9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,+DAA+D;AAC/D,eAAO,MAAM,eAAe,sHACyF,CAAC;AAEtH,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,oCAAoC,CAAC;AAEnE,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,oEAAoE,CAAC;AAEnG,yDAAyD;AACzD,eAAO,MAAM,aAAa;;;;;;;;;CAMhB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA+GtF,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,SAAS,CA6WhD,CAAC"}

package/dist/src/certification/census-data.js

@@ -0,0 +1,506 @@
+// AUTO-RECORDED FIXTURE DATA — do not hand-edit.
+//
+// Recorded from the public Esri Living Atlas FeatureServer (services.arcgis.com):
+//   https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0
+// US Census 2020 apportionment (public-domain data), publicly shared by Esri —
+// anonymous, read-only. Re-record with mcp/scripts/record-census-fixtures.mjs.
+//
+// This is the platform-free proof corpus: 52 rows (50 states + DC + Puerto Rico),
+// used to certify and eval @honua/mcp-server against a plain public FeatureServer
+// with ZERO Honua-server surfaces. Known aggregate anchors (verified live):
+//   rows=52  sum(pop)=335085841  sum(seats)=435  max(pop)=California(39576757)
+//   min(pop)=Wyoming(577719)  seats>=20 => 4 states (CA,TX,FL,NY).
+/** The public FeatureServer this fixture was recorded from. */
+export const CENSUS_ENDPOINT = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0";
+/** Service id (as it appears under /rest/services) for the recorded service. */
+export const CENSUS_SERVICE_ID = "2020_Census_State_Apportionment";
+/** Human layer name as advertised by the live layer metadata. */
+export const CENSUS_LAYER_NAME = "States 2020 Apportionment - U.S. House of Representatives Seats";
+/** Recorded layer extent (Web Mercator, wkid 102100). */
+export const CENSUS_EXTENT = {
+    xmin: -19942592.3656,
+    ymin: 2024070.8216000013,
+    xmax: 20012846.037699997,
+    ymax: 11523911.845299996,
+    spatialReference: { wkid: 102100, latestWkid: 3857 },
+};
+/** Recorded field list for layer 0 (all 22 fields, verbatim). */
+export const CENSUS_FIELDS = [
+    {
+        name: "OBJECTID",
+        type: "esriFieldTypeOID",
+        alias: "OBJECTID",
+    },
+    {
+        name: "NAME",
+        type: "esriFieldTypeString",
+        alias: "State Name",
+    },
+    {
+        name: "STUSPS",
+        type: "esriFieldTypeString",
+        alias: "State Abbreviation",
+    },
+    {
+        name: "GEO_ID",
+        type: "esriFieldTypeString",
+        alias: "GEOID FIPS Code",
+    },
+    {
+        name: "STATENS",
+        type: "esriFieldTypeString",
+        alias: "STATENS",
+    },
+    {
+        name: "GEOID",
+        type: "esriFieldTypeString",
+        alias: "GEOID FIPS Code",
+    },
+    {
+        name: "Total_Pop_2020",
+        type: "esriFieldTypeInteger",
+        alias: "Total Population, 2020",
+    },
+    {
+        name: "Seats_2020",
+        type: "esriFieldTypeInteger",
+        alias: "Seats in the U.S. House of Representatives, 2020",
+    },
+    {
+        name: "Resident_Pop_2020",
+        type: "esriFieldTypeInteger",
+        alias: "Resident Population, 2020",
+    },
+    {
+        name: "Overseas_Pop_2020",
+        type: "esriFieldTypeInteger",
+        alias: "Overseas Population, 2020",
+    },
+    {
+        name: "Total_Pop_2010",
+        type: "esriFieldTypeInteger",
+        alias: "Total Population, 2010",
+    },
+    {
+        name: "Seats_2010",
+        type: "esriFieldTypeInteger",
+        alias: "Seats in the U.S. House of Representatives, 2010",
+    },
+    {
+        name: "Resident_Pop_2010",
+        type: "esriFieldTypeInteger",
+        alias: "Resident Population, 2010",
+    },
+    {
+        name: "Overseas_Pop_2010",
+        type: "esriFieldTypeInteger",
+        alias: "Overseas Population, 2010",
+    },
+    {
+        name: "TotalPopChange_2010to2020",
+        type: "esriFieldTypeInteger",
+        alias: "Change in Total Population, 2010 to 2020",
+    },
+    {
+        name: "Total_Pct_Change_2010to2020",
+        type: "esriFieldTypeDouble",
+        alias: "Percent Change in Total Population, 2010 to 2020",
+    },
+    {
+        name: "Seats_Change_2010to2020",
+        type: "esriFieldTypeSmallInteger",
+        alias: "Change in Seats in the U.S. House of Representatives, 2010 to 2020",
+    },
+    {
+        name: "Seats_Change_2000to2010",
+        type: "esriFieldTypeSmallInteger",
+        alias: "Change in Seats in the U.S. House of Representatives, 2000 to 2010",
+    },
+    {
+        name: "Resident_Change_2010to2020",
+        type: "esriFieldTypeInteger",
+        alias: "Change in Resident Population, 2010 to 2020",
+    },
+    {
+        name: "Resident_Pct_Change_2010to2020",
+        type: "esriFieldTypeDouble",
+        alias: "Percent Change in Resident Population, 2010 to 2020",
+    },
+    {
+        name: "Shape__Area",
+        type: "esriFieldTypeDouble",
+        alias: "Shape__Area",
+    },
+    {
+        name: "Shape__Length",
+        type: "esriFieldTypeDouble",
+        alias: "Shape__Length",
+    },
+];
+/** All 52 recorded rows (attribute-only; geometry omitted to keep the fixture small). */
+export const CENSUS_ROWS = [
+    {
+        OBJECTID: 1,
+        NAME: "Alabama",
+        STUSPS: "AL",
+        Total_Pop_2020: 5030053,
+        Seats_2020: 7,
+    },
+    {
+        OBJECTID: 2,
+        NAME: "Alaska",
+        STUSPS: "AK",
+        Total_Pop_2020: 736081,
+        Seats_2020: 1,
+    },
+    {
+        OBJECTID: 3,
+        NAME: "Arizona",
+        STUSPS: "AZ",
+        Total_Pop_2020: 7158923,
+        Seats_2020: 9,
+    },
+    {
+        OBJECTID: 4,
+        NAME: "Arkansas",
+        STUSPS: "AR",
+        Total_Pop_2020: 3013756,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 5,
+        NAME: "California",
+        STUSPS: "CA",
+        Total_Pop_2020: 39576757,
+        Seats_2020: 52,
+    },
+    {
+        OBJECTID: 6,
+        NAME: "Colorado",
+        STUSPS: "CO",
+        Total_Pop_2020: 5782171,
+        Seats_2020: 8,
+    },
+    {
+        OBJECTID: 7,
+        NAME: "Connecticut",
+        STUSPS: "CT",
+        Total_Pop_2020: 3608298,
+        Seats_2020: 5,
+    },
+    {
+        OBJECTID: 8,
+        NAME: "Delaware",
+        STUSPS: "DE",
+        Total_Pop_2020: 990837,
+        Seats_2020: 1,
+    },
+    {
+        OBJECTID: 9,
+        NAME: "District of Columbia",
+        STUSPS: "DC",
+        Total_Pop_2020: 691533,
+        Seats_2020: null,
+    },
+    {
+        OBJECTID: 10,
+        NAME: "Florida",
+        STUSPS: "FL",
+        Total_Pop_2020: 21570527,
+        Seats_2020: 28,
+    },
+    {
+        OBJECTID: 11,
+        NAME: "Georgia",
+        STUSPS: "GA",
+        Total_Pop_2020: 10725274,
+        Seats_2020: 14,
+    },
+    {
+        OBJECTID: 12,
+        NAME: "Hawaii",
+        STUSPS: "HI",
+        Total_Pop_2020: 1460137,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 13,
+        NAME: "Idaho",
+        STUSPS: "ID",
+        Total_Pop_2020: 1841377,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 14,
+        NAME: "Illinois",
+        STUSPS: "IL",
+        Total_Pop_2020: 12822739,
+        Seats_2020: 17,
+    },
+    {
+        OBJECTID: 15,
+        NAME: "Indiana",
+        STUSPS: "IN",
+        Total_Pop_2020: 6790280,
+        Seats_2020: 9,
+    },
+    {
+        OBJECTID: 16,
+        NAME: "Iowa",
+        STUSPS: "IA",
+        Total_Pop_2020: 3192406,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 17,
+        NAME: "Kansas",
+        STUSPS: "KS",
+        Total_Pop_2020: 2940865,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 18,
+        NAME: "Kentucky",
+        STUSPS: "KY",
+        Total_Pop_2020: 4509342,
+        Seats_2020: 6,
+    },
+    {
+        OBJECTID: 19,
+        NAME: "Louisiana",
+        STUSPS: "LA",
+        Total_Pop_2020: 4661468,
+        Seats_2020: 6,
+    },
+    {
+        OBJECTID: 20,
+        NAME: "Maine",
+        STUSPS: "ME",
+        Total_Pop_2020: 1363582,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 21,
+        NAME: "Maryland",
+        STUSPS: "MD",
+        Total_Pop_2020: 6185278,
+        Seats_2020: 8,
+    },
+    {
+        OBJECTID: 22,
+        NAME: "Massachusetts",
+        STUSPS: "MA",
+        Total_Pop_2020: 7033469,
+        Seats_2020: 9,
+    },
+    {
+        OBJECTID: 23,
+        NAME: "Michigan",
+        STUSPS: "MI",
+        Total_Pop_2020: 10084442,
+        Seats_2020: 13,
+    },
+    {
+        OBJECTID: 24,
+        NAME: "Minnesota",
+        STUSPS: "MN",
+        Total_Pop_2020: 5709752,
+        Seats_2020: 8,
+    },
+    {
+        OBJECTID: 25,
+        NAME: "Mississippi",
+        STUSPS: "MS",
+        Total_Pop_2020: 2963914,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 26,
+        NAME: "Missouri",
+        STUSPS: "MO",
+        Total_Pop_2020: 6160281,
+        Seats_2020: 8,
+    },
+    {
+        OBJECTID: 27,
+        NAME: "Montana",
+        STUSPS: "MT",
+        Total_Pop_2020: 1085407,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 28,
+        NAME: "Nebraska",
+        STUSPS: "NE",
+        Total_Pop_2020: 1963333,
+        Seats_2020: 3,
+    },
+    {
+        OBJECTID: 29,
+        NAME: "Nevada",
+        STUSPS: "NV",
+        Total_Pop_2020: 3108462,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 30,
+        NAME: "New Hampshire",
+        STUSPS: "NH",
+        Total_Pop_2020: 1379089,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 31,
+        NAME: "New Jersey",
+        STUSPS: "NJ",
+        Total_Pop_2020: 9294493,
+        Seats_2020: 12,
+    },
+    {
+        OBJECTID: 32,
+        NAME: "New Mexico",
+        STUSPS: "NM",
+        Total_Pop_2020: 2120220,
+        Seats_2020: 3,
+    },
+    {
+        OBJECTID: 33,
+        NAME: "New York",
+        STUSPS: "NY",
+        Total_Pop_2020: 20215751,
+        Seats_2020: 26,
+    },
+    {
+        OBJECTID: 34,
+        NAME: "North Carolina",
+        STUSPS: "NC",
+        Total_Pop_2020: 10453948,
+        Seats_2020: 14,
+    },
+    {
+        OBJECTID: 35,
+        NAME: "North Dakota",
+        STUSPS: "ND",
+        Total_Pop_2020: 779702,
+        Seats_2020: 1,
+    },
+    {
+        OBJECTID: 36,
+        NAME: "Ohio",
+        STUSPS: "OH",
+        Total_Pop_2020: 11808848,
+        Seats_2020: 15,
+    },
+    {
+        OBJECTID: 37,
+        NAME: "Oklahoma",
+        STUSPS: "OK",
+        Total_Pop_2020: 3963516,
+        Seats_2020: 5,
+    },
+    {
+        OBJECTID: 38,
+        NAME: "Oregon",
+        STUSPS: "OR",
+        Total_Pop_2020: 4241500,
+        Seats_2020: 6,
+    },
+    {
+        OBJECTID: 39,
+        NAME: "Pennsylvania",
+        STUSPS: "PA",
+        Total_Pop_2020: 13011844,
+        Seats_2020: 17,
+    },
+    {
+        OBJECTID: 52,
+        NAME: "Puerto Rico",
+        STUSPS: "PR",
+        Total_Pop_2020: 3285874,
+        Seats_2020: null,
+    },
+    {
+        OBJECTID: 40,
+        NAME: "Rhode Island",
+        STUSPS: "RI",
+        Total_Pop_2020: 1098163,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 41,
+        NAME: "South Carolina",
+        STUSPS: "SC",
+        Total_Pop_2020: 5124712,
+        Seats_2020: 7,
+    },
+    {
+        OBJECTID: 42,
+        NAME: "South Dakota",
+        STUSPS: "SD",
+        Total_Pop_2020: 887770,
+        Seats_2020: 1,
+    },
+    {
+        OBJECTID: 43,
+        NAME: "Tennessee",
+        STUSPS: "TN",
+        Total_Pop_2020: 6916897,
+        Seats_2020: 9,
+    },
+    {
+        OBJECTID: 44,
+        NAME: "Texas",
+        STUSPS: "TX",
+        Total_Pop_2020: 29183290,
+        Seats_2020: 38,
+    },
+    {
+        OBJECTID: 45,
+        NAME: "Utah",
+        STUSPS: "UT",
+        Total_Pop_2020: 3275252,
+        Seats_2020: 4,
+    },
+    {
+        OBJECTID: 46,
+        NAME: "Vermont",
+        STUSPS: "VT",
+        Total_Pop_2020: 643503,
+        Seats_2020: 1,
+    },
+    {
+        OBJECTID: 47,
+        NAME: "Virginia",
+        STUSPS: "VA",
+        Total_Pop_2020: 8654542,
+        Seats_2020: 11,
+    },
+    {
+        OBJECTID: 48,
+        NAME: "Washington",
+        STUSPS: "WA",
+        Total_Pop_2020: 7715946,
+        Seats_2020: 10,
+    },
+    {
+        OBJECTID: 49,
+        NAME: "West Virginia",
+        STUSPS: "WV",
+        Total_Pop_2020: 1795045,
+        Seats_2020: 2,
+    },
+    {
+        OBJECTID: 50,
+        NAME: "Wisconsin",
+        STUSPS: "WI",
+        Total_Pop_2020: 5897473,
+        Seats_2020: 8,
+    },
+    {
+        OBJECTID: 51,
+        NAME: "Wyoming",
+        STUSPS: "WY",
+        Total_Pop_2020: 577719,
+        Seats_2020: 1,
+    },
+];

package/dist/src/certification/census-fixture-client.d.ts

@@ -0,0 +1,7 @@
+import type { HonuaClient } from "@honua/sdk-js";
+import { type CensusRow } from "./census-data.js";
+/** Filter the recorded rows by a (minimal) SQL WHERE clause. */
+export declare function filterRows(where: string | undefined): CensusRow[];
+/** Build the offline platform-free fixture client (a plain public FeatureServer). */
+export declare function createStandaloneFixtureClient(): HonuaClient;
+//# sourceMappingURL=census-fixture-client.d.ts.map

package/dist/src/certification/census-fixture-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"census-fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/census-fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAOjD,OAAO,EAML,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AA4F1B,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,CAOjE;AAyFD,qFAAqF;AACrF,wBAAgB,6BAA6B,IAAI,WAAW,CAiE3D"}