@honua/mcp-server 0.1.4-beta.0 → 0.1.9-beta.0

package/README.md

@@ -96,11 +96,27 @@ return a structured result
 instead of crashing, hanging, or returning misleading empty data. This is the
 same skip-with-reason honesty the certification suite uses.
 
+### Bootstrap-only local installation
+
+Local installation is deliberately absent from the ordinary `honua-mcp`
+catalog. During an explicitly approved laptop bootstrap, start a separate,
+single-purpose process that exposes only `honua_admin_install_local`:
+
+```bash
+HONUA_MCP_BOOTSTRAP=1 npx -y -p @honua/mcp-server honua-mcp
+```
+
+The tool requires `confirm: true`. Stop and remove this bootstrap server from
+the MCP client configuration after installation; the normal platform-free
+server remains read-only and cannot invoke the installer.
+
 ## Environment Variables
 
-- `HONUA_BASE_URL` (required): absolute base URL — a public ArcGIS folder
+- `HONUA_BASE_URL` (required in normal mode): absolute base URL — a public ArcGIS folder
   (`https://services.arcgis.com/<org>/arcgis`) or a Honua deployment
   (`https://honua.example.com`).
+- `HONUA_MCP_BOOTSTRAP` (bootstrap only): set to `1` or `true` to start the
+  isolated local-install catalog instead of the ordinary read-only server.
 - `HONUA_TRANSPORT` (optional): `grpc-web` (default, Honua deployments) or `rest`.
   Use `rest` for plain public ArcGIS/OGC endpoints.
 - `HONUA_API_KEY` (optional): API key when your deployment requires it. Public
@@ -123,6 +139,7 @@ All read-only:
 - `honua_statistics`
 - `honua_explain_capability_gap`
 - `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer
+- `honua_docs_search` — answer a Honua documentation question from the local versioned docs corpus (`llms-full.txt`), with a source-file and release-version citation per hit. Each citation is pinned to the exact commit the corpus bytes come from, so it keeps naming the text that was searched after `trunk` moves; when that commit cannot be established (an installed package with no checkout, or a locally regenerated corpus) the citation reports `sourceRevision: null` and links to `trunk` rather than claiming a pin it cannot back. Offline: reads committed files, never the network, and reports structured-unavailable when the corpus is not present in the installation. Point `HONUA_DOCS_CORPUS_PATH` at a corpus file (any name) or at a directory holding `llms-full.txt` to supply the corpus explicitly; `HONUA_SOURCE_REVISION` declares the commit when git is unavailable.
 
 ### Protocol-neutral tool contract
 
@@ -387,7 +404,15 @@ Environment variables:
 - `HONUA_MCP_REMOTE_URL` (required; alias `HONUA_MCP_URL`): the remote honua
   `/mcp` endpoint to proxy.
 - `HONUA_MCP_AUTH_TOKEN` (optional): sent as `Authorization: Bearer <token>`.
-- `HONUA_API_KEY` (optional): sent as `x-api-key`.
+- `HONUA_ADMIN_KEY` or `HONUA_API_KEY` (optional): sent as `x-api-key`.
+
+Configure at most one authentication scheme and one API-key source. The proxy
+rejects bearer plus API-key authentication and rejects simultaneous
+`HONUA_ADMIN_KEY` / `HONUA_API_KEY` values instead of choosing by precedence.
+Credentialed endpoints require HTTPS except for exact `localhost`, `127.0.0.1`,
+or `[::1]` HTTP development endpoints. Userinfo, query parameters, fragments,
+non-HTTP(S) URLs are rejected before connect, and redirect targets are never
+followed or sent credentials.
 
 A parity test (`test/proxy.test.ts`) asserts the tool/resource/template catalog
 the downstream client sees is byte-identical to the upstream surface, that
@@ -496,6 +521,9 @@ Shared env for every live run:
 - `HONUA_API_KEY`: sent as `x-api-key` (⇒ auth mode `api-key`) when the deployment uses key auth instead.
 - `HONUA_EVAL_REQUIRE_AUTH=1` (recommended): fail fast if neither credential is present.
 
+Set exactly one of `HONUA_MCP_AUTH_TOKEN` or `HONUA_API_KEY` for authenticated
+live runs; ambiguous authentication fails closed.
+
 ```bash
 # Anthropic Claude (default claude-opus-4-8; override with HONUA_EVAL_ANTHROPIC_MODEL):
 HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \

package/dist/src/certification/admin-parity.d.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export interface AdminParityReceipt {
+    readonly schemaVersion: "honua.admin-mcp-parity.v1";
+    readonly family: "honua_admin_*";
+    readonly expectedTools: number;
+    readonly expectedStaticTools: number;
+    readonly expectedTotalTools: number;
+    readonly directTools: number;
+    readonly proxiedTools: number;
+    readonly directStaticTools: number;
+    readonly proxiedStaticTools: number;
+    readonly directTotalTools: number;
+    readonly proxiedTotalTools: number;
+    readonly coverageSha256: string;
+    readonly exclusionRosterSha256: string;
+    readonly contractServerSha: string | null;
+    readonly pass: boolean;
+    readonly differences: readonly string[];
+}
+export interface AdminParityExpectation {
+    readonly publishedToolNames: readonly string[];
+    readonly excludedToolNames: readonly string[];
+    readonly expectedStaticTools: number;
+    readonly expectedTotalTools: number;
+}
+export declare function certifyAdminCatalogParity(directCatalog: readonly Tool[], proxiedCatalog: readonly Tool[], expectation?: AdminParityExpectation): AdminParityReceipt;
+export declare function normalizeAdminTools(tools: readonly Tool[]): {
+    name: string;
+    title: string | undefined;
+    description: string | undefined;
+    inputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?: {
+            [x: string]: object;
+        } | undefined;
+        required?: string[] | undefined;
+    };
+    outputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?: {
+            [x: string]: object;
+        } | undefined;
+        required?: string[] | undefined;
+    } | undefined;
+    annotations: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    } | undefined;
+}[];
+/**
+ * Hostile-server safety ceiling on the number of `tools/list` pages a single
+ * catalog read may consume.
+ *
+ * This is deliberately NOT the expected roster size. A roster assertion says
+ * "this catalog is wrong"; this ceiling says "this server never stopped
+ * paging". Conflating the two produced a single unactionable diagnostic and,
+ * worse, made an opt-in profile catalog (base + analysis + Esri GP) impossible
+ * to read at all because the *transport* refused any catalog larger than the
+ * default roster.
+ */
+export declare const MCP_TOOLS_LIST_MAX_PAGES = 1024;
+/**
+ * Hostile-server safety ceiling on the number of tools a single catalog read
+ * may accumulate. Independent of {@link MCP_DEFAULT_TOTAL_TOOL_COUNT} so that
+ * enabling additive server profiles is a roster question, not a transport
+ * failure.
+ */
+export declare const MCP_TOOLS_LIST_MAX_TOOLS = 8192;
+/** Maximum accepted `tools/list` continuation cursor length, in characters. */
+export declare const MCP_TOOLS_LIST_MAX_CURSOR_LENGTH = 1024;
+/**
+ * Read the complete MCP tool catalog. The server deliberately pages large
+ * catalogs, so a single tools/list response is not certification evidence for
+ * the 432-tool default roster (47 static plus 385 Admin MCP tools).
+ *
+ * Roster size is *not* enforced here. This function is responsible only for
+ * retrieving a complete, non-hostile catalog; deciding whether that catalog is
+ * the 432-tool default roster or a profile-enabled superset belongs to the
+ * certification and preflight callers.
+ */
+export declare function listAllTools(client: {
+    listTools(request?: {
+        cursor?: string;
+    }): Promise<{
+        tools: Tool[];
+        nextCursor?: string;
+    }>;
+}): Promise<Tool[]>;
+export declare function runAdminParityCertification(env?: NodeJS.ProcessEnv, outputPath?: string): Promise<AdminParityReceipt>;
+//# sourceMappingURL=admin-parity.d.ts.map

package/dist/src/certification/admin-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-parity.d.ts","sourceRoot":"","sources":["../../../src/certification/admin-parity.ts"],"names":[],"mappings":";AAeA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AASD,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,SAAS,IAAI,EAAE,EAC9B,cAAc,EAAE,SAAS,IAAI,EAAE,EAC/B,WAAW,GAAE,sBAA4C,GACxD,kBAAkB,CAqFpB;AAgCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;IAYzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE;IACzC,SAAS,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAgClB;AAED,wBAAsB,2BAA2B,CAC/C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,SAA0B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}

package/dist/src/certification/admin-parity.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import { ADMIN_MCP_CONTRACT_SERVER_SHA, ADMIN_MCP_COVERAGE_SHA256, ADMIN_MCP_EXCLUDED_OPERATIONS, ADMIN_MCP_EXCLUSION_ROSTER_SHA256, ADMIN_MCP_PUBLISHED_TOOL_NAMES, ADMIN_PUBLISHED_OPERATION_COUNT, MCP_DEFAULT_STATIC_TOOL_COUNT, MCP_DEFAULT_TOTAL_TOOL_COUNT, } from "@honua/sdk-js/control-plane";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { isMainEntrypoint } from "../entrypoint.js";
+import { connectUpstream, createProxyServer, resolveProxyOptions } from "../proxy.js";
+const DEFAULT_EXPECTATION = {
+    publishedToolNames: ADMIN_MCP_PUBLISHED_TOOL_NAMES,
+    excludedToolNames: ADMIN_MCP_EXCLUDED_OPERATIONS.map((operation) => operation.toolName),
+    expectedStaticTools: MCP_DEFAULT_STATIC_TOOL_COUNT,
+    expectedTotalTools: MCP_DEFAULT_TOTAL_TOOL_COUNT,
+};
+export function certifyAdminCatalogParity(directCatalog, proxiedCatalog, expectation = DEFAULT_EXPECTATION) {
+    const direct = normalizeAdminTools(directCatalog);
+    const proxied = normalizeAdminTools(proxiedCatalog);
+    const expectedTools = expectation.publishedToolNames.length;
+    const directStaticTools = directCatalog.length - direct.length;
+    const proxiedStaticTools = proxiedCatalog.length - proxied.length;
+    const differences = [];
+    if (expectedTools !== ADMIN_PUBLISHED_OPERATION_COUNT) {
+        differences.push(`certification expectation contains ${expectedTools} admin tools; generated contract requires ${ADMIN_PUBLISHED_OPERATION_COUNT}`);
+    }
+    if (direct.length !== expectedTools) {
+        differences.push(`direct catalog exposes ${direct.length} admin tools; expected ${expectedTools}`);
+    }
+    if (proxied.length !== expectedTools) {
+        differences.push(`proxied catalog exposes ${proxied.length} admin tools; expected ${expectedTools}`);
+    }
+    if (directStaticTools !== expectation.expectedStaticTools) {
+        differences.push(`direct catalog exposes ${directStaticTools} static tools; expected ${expectation.expectedStaticTools}`);
+    }
+    if (proxiedStaticTools !== expectation.expectedStaticTools) {
+        differences.push(`proxied catalog exposes ${proxiedStaticTools} static tools; expected ${expectation.expectedStaticTools}`);
+    }
+    if (directCatalog.length !== expectation.expectedTotalTools) {
+        differences.push(`direct catalog exposes ${directCatalog.length} total tools; expected ${expectation.expectedTotalTools}`);
+    }
+    if (proxiedCatalog.length !== expectation.expectedTotalTools) {
+        differences.push(`proxied catalog exposes ${proxiedCatalog.length} total tools; expected ${expectation.expectedTotalTools}`);
+    }
+    if (expectation.expectedStaticTools + expectedTools !== expectation.expectedTotalTools) {
+        differences.push(`certification equation failed: ${expectation.expectedStaticTools} static + ${expectedTools} admin ` +
+            `!= ${expectation.expectedTotalTools} total tools`);
+    }
+    for (const duplicate of findDuplicateNames(direct)) {
+        differences.push(`direct catalog repeats admin tool ${duplicate}`);
+    }
+    for (const duplicate of findDuplicateNames(proxied)) {
+        differences.push(`proxied catalog repeats admin tool ${duplicate}`);
+    }
+    for (const duplicate of findDuplicateNames(directCatalog)) {
+        if (!duplicate.startsWith("honua_admin_"))
+            differences.push(`direct catalog repeats static tool ${duplicate}`);
+    }
+    for (const duplicate of findDuplicateNames(proxiedCatalog)) {
+        if (!duplicate.startsWith("honua_admin_"))
+            differences.push(`proxied catalog repeats static tool ${duplicate}`);
+    }
+    compareExpectedRoster("direct", direct, expectation, differences);
+    compareExpectedRoster("proxied", proxied, expectation, differences);
+    const directByName = new Map(direct.map((tool) => [tool.name, tool]));
+    const proxiedByName = new Map(proxied.map((tool) => [tool.name, tool]));
+    for (const name of [...new Set([...directByName.keys(), ...proxiedByName.keys()])].sort()) {
+        const directTool = directByName.get(name);
+        const proxiedTool = proxiedByName.get(name);
+        if (!directTool)
+            differences.push(`${name} is missing from the direct HTTP catalog`);
+        else if (!proxiedTool)
+            differences.push(`${name} is missing from the proxied catalog`);
+        else if (stableJson(directTool) !== stableJson(proxiedTool))
+            differences.push(`${name} descriptor differs`);
+    }
+    return {
+        schemaVersion: "honua.admin-mcp-parity.v1",
+        family: "honua_admin_*",
+        expectedTools,
+        expectedStaticTools: expectation.expectedStaticTools,
+        expectedTotalTools: expectation.expectedTotalTools,
+        directTools: direct.length,
+        proxiedTools: proxied.length,
+        directStaticTools,
+        proxiedStaticTools,
+        directTotalTools: directCatalog.length,
+        proxiedTotalTools: proxiedCatalog.length,
+        coverageSha256: ADMIN_MCP_COVERAGE_SHA256,
+        exclusionRosterSha256: ADMIN_MCP_EXCLUSION_ROSTER_SHA256,
+        contractServerSha: ADMIN_MCP_CONTRACT_SERVER_SHA,
+        pass: differences.length === 0,
+        differences,
+    };
+}
+function compareExpectedRoster(transport, tools, expectation, differences) {
+    const actual = new Set(tools.map((tool) => tool.name));
+    const expected = new Set(expectation.publishedToolNames);
+    for (const name of [...expected].sort()) {
+        if (!actual.has(name))
+            differences.push(`${name} is missing from the ${transport} catalog contract`);
+    }
+    for (const name of [...actual].sort()) {
+        if (!expected.has(name))
+            differences.push(`${name} is not classified as published in the ${transport} catalog contract`);
+    }
+    for (const name of [...expectation.excludedToolNames].sort()) {
+        if (actual.has(name))
+            differences.push(`${transport} catalog advertises explicitly excluded admin tool ${name}`);
+    }
+}
+function findDuplicateNames(tools) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name))
+            duplicates.add(tool.name);
+        else
+            seen.add(tool.name);
+    }
+    return [...duplicates].sort();
+}
+export function normalizeAdminTools(tools) {
+    return tools
+        .filter((tool) => tool.name.startsWith("honua_admin_"))
+        .map((tool) => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations,
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Hostile-server safety ceiling on the number of `tools/list` pages a single
+ * catalog read may consume.
+ *
+ * This is deliberately NOT the expected roster size. A roster assertion says
+ * "this catalog is wrong"; this ceiling says "this server never stopped
+ * paging". Conflating the two produced a single unactionable diagnostic and,
+ * worse, made an opt-in profile catalog (base + analysis + Esri GP) impossible
+ * to read at all because the *transport* refused any catalog larger than the
+ * default roster.
+ */
+export const MCP_TOOLS_LIST_MAX_PAGES = 1_024;
+/**
+ * Hostile-server safety ceiling on the number of tools a single catalog read
+ * may accumulate. Independent of {@link MCP_DEFAULT_TOTAL_TOOL_COUNT} so that
+ * enabling additive server profiles is a roster question, not a transport
+ * failure.
+ */
+export const MCP_TOOLS_LIST_MAX_TOOLS = 8_192;
+/** Maximum accepted `tools/list` continuation cursor length, in characters. */
+export const MCP_TOOLS_LIST_MAX_CURSOR_LENGTH = 1_024;
+/**
+ * Read the complete MCP tool catalog. The server deliberately pages large
+ * catalogs, so a single tools/list response is not certification evidence for
+ * the 432-tool default roster (47 static plus 385 Admin MCP tools).
+ *
+ * Roster size is *not* enforced here. This function is responsible only for
+ * retrieving a complete, non-hostile catalog; deciding whether that catalog is
+ * the 432-tool default roster or a profile-enabled superset belongs to the
+ * certification and preflight callers.
+ */
+export async function listAllTools(client) {
+    const tools = [];
+    let cursor;
+    const seenCursors = new Set();
+    let pageCount = 0;
+    do {
+        pageCount += 1;
+        if (pageCount > MCP_TOOLS_LIST_MAX_PAGES) {
+            throw new Error(`MCP tools/list exceeded the ${MCP_TOOLS_LIST_MAX_PAGES}-page pagination safety ceiling after ${tools.length} tools; the server did not terminate its cursor chain. This is a pagination fault, not a roster assertion.`);
+        }
+        const page = await client.listTools(cursor ? { cursor } : undefined);
+        if (tools.length + page.tools.length > MCP_TOOLS_LIST_MAX_TOOLS) {
+            throw new Error(`MCP tools/list exceeded the ${MCP_TOOLS_LIST_MAX_TOOLS}-tool pagination safety ceiling on page ${pageCount}; the server returned an implausible catalog. This is a pagination fault, not a roster assertion.`);
+        }
+        tools.push(...page.tools);
+        cursor = page.nextCursor;
+        if (cursor !== undefined && (cursor.length === 0 || cursor.length > MCP_TOOLS_LIST_MAX_CURSOR_LENGTH)) {
+            throw new Error("MCP tools/list returned an invalid bounded cursor");
+        }
+        if (cursor && seenCursors.has(cursor)) {
+            throw new Error(`MCP tools/list repeated cursor ${cursor}`);
+        }
+        if (cursor && page.tools.length === 0) {
+            throw new Error("MCP tools/list returned an empty page with a continuation cursor");
+        }
+        if (cursor)
+            seenCursors.add(cursor);
+    } while (cursor);
+    return tools;
+}
+export async function runAdminParityCertification(env = process.env, outputPath = "admin-mcp-parity.json") {
+    if (ADMIN_MCP_CONTRACT_SERVER_SHA === null) {
+        throw new Error("Admin MCP live certification is blocked until config/admin-client.v1.json pins the final server head.");
+    }
+    const upstream = await connectUpstream(resolveProxyOptions(env));
+    const proxy = createProxyServer(upstream);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const proxied = new Client({ name: "honua-admin-parity", version: "1.0.0" });
+    try {
+        await proxy.connect(serverTransport);
+        await proxied.connect(clientTransport);
+        const directTools = await listAllTools(upstream);
+        const proxiedTools = await listAllTools(proxied);
+        const receipt = certifyAdminCatalogParity(directTools, proxiedTools);
+        await writeFile(outputPath, `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+        if (!receipt.pass)
+            throw new Error(`Admin MCP parity failed: ${receipt.differences.join("; ")}`);
+        return receipt;
+    }
+    finally {
+        await proxied.close().catch(() => { });
+        await proxy.close().catch(() => { });
+        await upstream.close().catch(() => { });
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+}
+if (isMainEntrypoint(import.meta.url)) {
+    runAdminParityCertification(process.env, process.argv[2]).catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

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

@@ -1 +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;AAMjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEpG,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEpE;AAED,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,CActF;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,CAehH"}
+{"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,EAAwC,MAAM,aAAa,CAAC;AAMtF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEpG,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEpE;AAED,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,CActF;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,YAAY,CAK9E;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,IAAI,MAAM,CAc1C;AAED,gDAAgD;AAChD,wBAAsB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAehH"}

package/dist/src/certification/target.js

@@ -4,7 +4,7 @@ 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 { connectUpstream, resolveProxyOptions } from "../proxy.js";
 import { createStandaloneFixtureClient } from "./census-fixture-client.js";
 import { startMockUpstream } from "./mock-upstream.js";
 import { OGC_ENDPOINT } from "./ogc-data.js";
@@ -26,19 +26,10 @@ export function resolveTargetMode(env = process.env) {
 }
 /** 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) {
+    if (!(env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL)) {
         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,
-    };
+    return resolveProxyOptions(env);
 }
 /** Resolve the built `honua-mcp-proxy` entry usable from src (vitest) or dist. */
 export function resolveProxyEntry() {
@@ -200,32 +191,33 @@ async function openStdioProxyTarget(env) {
     const clients = [];
     // Upstream: a live /mcp when configured, otherwise the in-process mock.
     let mock;
-    let upstreamUrl;
-    let upstreamToken;
+    let upstreamOptions;
     let backend;
     if (env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL) {
-        const options = resolveRemoteProxyOptions(env);
-        upstreamUrl = options.remoteUrl;
-        upstreamToken = options.authToken;
+        upstreamOptions = resolveRemoteProxyOptions(env);
         backend = "live";
     }
     else {
         mock = await startMockUpstream();
-        upstreamUrl = mock.url;
-        upstreamToken = mock.authToken;
+        upstreamOptions = { remoteUrl: mock.url, authToken: mock.authToken };
         backend = "mock-upstream";
     }
     const spawnProxyClient = async (withAuth) => {
         const childEnv = {
             ...process.env,
-            HONUA_MCP_REMOTE_URL: upstreamUrl,
+            HONUA_MCP_REMOTE_URL: upstreamOptions.remoteUrl,
         };
-        if (withAuth && upstreamToken) {
-            childEnv.HONUA_MCP_AUTH_TOKEN = upstreamToken;
+        delete childEnv.HONUA_MCP_AUTH_TOKEN;
+        delete childEnv.HONUA_ADMIN_KEY;
+        delete childEnv.HONUA_API_KEY;
+        if (withAuth && upstreamOptions.authToken) {
+            childEnv.HONUA_MCP_AUTH_TOKEN = upstreamOptions.authToken;
+        }
+        else if (withAuth && upstreamOptions.apiKey) {
+            childEnv.HONUA_API_KEY = upstreamOptions.apiKey;
         }
         else {
-            delete childEnv.HONUA_MCP_AUTH_TOKEN;
-            delete childEnv.HONUA_API_KEY;
+            // Keep the certification's anonymous negative control credential-free.
         }
         const transport = new StdioClientTransport({
             command: process.execPath,
@@ -242,8 +234,8 @@ async function openStdioProxyTarget(env) {
     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",
+        serverLabel: `honua-mcp-proxy → ${backend === "live" ? upstreamOptions.remoteUrl : "in-process mock /mcp"}`,
+        authMode: upstreamOptions.authToken ? "bearer" : upstreamOptions.apiKey ? "api-key" : "anonymous",
         honuaTransport: env.HONUA_TRANSPORT ?? null,
         client,
         supportsUnauthenticatedPass: true,

package/dist/src/credential-endpoint.d.ts

@@ -0,0 +1,3 @@
+/** Validate an HTTP endpoint before any transport is created. */
+export declare function requireSecureCredentialEndpoint(value: string, label: string, credentialed?: boolean): URL;
+//# sourceMappingURL=credential-endpoint.d.ts.map

package/dist/src/credential-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-endpoint.d.ts","sourceRoot":"","sources":["../../src/credential-endpoint.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,UAAO,GAAG,GAAG,CAiBtG"}

package/dist/src/credential-endpoint.js

@@ -0,0 +1,24 @@
+/** Validate an HTTP endpoint before any transport is created. */
+export function requireSecureCredentialEndpoint(value, label, credentialed = true) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be a valid absolute URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`${label} must use http or https`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error(`${label} must not include embedded credentials, query parameters, or a fragment`);
+    }
+    if (credentialed && url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+        throw new Error(`${label} requires HTTPS except for exact loopback HTTP development endpoints`);
+    }
+    return url;
+}
+function isLoopbackHost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}

package/dist/src/entrypoint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * True when the module identified by `moduleUrl` is the process entrypoint.
+ *
+ * The obvious spelling of this check — `process.argv[1] === fileURLToPath(import.meta.url)`
+ * — is correct only when the module file is invoked by its own path. npm installs a
+ * package's `bin` entries as symlinks under `node_modules/.bin`, so a user (or an agent)
+ * running the documented command gets `process.argv[1]` pointing at the shim, never at the
+ * module file. The strings differ, the guard does not match, and the binary exits 0 having
+ * done nothing at all (#1528).
+ *
+ * That is the worst available failure shape: no output, no diagnostic, no non-zero status —
+ * nothing for a caller to react to. It is how the honua-release#123 terminal driver recorded
+ * the pinned `honua-mcp-proxy` stage as blocked.
+ *
+ * Resolving both sides through `realpath` makes the shim and the module compare equal. The
+ * guard is kept rather than dropped because these modules are also imported by tests, which
+ * must not start a server as a side effect of importing.
+ */
+export declare function isMainEntrypoint(moduleUrl: string): boolean;
+//# sourceMappingURL=entrypoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../../src/entrypoint.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAkB3D"}

package/dist/src/entrypoint.js

@@ -0,0 +1,38 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * True when the module identified by `moduleUrl` is the process entrypoint.
+ *
+ * The obvious spelling of this check — `process.argv[1] === fileURLToPath(import.meta.url)`
+ * — is correct only when the module file is invoked by its own path. npm installs a
+ * package's `bin` entries as symlinks under `node_modules/.bin`, so a user (or an agent)
+ * running the documented command gets `process.argv[1]` pointing at the shim, never at the
+ * module file. The strings differ, the guard does not match, and the binary exits 0 having
+ * done nothing at all (#1528).
+ *
+ * That is the worst available failure shape: no output, no diagnostic, no non-zero status —
+ * nothing for a caller to react to. It is how the honua-release#123 terminal driver recorded
+ * the pinned `honua-mcp-proxy` stage as blocked.
+ *
+ * Resolving both sides through `realpath` makes the shim and the module compare equal. The
+ * guard is kept rather than dropped because these modules are also imported by tests, which
+ * must not start a server as a side effect of importing.
+ */
+export function isMainEntrypoint(moduleUrl) {
+    const invoked = process.argv[1];
+    if (!invoked) {
+        return false;
+    }
+    const modulePath = fileURLToPath(moduleUrl);
+    if (invoked === modulePath) {
+        return true;
+    }
+    // realpathSync throws for a path that does not exist, which is not an error here:
+    // it just means this module is not what was invoked.
+    try {
+        return realpathSync(invoked) === realpathSync(modulePath);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/index.d.ts

@@ -3,7 +3,10 @@ import { HonuaClient } from "@honua/sdk-js";
 import type { HonuaTransport } from "@honua/sdk-js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type NlMapControlMcpHost } from "./nl-map-control.js";
+import type { ControlPlaneCommandMcpHost } from "./tools/control-plane-command.js";
 export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
+export { CONTROL_PLANE_COMMAND_TOOL_PREFIX, controlPlaneCommandToolName, controlPlaneCommandToolSchema, registerControlPlaneCommandTools, } from "./tools/control-plane-command.js";
+export type { ControlPlaneCommandMcpHost } from "./tools/control-plane-command.js";
 export type { CreateNlMapControlMcpHostOptions, McpNlMapExecutionResponse, McpNlMapPlanResponse, McpNlMapReceipt, NlMapControlMcpHost, NlMapControlMcpRequestContext, } from "./nl-map-control.js";
 export interface RuntimeOptions {
     baseUrl: string;
@@ -15,6 +18,13 @@ export interface RuntimeOptions {
 export interface CreateServerOptions {
     /** Optional BYO-LLM/map-runtime host for the experimental NL map-plan tools. */
     readonly nlMapControl?: NlMapControlMcpHost;
+    /**
+     * Optional control-plane command runtime. When supplied, the server also
+     * publishes one generated thin adapter per shared command (see
+     * {@link registerControlPlaneCommandTools}). Omitted by default so the
+     * standalone catalog stays platform-free and read-only.
+     */
+    readonly controlPlaneCommands?: ControlPlaneCommandMcpHost;
 }
 export declare const SERVER_VERSION: string;
 export declare function resolveRuntimeOptions(env: NodeJS.ProcessEnv): RuntimeOptions;
@@ -46,13 +56,24 @@ export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClien
  * 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.
+ * Local installation is intentionally absent from this catalog and is exposed
+ * only by {@link createBootstrapServer}.
+ *
+ * Control-plane MUTATION is likewise absent by default, and when a host does
+ * enable it ({@link CreateServerOptions.controlPlaneCommands}) MCP does not get
+ * a workflow of its own: the tools are generated from the shared command
+ * catalog in `@honua/sdk-js/control-plane`, so an MCP invocation and the
+ * equivalent `honua` CLI, Studio, or direct-JS invocation share one
+ * implementation and one receipt `auditKey`.
  */
 export declare function createServer(client: HonuaClient, options?: CreateServerOptions): McpServer;
+/** Bootstrap-only MCP surface for a laptop that does not have Honua yet. */
+export declare function createBootstrapServer(): 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 —
+ * transport/auth) and exposes {@link createServer} — the ten 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.

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;AAGtF,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,qBAAqB,CAAC;AAe7F,OAAO,EACL,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,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;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;CAC7C;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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aAsGlF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAItF,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,qBAAqB,CAAC;AAM7F,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAanF,OAAO,EACL,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,2BAA2B,EAC3B,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,YAAY,EACV,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,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;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,0BAA0B,CAAC;CAC5D;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aAoHlF;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}