@honua/mcp-server 0.0.10-alpha.0 → 0.0.20-alpha.0

package/dist/src/certification/report.js

@@ -0,0 +1,90 @@
+/** Render a human-readable Markdown summary of a certification report. */
+export function renderMarkdown(report) {
+    const s = report.summary;
+    const status = s.pass ? "✅ PASS" : "❌ FAIL";
+    const lines = [];
+    lines.push(`# MCP Certification — ${report.server.name} v${report.server.version}`);
+    lines.push("");
+    lines.push(`**Result:** ${status}`);
+    lines.push("");
+    lines.push(`- Generated: \`${report.generatedAt}\``);
+    lines.push(`- Certified surface: ${report.protocol.surface}`);
+    lines.push(`- Target mode: \`${report.protocol.targetMode}\``);
+    lines.push(`- MCP transport: \`${report.protocol.mcpTransport}\``);
+    lines.push(`- Backend: \`${report.protocol.backend}\`${report.protocol.honuaTransport ? ` (Honua transport: \`${report.protocol.honuaTransport}\`)` : ""}`);
+    lines.push(`- Standard: \`${report.standard.source}\` (index ${report.standard.indexDate}, ${report.standard.dialect})`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push("");
+    lines.push("| Metric | Value |");
+    lines.push("| --- | ---: |");
+    lines.push(`| Tools discovered | ${s.toolsDiscovered} |`);
+    lines.push(`| Tools with valid inputSchema | ${s.toolsSchemaValid} / ${s.toolsDiscovered} |`);
+    lines.push(`| Tools conformance-checked | ${s.toolsConformanceChecked} |`);
+    lines.push(`| Tools conformant | ${s.toolsConformant} / ${s.toolsConformanceChecked} |`);
+    lines.push(`| Tools round-tripped | ${s.toolsRoundTripped} |`);
+    lines.push(`| Tools with output-schema validated | ${s.toolsOutputValidated} |`);
+    lines.push(`| Resources discovered | ${s.resourcesDiscovered} |`);
+    lines.push(`| Prompts discovered | ${s.promptsDiscovered} |`);
+    lines.push(`| Contracts checked | ${s.contractsPassed} / ${s.contractsChecked} passed |`);
+    lines.push(`| Known gaps | ${s.knownGaps} |`);
+    lines.push(`| Failures | ${s.failures} |`);
+    lines.push("");
+    lines.push("## Tools");
+    lines.push("");
+    lines.push("| Tool | Schema | Standard | Conformant | Read-only | Round-trip | Output schema |");
+    lines.push("| --- | :---: | --- | :---: | :---: | :---: | :---: |");
+    for (const t of report.tools) {
+        const conformant = t.conformant === null ? "n/a" : t.conformant ? "yes" : "**NO**";
+        const outputCol = t.structuredOutputValidated === true
+            ? "validated"
+            : t.structuredOutputValidated === false
+                ? "**INVALID**"
+                : t.hasOutputSchema
+                    ? "advertised"
+                    : "no";
+        lines.push(`| \`${t.name}\` | ${t.schemaValid ? "valid" : "**invalid**"} | ${t.standardName ?? "—"} | ${conformant} | ${t.readOnly ? "yes" : "no"} | ${t.roundTrip} | ${outputCol} |`);
+    }
+    lines.push("");
+    lines.push("## Contracts");
+    lines.push("");
+    lines.push("| Contract | Target | Status | Detail |");
+    lines.push("| --- | --- | :---: | --- |");
+    for (const c of report.contracts) {
+        const icon = c.status === "passed" ? "✅" : c.status === "failed" ? "❌" : "➖";
+        lines.push(`| \`${c.contract}\` | \`${c.target}\` | ${icon} ${c.status} | ${c.detail} |`);
+    }
+    lines.push("");
+    const toolErrors = report.tools.filter((t) => t.errors.length > 0);
+    if (toolErrors.length > 0) {
+        lines.push("### Tool failures");
+        lines.push("");
+        for (const t of toolErrors) {
+            lines.push(`- \`${t.name}\``);
+            for (const e of t.errors) {
+                lines.push(`  - ${e}`);
+            }
+        }
+        lines.push("");
+    }
+    if (report.resources.length > 0) {
+        lines.push("## Resources");
+        lines.push("");
+        for (const r of report.resources) {
+            lines.push(`- \`${r.name}\` — \`${r.uri}\``);
+        }
+        lines.push("");
+    }
+    if (report.knownGaps.length > 0) {
+        lines.push("## Known gaps");
+        lines.push("");
+        lines.push("These are standard capabilities not yet advertised as discrete tools, or advertised tools outside the standard. They are recorded, not failed.");
+        lines.push("");
+        for (const g of report.knownGaps) {
+            const family = g.family ? ` _(${g.family})_` : "";
+            lines.push(`- **${g.kind}** \`${g.name}\`${family} — ${g.detail}`);
+        }
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,28 @@
+import { type CertificationReport } from "./certifier.js";
+import { type CertificationTarget } from "./target.js";
+/**
+ * Programmatic certification runner.
+ *
+ * The certifier connects to one of three targets (selected by
+ * `HONUA_MCP_CERT_TARGET`) and certifies the honua `/mcp` OPERATOR surface — the
+ * real ~20-tool catalog with output schemas, structured errors, cursor
+ * pagination, and an auth boundary — never the retired 9-tool static server:
+ *
+ *   - `offline`     (default): an in-process streamable-HTTP mock of `/mcp`.
+ *                    Deterministic, zero network, gates every PR.
+ *   - `remote`      : a live `/mcp` (HONUA_MCP_REMOTE_URL + auth). workflow_dispatch.
+ *   - `stdio-proxy` : the `honua-mcp-proxy` binary against an upstream, over stdio.
+ */
+export interface RunOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export declare function runCertification(options?: RunOptions): Promise<CertificationReport>;
+/** Certify an already-opened target, closing it when done. */
+export declare function certifyTarget(target: CertificationTarget, env?: NodeJS.ProcessEnv): Promise<CertificationReport>;
+export interface ArtifactPaths {
+    json: string;
+    markdown: string;
+}
+/** Write the JSON + Markdown certification artifacts to disk. */
+export declare function writeArtifacts(report: CertificationReport, paths: ArtifactPaths): void;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/certification/run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,aAAa,CAAC;AAEhF;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7F;AAED,8DAA8D;AAC9D,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAc9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAGtF"}

package/dist/src/certification/run.js

@@ -0,0 +1,31 @@
+import { writeFileSync } from "node:fs";
+import { certify } from "./certifier.js";
+import { renderMarkdown } from "./report.js";
+import { openCertificationTarget } from "./target.js";
+export async function runCertification(options = {}) {
+    const env = options.env ?? process.env;
+    const target = await openCertificationTarget(env);
+    return certifyTarget(target, env);
+}
+/** Certify an already-opened target, closing it when done. */
+export async function certifyTarget(target, env = process.env) {
+    try {
+        return await certify({
+            client: target.client,
+            targetMode: target.mode,
+            backend: target.backend,
+            surface: target.serverLabel,
+            honuaTransport: target.honuaTransport,
+            connectUnauthenticated: target.supportsUnauthenticatedPass ? () => target.connectUnauthenticated() : undefined,
+            env,
+        });
+    }
+    finally {
+        await target.close();
+    }
+}
+/** Write the JSON + Markdown certification artifacts to disk. */
+export function writeArtifacts(report, paths) {
+    writeFileSync(paths.json, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    writeFileSync(paths.markdown, renderMarkdown(report), "utf8");
+}

package/dist/src/certification/schema-index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Loader for the vendored geospatial-mcp JSON Schemas and their index.
+ *
+ * The schemas are vendored under `certification/geospatial-mcp-schemas/` (see
+ * that directory's `PROVENANCE.md`). Loading is filesystem-only and fully
+ * deterministic — no network access and no model/API calls.
+ */
+export interface StandardToolEntry {
+    /** Bare taxonomy.md tool name (e.g. `query_features`). */
+    standardName: string;
+    /** Name the reference implementation advertises, or null when unimplemented. */
+    referenceToolName: string | null;
+    family: string;
+    /** Relative path of the schema file, e.g. `tools/query_features.schema.json`. */
+    schema: string;
+    implementationStatus: "implemented" | "known-gap";
+    notes?: string;
+}
+export interface StandardResourceEntry {
+    family: string;
+    uriForm: string;
+    schema: string;
+    shapeFidelity: string;
+    implementationStatus?: "implemented" | "known-gap";
+    notes?: string;
+}
+export interface SchemaIndex {
+    title: string;
+    date: string;
+    dialect: string;
+    tools: StandardToolEntry[];
+    resources: StandardResourceEntry[];
+    common: {
+        name: string;
+        schema: string;
+        role: string;
+    }[];
+    conformance?: {
+        name: string;
+        schema: string;
+        role: string;
+    }[];
+}
+/**
+ * Reference-implementation aliasing decision (SDK-local, NOT part of the
+ * vendored standard): the honua-server /mcp surface advertises
+ * `honua_dry_run_plan` alongside `honua_validate_plan`, both driven by the same
+ * partial-plan input schema (see the `validate_plan` entry's notes in the
+ * vendored index). The vendored `index.json` is a byte-exact copy of the
+ * upstream standard and must never be hand-edited to encode this, so the alias
+ * lives here in code instead.
+ */
+export declare const REFERENCE_TOOL_ALIASES: Readonly<Record<string, string>>;
+export type JsonSchema = Record<string, unknown>;
+export declare const SCHEMA_ROOT: URL;
+/** Load and cache the machine-readable schema index. */
+export declare function loadSchemaIndex(): SchemaIndex;
+/** Load and cache a single vendored schema by its index-relative path. */
+export declare function loadSchemaFile(relativePath: string): JsonSchema;
+/** Resolve the absolute on-disk path of the vendored schema root (for diagnostics). */
+export declare function schemaRootPath(): string;
+/**
+ * Build a lookup from the name a tool advertises (`referenceToolName`) to its
+ * standard schema entry. Only entries that name a reference tool are included.
+ * SDK-local reference aliases (see {@link REFERENCE_TOOL_ALIASES}) map extra
+ * advertised names onto the same standard entry.
+ */
+export declare function buildReferenceToolLookup(index: SchemaIndex): Map<string, StandardToolEntry>;
+//# sourceMappingURL=schema-index.d.ts.map

package/dist/src/certification/schema-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-index.d.ts","sourceRoot":"","sources":["../../../src/certification/schema-index.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,aAAa,GAAG,WAAW,CAAC;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzD,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnE,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwBjD,eAAO,MAAM,WAAW,KAAsB,CAAC;AAK/C,wDAAwD;AACxD,wBAAgB,eAAe,IAAI,WAAW,CAM7C;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAS/D;AAED,uFAAuF;AACvF,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAc3F"}

package/dist/src/certification/schema-index.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Reference-implementation aliasing decision (SDK-local, NOT part of the
+ * vendored standard): the honua-server /mcp surface advertises
+ * `honua_dry_run_plan` alongside `honua_validate_plan`, both driven by the same
+ * partial-plan input schema (see the `validate_plan` entry's notes in the
+ * vendored index). The vendored `index.json` is a byte-exact copy of the
+ * upstream standard and must never be hand-edited to encode this, so the alias
+ * lives here in code instead.
+ */
+export const REFERENCE_TOOL_ALIASES = {
+    honua_dry_run_plan: "honua_validate_plan",
+};
+/**
+ * Resolved root of the vendored schema tree.
+ *
+ * The vendored schemas live at the package root under
+ * `certification/geospatial-mcp-schemas/`. This module runs from two locations:
+ *   - compiled: `dist/src/certification/schema-index.js` (3 levels deep)
+ *   - vitest:   `src/certification/schema-index.ts` (2 levels deep)
+ * so we probe candidate depths and pick the one that exists on disk.
+ */
+function resolveSchemaRoot() {
+    const candidates = ["../../../certification/geospatial-mcp-schemas/", "../../certification/geospatial-mcp-schemas/"];
+    for (const candidate of candidates) {
+        const url = new URL(candidate, import.meta.url);
+        if (existsSync(new URL("index.json", url))) {
+            return url;
+        }
+    }
+    // Fall back to the compiled-layout path; the loader will surface a clear
+    // ENOENT if the vendored schemas are genuinely missing.
+    return new URL(candidates[0], import.meta.url);
+}
+export const SCHEMA_ROOT = resolveSchemaRoot();
+let cachedIndex;
+const schemaCache = new Map();
+/** Load and cache the machine-readable schema index. */
+export function loadSchemaIndex() {
+    if (!cachedIndex) {
+        const indexPath = new URL("index.json", SCHEMA_ROOT);
+        cachedIndex = JSON.parse(readFileSync(indexPath, "utf8"));
+    }
+    return cachedIndex;
+}
+/** Load and cache a single vendored schema by its index-relative path. */
+export function loadSchemaFile(relativePath) {
+    const cached = schemaCache.get(relativePath);
+    if (cached) {
+        return cached;
+    }
+    const path = new URL(relativePath, SCHEMA_ROOT);
+    const schema = JSON.parse(readFileSync(path, "utf8"));
+    schemaCache.set(relativePath, schema);
+    return schemaCache.get(relativePath);
+}
+/** Resolve the absolute on-disk path of the vendored schema root (for diagnostics). */
+export function schemaRootPath() {
+    return fileURLToPath(SCHEMA_ROOT);
+}
+/**
+ * Build a lookup from the name a tool advertises (`referenceToolName`) to its
+ * standard schema entry. Only entries that name a reference tool are included.
+ * SDK-local reference aliases (see {@link REFERENCE_TOOL_ALIASES}) map extra
+ * advertised names onto the same standard entry.
+ */
+export function buildReferenceToolLookup(index) {
+    const lookup = new Map();
+    for (const tool of index.tools) {
+        if (tool.referenceToolName) {
+            lookup.set(tool.referenceToolName, tool);
+        }
+    }
+    for (const [alias, canonical] of Object.entries(REFERENCE_TOOL_ALIASES)) {
+        const entry = lookup.get(canonical);
+        if (entry) {
+            lookup.set(alias, entry);
+        }
+    }
+    return lookup;
+}

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

@@ -0,0 +1,40 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { type ProxyOptions } from "../proxy.js";
+/**
+ * Certification target selection.
+ *
+ * The certifier drives one of three targets, all reached through the SAME MCP
+ * client path the proxy uses so what's certified is the real operator surface,
+ * never the retired static server:
+ *
+ *   - `offline`     (CI default): a real in-process streamable-HTTP mock of the
+ *                    honua `/mcp` operator catalog. Gates every PR without a
+ *                    live server.
+ *   - `remote`      : a live streamable-HTTP `/mcp` (HONUA_MCP_REMOTE_URL + auth).
+ *                    Reuses the proxy's upstream connection logic verbatim.
+ *   - `stdio-proxy` : spawns the `honua-mcp-proxy` binary against an upstream and
+ *                     certifies through stdio, proving the proxy chain end-to-end.
+ */
+export type CertTargetMode = "offline" | "remote" | "stdio-proxy";
+export interface CertificationTarget {
+    mode: CertTargetMode;
+    backend: "mock-upstream" | "live";
+    /** Human-readable label for the certified surface (artifact provenance). */
+    serverLabel: string;
+    honuaTransport: string | null;
+    /** Authenticated, connected MCP client. */
+    client: Client;
+    /** Whether an unauthenticated pass is possible for the auth contract. */
+    supportsUnauthenticatedPass: boolean;
+    /** Open a fresh, UNauthenticated client to the same surface (auth contract). */
+    connectUnauthenticated(): Promise<Client>;
+    close(): Promise<void>;
+}
+export declare function resolveTargetMode(env?: NodeJS.ProcessEnv): CertTargetMode;
+/** Resolve the remote `/mcp` endpoint + credentials from the environment. */
+export declare function resolveRemoteProxyOptions(env: NodeJS.ProcessEnv): ProxyOptions;
+/** Resolve the built `honua-mcp-proxy` entry usable from src (vitest) or dist. */
+export declare function resolveProxyEntry(): string;
+/** Open the configured certification target. */
+export declare function openCertificationTarget(env?: NodeJS.ProcessEnv): Promise<CertificationTarget>;
+//# sourceMappingURL=target.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../src/certification/target.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,aAAa,CAAC;AAGjE;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC;IAClC,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,2BAA2B,EAAE,OAAO,CAAC;IACrC,gFAAgF;IAChF,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,cAAc,CAMtF;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,YAAY,CAc9E;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,IAAI,MAAM,CAc1C;AAED,gDAAgD;AAChD,wBAAsB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAShH"}

package/dist/src/certification/target.js

@@ -0,0 +1,167 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { connectUpstream } from "../proxy.js";
+import { startMockUpstream } from "./mock-upstream.js";
+export function resolveTargetMode(env = process.env) {
+    const raw = (env.HONUA_MCP_CERT_TARGET ?? "offline").trim().toLowerCase();
+    if (raw === "offline" || raw === "remote" || raw === "stdio-proxy") {
+        return raw;
+    }
+    throw new Error(`HONUA_MCP_CERT_TARGET must be "offline", "remote", or "stdio-proxy", received "${raw}"`);
+}
+/** Resolve the remote `/mcp` endpoint + credentials from the environment. */
+export function resolveRemoteProxyOptions(env) {
+    const remoteUrl = env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL;
+    if (!remoteUrl) {
+        throw new Error("HONUA_MCP_REMOTE_URL is required for remote / stdio-proxy certification against a live /mcp.");
+    }
+    const parsed = new 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,
+    };
+}
+/** Resolve the built `honua-mcp-proxy` entry usable from src (vitest) or dist. */
+export function resolveProxyEntry() {
+    const candidates = ["../proxy.js", "../../dist/src/proxy.js"];
+    for (const candidate of candidates) {
+        const url = new URL(candidate, import.meta.url);
+        if (url.protocol === "file:" && existsSync(url)) {
+            const path = fileURLToPath(url);
+            if (path.endsWith(".js")) {
+                return path;
+            }
+        }
+    }
+    throw new Error("Could not locate the built honua-mcp-proxy entry (dist/src/proxy.js). Run `npm run build` before stdio-proxy certification.");
+}
+/** Open the configured certification target. */
+export async function openCertificationTarget(env = process.env) {
+    const mode = resolveTargetMode(env);
+    if (mode === "remote") {
+        return openRemoteTarget(env);
+    }
+    if (mode === "stdio-proxy") {
+        return openStdioProxyTarget(env);
+    }
+    return openOfflineTarget(env);
+}
+async function openOfflineTarget(env) {
+    const mock = await startMockUpstream();
+    const authedClients = [];
+    const client = await connectUpstream({ remoteUrl: mock.url, authToken: mock.authToken });
+    authedClients.push(client);
+    return {
+        mode: "offline",
+        backend: "mock-upstream",
+        serverLabel: "honua /mcp operator catalog (in-process streamable-HTTP mock)",
+        honuaTransport: env.HONUA_TRANSPORT ?? null,
+        client,
+        supportsUnauthenticatedPass: true,
+        async connectUnauthenticated() {
+            const unauth = await connectUpstream({ remoteUrl: mock.url });
+            authedClients.push(unauth);
+            return unauth;
+        },
+        async close() {
+            for (const c of authedClients) {
+                await c.close().catch(() => { });
+            }
+            await mock.close();
+        },
+    };
+}
+async function openRemoteTarget(env) {
+    const options = resolveRemoteProxyOptions(env);
+    const clients = [];
+    const client = await connectUpstream(options);
+    clients.push(client);
+    return {
+        mode: "remote",
+        backend: "live",
+        serverLabel: `live honua /mcp (${options.remoteUrl})`,
+        honuaTransport: env.HONUA_TRANSPORT ?? null,
+        client,
+        supportsUnauthenticatedPass: true,
+        async connectUnauthenticated() {
+            const unauth = await connectUpstream({ remoteUrl: options.remoteUrl });
+            clients.push(unauth);
+            return unauth;
+        },
+        async close() {
+            for (const c of clients) {
+                await c.close().catch(() => { });
+            }
+        },
+    };
+}
+async function openStdioProxyTarget(env) {
+    const proxyEntry = resolveProxyEntry();
+    const clients = [];
+    // Upstream: a live /mcp when configured, otherwise the in-process mock.
+    let mock;
+    let upstreamUrl;
+    let upstreamToken;
+    let backend;
+    if (env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL) {
+        const options = resolveRemoteProxyOptions(env);
+        upstreamUrl = options.remoteUrl;
+        upstreamToken = options.authToken;
+        backend = "live";
+    }
+    else {
+        mock = await startMockUpstream();
+        upstreamUrl = mock.url;
+        upstreamToken = mock.authToken;
+        backend = "mock-upstream";
+    }
+    const spawnProxyClient = async (withAuth) => {
+        const childEnv = {
+            ...process.env,
+            HONUA_MCP_REMOTE_URL: upstreamUrl,
+        };
+        if (withAuth && upstreamToken) {
+            childEnv.HONUA_MCP_AUTH_TOKEN = upstreamToken;
+        }
+        else {
+            delete childEnv.HONUA_MCP_AUTH_TOKEN;
+            delete childEnv.HONUA_API_KEY;
+        }
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [proxyEntry],
+            env: childEnv,
+            stderr: "inherit",
+        });
+        const c = new Client({ name: "honua-mcp-certifier", version: "1.0.0" });
+        await c.connect(transport);
+        clients.push(c);
+        return c;
+    };
+    const client = await spawnProxyClient(true);
+    return {
+        mode: "stdio-proxy",
+        backend,
+        serverLabel: `honua-mcp-proxy → ${backend === "live" ? upstreamUrl : "in-process mock /mcp"}`,
+        honuaTransport: env.HONUA_TRANSPORT ?? null,
+        client,
+        supportsUnauthenticatedPass: true,
+        async connectUnauthenticated() {
+            return spawnProxyClient(false);
+        },
+        async close() {
+            for (const c of clients) {
+                await c.close().catch(() => { });
+            }
+            if (mock) {
+                await mock.close();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/eval/cli.ts"],"names":[],"mappings":""}

package/dist/src/eval/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveCorpus } from "./corpus.js";
+import { parseDriverName, selectDrivers } from "./drivers/index.js";
+import { renderMarkdown } from "./report.js";
+import { runEval } from "./runner.js";
+/**
+ * Cross-model MCP workflow eval CLI (honua-server #1956).
+ *
+ * Modes:
+ *   (default)        Run the eval, write artifacts, exit non-zero if the
+ *                    deterministic control did not pass every scenario.
+ *   --artifact-only  Run the eval, write artifacts, ALWAYS exit 0 (evidence
+ *                    upload step; runs with always() in CI).
+ *   --offline        Force the in-memory fixture surface + deterministic driver
+ *                    only, even if API keys / HONUA_MCP_REMOTE_URL are set.
+ *   --driver <name>  Run the deterministic control plus the named live driver(s)
+ *                    (repeatable or comma-separated): anthropic | openai | bedrock.
+ *                    The named driver is run even if its key/opt-in is absent so an
+ *                    explicit request yields an honest driverError, not a silent
+ *                    skip. Without --driver, drivers are auto-resolved from env.
+ *   --corpus <name>  Select the corpus explicitly: analyst | operator | northstar |
+ *                    all. This overrides HONUA_EVAL_CORPUS and is how the `eval:live`
+ *                    script targets the operator surface without relying on shell env
+ *                    (cross-platform). `northstar` targets the three P1-gate
+ *                    workflows. Defaults to the env-driven selection.
+ *
+ * Corpus selection is env-driven (see `resolveCorpus`): default is the analyst
+ * corpus (in-process SDK fixture surface, the CI control); `HONUA_EVAL_CORPUS=operator`
+ * targets the honua-server operator MCP surface for live runs; `all` runs both.
+ *
+ * Offline and deterministic by default: zero model/API calls. Live cross-model
+ * runs activate when ANTHROPIC_API_KEY / OPENAI_API_KEY are set (Anthropic/OpenAI
+ * APIs) or HONUA_EVAL_BEDROCK is set (Claude via Amazon Bedrock, AWS credential
+ * chain), and live remote MCP runs when HONUA_MCP_REMOTE_URL is set. Keys are
+ * never hardcoded — they come from the environment.
+ */
+const CORPUS_NAMES = ["analyst", "operator", "northstar", "all"];
+function parseArgs(argv) {
+    let artifactOnly = false;
+    let offline = false;
+    let outDir = fileURLToPath(new URL("../../../", import.meta.url));
+    const drivers = [];
+    let corpus;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--artifact-only") {
+            artifactOnly = true;
+        }
+        else if (arg === "--offline") {
+            offline = true;
+        }
+        else if (arg === "--out-dir") {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error("--out-dir requires a directory argument");
+            }
+            outDir = resolve(value);
+        }
+        else if (arg === "--corpus") {
+            const value = argv[++i];
+            if (!value || !CORPUS_NAMES.includes(value)) {
+                throw new Error(`--corpus requires one of: ${CORPUS_NAMES.join(", ")}`);
+            }
+            corpus = value;
+        }
+        else if (arg === "--driver") {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error("--driver requires a driver name (anthropic | openai | bedrock)");
+            }
+            for (const name of value.split(",")) {
+                const trimmed = name.trim();
+                if (trimmed.length > 0) {
+                    drivers.push(parseDriverName(trimmed));
+                }
+            }
+        }
+    }
+    return { artifactOnly, offline, outDir, drivers, ...(corpus ? { corpus } : {}) };
+}
+/** Map the `--corpus` alias to the corresponding HONUA_EVAL_CORPUS selection. */
+function corpusForName(name) {
+    const selector = name === "analyst" ? "" : name; // analyst is the env default
+    return resolveCorpus({ ...process.env, HONUA_EVAL_CORPUS: selector });
+}
+async function main() {
+    const { artifactOnly, offline, outDir, drivers, corpus } = parseArgs(process.argv.slice(2));
+    const report = await runEval({
+        forceOffline: offline,
+        ...(drivers.length > 0 ? { drivers: selectDrivers(drivers) } : {}),
+        ...(corpus ? { corpus: corpusForName(corpus) } : {}),
+    });
+    const jsonPath = resolve(outDir, "mcp-eval-results.json");
+    const mdPath = resolve(outDir, "mcp-eval-results.md");
+    writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    writeFileSync(mdPath, renderMarkdown(report), "utf8");
+    const s = report.summary;
+    const status = s.pass ? "PASS" : "FAIL";
+    process.stdout.write(`MCP cross-model eval ${status}: ${s.scenarios} scenarios, ${s.modelsEvaluated} models ` +
+        `(${s.liveModelsEvaluated} live), surface=${report.surface.backend}.\n`);
+    for (const m of report.models) {
+        process.stdout.write(`  ${m.id}: success ${(m.successRate * 100).toFixed(0)}%, clarify ${(m.clarificationRate * 100).toFixed(0)}%, ` +
+            `edit ${(m.editRate * 100).toFixed(0)}% (${m.pass}/${m.scenarios} passed)\n`);
+    }
+    process.stdout.write(`Artifacts: ${jsonPath}\n           ${mdPath}\n`);
+    if (!artifactOnly && !s.pass) {
+        process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Eval error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+});