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

package/dist/src/certification/mock-upstream.js

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createOperatorCatalogServer } from "./operator-catalog.js";
+function readBearer(req) {
+    const header = req.headers.authorization;
+    if (typeof header === "string" && header.toLowerCase().startsWith("bearer ")) {
+        return header.slice(7).trim();
+    }
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.length > 0) {
+        return apiKey;
+    }
+    return undefined;
+}
+/** Start the mock operator upstream and resolve once it is listening. */
+export async function startMockUpstream(options = {}) {
+    const authToken = options.authToken ?? "mock-cert-token";
+    const paginate = options.paginate ?? true;
+    // One transport + server per session (the documented multi-session pattern),
+    // so multiple certifier clients — the authenticated pass and the
+    // unauthenticated auth-contract pass — can connect concurrently.
+    const sessions = new Map();
+    const httpServer = createServer((req, res) => {
+        void handleHttpRequest(req, res, sessions, authToken, paginate);
+    });
+    await new Promise((resolve) => httpServer.listen(0, "127.0.0.1", resolve));
+    const address = httpServer.address();
+    const url = `http://127.0.0.1:${address.port}/mcp`;
+    return {
+        url,
+        authToken,
+        async close() {
+            for (const transport of sessions.values()) {
+                await transport.close().catch(() => { });
+            }
+            sessions.clear();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        },
+    };
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function handleHttpRequest(req, res, sessions, authToken, paginate) {
+    const token = readBearer(req);
+    if (token && token === authToken) {
+        // AuthInfo the transport threads through to request handlers (per request).
+        req.auth = { token, clientId: "cert-client", scopes: ["operator"] };
+    }
+    const sessionId = req.headers["mcp-session-id"];
+    const existing = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
+    if (existing) {
+        await existing.handleRequest(req, res);
+        return;
+    }
+    // No session yet — only an initialize request may open one.
+    const body = await readJsonBody(req);
+    if (!isInitializeRequest(body)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Bad Request: no valid session ID provided" },
+            id: null,
+        }));
+        return;
+    }
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true,
+        onsessioninitialized: (id) => {
+            sessions.set(id, transport);
+        },
+    });
+    transport.onclose = () => {
+        if (transport.sessionId) {
+            sessions.delete(transport.sessionId);
+        }
+    };
+    const server = createOperatorCatalogServer({ paginate });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}

package/dist/src/certification/operator-catalog.d.ts

@@ -0,0 +1,82 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type JsonSchema } from "./schema-index.js";
+/**
+ * In-process mock of the honua-server `/mcp` operator surface.
+ *
+ * This is the offline, CI-default certification target: a representative
+ * streamable-HTTP MCP catalog shaped like the real honua-server `/mcp` (see
+ * honua-server #1950), NOT the retired 9-tool static `@honua/mcp-server`. It
+ * exists so the `mcp-sdk` CI gate can certify the operator surface — tools with
+ * output schemas, structured errors, cursor pagination, and an auth boundary —
+ * on every PR without a live server.
+ *
+ * Fixtures are derived from the vendored geospatial-mcp schemas: every mapped
+ * tool advertises the vendored inputSchema verbatim, so the certifier's
+ * conformance check exercises the real standard shape rather than a hand-rolled
+ * approximation.
+ *
+ * Nothing here is a product server. It is a labeled test fixture whose only job
+ * is to give the certifier a faithful `/mcp`-shaped surface to certify offline.
+ */
+/** Canonical structured error the operator surface returns on failure paths. */
+export interface StructuredOperatorError {
+    /**
+     * Stable, machine-actionable code. The auth boundary emits `unauthenticated`
+     * / `permission_denied`; argument validation emits `invalid_argument`.
+     */
+    code: "unauthenticated" | "permission_denied" | "invalid_argument" | "not_found" | "execution_failed";
+    /** geoprocessing-error envelope (validates against common/geoprocessing-error.schema.json). */
+    error: {
+        kind: "ValidationFailed" | "AuthorizationDenied" | "UnknownDataset" | "UnknownProcess" | "ExecutionFailed" | "Timeout" | "Cancelled" | "OutputBindingFailed";
+        message: string;
+        stepId?: string;
+        violations?: {
+            code: string;
+            message: string;
+            fieldPath?: string;
+        }[];
+    };
+}
+export interface OperatorTool {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    readOnly: boolean;
+    /** Deterministic structured output for a successful (authenticated) call. */
+    sampleOutput: Record<string, unknown>;
+}
+/**
+ * Representative operator catalog. Every tool advertises its vendored standard
+ * inputSchema verbatim — including the Honua-extension discovery tools
+ * (`honua_list_capabilities`, `honua_resolve_entity`) and
+ * `honua_publish_service`, which the standard maps to its own `publish_service`
+ * entry as a documented divergence from the known-gap `publish_result` family.
+ */
+export declare function buildOperatorTools(): OperatorTool[];
+export interface OperatorResource {
+    uri: string;
+    name: string;
+    mimeType: string;
+    contents: unknown;
+}
+export declare function buildOperatorResources(): OperatorResource[];
+/** Page size for the paginated tools/list and resources/list responses. */
+export declare const CATALOG_PAGE_SIZE = 12;
+export interface OperatorCatalogOptions {
+    /**
+     * Whether an initial catalog page is followed by a `nextCursor` (default
+     * true). The certifier's pagination contract requires at least one paginated
+     * list; disable only for negative tests.
+     */
+    paginate?: boolean;
+}
+/**
+ * Build the low-level MCP `Server` for the mock operator catalog. Auth is
+ * enforced per request from `extra.authInfo` (populated by the HTTP transport
+ * from the bearer token), so a single server instance drives both the
+ * authenticated certification pass and the unauthenticated auth-contract pass.
+ */
+export declare function createOperatorCatalogServer(options?: OperatorCatalogOptions): Server;
+//# sourceMappingURL=operator-catalog.d.ts.map

package/dist/src/certification/operator-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-catalog.d.ts","sourceRoot":"","sources":["../../../src/certification/operator-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAUnE,OAAO,EAAE,KAAK,UAAU,EAA6D,MAAM,mBAAmB,CAAC;AAE/G;;;;;;;;;;;;;;;;;GAiBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,WAAW,GAAG,kBAAkB,CAAC;IACtG,+FAA+F;IAC/F,KAAK,EAAE;QACL,IAAI,EACA,kBAAkB,GAClB,qBAAqB,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,SAAS,GACT,WAAW,GACX,qBAAqB,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACtE,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,YAAY,EAAE,UAAU,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AA0BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,EAAE,CAwSnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,EAAE,CA2B3D;AAED,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAoCpC,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CA+ExF"}

package/dist/src/certification/operator-catalog.js

@@ -0,0 +1,466 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { compileValidator } from "./json-schema.js";
+import { buildReferenceToolLookup, loadSchemaFile, loadSchemaIndex } from "./schema-index.js";
+const OBJECT_SCHEMA = (properties, required = []) => ({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties,
+    required,
+    additionalProperties: true,
+});
+/** Load a vendored tool inputSchema by its advertised (reference) name. */
+function vendoredInputSchema(referenceName) {
+    const index = loadSchemaIndex();
+    const lookup = buildReferenceToolLookup(index);
+    const entry = lookup.get(referenceName);
+    if (!entry) {
+        throw new Error(`operator-catalog: no vendored schema mapped for ${referenceName}`);
+    }
+    // Advertise the vendored shape verbatim (minus the schema $id, which is a
+    // registry URL, not a tool inputSchema field) so conformance exercises the
+    // real standard shape.
+    const schema = { ...loadSchemaFile(entry.schema) };
+    delete schema.$id;
+    return schema;
+}
+/**
+ * Representative operator catalog. Every tool advertises its vendored standard
+ * inputSchema verbatim — including the Honua-extension discovery tools
+ * (`honua_list_capabilities`, `honua_resolve_entity`) and
+ * `honua_publish_service`, which the standard maps to its own `publish_service`
+ * entry as a documented divergence from the known-gap `publish_result` family.
+ */
+export function buildOperatorTools() {
+    return [
+        {
+            name: "honua_list_layers",
+            title: "List layers",
+            description: "Discover published services and their layers.",
+            inputSchema: vendoredInputSchema("honua_list_layers"),
+            outputSchema: OBJECT_SCHEMA({
+                layers: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({
+                        serviceId: { type: "string" },
+                        layerId: { type: "integer" },
+                        name: { type: "string" },
+                        geometryType: { type: "string" },
+                    }, ["serviceId", "layerId", "name"]),
+                },
+                nextCursor: { type: "string" },
+            }, ["layers"]),
+            readOnly: true,
+            sampleOutput: {
+                layers: [{ serviceId: "svc-parks", layerId: 0, name: "Parks", geometryType: "Polygon" }],
+            },
+        },
+        {
+            name: "honua_query_features",
+            title: "Query features",
+            description: "Query features from a published layer with attribute/spatial filters.",
+            inputSchema: vendoredInputSchema("honua_query_features"),
+            outputSchema: OBJECT_SCHEMA({
+                features: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({ attributes: { type: "object" } }, ["attributes"]),
+                },
+                count: { type: "integer", minimum: 0 },
+                nextCursor: { type: "string" },
+            }, ["features", "count"]),
+            readOnly: true,
+            sampleOutput: {
+                features: [{ attributes: { OBJECTID: 1, NAME: "Central Park" } }],
+                count: 1,
+            },
+        },
+        {
+            name: "honua_render_map",
+            title: "Render map",
+            description: "Render an image of ordered layers over an extent.",
+            inputSchema: vendoredInputSchema("honua_render_map"),
+            outputSchema: OBJECT_SCHEMA({
+                image: OBJECT_SCHEMA({
+                    format: { type: "string" },
+                    base64: { type: "string" },
+                    width: { type: "integer" },
+                    height: { type: "integer" },
+                }, ["format", "base64", "width", "height"]),
+            }, ["image"]),
+            readOnly: true,
+            sampleOutput: {
+                image: { format: "image/png", base64: "iVBORw0KGgo=", width: 512, height: 512 },
+            },
+        },
+        {
+            name: "honua_geocode_address",
+            title: "Geocode address",
+            description: "Resolve a freeform address to ranked candidates.",
+            inputSchema: vendoredInputSchema("honua_geocode_address"),
+            outputSchema: OBJECT_SCHEMA({
+                candidates: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({
+                        label: { type: "string" },
+                        score: { type: "number" },
+                        lon: { type: "number" },
+                        lat: { type: "number" },
+                    }, ["label", "score", "lon", "lat"]),
+                },
+            }, ["candidates"]),
+            readOnly: true,
+            sampleOutput: {
+                candidates: [{ label: "1600 Pennsylvania Ave NW", score: 0.98, lon: -77.0365, lat: 38.8977 }],
+            },
+        },
+        {
+            name: "honua_solve_route",
+            title: "Solve route",
+            description: "Solve an ordered route through a sequence of stops.",
+            inputSchema: vendoredInputSchema("honua_solve_route"),
+            outputSchema: OBJECT_SCHEMA({
+                route: OBJECT_SCHEMA({ distanceMeters: { type: "number" }, durationSeconds: { type: "number" } }, [
+                    "distanceMeters",
+                    "durationSeconds",
+                ]),
+            }, ["route"]),
+            readOnly: true,
+            sampleOutput: { route: { distanceMeters: 1234.5, durationSeconds: 210 } },
+        },
+        {
+            name: "honua_plan_analysis",
+            title: "Plan analysis",
+            description: "Compile a natural-language intent into an analysis plan.",
+            inputSchema: vendoredInputSchema("honua_plan_analysis"),
+            outputSchema: OBJECT_SCHEMA({
+                plan: OBJECT_SCHEMA({ planId: { type: "string" }, steps: { type: "array" } }, ["planId", "steps"]),
+            }, ["plan"]),
+            readOnly: true,
+            sampleOutput: {
+                plan: { planId: "plan-001", steps: [{ stepId: "s1", kind: "QueryFeatures" }] },
+            },
+        },
+        {
+            name: "honua_ground_candidates",
+            title: "Ground candidates",
+            description: "Ground a goal to a workflow family and ranked candidates.",
+            inputSchema: vendoredInputSchema("honua_ground_candidates"),
+            outputSchema: OBJECT_SCHEMA({ intentId: { type: "string" }, candidates: { type: "array" } }, [
+                "intentId",
+                "candidates",
+            ]),
+            readOnly: true,
+            sampleOutput: { intentId: "int-001", candidates: [{ family: "Analyze", score: 0.9 }] },
+        },
+        {
+            name: "honua_clarify_intent",
+            title: "Clarify intent",
+            description: "Re-run grounding with the operator's answers merged in.",
+            inputSchema: vendoredInputSchema("honua_clarify_intent"),
+            outputSchema: OBJECT_SCHEMA({ intentId: { type: "string" }, resolved: { type: "boolean" } }, [
+                "intentId",
+                "resolved",
+            ]),
+            readOnly: true,
+            sampleOutput: { intentId: "int-001", resolved: true },
+        },
+        {
+            name: "honua_validate_plan",
+            title: "Validate plan",
+            description: "Validate a (possibly partial) analysis plan and report structured violations.",
+            inputSchema: vendoredInputSchema("honua_validate_plan"),
+            outputSchema: OBJECT_SCHEMA({
+                valid: { type: "boolean" },
+                violations: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({ code: { type: "string" }, message: { type: "string" } }, ["code", "message"]),
+                },
+            }, ["valid", "violations"]),
+            readOnly: true,
+            sampleOutput: { valid: false, violations: [{ code: "EMPTY_PLAN_ID", message: "planId is empty" }] },
+        },
+        {
+            name: "honua_dry_run_plan",
+            title: "Dry-run plan",
+            description: "Preview a plan's execution without submitting a job.",
+            inputSchema: vendoredInputSchema("honua_dry_run_plan"),
+            outputSchema: OBJECT_SCHEMA({
+                planId: { type: "string" },
+                estimated: OBJECT_SCHEMA({ steps: { type: "integer" } }, ["steps"]),
+            }, ["planId", "estimated"]),
+            readOnly: true,
+            sampleOutput: { planId: "plan-001", estimated: { steps: 1 } },
+        },
+        {
+            name: "honua_list_capabilities",
+            title: "List capabilities",
+            description: "List capabilities advertised by the connected honua deployment.",
+            inputSchema: vendoredInputSchema("honua_list_capabilities"),
+            outputSchema: OBJECT_SCHEMA({
+                capabilities: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({ name: { type: "string" }, supported: { type: "boolean" } }, ["name", "supported"]),
+                },
+            }, ["capabilities"]),
+            readOnly: true,
+            sampleOutput: { capabilities: [{ name: "query", supported: true }] },
+        },
+        {
+            name: "honua_resolve_entity",
+            title: "Resolve entity",
+            description: "Resolve a freeform reference to canonical platform entities.",
+            inputSchema: vendoredInputSchema("honua_resolve_entity"),
+            outputSchema: OBJECT_SCHEMA({
+                entities: {
+                    type: "array",
+                    items: OBJECT_SCHEMA({ id: { type: "string" }, kind: { type: "string" } }, ["id", "kind"]),
+                },
+            }, ["entities"]),
+            readOnly: true,
+            sampleOutput: { entities: [{ id: "svc-parks", kind: "service" }] },
+        },
+        // ── Mutating / control-plane tools (never round-tripped) ─────────
+        {
+            name: "honua_execute_plan",
+            title: "Execute plan",
+            description: "Submit an executable plan and return an execution-job reference.",
+            inputSchema: vendoredInputSchema("honua_execute_plan"),
+            outputSchema: OBJECT_SCHEMA({ jobId: { type: "string" }, status: { type: "string" } }, ["jobId", "status"]),
+            readOnly: false,
+            sampleOutput: { jobId: "job-001", status: "Submitted" },
+        },
+        {
+            name: "honua_cancel_job",
+            title: "Cancel job",
+            description: "Request cancellation of a submitted execution job.",
+            inputSchema: vendoredInputSchema("honua_cancel_job"),
+            outputSchema: OBJECT_SCHEMA({ jobId: { type: "string" }, status: { type: "string" } }, ["jobId", "status"]),
+            readOnly: false,
+            sampleOutput: { jobId: "job-001", status: "Cancelling" },
+        },
+        {
+            name: "honua_propose_operation",
+            title: "Propose operation",
+            description: "Propose an in-scope control-plane operation for human approval.",
+            inputSchema: vendoredInputSchema("honua_propose_operation"),
+            outputSchema: OBJECT_SCHEMA({ proposalId: { type: "string" }, status: { type: "string" } }, [
+                "proposalId",
+                "status",
+            ]),
+            readOnly: false,
+            sampleOutput: { proposalId: "prop-001", status: "PendingApproval" },
+        },
+        {
+            name: "honua_publish_service",
+            title: "Publish service",
+            description: "Publish a source table as a new hosted service (documented divergence from the standard publish_result family, which remains a known-gap).",
+            inputSchema: vendoredInputSchema("honua_publish_service"),
+            outputSchema: OBJECT_SCHEMA({ publishedServiceId: { type: "string" }, uri: { type: "string" } }, [
+                "publishedServiceId",
+                "uri",
+            ]),
+            readOnly: false,
+            sampleOutput: { publishedServiceId: "svc-pub-001", uri: "honua://services/svc-pub-001" },
+        },
+        {
+            name: "honua_create_map_package",
+            title: "Create map package",
+            description: "Compose a map package from an intent and inputs.",
+            inputSchema: vendoredInputSchema("honua_create_map_package"),
+            outputSchema: OBJECT_SCHEMA({ mapPackageId: { type: "string" }, uri: { type: "string" } }, [
+                "mapPackageId",
+                "uri",
+            ]),
+            readOnly: false,
+            sampleOutput: { mapPackageId: "map-001", uri: "honua://maps/map-001" },
+        },
+        {
+            name: "honua_create_app_package",
+            title: "Create app package",
+            description: "Compose an app package from an intent and inputs.",
+            inputSchema: vendoredInputSchema("honua_create_app_package"),
+            outputSchema: OBJECT_SCHEMA({ appPackageId: { type: "string" }, uri: { type: "string" } }, [
+                "appPackageId",
+                "uri",
+            ]),
+            readOnly: false,
+            sampleOutput: { appPackageId: "app-001", uri: "honua://apps/app-001" },
+        },
+    ];
+}
+export function buildOperatorResources() {
+    return [
+        {
+            uri: "honua://results/res-001",
+            name: "Result package res-001",
+            mimeType: "application/json",
+            contents: { result_package_id: "res-001", status: "Ready", artifacts: [] },
+        },
+        {
+            uri: "honua://workspaces/ws-001",
+            name: "Workspace ws-001",
+            mimeType: "application/json",
+            contents: { workspace_id: "ws-001", artifacts: [] },
+        },
+        {
+            uri: "honua://styles/topographic",
+            name: "Style topographic",
+            mimeType: "application/json",
+            contents: { style_id: "topographic", title: "Topographic" },
+        },
+        {
+            uri: "honua://services/svc-parks",
+            name: "Published service svc-parks",
+            mimeType: "application/json",
+            contents: { published_service_id: "svc-parks", title: "Parks" },
+        },
+    ];
+}
+/** Page size for the paginated tools/list and resources/list responses. */
+export const CATALOG_PAGE_SIZE = 12;
+const UNAUTHENTICATED_ERROR = {
+    code: "unauthenticated",
+    error: {
+        kind: "AuthorizationDenied",
+        message: "Request is not authenticated. Provide a bearer token or API key.",
+    },
+};
+function invalidArgumentError(violations) {
+    return {
+        code: "invalid_argument",
+        error: {
+            kind: "ValidationFailed",
+            message: "One or more arguments failed validation.",
+            violations,
+        },
+    };
+}
+function validateToolArgs(tool, args) {
+    const validate = compileValidator(tool.inputSchema);
+    const valid = validate(args);
+    if (valid) {
+        return [];
+    }
+    return (validate.errors ?? []).map((e) => ({
+        code: "SCHEMA_VIOLATION",
+        message: `${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`.trim(),
+        fieldPath: e.instancePath || undefined,
+    }));
+}
+/**
+ * Build the low-level MCP `Server` for the mock operator catalog. Auth is
+ * enforced per request from `extra.authInfo` (populated by the HTTP transport
+ * from the bearer token), so a single server instance drives both the
+ * authenticated certification pass and the unauthenticated auth-contract pass.
+ */
+export function createOperatorCatalogServer(options = {}) {
+    const paginate = options.paginate ?? true;
+    const tools = buildOperatorTools();
+    const resources = buildOperatorResources();
+    const toolsByName = new Map(tools.map((t) => [t.name, t]));
+    const server = new Server({ name: "honua", version: "operator-mcp-mock" }, {
+        capabilities: { tools: { listChanged: true }, resources: { listChanged: true } },
+        instructions: "Mock honua /mcp operator surface for offline certification.",
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+        const advertised = tools.map((t) => ({
+            name: t.name,
+            title: t.title,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            outputSchema: t.outputSchema,
+            annotations: { readOnlyHint: t.readOnly },
+        }));
+        return paginateList(advertised, request.params?.cursor, paginate, "tools");
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = toolsByName.get(request.params.name);
+        if (!tool) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`, {
+                code: "not_found",
+                error: { kind: "UnknownProcess", message: `Unknown tool: ${request.params.name}` },
+            });
+        }
+        // Auth boundary: tools/call requires an authenticated request.
+        if (!extra.authInfo) {
+            return toolErrorResult(UNAUTHENTICATED_ERROR);
+        }
+        // Argument validation: invalid args yield a structured, actionable tool
+        // result (isError) — never a protocol-level error.
+        const violations = validateToolArgs(tool, request.params.arguments ?? {});
+        if (violations.length > 0) {
+            return toolErrorResult(invalidArgumentError(violations));
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(tool.sampleOutput) }],
+            structuredContent: tool.sampleOutput,
+            isError: false,
+        };
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
+        const advertised = resources.map((r) => ({ uri: r.uri, name: r.name, mimeType: r.mimeType }));
+        return paginateList(advertised, request.params?.cursor, paginate, "resources");
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => {
+        // Auth boundary: resources/read requires an authenticated request. Resources
+        // have no `isError` result channel, so the structured signal is carried on a
+        // protocol error's `data`.
+        if (!extra.authInfo) {
+            throw new McpError(ErrorCode.InvalidRequest, UNAUTHENTICATED_ERROR.error.message, UNAUTHENTICATED_ERROR);
+        }
+        const resource = resources.find((r) => r.uri === request.params.uri);
+        if (!resource) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown resource: ${request.params.uri}`, {
+                code: "not_found",
+                error: { kind: "UnknownDataset", message: `Unknown resource: ${request.params.uri}` },
+            });
+        }
+        return {
+            contents: [{ uri: resource.uri, mimeType: resource.mimeType, text: JSON.stringify(resource.contents) }],
+        };
+    });
+    return server;
+}
+function toolErrorResult(error) {
+    return {
+        content: [{ type: "text", text: error.error.message }],
+        structuredContent: error,
+        isError: true,
+    };
+}
+/**
+ * Split a catalog into a first page + `nextCursor`, honoring an incoming cursor.
+ * The cursor is an opaque, deterministic offset token.
+ */
+function paginateList(items, cursor, paginate, key) {
+    if (!paginate || items.length <= CATALOG_PAGE_SIZE) {
+        return { [key]: items };
+    }
+    const offset = decodeCursor(cursor);
+    const page = items.slice(offset, offset + CATALOG_PAGE_SIZE);
+    const nextOffset = offset + page.length;
+    const result = { [key]: page };
+    if (nextOffset < items.length) {
+        result.nextCursor = encodeCursor(nextOffset);
+    }
+    return result;
+}
+function encodeCursor(offset) {
+    return Buffer.from(`offset:${offset}`, "utf8").toString("base64");
+}
+function decodeCursor(cursor) {
+    if (!cursor) {
+        return 0;
+    }
+    try {
+        const decoded = Buffer.from(cursor, "base64").toString("utf8");
+        const match = /^offset:(\d+)$/.exec(decoded);
+        if (match) {
+            return Number.parseInt(match[1], 10);
+        }
+    }
+    catch {
+        // fall through
+    }
+    return 0;
+}

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

@@ -0,0 +1,4 @@
+import type { CertificationReport } from "./certifier.js";
+/** Render a human-readable Markdown summary of a certification report. */
+export declare function renderMarkdown(report: CertificationReport): string;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/certification/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CA6GlE"}