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

package/dist/src/eval/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Cross-model MCP workflow eval — shared types (honua-server #1956, WS-H).
+ *
+ * The eval proves the north-star claim "any client → any workflow": a held-out
+ * corpus of GIS workflows is driven through the honua MCP surface by DIFFERENT
+ * client LLMs (Claude AND a GPT model), and end-to-end success / clarification /
+ * edit rates are recorded per model. A deterministic (scripted) driver provides
+ * an offline control that runs in CI with no model/API calls.
+ */
+/** A tool as advertised by the MCP surface, handed to a model driver. */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+/** Result of a single `tools/call` over the MCP surface. */
+export interface ToolCallResult {
+    isError: boolean;
+    /** Flattened text content of the tool result (what a model would read back). */
+    text: string;
+}
+/** The MCP surface a driver may exercise while solving a workflow. */
+export interface WorkflowContext {
+    tools: ToolDescriptor[];
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+}
+/** One step a driver took: a tool call and whether it errored. */
+export interface TranscriptStep {
+    tool: string;
+    args: Record<string, unknown>;
+    isError: boolean;
+}
+/** What a driver produced for one scenario. */
+export interface WorkflowTranscript {
+    scenarioId: string;
+    modelId: string;
+    steps: TranscriptStep[];
+    finalAnswer: string;
+    /** The driver asked the user a clarifying question instead of completing. */
+    clarificationRequested: boolean;
+    /** Tool calls that returned isError (a proxy for self-correction / edits). */
+    errorCount: number;
+    /** Driver-level failure (timeout, exception, model unavailable). */
+    driverError?: string;
+}
+/** Declarative success criteria graded against a transcript. */
+export interface SuccessCriteria {
+    /** Tools that must be called at least once (any order). */
+    requiredTools: string[];
+    /** An ordered subsequence of tool names that must appear in order. */
+    expectedToolSequence?: string[];
+    /** Tools that must never be called (e.g. write/destructive tools). */
+    forbiddenTools?: string[];
+    /** Case-insensitive substrings the final answer must contain. */
+    answerMustInclude?: string[];
+    /**
+     * SEMANTIC assertions (issue #369) — grade the MEANING of the answer, not just
+     * the tool trajectory. Ride on the deterministic control against grounded
+     * fixtures (known feature counts, known geographic facts), so a wrong number or
+     * a hallucinated place name fails the scenario.
+     */
+    /** Case-insensitive substrings the final answer must NOT contain (anti-hallucination / wrong-answer guard). */
+    answerMustNotInclude?: string[];
+    /** Regular-expression sources the final answer must ALL match (case-insensitive) — exact numeric / value checks. */
+    answerMustMatch?: string[];
+    /**
+     * The prompt is deliberately ambiguous or unsupported: a correct client asks a
+     * clarifying question (or refuses) instead of guessing. When true, a `clarified`
+     * transcript grades as `pass` and a completed transcript grades as `fail`.
+     */
+    expectClarification?: boolean;
+}
+/** One GIS workflow in the held-out corpus. */
+export interface Scenario {
+    id: string;
+    title: string;
+    category: string;
+    /** The natural-language task handed to the client LLM. */
+    prompt: string;
+    criteria: SuccessCriteria;
+    /**
+     * Scripted "ideal client" trajectory used by the deterministic offline driver.
+     * Live LLM drivers ignore this and plan their own tool calls.
+     */
+    script: {
+        tool: string;
+        args: Record<string, unknown>;
+    }[];
+    /**
+     * Ambiguity/refusal scenarios: the deterministic driver asks this clarifying
+     * question INSTEAD of running the script (an empty script is typical). Live LLM
+     * drivers decide for themselves whether to clarify from the prompt alone. Pair
+     * with `criteria.expectClarification: true`.
+     */
+    clarify?: {
+        question: string;
+    };
+}
+/** Per-scenario grade for one model. */
+export type GradeOutcome = "pass" | "fail" | "clarified" | "error";
+export interface ScenarioGrade {
+    scenarioId: string;
+    modelId: string;
+    outcome: GradeOutcome;
+    /** Human-readable reasons a grade was not `pass`. */
+    violations: string[];
+    errorCount: number;
+}
+/** A driver wraps a single client model (or the deterministic control). */
+export interface ModelDriver {
+    /** Stable identifier recorded in the artifact, e.g. "claude-opus-4-8". */
+    readonly id: string;
+    readonly vendor: "anthropic" | "openai" | "bedrock" | "deterministic";
+    /** Whether this driver can actually run (key + SDK present). */
+    isAvailable(): boolean;
+    runWorkflow(scenario: Scenario, ctx: WorkflowContext): Promise<WorkflowTranscript>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/eval/types.d.ts.map

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

package/dist/src/eval/types.js

@@ -0,0 +1,10 @@
+/**
+ * Cross-model MCP workflow eval — shared types (honua-server #1956, WS-H).
+ *
+ * The eval proves the north-star claim "any client → any workflow": a held-out
+ * corpus of GIS workflows is driven through the honua MCP surface by DIFFERENT
+ * client LLMs (Claude AND a GPT model), and end-to-end success / clarification /
+ * edit rates are recorded per model. A deterministic (scripted) driver provides
+ * an offline control that runs in CI with no model/API calls.
+ */
+export {};

package/dist/src/helpers.d.ts

@@ -10,6 +10,17 @@ export declare function jsonText(result: unknown): {
     }>;
 };
 export declare function metadataErrorText(): string;
+/**
+ * Coerce a feature `count` from a query response into a usable value.
+ *
+ * The default `grpc-web` transport returns counts via `toSafeNumberOrString`,
+ * which yields a **string** when the proto count exceeds
+ * `Number.MAX_SAFE_INTEGER` (chosen specifically to avoid precision loss). Both
+ * a finite `number` and a numeric `string` are valid counts; anything else
+ * (non-finite numbers, non-numeric strings, missing values) returns
+ * `undefined`.
+ */
+export declare function coerceCount(value: unknown): number | string | undefined;
 export declare function encodeServiceId(serviceId: string): string;
 export declare function decodeServiceId(encoded: string): string;
 export declare function parseLayerId(value: string): number;

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

@@ -1 +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"}
+{"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;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvE;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

@@ -55,6 +55,28 @@ export function jsonText(result) {
 export function metadataErrorText() {
     return METADATA_ERROR_MESSAGE;
 }
+/**
+ * Coerce a feature `count` from a query response into a usable value.
+ *
+ * The default `grpc-web` transport returns counts via `toSafeNumberOrString`,
+ * which yields a **string** when the proto count exceeds
+ * `Number.MAX_SAFE_INTEGER` (chosen specifically to avoid precision loss). Both
+ * a finite `number` and a numeric `string` are valid counts; anything else
+ * (non-finite numbers, non-numeric strings, missing values) returns
+ * `undefined`.
+ */
+export function coerceCount(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === "string") {
+        // Accept canonical base-10 integer strings (optionally signed). These are
+        // the large-count representation the grpc adapter emits to preserve
+        // precision beyond Number.MAX_SAFE_INTEGER.
+        return /^-?\d+$/.test(value.trim()) ? value.trim() : undefined;
+    }
+    return undefined;
+}
 export function encodeServiceId(serviceId) {
     return encodeURIComponent(serviceId);
 }

package/dist/src/index.d.ts

@@ -12,5 +12,36 @@ export interface RuntimeOptions {
 export declare const SERVER_VERSION: string;
 export declare function resolveRuntimeOptions(env: NodeJS.ProcessEnv): RuntimeOptions;
 export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClient;
+/**
+ * The PLATFORM-FREE standalone MCP surface (issue #369).
+ *
+ * This is the direct-SDK operator surface: nine read-only geospatial tools wired
+ * straight onto `@honua/sdk-js`, which speaks plain Esri GeoServices / OGC API
+ * over standard REST paths (`/rest/services`, `/FeatureServer/{id}/query`, …).
+ * Point it at ANY public FeatureServer / OGC endpoint (e.g. a `services.arcgis.com`
+ * FeatureServer) with ZERO Honua-server assumptions — no admin API, no `/healthz`,
+ * no `/mcp` catalog. This is what the `honua-mcp` bin runs (see {@link runStandalone}),
+ * and what the platform-free certification lane + eval corpus exercise.
+ *
+ * Tools that need a Honua-only surface (server-side styling via OGC API – Styles,
+ * a `/rest/services` catalog) degrade gracefully on a plain target: they return a
+ * structured "not available on this target" result rather than crashing or
+ * returning misleading empty data (see `capability.ts`).
+ *
+ * The Honua-ENHANCED surface — the full `/mcp` operator catalog with governed
+ * mutation, jobs, and publishing — is a superset reached over streamable-HTTP and
+ * mirrored to stdio by `honua-mcp-proxy` ({@link runProxy}); it requires a Honua
+ * deployment. Standalone is the front door; the proxy is the upgrade path.
+ */
 export declare function createServer(client: HonuaClient): McpServer;
+/**
+ * Run the platform-free standalone server end-to-end over stdio.
+ *
+ * Builds a `HonuaClient` from the environment (`HONUA_BASE_URL` + optional
+ * transport/auth) and exposes {@link createServer} — the nine read-only tools —
+ * to a stdio MCP client (Claude Desktop / Claude Code / any MCP agent). Point
+ * `HONUA_BASE_URL` at any public FeatureServer/OGC endpoint; no Honua server is
+ * required. For the Honua-enhanced `/mcp` catalog, use `honua-mcp-proxy` instead.
+ */
+export declare function runStandalone(env?: NodeJS.ProcessEnv): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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;AAatF,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,aAqE/C"}
+{"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;AAgBtF,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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,aAyF/C;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}

package/dist/src/index.js

@@ -6,10 +6,13 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 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 stylesResource from "./resources/styles.js";
+import * as applyStylePreset from "./tools/apply-style-preset.js";
 import * as countFeatures from "./tools/count-features.js";
 import * as describeLayer from "./tools/describe-layer.js";
 import * as explainCapabilityGap from "./tools/explain-capability-gap.js";
 import * as getExtent from "./tools/get-extent.js";
+import * as getStyle from "./tools/get-style.js";
 import * as listServices from "./tools/list-services.js";
 import * as queryFeatures from "./tools/query-features.js";
 import * as statistics from "./tools/statistics.js";
@@ -113,33 +116,76 @@ export function createClientFromEnv(env = process.env) {
         retry: options.retryMaxRetries > 0 ? { maxRetries: options.retryMaxRetries } : undefined,
     });
 }
+/**
+ * The PLATFORM-FREE standalone MCP surface (issue #369).
+ *
+ * This is the direct-SDK operator surface: nine read-only geospatial tools wired
+ * straight onto `@honua/sdk-js`, which speaks plain Esri GeoServices / OGC API
+ * over standard REST paths (`/rest/services`, `/FeatureServer/{id}/query`, …).
+ * Point it at ANY public FeatureServer / OGC endpoint (e.g. a `services.arcgis.com`
+ * FeatureServer) with ZERO Honua-server assumptions — no admin API, no `/healthz`,
+ * no `/mcp` catalog. This is what the `honua-mcp` bin runs (see {@link runStandalone}),
+ * and what the platform-free certification lane + eval corpus exercise.
+ *
+ * Tools that need a Honua-only surface (server-side styling via OGC API – Styles,
+ * a `/rest/services` catalog) degrade gracefully on a plain target: they return a
+ * structured "not available on this target" result rather than crashing or
+ * returning misleading empty data (see `capability.ts`).
+ *
+ * The Honua-ENHANCED surface — the full `/mcp` operator catalog with governed
+ * mutation, jobs, and publishing — is a superset reached over streamable-HTTP and
+ * mirrored to stdio by `honua-mcp-proxy` ({@link runProxy}); it requires a Honua
+ * deployment. Standalone is the front door; the proxy is the upgrade path.
+ */
 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_list_services", "Discover all available feature services on any FeatureServer folder. Set includeDetails=true for descriptions, layer counts, and spatial references. Degrades gracefully when the target has no service catalog.", 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)));
-    server.tool("honua_explain_capability_gap", "Explain whether a Honua source/protocol supports a capability and suggest a safe fallback when it does not.", explainCapabilityGap.schema.shape, async (args) => explainCapabilityGap.execute(client, explainCapabilityGap.schema.parse(args)));
+    server.tool("honua_explain_capability_gap", "Explain whether a source/protocol supports a capability and suggest a safe fallback when it does not.", explainCapabilityGap.schema.shape, async (args) => explainCapabilityGap.execute(client, explainCapabilityGap.schema.parse(args)));
+    server.tool("honua_get_style", "Resolve a style from a server's OGC API – Styles surface. Pass styleId for the canonical StyleRef (style_id, title, encodings incl. inlined MapLibre); omit it to list available styles. On a plain FeatureServer with no styling surface, reports a structured 'not available on this target' result.", getStyle.schema.shape, async (args) => getStyle.execute(client, getStyle.schema.parse(args)));
+    server.tool("honua_apply_style_preset", "Resolve a style preset and its MapLibre stylesheet for client-side application. Read-only: returns the stylesheet to apply locally; it does not mutate server state. Degrades gracefully on a target with no styling surface.", applyStylePreset.schema.shape, async (args) => applyStylePreset.execute(client, applyStylePreset.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));
+    server.resource("styles-catalog", stylesResource.uri, async (uri) => stylesResource.readCatalog(client));
+    server.resource("style", new ResourceTemplate(stylesResource.uriTemplate, { list: undefined }), async (uri, params) => stylesResource.read(client, params.styleId));
     return server;
 }
-async function main() {
-    const client = createClientFromEnv();
+/* v8 ignore start -- live-process entry: wires the stdio transport to a real
+   SDK client against HONUA_BASE_URL; exercised by running the bin, not unit tests.
+   The unit-testable logic (option resolution, client construction, server wiring)
+   lives in the exported functions above and is covered there. */
+/**
+ * Run the platform-free standalone server end-to-end over stdio.
+ *
+ * Builds a `HonuaClient` from the environment (`HONUA_BASE_URL` + optional
+ * transport/auth) and exposes {@link createServer} — the nine read-only tools —
+ * to a stdio MCP client (Claude Desktop / Claude Code / any MCP agent). Point
+ * `HONUA_BASE_URL` at any public FeatureServer/OGC endpoint; no Honua server is
+ * required. For the Honua-enhanced `/mcp` catalog, use `honua-mcp-proxy` instead.
+ */
+export async function runStandalone(env = process.env) {
+    const client = createClientFromEnv(env);
     const server = createServer(client);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+/** `honua-mcp` bin entry — the platform-free standalone server. */
+async function main() {
+    await runStandalone();
+}
 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);
     });
 }
+/* v8 ignore stop */

package/dist/src/provenance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Self-proving provenance for certification & eval artifacts (A5 provability).
+ *
+ * A published report is only evidence if a reader can verify WHAT was tested and
+ * WITH WHICH code. Every artifact carries a `provenance` block naming the target
+ * surface, the negotiated MCP protocol version, the advertised tool count, the
+ * auth mode, the git SHA of the certification/eval suite, and a timestamp. That
+ * turns "we pass" into "here is the exact, reproducible run that passed".
+ */
+/** How the eval/cert authenticated to the surface (proves the run was authed). */
+export type AuthMode = "bearer" | "api-key" | "anonymous" | "none" | "unknown";
+/** The reproducibility fingerprint attached to every artifact. */
+export interface SuiteProvenance {
+    /** Git SHA of the certification/eval suite that produced this artifact. */
+    suiteGitSha: string;
+    /** Where the SHA came from (CI env, local git, or unresolved). */
+    suiteGitShaSource: "env" | "git" | "unknown";
+    /** Human-readable target surface / URL under test. */
+    targetUrl: string;
+    /** MCP protocol version negotiated with the surface, when observable. */
+    protocolVersion: string | null;
+    /** Number of tools the surface advertised. */
+    toolCount: number;
+    /** How the run authenticated to the surface. */
+    authMode: AuthMode;
+}
+/**
+ * Resolve the git SHA of the running suite. Prefers the CI-provided `GITHUB_SHA`
+ * (or an explicit `HONUA_SUITE_GIT_SHA` override), then falls back to
+ * `git rev-parse HEAD`, then to `"unknown"` so an artifact is always self-labeled
+ * even outside a git checkout.
+ */
+export declare function resolveSuiteGitSha(env?: NodeJS.ProcessEnv): {
+    sha: string;
+    source: SuiteProvenance["suiteGitShaSource"];
+};
+/**
+ * Read the negotiated MCP protocol version off a connected client, if its
+ * transport exposes one (the streamable-HTTP client transport does after
+ * `initialize`). Returns `null` for transports that do not surface it
+ * (stdio / in-memory), so the field is honest rather than fabricated.
+ */
+export declare function readNegotiatedProtocolVersion(client: unknown): string | null;
+//# sourceMappingURL=provenance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/provenance.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/E,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,iBAAiB,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IAC7C,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,eAAe,CAAC,mBAAmB,CAAC,CAAC;CAC9C,CAiBA;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5E"}

package/dist/src/provenance.js

@@ -0,0 +1,37 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Resolve the git SHA of the running suite. Prefers the CI-provided `GITHUB_SHA`
+ * (or an explicit `HONUA_SUITE_GIT_SHA` override), then falls back to
+ * `git rev-parse HEAD`, then to `"unknown"` so an artifact is always self-labeled
+ * even outside a git checkout.
+ */
+export function resolveSuiteGitSha(env = process.env) {
+    const fromEnv = (env.HONUA_SUITE_GIT_SHA ?? env.GITHUB_SHA ?? "").trim();
+    if (fromEnv.length > 0) {
+        return { sha: fromEnv, source: "env" };
+    }
+    try {
+        const sha = execFileSync("git", ["rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (sha.length > 0) {
+            return { sha, source: "git" };
+        }
+    }
+    catch {
+        // not a git checkout / git unavailable
+    }
+    return { sha: "unknown", source: "unknown" };
+}
+/**
+ * Read the negotiated MCP protocol version off a connected client, if its
+ * transport exposes one (the streamable-HTTP client transport does after
+ * `initialize`). Returns `null` for transports that do not surface it
+ * (stdio / in-memory), so the field is honest rather than fabricated.
+ */
+export function readNegotiatedProtocolVersion(client) {
+    const transport = client.transport;
+    const version = transport?.protocolVersion;
+    return typeof version === "string" && version.length > 0 ? version : null;
+}

package/dist/src/proxy.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Transport-symmetric stdio proxy for the honua MCP surface (honua-server #1950).
+ *
+ * The honua server exposes a single MCP catalog over streamable-HTTP/SSE at
+ * `/mcp`. Claude-Desktop-style clients speak stdio. Rather than reimplementing
+ * the tool/resource catalog (the older `@honua/mcp-server` discovery surface did
+ * exactly that, which is how the two halves drifted apart), this proxy bridges a
+ * local stdio MCP client to the remote HTTP-SSE MCP server: it connects upstream
+ * as an MCP client, then re-exposes the *same* catalog downstream over stdio.
+ *
+ * Because every request and notification is forwarded verbatim, the stdio
+ * surface is transport-symmetric with the HTTP-SSE surface by construction —
+ * identical tools, identical input/output schemas, identical resources and
+ * prompts, and live `list_changed` notifications. There is one source-of-truth
+ * catalog (the server's `/mcp`); the SDK proxies it.
+ */
+export interface ProxyOptions {
+    /** Absolute URL of the remote honua MCP endpoint (e.g. https://demo.honua.io/mcp). */
+    remoteUrl: string;
+    /** Optional bearer token for the remote MCP surface. */
+    authToken?: string | undefined;
+    /** Optional API key (sent as x-api-key) for deployments that require it. */
+    apiKey?: string | undefined;
+}
+export declare function resolveProxyOptions(env?: NodeJS.ProcessEnv): ProxyOptions;
+/** Build request headers for the upstream connection from the resolved options. */
+export declare function buildUpstreamHeaders(options: ProxyOptions): Record<string, string>;
+/** Connect an upstream MCP client to the remote honua /mcp over streamable HTTP. */
+export declare function connectUpstream(options: ProxyOptions): Promise<Client>;
+/**
+ * Build a low-level MCP server that forwards every request and `list_changed`
+ * notification to the already-connected upstream client. The proxy advertises
+ * exactly the upstream's name, version, and capabilities, so the downstream
+ * (stdio) surface mirrors the upstream (HTTP-SSE) surface.
+ */
+export declare function createProxyServer(upstream: Client): Server;
+/**
+ * Run the stdio proxy end-to-end: resolve the remote `/mcp` from the
+ * environment, connect upstream, and expose the mirrored catalog over stdio.
+ * Also used by the deprecated `honua-mcp` bin, which now delegates here.
+ */
+export declare function runProxy(env?: NodeJS.ProcessEnv): Promise<void>;
+//# sourceMappingURL=proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAiBnE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAqBtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASlF;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+C1D;AAOD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlF"}

package/dist/src/proxy.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { SERVER_VERSION } from "./index.js";
+export function resolveProxyOptions(env = process.env) {
+    const remoteUrl = env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL;
+    if (!remoteUrl) {
+        throw new Error("HONUA_MCP_REMOTE_URL environment variable is required (the remote honua /mcp endpoint to proxy).");
+    }
+    let parsed;
+    try {
+        parsed = new URL(remoteUrl);
+    }
+    catch {
+        throw new Error(`HONUA_MCP_REMOTE_URL must be a valid absolute URL: ${remoteUrl}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`HONUA_MCP_REMOTE_URL must use http or https: ${remoteUrl}`);
+    }
+    return {
+        remoteUrl: parsed.toString(),
+        authToken: env.HONUA_MCP_AUTH_TOKEN,
+        apiKey: env.HONUA_API_KEY,
+    };
+}
+/** Build request headers for the upstream connection from the resolved options. */
+export function buildUpstreamHeaders(options) {
+    const headers = {};
+    if (options.authToken) {
+        headers.Authorization = `Bearer ${options.authToken}`;
+    }
+    if (options.apiKey) {
+        headers["x-api-key"] = options.apiKey;
+    }
+    return headers;
+}
+/** Connect an upstream MCP client to the remote honua /mcp over streamable HTTP. */
+export async function connectUpstream(options) {
+    const headers = buildUpstreamHeaders(options);
+    const transport = new StreamableHTTPClientTransport(new URL(options.remoteUrl), {
+        requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+    });
+    const client = new Client({ name: "honua-mcp-stdio-proxy", version: SERVER_VERSION });
+    await client.connect(transport);
+    return client;
+}
+/**
+ * Build a low-level MCP server that forwards every request and `list_changed`
+ * notification to the already-connected upstream client. The proxy advertises
+ * exactly the upstream's name, version, and capabilities, so the downstream
+ * (stdio) surface mirrors the upstream (HTTP-SSE) surface.
+ */
+export function createProxyServer(upstream) {
+    const upstreamInfo = upstream.getServerVersion() ?? { name: "honua", version: SERVER_VERSION };
+    const upstreamCapabilities = upstream.getServerCapabilities() ?? {};
+    const server = new Server({ name: upstreamInfo.name, version: upstreamInfo.version }, {
+        capabilities: upstreamCapabilities,
+        instructions: upstream.getInstructions(),
+    });
+    // ── Tools ──────────────────────────────────────────────────────
+    if (upstreamCapabilities.tools) {
+        server.setRequestHandler(ListToolsRequestSchema, async (request) => upstream.listTools(request.params));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => upstream.callTool(request.params));
+    }
+    // ── Resources ──────────────────────────────────────────────────
+    if (upstreamCapabilities.resources) {
+        server.setRequestHandler(ListResourcesRequestSchema, async (request) => upstream.listResources(request.params));
+        server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) => upstream.listResourceTemplates(request.params));
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => upstream.readResource(request.params));
+    }
+    // ── Prompts ────────────────────────────────────────────────────
+    if (upstreamCapabilities.prompts) {
+        server.setRequestHandler(ListPromptsRequestSchema, async (request) => upstream.listPrompts(request.params));
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => upstream.getPrompt(request.params));
+    }
+    // ── list_changed notification forwarding ───────────────────────
+    // Keeps the stdio surface live: when the server's catalog changes, the
+    // downstream client is told, exactly as an HTTP-SSE client would be.
+    upstream.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        await server.sendToolListChanged();
+    });
+    upstream.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        await server.sendResourceListChanged();
+    });
+    upstream.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
+        await server.sendPromptListChanged();
+    });
+    return server;
+}
+/* v8 ignore start -- live-process entry: wires the stdio transport to a real
+   remote /mcp upstream; exercised by running the proxy, not by unit tests. The
+   unit-testable logic (option/header resolution, upstream connect, catalog
+   forwarding) lives in the exported functions above and is covered there. */
+/**
+ * Run the stdio proxy end-to-end: resolve the remote `/mcp` from the
+ * environment, connect upstream, and expose the mirrored catalog over stdio.
+ * Also used by the deprecated `honua-mcp` bin, which now delegates here.
+ */
+export async function runProxy(env = process.env) {
+    const options = resolveProxyOptions(env);
+    const upstream = await connectUpstream(options);
+    const server = createProxyServer(upstream);
+    // Tear down both ends together so a dropped upstream surfaces to the client.
+    const shutdown = async () => {
+        await server.close().catch(() => { });
+        await upstream.close().catch(() => { });
+    };
+    upstream.onclose = () => {
+        void shutdown();
+    };
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runProxy().catch((err) => {
+        process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}
+/* v8 ignore stop */

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

@@ -0,0 +1,29 @@
+import type { HonuaClient } from "@honua/sdk-js";
+/** URI for the styles catalog resource (`honua://styles`). */
+export declare const uri = "honua://styles";
+/** URI template for a single style resource (`honua://styles/{styleId}`). */
+export declare const uriTemplate = "honua://styles/{styleId}";
+/**
+ * Read the styles catalog: the list of styles available on the server, each
+ * with its stable styleId, title, and canonical URI (`honua://styles/{id}`).
+ */
+export declare function readCatalog(client: HonuaClient): Promise<{
+    contents: {
+        uri: string;
+        mimeType: "application/json";
+        text: string;
+    }[];
+}>;
+/**
+ * Read a single style as a `StyleRef` projection (style_id / title /
+ * description / style_version / encodings / legend_url), resolved against the
+ * server's `/ogc/styles/{styleId}` surface.
+ */
+export declare function read(client: HonuaClient, styleId: string): Promise<{
+    contents: {
+        uri: string;
+        mimeType: "application/json";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=styles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../../src/resources/styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAQjD,8DAA8D;AAC9D,eAAO,MAAM,GAAG,mBAAmB,CAAC;AAEpC,6EAA6E;AAC7E,eAAO,MAAM,WAAW,6BAA6B,CAAC;AAEtD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW;;;;;;GAyBpD;AAeD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM;;;;;;GAoB9D"}