@honua/mcp-server 0.0.10-alpha.0 → 0.1.0-beta.0

package/dist/src/certification/census-fixture-client.js

@@ -0,0 +1,226 @@
+import { CENSUS_EXTENT, CENSUS_FIELDS, CENSUS_LAYER_NAME, CENSUS_ROWS, CENSUS_SERVICE_ID, } from "./census-data.js";
+/**
+ * Offline PLATFORM-FREE fixture `HonuaClient` (issue #369).
+ *
+ * Where {@link ./fixture-client.ts:createFixtureClient} models a Honua-enhanced
+ * deployment (it serves the OGC API – Styles surface), this client models a PLAIN
+ * public Esri FeatureServer — exactly what the standalone `honua-mcp` front door
+ * points at. It replays the recorded US Census apportionment layer
+ * (services.arcgis.com; see `census-data.ts`) through a tiny in-memory GeoServices
+ * evaluator so `count / query / extent / statistics` return REAL, deterministic
+ * answers with no network. Crucially it exposes NO Honua-only surface: every
+ * `pipelineFetch` (the OGC API – Styles path the style tools probe) 404s, so the
+ * capability-degradation path is exercised for real.
+ *
+ * The evaluator is verified against the live recordings in
+ * `test/certification/census-fixture-client.test.ts` (count=52, sum(pop)=335085841,
+ * sum(seats)=435, max=California, min=Wyoming), so the semantic eval assertions
+ * that ride on it are grounded, not hand-waved.
+ */
+const SPATIAL_REFERENCE = { wkid: 102100, latestWkid: 3857 };
+function fieldValue(row, field) {
+    return row[field];
+}
+function compare(actual, op, expected) {
+    if (actual === undefined || actual === null) {
+        // NULL never satisfies a comparison (matches GeoServices/SQL semantics).
+        return false;
+    }
+    if (typeof expected === "string" || typeof actual === "string") {
+        const a = String(actual);
+        const e = String(expected);
+        switch (op) {
+            case "=":
+                return a === e;
+            case "<>":
+            case "!=":
+                return a !== e;
+            default:
+                throw new Error(`census fixture: operator ${op} is not supported for string values`);
+        }
+    }
+    switch (op) {
+        case "=":
+            return actual === expected;
+        case "<>":
+        case "!=":
+            return actual !== expected;
+        case ">":
+            return actual > expected;
+        case ">=":
+            return actual >= expected;
+        case "<":
+            return actual < expected;
+        case "<=":
+            return actual <= expected;
+        default:
+            throw new Error(`census fixture: unsupported operator "${op}"`);
+    }
+}
+function matchClause(row, clause) {
+    const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(>=|<=|<>|!=|=|>|<)\s*(.+?)\s*$/.exec(clause);
+    if (!match) {
+        throw new Error(`census fixture: unsupported WHERE clause "${clause}"`);
+    }
+    const [, field, op, rawValue] = match;
+    const actual = fieldValue(row, field);
+    if (actual === undefined) {
+        throw new Error(`census fixture: unknown field "${field}" in WHERE`);
+    }
+    const expected = /^'.*'$/.test(rawValue) ? rawValue.slice(1, -1) : Number(rawValue);
+    if (typeof expected === "number" && Number.isNaN(expected)) {
+        throw new Error(`census fixture: unparseable value in WHERE clause "${clause}"`);
+    }
+    return compare(actual, op, expected);
+}
+/** Filter the recorded rows by a (minimal) SQL WHERE clause. */
+export function filterRows(where) {
+    const clause = (where ?? "1=1").trim();
+    if (clause === "" || clause === "1=1") {
+        return [...CENSUS_ROWS];
+    }
+    const conditions = clause.split(/\s+AND\s+/i);
+    return CENSUS_ROWS.filter((row) => conditions.every((condition) => matchClause(row, condition)));
+}
+function orderRows(rows, orderByFields) {
+    const specs = orderByFields.split(",").map((part) => {
+        const [field, dir] = part.trim().split(/\s+/);
+        return { field, descending: (dir ?? "ASC").toUpperCase() === "DESC" };
+    });
+    return [...rows].sort((a, b) => {
+        for (const { field, descending } of specs) {
+            const av = fieldValue(a, field);
+            const bv = fieldValue(b, field);
+            if (av === bv) {
+                continue;
+            }
+            const less = (av ?? 0) < (bv ?? 0);
+            return (less ? -1 : 1) * (descending ? -1 : 1);
+        }
+        return 0;
+    });
+}
+function aggregate(rows, type, field) {
+    // GeoServices aggregate statistics ignore NULL values (e.g. DC/PR seats).
+    const values = rows.map((row) => fieldValue(row, field)).filter((v) => typeof v === "number");
+    switch (type) {
+        case "count":
+            return values.length;
+        case "sum":
+            return values.reduce((acc, v) => acc + v, 0);
+        case "min":
+            return values.length > 0 ? Math.min(...values) : 0;
+        case "max":
+            return values.length > 0 ? Math.max(...values) : 0;
+        case "avg":
+            return values.reduce((acc, v) => acc + v, 0) / (values.length || 1);
+        case "stddev": {
+            const mean = values.reduce((acc, v) => acc + v, 0) / (values.length || 1);
+            const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / (values.length || 1);
+            return Math.sqrt(variance);
+        }
+        default:
+            throw new Error(`census fixture: unsupported statisticType "${type}"`);
+    }
+}
+function computeStatistics(rows, request) {
+    const stats = request.outStatistics ?? [];
+    const groupField = request.groupByFieldsForStatistics?.split(",")[0]?.trim();
+    const build = (subset, groupValue) => {
+        const attributes = {};
+        if (groupField && groupValue !== undefined) {
+            attributes[groupField] = groupValue;
+        }
+        for (const stat of stats) {
+            attributes[stat.outStatisticFieldName] = aggregate(subset, stat.statisticType, stat.onStatisticField);
+        }
+        return { attributes };
+    };
+    if (!groupField) {
+        return { features: [build(rows)] };
+    }
+    const groups = new Map();
+    for (const row of rows) {
+        const key = fieldValue(row, groupField) ?? "";
+        const bucket = groups.get(key) ?? [];
+        bucket.push(row);
+        groups.set(key, bucket);
+    }
+    const features = [...groups.entries()].map(([value, subset]) => build(subset, value));
+    return { features };
+}
+function projectAttributes(row, outFields) {
+    if (outFields === undefined || outFields === "*" || (Array.isArray(outFields) && outFields.length === 0)) {
+        return { ...row };
+    }
+    const requested = Array.isArray(outFields) ? outFields : outFields.split(",").map((f) => f.trim());
+    const attributes = {};
+    for (const field of requested) {
+        const value = fieldValue(row, field);
+        if (value !== undefined) {
+            attributes[field] = value;
+        }
+    }
+    return attributes;
+}
+/** Build the offline platform-free fixture client (a plain public FeatureServer). */
+export function createStandaloneFixtureClient() {
+    const client = {
+        serverBaseUrl: "https://services.arcgis.com",
+        async listServices() {
+            return { services: [{ name: CENSUS_SERVICE_ID, type: "FeatureServer" }] };
+        },
+        async getFeatureServiceMetadata(_serviceId) {
+            return {
+                serviceDescription: "US Census 2020 apportionment (public Esri Living Atlas FeatureServer)",
+                layers: [{ id: 0, name: CENSUS_LAYER_NAME }],
+                spatialReference: SPATIAL_REFERENCE,
+            };
+        },
+        async getLayerMetadata(_serviceId, _layerId) {
+            return {
+                id: 0,
+                name: CENSUS_LAYER_NAME,
+                description: "One row per state (plus DC and Puerto Rico) with 2020 population and apportioned House seats.",
+                geometryType: "esriGeometryPolygon",
+                fields: CENSUS_FIELDS.map((f) => ({ ...f })),
+                extent: CENSUS_EXTENT,
+                spatialReference: SPATIAL_REFERENCE,
+                relationships: [],
+            };
+        },
+        async queryFeatures(request = {}) {
+            const rows = filterRows(request.where);
+            const extra = request.extraParams ?? {};
+            if (extra.returnCountOnly === true) {
+                return { count: rows.length };
+            }
+            if (extra.returnExtentOnly === true) {
+                return { count: rows.length, extent: CENSUS_EXTENT };
+            }
+            if (request.outStatistics && request.outStatistics.length > 0) {
+                return computeStatistics(rows, request);
+            }
+            const ordered = request.orderByFields ? orderRows(rows, request.orderByFields) : rows;
+            const offset = request.resultOffset ?? 0;
+            const limit = request.resultRecordCount ?? ordered.length;
+            const page = ordered.slice(offset, offset + limit);
+            return {
+                objectIdFieldName: "OBJECTID",
+                geometryType: "esriGeometryPolygon",
+                spatialReference: SPATIAL_REFERENCE,
+                features: page.map((row) => ({ attributes: projectAttributes(row, request.outFields) })),
+                exceededTransferLimit: false,
+            };
+        },
+        // No Honua-only surface: the OGC API - Styles probe always 404s so the
+        // capability-degradation path is exercised against a real plain endpoint.
+        async pipelineFetch(_method, _path) {
+            return new Response(JSON.stringify({ error: { code: 404, message: "not found" } }), {
+                status: 404,
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+    };
+    return client;
+}

package/dist/src/certification/certifier.d.ts

@@ -0,0 +1,125 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type AuthMode, type SuiteProvenance } from "../provenance.js";
+import { AUTH_ERROR_CODES } from "./contracts.js";
+import type { CertTargetMode } from "./target.js";
+/** Per-tool certification record (machine-readable). */
+export interface ToolCertification {
+    name: string;
+    discovered: true;
+    /** inputSchema is structurally valid JSON Schema (draft 2020-12 dialect). */
+    schemaValid: boolean;
+    /** Whether the server advertises a structured-output schema for this tool. */
+    hasOutputSchema: boolean;
+    /** Matched standard tool (by referenceToolName / alias), if any. */
+    standardName: string | null;
+    /** Conformant to the matched standard schema. `null` when no standard match. */
+    conformant: boolean | null;
+    /** Server-advertised read-only hint; round-trip only runs for read-only tools. */
+    readOnly: boolean;
+    /** Round-trip outcome. `skipped` when not read-only or no fixture input. */
+    roundTrip: "passed" | "failed" | "skipped";
+    /** Whether structuredContent validated against the advertised outputSchema. `null` when not exercised. */
+    structuredOutputValidated: boolean | null;
+    errors: string[];
+    notes: string[];
+}
+/** Per-resource certification record. */
+export interface ResourceCertification {
+    name: string;
+    uri: string;
+    discovered: true;
+}
+/** A standard capability advertised by the spec but not implemented here. */
+export interface KnownGap {
+    kind: "standard-tool" | "advertised-tool";
+    name: string;
+    family?: string;
+    detail: string;
+}
+/** A cross-cutting contract check against the certified surface. */
+export interface ContractCheck {
+    contract: "output-schema" | "error-shape" | "auth-unauthenticated" | "list-pagination" | "query-pagination" | "mutating-round-trip" | "mutating-permission-denied" | "async-job-lifecycle";
+    target: string;
+    status: "passed" | "failed" | "skipped";
+    detail: string;
+}
+export interface CertificationReport {
+    schemaVersion: 2;
+    generatedAt: string;
+    server: {
+        name: string;
+        version: string;
+    };
+    protocol: {
+        mcpTransport: string;
+        honuaTransport: string | null;
+        backend: "mock-upstream" | "live";
+        targetMode: CertTargetMode;
+        surface: string;
+    };
+    standard: {
+        source: string;
+        indexDate: string;
+        dialect: string;
+    };
+    /** Self-proving provenance: what was certified, with which suite, how authed. */
+    provenance: SuiteProvenance;
+    summary: {
+        pass: boolean;
+        toolsDiscovered: number;
+        toolsSchemaValid: number;
+        toolsConformanceChecked: number;
+        toolsConformant: number;
+        toolsRoundTripped: number;
+        toolsOutputValidated: number;
+        resourcesDiscovered: number;
+        promptsDiscovered: number;
+        contractsChecked: number;
+        contractsPassed: number;
+        contractsFailed: number;
+        contractsSkipped: number;
+        knownGaps: number;
+        failures: number;
+    };
+    tools: ToolCertification[];
+    resources: ResourceCertification[];
+    prompts: {
+        name: string;
+        discovered: true;
+    }[];
+    contracts: ContractCheck[];
+    knownGaps: KnownGap[];
+}
+export interface CertifyOptions {
+    /** Authenticated, connected MCP client to certify. */
+    client: Client;
+    /** Which target the client is connected to. */
+    targetMode: CertTargetMode;
+    /** Backend behind the surface (mock upstream or a live server). */
+    backend: "mock-upstream" | "live";
+    /** Human-readable label of the certified surface. */
+    surface: string;
+    /** Logical Honua backend transport for the artifact, if known. */
+    honuaTransport?: string | null;
+    /** Open a fresh, unauthenticated client for the auth contract (optional). */
+    connectUnauthenticated?: (() => Promise<Client>) | undefined;
+    /** How the authenticated client reached the surface (recorded in provenance). */
+    authMode?: AuthMode;
+    /** Environment used to resolve round-trip identifiers. */
+    env?: NodeJS.ProcessEnv;
+}
+/** Determine whether a discovered tool is safe to round-trip (read-only). */
+export declare function isReadOnlyTool(tool: {
+    name: string;
+    annotations?: {
+        readOnlyHint?: boolean;
+    };
+}): boolean;
+/**
+ * Connect an MCP client to the certified surface and produce a deterministic
+ * certification report. The client is already connected (offline mock upstream,
+ * a live `/mcp`, or the stdio proxy); certify never owns its lifecycle.
+ */
+export declare function certify(options: CertifyOptions): Promise<CertificationReport>;
+export { AUTH_ERROR_CODES };
+//# sourceMappingURL=certifier.d.ts.map

package/dist/src/certification/certifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certifier.d.ts","sourceRoot":"","sources":["../../../src/certification/certifier.ts"],"names":[],"mappings":"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"}