@honua/mcp-server 0.0.20-alpha.0 → 0.1.1-beta.0

package/dist/src/nl-map-control.js

@@ -0,0 +1,470 @@
+import { verifyAgentApproval, verifyAgentStepAuthorization, } from "@honua/sdk-js/agent-safety";
+import { NL_MAP_CONTROL_TOOL_DEFINITIONS, NL_MAP_CONTROL_VERSION, NL_MAP_PLAN_KIND, agentEffectForNlEffect, createNlMapControl, hashNlMapPlan, } from "@honua/sdk-js/nl-map-control";
+import { canonicalStringify, sha256, toJsonValue } from "@honua/sdk-js/query-planner";
+import { z } from "zod";
+import { snapshotMcpJson } from "./stable-json.js";
+const MCP_NL_MAP_RECEIPT_KIND = "honua.mcp-nl-map-receipt";
+const PLAN_ID = /^nlplan_[0-9a-f]{16}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const SENSITIVE_KEYS = new Set([
+    "accesstoken",
+    "apikey",
+    "authorization",
+    "cookie",
+    "credential",
+    "credentials",
+    "cursor",
+    "endpoint",
+    "password",
+    "refreshtoken",
+    "resumetoken",
+    "secret",
+    "signedurl",
+    "token",
+    "url",
+    "uri",
+    "watermark",
+]);
+const CREDENTIAL_TEXT = /\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]+|\b(?:api[_-]?key|access[_-]?token|password|secret)\s*[:=]\s*[^\s,;]+/giu;
+const CURSOR_TEXT = /\b(?:cursor|resume[_ -]?token|watermark)\s*[:=]\s*[^\s,;]+/giu;
+const URL_TEXT = /https?:\/\/[^\s"'<>]+/giu;
+const PUBLIC_ERROR_CODES = new Set([
+    "aborted",
+    "approval-expired",
+    "approval-invalid",
+    "approval-required",
+    "authorization-scope-denied",
+    "cancelled",
+    "context-mismatch",
+    "fixture-mismatch",
+    "integrity-failed",
+    "invalid-input",
+    "invalid-options",
+    "plan-invalid",
+    "plan-required",
+    "policy-denied",
+    "refusal",
+    "retries-exhausted",
+    "signature-invalid",
+    "unsafe-output",
+]);
+class HonuaNlMapMcpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HonuaNlMapMcpError";
+        this.code = code;
+    }
+}
+/**
+ * Bind the experimental NL map controller to the MCP trust boundary.
+ *
+ * The host pre-authorizes and atomically consumes every approved step before
+ * delegating to `createNlMapControl`. This preserves the SDK's exact plan and
+ * signature checks while preventing approval replay through a second transport
+ * call. No caller-provided credential or cursor is included in MCP output.
+ */
+export function createNlMapControlMcpHost(options) {
+    if (!options?.control?.approvalVerifier) {
+        throw new TypeError("NL map MCP hosting requires control.approvalVerifier");
+    }
+    if (!options.approvalUseConsumer) {
+        throw new TypeError("NL map MCP hosting requires an atomic approvalUseConsumer");
+    }
+    const control = createNlMapControl(options.control);
+    const approvalVerifier = options.control.approvalVerifier;
+    const approvalUseConsumer = options.approvalUseConsumer;
+    const resolveAuthorizationScopes = options.resolveAuthorizationScopes;
+    const configuredNow = options.control.policy?.now;
+    const now = () => configuredNow?.() ?? new Date().toISOString();
+    return Object.freeze({
+        control,
+        async propose(input, context = {}) {
+            const signal = requestSignal(context);
+            signal?.throwIfAborted();
+            const request = snapshotMcpObject(input, "proposeMapPlan input");
+            const instruction = request.instruction;
+            if (typeof instruction !== "string" || instruction.trim().length === 0 || instruction.length > 16_384) {
+                throw new HonuaNlMapMcpError("invalid-input", "proposeMapPlan requires a non-empty instruction");
+            }
+            const plan = parseMcpPlan(await control.propose(instruction, {
+                ...(signal ? { signal } : {}),
+            }));
+            signal?.throwIfAborted();
+            assertMcpSafePlan(plan);
+            return Object.freeze({ plan, approvalRequired: planRequiresMcpApproval(plan) });
+        },
+        async execute(input, context = {}) {
+            const signal = requestSignal(context);
+            signal?.throwIfAborted();
+            const request = snapshotMcpObject(input, "executeMapPlan input");
+            const plan = parseMcpPlan(request.plan);
+            assertMcpSafePlan(plan);
+            const approval = request.approval === undefined ? undefined : request.approval;
+            if (approval === undefined && planRequiresMcpApproval(plan)) {
+                throw new HonuaNlMapMcpError("approval-required", "MCP source-scoped and effectful map plans require a signed approval envelope");
+            }
+            if (approval !== undefined) {
+                const authorizationTime = now();
+                await verifyAgentApproval(approval.dryRun, approval.policy, approval.approval, approvalVerifier, approval.context, {
+                    now: authorizationTime,
+                    ...(signal ? { signal } : {}),
+                });
+                signal?.throwIfAborted();
+                assertApprovalPlanIdentity(plan, approval);
+                const transportScopes = requestAuthorizationScopes(context);
+                const grantedInput = resolveAuthorizationScopes
+                    ? await resolveAuthorizationScopes(transportScopes)
+                    : transportScopes;
+                signal?.throwIfAborted();
+                const grantedScopes = snapshotAuthorizationScopes(grantedInput, "resolved authorization scopes");
+                assertAuthorizationScopes(approval, grantedScopes);
+                for (let index = 0; index < plan.steps.length; index += 1) {
+                    signal?.throwIfAborted();
+                    const step = plan.steps[index];
+                    const approvedStep = approval.dryRun.plan.steps[index];
+                    const sourceId = authorizationSourceId(step, approvedStep.source.id);
+                    await verifyAgentStepAuthorization(approval.dryRun, approval.policy, approval.approval, approvalVerifier, approval.context, step.id, {
+                        tool: step.tool,
+                        effect: agentEffectForNlEffect(step.effect),
+                        sourceId,
+                        queryPlan: approvedStep.queryPlan,
+                        fields: approvedStep.fields,
+                        parameters: toJsonValue(step.call.args ?? {}),
+                    }, approvalUseConsumer, {
+                        now: authorizationTime,
+                        ...(signal ? { signal } : {}),
+                    });
+                }
+            }
+            signal?.throwIfAborted();
+            const execution = await control.execute(plan, {
+                ...(approval ? { approval } : {}),
+                ...(signal ? { signal } : {}),
+            });
+            return executionResponse(execution);
+        },
+    });
+}
+const proposeSchema = z
+    .object({
+    instruction: z.string().trim().min(1).max(16_384),
+})
+    .strict();
+const executeSchema = z
+    .object({
+    plan: z.record(z.string(), z.unknown()),
+    approval: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/** Register `proposeMapPlan` and `executeMapPlan` on a real MCP server. */
+export function registerNlMapControlMcpTools(server, host) {
+    const proposeDefinition = NL_MAP_CONTROL_TOOL_DEFINITIONS[0];
+    const executeDefinition = NL_MAP_CONTROL_TOOL_DEFINITIONS[1];
+    server.registerTool(proposeDefinition.name, {
+        title: proposeDefinition.title,
+        description: proposeDefinition.description,
+        inputSchema: proposeSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (args, extra) => {
+        try {
+            return successResult(await host.propose(args, {
+                signal: extra.signal,
+                transportAuthorizationScopes: extra.authInfo?.scopes ?? [],
+            }));
+        }
+        catch (error) {
+            return errorResult(error, extra.signal);
+        }
+    });
+    server.registerTool(executeDefinition.name, {
+        title: executeDefinition.title,
+        description: `${executeDefinition.description} In the MCP host, source-scoped reads also require a signed approval so transport scopes can be matched to the exact source binding.`,
+        inputSchema: executeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args, extra) => {
+        try {
+            return successResult(await host.execute({ plan: args.plan, ...(args.approval === undefined ? {} : { approval: args.approval }) }, {
+                signal: extra.signal,
+                transportAuthorizationScopes: extra.authInfo?.scopes ?? [],
+            }));
+        }
+        catch (error) {
+            return errorResult(error, extra.signal);
+        }
+    });
+}
+function snapshotMcpObject(input, label, code = "invalid-input") {
+    try {
+        const snapshot = snapshotMcpJson(input, label);
+        if (snapshot === null || typeof snapshot !== "object" || Array.isArray(snapshot)) {
+            throw new TypeError(`${label} must be an object`);
+        }
+        return snapshot;
+    }
+    catch {
+        throw new HonuaNlMapMcpError(code, `${label} is not safe bounded JSON`);
+    }
+}
+function requestSignal(context) {
+    const value = requestContextProperty(context, "signal");
+    if (value === undefined)
+        return undefined;
+    try {
+        if (!(value instanceof AbortSignal))
+            throw new TypeError("signal must be an AbortSignal");
+    }
+    catch {
+        throw new HonuaNlMapMcpError("invalid-input", "MCP request context contains an invalid signal");
+    }
+    return value;
+}
+function requestAuthorizationScopes(context) {
+    const value = requestContextProperty(context, "transportAuthorizationScopes");
+    return snapshotAuthorizationScopes(value ?? [], "transport authorization scopes");
+}
+function requestContextProperty(context, key) {
+    try {
+        if (!context || typeof context !== "object" || Array.isArray(context)) {
+            throw new TypeError("context must be an object");
+        }
+        const prototype = Object.getPrototypeOf(context);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new TypeError("context must be plain");
+        const descriptor = Reflect.getOwnPropertyDescriptor(context, key);
+        if (!descriptor)
+            return undefined;
+        if (!("value" in descriptor) || !descriptor.enumerable)
+            throw new TypeError("context property must be data");
+        return descriptor.value;
+    }
+    catch {
+        throw new HonuaNlMapMcpError("invalid-input", "MCP request context could not be read safely");
+    }
+}
+function snapshotAuthorizationScopes(input, label) {
+    let snapshot;
+    try {
+        snapshot = snapshotMcpJson(input, label);
+    }
+    catch {
+        throw new HonuaNlMapMcpError("invalid-input", `${label} are not safe bounded JSON`);
+    }
+    if (!Array.isArray(snapshot) ||
+        snapshot.length > 128 ||
+        snapshot.some((scope) => typeof scope !== "string" || scope.length === 0 || hasControlCharacters(scope))) {
+        throw new HonuaNlMapMcpError("invalid-input", `${label} must be a bounded list of non-empty strings`);
+    }
+    return Object.freeze([...new Set(snapshot)].sort());
+}
+function parseMcpPlan(input) {
+    const plan = snapshotMcpObject(input, "NL map plan");
+    if (plan.kind !== NL_MAP_PLAN_KIND ||
+        plan.version !== NL_MAP_CONTROL_VERSION ||
+        typeof plan.id !== "string" ||
+        !PLAN_ID.test(plan.id) ||
+        typeof plan.fingerprint !== "string" ||
+        !DIGEST.test(plan.fingerprint) ||
+        !Array.isArray(plan.steps) ||
+        plan.steps.length === 0) {
+        throw new HonuaNlMapMcpError("invalid-input", "executeMapPlan requires a valid NL map plan identity");
+    }
+    let fingerprint;
+    try {
+        fingerprint = hashNlMapPlan(plan);
+    }
+    catch {
+        throw new HonuaNlMapMcpError("invalid-input", "executeMapPlan plan content is not canonical JSON");
+    }
+    const expectedId = `nlplan_${fingerprint.slice("sha256:".length, "sha256:".length + 16)}`;
+    if (fingerprint !== plan.fingerprint || plan.id !== expectedId) {
+        throw new HonuaNlMapMcpError("invalid-input", "executeMapPlan plan identity does not match its content");
+    }
+    return plan;
+}
+function assertApprovalPlanIdentity(plan, approval) {
+    if (!approval ||
+        typeof approval !== "object" ||
+        !approval.dryRun ||
+        approval.dryRun.plan.id !== plan.id ||
+        approval.dryRun.plan.steps.length !== plan.steps.length) {
+        throw new HonuaNlMapMcpError("invalid-input", "approval does not bind to the supplied plan identity");
+    }
+    for (let index = 0; index < plan.steps.length; index += 1) {
+        const step = plan.steps[index];
+        const approved = approval.dryRun.plan.steps[index];
+        if (approved.id !== step.id ||
+            approved.tool !== step.tool ||
+            approved.effect !== agentEffectForNlEffect(step.effect) ||
+            approved.queryPlan.fingerprint !== plan.fingerprint) {
+            throw new HonuaNlMapMcpError("invalid-input", "approval step identity does not match the supplied plan");
+        }
+        authorizationSourceId(step, approved.source.id);
+    }
+}
+function authorizationSourceId(step, approvedSourceId) {
+    const sourceId = step.call.args?.sourceId;
+    if (sourceId !== undefined) {
+        if (typeof sourceId !== "string" || sourceId.length === 0 || sourceId !== approvedSourceId) {
+            throw new HonuaNlMapMcpError("invalid-input", "approval source binding does not match the supplied map operation");
+        }
+        return sourceId;
+    }
+    return approvedSourceId;
+}
+function planRequiresMcpApproval(plan) {
+    return (!plan.readOnly ||
+        plan.steps.some((step) => step.call.args?.sourceId !== undefined));
+}
+function assertAuthorizationScopes(approval, grantedInput) {
+    const granted = new Set(grantedInput);
+    const required = new Set(approval.dryRun.plan.steps.flatMap((step) => [...step.source.authorizationScope]));
+    for (const scope of required) {
+        if (!granted.has(scope)) {
+            throw new HonuaNlMapMcpError("authorization-scope-denied", "MCP transport authorization does not cover the approved map operation");
+        }
+    }
+}
+function assertMcpSafePlan(plan) {
+    assertMcpSafeJson(plan, "NL map plan");
+}
+function assertMcpSafeJson(value, label) {
+    let original;
+    let redacted;
+    try {
+        original = canonicalStringify(toJsonValue(value));
+        redacted = canonicalStringify(toJsonValue(redactForMcp(value)));
+    }
+    catch {
+        throw new HonuaNlMapMcpError("invalid-input", `${label} is not safe canonical JSON`);
+    }
+    if (original !== redacted) {
+        throw new HonuaNlMapMcpError("unsafe-output", `${label} contains credential, cursor, or endpoint material that cannot cross the MCP boundary`);
+    }
+}
+function executionResponse(execution) {
+    const sdkReceipt = execution.receipt;
+    const unsignedReceipt = snapshotMcpObject({
+        kind: MCP_NL_MAP_RECEIPT_KIND,
+        version: NL_MAP_CONTROL_VERSION,
+        planId: execution.planId,
+        planFingerprint: execution.planFingerprint,
+        mode: execution.mode,
+        outcome: execution.outcome,
+        ...(sdkReceipt.approvalDigest ? { approvalDigest: sdkReceipt.approvalDigest } : {}),
+        startedAt: sdkReceipt.startedAt,
+        completedAt: sdkReceipt.completedAt,
+        steps: sdkReceipt.steps,
+        sdkReceiptDigest: sdkReceipt.receiptDigest,
+    }, "MCP execution receipt", "unsafe-output");
+    assertMcpSafeJson(unsignedReceipt, "MCP execution receipt");
+    const receiptDigest = sha256(canonicalStringify(toJsonValue(unsignedReceipt)));
+    const receipt = snapshotMcpObject({
+        ...unsignedReceipt,
+        id: `mcpreceipt_${receiptDigest.slice("sha256:".length, "sha256:".length + 16)}`,
+        receiptDigest,
+    }, "MCP execution receipt", "unsafe-output");
+    const response = snapshotMcpObject({
+        planId: execution.planId,
+        planFingerprint: execution.planFingerprint,
+        mode: execution.mode,
+        outcome: execution.outcome,
+        receipt,
+    }, "MCP execution response", "unsafe-output");
+    assertMcpSafeJson(response, "MCP execution response");
+    return response;
+}
+function successResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value) }],
+    };
+}
+function errorResult(error, signal) {
+    const code = signal.aborted ? "cancelled" : safeErrorCode(error);
+    const message = safeErrorMessage(code);
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify({ error: { code, message } }) }],
+    };
+}
+function safeErrorCode(error) {
+    try {
+        if (error && typeof error === "object") {
+            const descriptor = Reflect.getOwnPropertyDescriptor(error, "code");
+            const code = descriptor && "value" in descriptor ? descriptor.value : undefined;
+            if (typeof code === "string" && PUBLIC_ERROR_CODES.has(code))
+                return code;
+        }
+    }
+    catch {
+        return "execution-refused";
+    }
+    return "execution-refused";
+}
+function safeErrorMessage(code) {
+    switch (code) {
+        case "cancelled":
+        case "aborted":
+            return "The map-plan request was cancelled before execution.";
+        case "authorization-scope-denied":
+            return "The authenticated MCP scopes do not authorize this map plan.";
+        case "approval-required":
+            return "This map plan requires a signed approval envelope.";
+        case "approval-expired":
+            return "The map-plan approval has expired.";
+        case "policy-denied":
+            return "The map-plan approval was denied or has already been used.";
+        case "signature-invalid":
+        case "integrity-failed":
+        case "context-mismatch":
+        case "approval-invalid":
+            return "The map-plan approval could not be verified.";
+        case "plan-invalid":
+        case "plan-required":
+        case "invalid-input":
+            return "The supplied map plan or approval is invalid.";
+        case "unsafe-output":
+            return "The plan was refused because its output would expose sensitive material.";
+        default:
+            return "The map-plan request was refused safely.";
+    }
+}
+function redactForMcp(value, key) {
+    if (key && SENSITIVE_KEYS.has(normalizeKey(key)))
+        return "[REDACTED]";
+    if (typeof value === "string")
+        return redactText(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactForMcp(item));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, redactForMcp(child, name)]));
+    }
+    return value;
+}
+function normalizeKey(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+}
+function hasControlCharacters(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+function redactText(value) {
+    return value
+        .replace(URL_TEXT, "[REDACTED_URL]")
+        .replace(CREDENTIAL_TEXT, "[REDACTED]")
+        .replace(CURSOR_TEXT, "[REDACTED]");
+}

package/dist/src/provenance.d.ts

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

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

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

package/dist/src/provenance.js

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

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

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

package/dist/src/resources/styles.js

@@ -1,4 +1,7 @@
-import { listStyles, resolveStyleRef } from "../styles.js";
+import { CapabilityUnavailableError, capabilityUnavailablePayload } from "../capability.js";
+import { STYLE_SURFACE, listStyles, resolveStyleRef } from "../styles.js";
+const STYLE_GUIDANCE = "This target is a plain FeatureServer/OGC endpoint with no OGC API - Styles surface. " +
+    "Build a MapLibre style client-side, or point honua-mcp at a Honua deployment for managed styles.";
 /** URI for the styles catalog resource (`honua://styles`). */
 export const uri = "honua://styles";
 /** URI template for a single style resource (`honua://styles/{styleId}`). */
@@ -8,7 +11,16 @@ export const uriTemplate = "honua://styles/{styleId}";
  * with its stable styleId, title, and canonical URI (`honua://styles/{id}`).
  */
 export async function readCatalog(client) {
-    const list = await listStyles(client);
+    let list;
+    try {
+        list = await listStyles(client);
+    }
+    catch (err) {
+        if (err instanceof CapabilityUnavailableError) {
+            return unavailableContents(uri, err.reason);
+        }
+        throw err;
+    }
     const styles = list.styles.map((entry) => ({
         styleId: entry.id,
         title: entry.title ?? entry.id,
@@ -24,13 +36,34 @@ export async function readCatalog(client) {
         ],
     };
 }
+/** Structured "not available on this target" resource body (platform-free mode). */
+function unavailableContents(resourceUri, reason) {
+    return {
+        contents: [
+            {
+                uri: resourceUri,
+                mimeType: "application/json",
+                text: JSON.stringify(capabilityUnavailablePayload(STYLE_SURFACE, reason, STYLE_GUIDANCE), null, 2),
+            },
+        ],
+    };
+}
 /**
  * Read a single style as a `StyleRef` projection (style_id / title /
  * description / style_version / encodings / legend_url), resolved against the
  * server's `/ogc/styles/{styleId}` surface.
  */
 export async function read(client, styleId) {
-    const styleRef = await resolveStyleRef(client, styleId);
+    let styleRef;
+    try {
+        styleRef = await resolveStyleRef(client, styleId);
+    }
+    catch (err) {
+        if (err instanceof CapabilityUnavailableError) {
+            return unavailableContents(`honua://styles/${encodeURIComponent(styleId)}`, err.reason);
+        }
+        throw err;
+    }
     return {
         contents: [
             {

package/dist/src/stable-json.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue } from "@honua/sdk-js/query-planner";
+/** Stable boundary error whose message never includes a reflected value or trap error. */
+export declare class McpJsonSnapshotError extends Error {
+    constructor(message: string);
+}
+/**
+ * Detach untrusted JSON without invoking property getters.
+ *
+ * The clone is deeply frozen and bounded before any asynchronous authorization
+ * callback can observe it. Reflection failures (including Proxy traps) collapse
+ * to one stable error instead of reflecting attacker-controlled messages.
+ */
+export declare function snapshotMcpJson(input: unknown, label: string): JsonValue;
+//# sourceMappingURL=stable-json.d.ts.map

package/dist/src/stable-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-json.d.ts","sourceRoot":"","sources":["../../src/stable-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAe7D,0FAA0F;AAC1F,qBAAa,oBAAqB,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAKnC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAOxE"}