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

package/dist/src/certification/report.js

@@ -0,0 +1,103 @@
+/** 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("");
+    const p = report.provenance;
+    lines.push("## Provenance");
+    lines.push("");
+    lines.push("| Field | Value |");
+    lines.push("| --- | --- |");
+    lines.push(`| Target | ${p.targetUrl} |`);
+    lines.push(`| Auth mode | \`${p.authMode}\` |`);
+    lines.push(`| Negotiated protocol | \`${p.protocolVersion ?? "n/a"}\` |`);
+    lines.push(`| Tools advertised | ${p.toolCount} |`);
+    lines.push(`| Suite git SHA | \`${p.suiteGitSha}\` (${p.suiteGitShaSource}) |`);
+    lines.push(`| Generated | \`${report.generatedAt}\` |`);
+    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(`| Contracts skipped | ${s.contractsSkipped} |`);
+    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,CAe9B;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,32 @@
+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,
+            authMode: target.authMode,
+            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,94 @@
+/**
+ * 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>>;
+/**
+ * Platform-gated degradations (SDK-local, NOT part of the vendored standard).
+ *
+ * Some reference-shape tools require standard properties that are *platform
+ * bindings* — identifiers that only have meaning against a Honua
+ * publishing/authoring surface. The platform-free (standalone) front door
+ * (issue #369) has no such surface, so it intentionally degrades these tools to
+ * a non-error, client-side projection and legitimately omits the binding
+ * identifiers, keeping only the taxonomy essence.
+ *
+ * This maps an advertised reference tool name to the required standard
+ * properties it may shed WITHOUT counting as non-conformant on a platform-free
+ * target. It is deliberately narrow: it never relaxes read-addressing required
+ * properties (e.g. `honua_query_features` still must require serviceId+layerId),
+ * only true platform-authoring bindings. The vendored `index.json` and schema
+ * files are byte-exact copies of the upstream standard and must never be
+ * hand-edited to encode this, so the decision lives here in code instead.
+ *
+ * `honua_apply_style_preset`: the reference shape binds a StyleRef preset onto a
+ * PUBLISHED layer (serviceId+layerId) via the server OGC API – Styles authoring
+ * surface (ADR-0048). The platform-free surface resolves a preset for
+ * client-side application keyed on `styleId` alone (ADR-0028: never mutates
+ * server state), so it sheds serviceId+layerId.
+ */
+export declare const PLATFORM_FREE_DEGRADATIONS: Readonly<Record<string, readonly 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAElF,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,109 @@
+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",
+};
+/**
+ * Platform-gated degradations (SDK-local, NOT part of the vendored standard).
+ *
+ * Some reference-shape tools require standard properties that are *platform
+ * bindings* — identifiers that only have meaning against a Honua
+ * publishing/authoring surface. The platform-free (standalone) front door
+ * (issue #369) has no such surface, so it intentionally degrades these tools to
+ * a non-error, client-side projection and legitimately omits the binding
+ * identifiers, keeping only the taxonomy essence.
+ *
+ * This maps an advertised reference tool name to the required standard
+ * properties it may shed WITHOUT counting as non-conformant on a platform-free
+ * target. It is deliberately narrow: it never relaxes read-addressing required
+ * properties (e.g. `honua_query_features` still must require serviceId+layerId),
+ * only true platform-authoring bindings. The vendored `index.json` and schema
+ * files are byte-exact copies of the upstream standard and must never be
+ * hand-edited to encode this, so the decision lives here in code instead.
+ *
+ * `honua_apply_style_preset`: the reference shape binds a StyleRef preset onto a
+ * PUBLISHED layer (serviceId+layerId) via the server OGC API – Styles authoring
+ * surface (ADR-0048). The platform-free surface resolves a preset for
+ * client-side application keyed on `styleId` alone (ADR-0028: never mutates
+ * server state), so it sheds serviceId+layerId.
+ */
+export const PLATFORM_FREE_DEGRADATIONS = {
+    honua_apply_style_preset: ["serviceId", "layerId"],
+};
+/**
+ * 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,48 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { AuthMode } from "../provenance.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.
+ *   - `standalone`  : the PLATFORM-FREE front door (issue #369). Certifies the
+ *                     direct-SDK `createServer` surface against an in-process fixture
+ *                     of a PLAIN public FeatureServer (recorded census layer, no
+ *                     Honua surfaces). Proves the tools certify green against a
+ *                     non-Honua endpoint, with Honua-only tools skip-with-reason.
+ */
+export type CertTargetMode = "offline" | "remote" | "stdio-proxy" | "standalone";
+export interface CertificationTarget {
+    mode: CertTargetMode;
+    backend: "mock-upstream" | "live";
+    /** Human-readable label for the certified surface (artifact provenance). */
+    serverLabel: string;
+    /** How the authenticated client reached the surface (recorded in provenance). */
+    authMode: AuthMode;
+    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;AAInE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,aAAa,CAAC;AAIjE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC;AAEjF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC;IAClC,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,EAAE,QAAQ,CAAC;IACnB,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,CAQtF;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,CAYhH"}

package/dist/src/certification/target.js

@@ -0,0 +1,219 @@
+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 { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createClientFromEnv, createServer } from "../index.js";
+import { connectUpstream } from "../proxy.js";
+import { createStandaloneFixtureClient } from "./census-fixture-client.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" || raw === "standalone") {
+        return raw;
+    }
+    throw new Error(`HONUA_MCP_CERT_TARGET must be "offline", "remote", "stdio-proxy", or "standalone", 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);
+    }
+    if (mode === "standalone") {
+        return openStandaloneTarget(env);
+    }
+    return openOfflineTarget(env);
+}
+/**
+ * Open the platform-free standalone target: the direct-SDK `createServer` surface,
+ * reached over an in-memory MCP transport. By default it is wired to an in-process
+ * fixture of a plain public FeatureServer (recorded census layer, no Honua
+ * surfaces) — deterministic, no network, gates CI. When `HONUA_BASE_URL` is set
+ * (the scheduled live variant) it drives a REAL `HonuaClient` against that public
+ * FeatureServer/OGC endpoint instead. Either way there is no transport auth
+ * boundary, so the auth contracts skip-with-reason and the Honua-only style tools
+ * degrade to structured "not available on this target" results.
+ */
+async function openStandaloneTarget(env) {
+    const live = typeof env.HONUA_BASE_URL === "string" && env.HONUA_BASE_URL.length > 0;
+    const client_ = live ? createClientFromEnv(env) : createStandaloneFixtureClient();
+    const server = createServer(client_);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "honua-mcp-certifier", version: "1.0.0" });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    return {
+        mode: "standalone",
+        backend: live ? "live" : "mock-upstream",
+        serverLabel: live
+            ? `honua-mcp standalone → ${env.HONUA_BASE_URL} (live public FeatureServer, no Honua surfaces)`
+            : "honua-mcp standalone → plain public FeatureServer (recorded census fixture, no Honua surfaces)",
+        authMode: "anonymous",
+        honuaTransport: env.HONUA_TRANSPORT ?? null,
+        client,
+        // A plain FeatureServer has no MCP transport auth boundary — the auth
+        // contracts skip-with-reason rather than assert an enforcement that a
+        // platform-free target does not (and should not) provide.
+        supportsUnauthenticatedPass: false,
+        connectUnauthenticated() {
+            return Promise.reject(new Error("standalone target has no auth boundary"));
+        },
+        async close() {
+            await client.close().catch(() => { });
+            await server.close().catch(() => { });
+        },
+    };
+}
+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)",
+        authMode: "bearer",
+        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();
+        },
+    };
+}
+function resolveAuthMode(options) {
+    return options.authToken ? "bearer" : options.apiKey ? "api-key" : "anonymous";
+}
+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})`,
+        authMode: resolveAuthMode(options),
+        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"}`,
+        authMode: upstreamToken ? "bearer" : env.HONUA_API_KEY ? "api-key" : "anonymous",
+        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":""}