@honua/mcp-server 0.1.0-beta.0 → 0.1.1-beta.0

package/README.md

@@ -75,6 +75,48 @@ All read-only:
 - `honua_explain_capability_gap`
 - `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer
 
+Hosts that use signed safe-agent plans can import
+`@honua/mcp-server/agent-execution`. Its `createReadOnlyMcpAgentExecutor` binds
+one named read tool to `@honua/sdk-js/agent-safety`'s exact approved-operation,
+durable-audit, and signed-receipt path. It never enables wildcard dispatch or
+mutation on the standalone server. The descriptor requires a bounded exact name
+and a deterministic `countRows(result)` callback; missing or invalid row counts
+fail instead of being reported as zero.
+
+### Optional natural-language map-plan tools
+
+Embedded hosts with a map runtime, BYO-LLM callback, approval verifier, and
+atomic approval-use store can opt into two additional tools:
+
+- `proposeMapPlan` — compiles an instruction into an inspectable, content-addressed plan and never executes it.
+- `executeMapPlan` — accepts that plan plus a signed approval envelope and executes only after scope, signature,
+  expiry, single-use, cancellation, and plan-identity checks. The envelope is required for effects and for every
+  read step that names a `sourceId`; only non-source inspection may use read-only auto-execution.
+
+```ts
+import { createNlMapControlMcpHost, createServer } from "@honua/mcp-server";
+
+const nlMapControl = createNlMapControlMcpHost({
+  control: {
+    tools: { runtime },
+    llm: callYourModel,
+    approvalVerifier,
+    receiptSigner,
+  },
+  approvalUseConsumer, // host-owned atomic consume + verify callbacks
+  resolveAuthorizationScopes: (transportScopes) => transportScopes,
+});
+
+const server = createServer(honuaClient, { nlMapControl });
+```
+
+The callbacks are deliberately not inferred from environment variables: model
+transport, map authority, signing keys, and replay storage remain host-owned.
+The MCP response omits raw tool results and the original instruction from its
+execution receipt. Plans containing credential, cursor, or endpoint material
+are refused instead of returning a redacted plan that could no longer match its
+approval fingerprint.
+
 ## MCP Resources
 
 - `honua://services`
@@ -112,9 +154,16 @@ npm run certify
 
 # CI entry points (also runnable locally):
 npm run test:certification            # gate: runs harness tests + certifier, exits non-zero on failure
+npm run test:certification:nl-map-control # gate: approval/scope/replay/cancellation/receipt security matrix
 npm run test:certification:artifact   # evidence: writes artifacts, always exits 0
 ```
 
+The certification test lane also hosts the optional NL tools over an in-memory
+MCP transport with a deterministic fixture completion and mock map runtime. It proves
+propose→approve→execute plus missing, expired, replayed, wrong-scope, tampered,
+cancelled, deterministic-receipt, and redaction cases without a model, API key,
+network service, or wall-clock dependency.
+
 ### Platform-free certification lane
 
 A dedicated **standalone** target (`HONUA_MCP_CERT_TARGET=standalone`, or

package/dist/src/agent-execution.d.ts

@@ -0,0 +1,16 @@
+import type { AgentOperationExecutorV1 } from "@honua/sdk-js/agent-safety";
+import type { JsonValue } from "@honua/sdk-js/query-planner";
+/** A named, read-only MCP tool handler adapted to the SDK approval boundary. */
+export interface ReadOnlyMcpAgentTool<TArguments> {
+    readonly name: string;
+    parse(parameters: JsonValue): TArguments;
+    execute(arguments_: TArguments, signal?: AbortSignal): Promise<unknown>;
+    /** Deterministically count logical rows/records in the returned MCP result. */
+    countRows(result: unknown): number;
+}
+/**
+ * Adapt a standalone MCP read tool without introducing a second approval or
+ * audit model. The SDK validates the exact tool/effect before this handler runs.
+ */
+export declare function createReadOnlyMcpAgentExecutor<TArguments>(tool: ReadOnlyMcpAgentTool<TArguments>): AgentOperationExecutorV1;
+//# sourceMappingURL=agent-execution.d.ts.map

package/dist/src/agent-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution.d.ts","sourceRoot":"","sources":["../../src/agent-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAE7D,gFAAgF;AAChF,MAAM,WAAW,oBAAoB,CAAC,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,UAAU,EAAE,SAAS,GAAG,UAAU,CAAC;IACzC,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,+EAA+E;IAC/E,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EACvD,IAAI,EAAE,oBAAoB,CAAC,UAAU,CAAC,GACrC,wBAAwB,CA0B1B"}

package/dist/src/agent-execution.js

@@ -0,0 +1,46 @@
+/**
+ * Adapt a standalone MCP read tool without introducing a second approval or
+ * audit model. The SDK validates the exact tool/effect before this handler runs.
+ */
+export function createReadOnlyMcpAgentExecutor(tool) {
+    if (!tool || typeof tool !== "object")
+        throw new TypeError("MCP tool descriptor is required");
+    const name = dataProperty(tool, "name");
+    if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/.test(name))
+        throw new TypeError("MCP tool name must be a bounded exact identifier");
+    const parse = callback(tool, "parse");
+    const execute = callback(tool, "execute");
+    const countRows = callback(tool, "countRows");
+    return Object.freeze({
+        tool: name,
+        effect: "read",
+        async execute(operation, _limits, signal) {
+            if (operation.tool !== name || operation.effect !== "read")
+                throw new TypeError("approved operation does not match the read-only MCP tool");
+            const arguments_ = parse(operation.parameters);
+            const result = await execute(arguments_, signal);
+            const rows = countRows(result);
+            if (!Number.isSafeInteger(rows) || rows < 0)
+                throw new TypeError("MCP tool row count must be a non-negative safe integer");
+            return { rows, value: result };
+        },
+    });
+}
+function dataProperty(input, key) {
+    let descriptor;
+    try {
+        descriptor = Reflect.getOwnPropertyDescriptor(input, key);
+    }
+    catch {
+        throw new TypeError(`MCP tool ${key} could not be safely captured`);
+    }
+    if (!descriptor || descriptor.get || descriptor.set)
+        throw new TypeError(`MCP tool ${key} must be a data property`);
+    return descriptor.value;
+}
+function callback(input, key) {
+    const value = dataProperty(input, key);
+    if (typeof value !== "function")
+        throw new TypeError(`MCP tool ${key} callback is required`);
+    return value.bind(input);
+}

package/dist/src/certification/census-fixture-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"census-fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/census-fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAML,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AA4F1B,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,CAOjE;AAyFD,qFAAqF;AACrF,wBAAgB,6BAA6B,IAAI,WAAW,CAiE3D"}
+{"version":3,"file":"census-fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/census-fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAOjD,OAAO,EAML,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AA4F1B,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,CAOjE;AAyFD,qFAAqF;AACrF,wBAAgB,6BAA6B,IAAI,WAAW,CAiE3D"}

package/dist/src/certification/fixture-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,eAAe,CAAC;AAsDvB,mFAAmF;AACnF,wBAAgB,mBAAmB,IAAI,WAAW,CAkEjD"}
+{"version":3,"file":"fixture-client.d.ts","sourceRoot":"","sources":["../../../src/certification/fixture-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AA4DjD,mFAAmF;AACnF,wBAAgB,mBAAmB,IAAI,WAAW,CAkEjD"}

package/dist/src/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { EsriGeometryType, EsriSpatialRel } from "@honua/sdk-js";
+import type { EsriGeometryType, EsriSpatialRel } from "@honua/sdk-js/honua";
 export declare const GEOMETRY_TYPES: readonly ["esriGeometryPoint", "esriGeometryPolyline", "esriGeometryPolygon", "esriGeometryEnvelope", "esriGeometryMultipoint"];
 export declare function mapSpatialRel(rel: string | undefined): EsriSpatialRel | undefined;
 export declare function clampLimit(limit: number | undefined): number;

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

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMtE,eAAO,MAAM,cAAc,iIAMjB,CAAC;AAQX,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAKjF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,gBAAgB,GAAG,SAAS,CA8B9B;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAE5F;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM5E,eAAO,MAAM,cAAc,iIAMjB,CAAC;AAQX,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAKjF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,YAAY,EAAE,gBAAgB,GAAG,SAAS,GACzC,gBAAgB,GAAG,SAAS,CA8B9B;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAE5F;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}

package/dist/src/index.d.ts

@@ -2,6 +2,9 @@
 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";
+export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
+export type { CreateNlMapControlMcpHostOptions, McpNlMapExecutionResponse, McpNlMapPlanResponse, McpNlMapReceipt, NlMapControlMcpHost, NlMapControlMcpRequestContext, } from "./nl-map-control.js";
 export interface RuntimeOptions {
     baseUrl: string;
     apiKey: string | undefined;
@@ -9,6 +12,10 @@ export interface RuntimeOptions {
     timeoutMs: number;
     retryMaxRetries: number;
 }
+export interface CreateServerOptions {
+    /** Optional BYO-LLM/map-runtime host for the experimental NL map-plan tools. */
+    readonly nlMapControl?: NlMapControlMcpHost;
+}
 export declare const SERVER_VERSION: string;
 export declare function resolveRuntimeOptions(env: NodeJS.ProcessEnv): RuntimeOptions;
 export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClient;
@@ -33,7 +40,7 @@ export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): HonuaClien
  * 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.
  */
-export declare function createServer(client: HonuaClient): McpServer;
+export declare function createServer(client: HonuaClient, options?: CreateServerOptions): McpServer;
 /**
  * Run the platform-free standalone server end-to-end over stdio.
  *

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;AAgBtF,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;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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,aAyF/C;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":";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;AAc7F,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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,aA6FlF;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF"}

package/dist/src/index.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { HonuaClient } from "@honua/sdk-js";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerNlMapControlMcpTools } from "./nl-map-control.js";
 import * as layerSchemaResource from "./resources/layer-schema.js";
 import * as servicesResource from "./resources/services.js";
 import * as stylesResource from "./resources/styles.js";
@@ -16,6 +17,7 @@ import * as getStyle from "./tools/get-style.js";
 import * as listServices from "./tools/list-services.js";
 import * as queryFeatures from "./tools/query-features.js";
 import * as statistics from "./tools/statistics.js";
+export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_SERVER_VERSION = "0.0.3-alpha.0";
@@ -137,13 +139,16 @@ export function createClientFromEnv(env = process.env) {
  * 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.
  */
-export function createServer(client) {
+export function createServer(client, options = {}) {
     const server = new McpServer({
         name: "honua",
         version: SERVER_VERSION,
     });
     // ── Tools ──────────────────────────────────────────────────────
     server.tool("honua_list_services", "Discover all available feature services on any FeatureServer folder. Set includeDetails=true for descriptions, layer counts, and spatial references. Degrades gracefully when the target has no service catalog.", listServices.schema.shape, async (args) => listServices.execute(client, listServices.schema.parse(args)));
+    if (options.nlMapControl) {
+        registerNlMapControlMcpTools(server, options.nlMapControl);
+    }
     server.tool("honua_describe_layer", "Get full schema for a layer — fields, geometry type, extent, relationships.", describeLayer.schema.shape, async (args) => describeLayer.execute(client, describeLayer.schema.parse(args)));
     server.tool("honua_query_features", "Query features with attribute filters, spatial filters, field selection, and pagination. returnGeometry defaults to false to save tokens.", queryFeatures.schema.shape, async (args) => queryFeatures.execute(client, queryFeatures.schema.parse(args)));
     server.tool("honua_count_features", "Count features matching a filter without returning data. Use before querying to check cardinality.", countFeatures.schema.shape, async (args) => countFeatures.execute(client, countFeatures.schema.parse(args)));

package/dist/src/nl-map-control.d.ts

@@ -0,0 +1,70 @@
+import { type AgentApprovalUseConsumer } from "@honua/sdk-js/agent-safety";
+import { type CreateNlMapControlOptions, NL_MAP_CONTROL_VERSION, type NlMapControl, type NlMapPlan, type NlMapPlanExecution } from "@honua/sdk-js/nl-map-control";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+declare const MCP_NL_MAP_RECEIPT_KIND: "honua.mcp-nl-map-receipt";
+export interface NlMapControlMcpRequestContext {
+    readonly signal?: AbortSignal;
+    /** Scopes authenticated by the MCP transport. Caller arguments never populate this field. */
+    readonly transportAuthorizationScopes?: readonly string[];
+}
+export interface CreateNlMapControlMcpHostOptions {
+    /** The identical controller configuration used by the in-app NL surface. */
+    readonly control: CreateNlMapControlOptions;
+    /** Atomic, host-authenticated approval-use store. Required for every approved MCP execution. */
+    readonly approvalUseConsumer: AgentApprovalUseConsumer;
+    /**
+     * Resolve trusted scopes for transports without MCP `authInfo` (for example an
+     * embedded stdio host). The input contains transport-authenticated scopes only.
+     */
+    readonly resolveAuthorizationScopes?: (transportScopes: readonly string[]) => readonly string[] | Promise<readonly string[]>;
+}
+export interface McpNlMapPlanResponse {
+    readonly plan: NlMapPlan;
+    readonly approvalRequired: boolean;
+}
+export interface McpNlMapReceipt {
+    readonly kind: typeof MCP_NL_MAP_RECEIPT_KIND;
+    readonly version: typeof NL_MAP_CONTROL_VERSION;
+    readonly id: string;
+    readonly planId: string;
+    readonly planFingerprint: `sha256:${string}`;
+    readonly mode: NlMapPlanExecution["mode"];
+    readonly outcome: NlMapPlanExecution["outcome"];
+    readonly approvalDigest?: `sha256:${string}`;
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly steps: NlMapPlanExecution["receipt"]["steps"];
+    /** Digest of the SDK receipt retained by the host. Its raw instruction is never returned over MCP. */
+    readonly sdkReceiptDigest: `sha256:${string}`;
+    readonly receiptDigest: `sha256:${string}`;
+}
+export interface McpNlMapExecutionResponse {
+    readonly planId: string;
+    readonly planFingerprint: `sha256:${string}`;
+    readonly mode: NlMapPlanExecution["mode"];
+    readonly outcome: NlMapPlanExecution["outcome"];
+    readonly receipt: McpNlMapReceipt;
+}
+export interface NlMapControlMcpHost {
+    readonly control: NlMapControl;
+    propose(input: {
+        readonly instruction: string;
+    }, context?: NlMapControlMcpRequestContext): Promise<McpNlMapPlanResponse>;
+    execute(input: {
+        readonly plan: unknown;
+        readonly approval?: unknown;
+    }, context?: NlMapControlMcpRequestContext): Promise<McpNlMapExecutionResponse>;
+}
+/**
+ * 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 declare function createNlMapControlMcpHost(options: CreateNlMapControlMcpHostOptions): NlMapControlMcpHost;
+/** Register `proposeMapPlan` and `executeMapPlan` on a real MCP server. */
+export declare function registerNlMapControlMcpTools(server: McpServer, host: NlMapControlMcpHost): void;
+export {};
+//# sourceMappingURL=nl-map-control.d.ts.map

package/dist/src/nl-map-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nl-map-control.d.ts","sourceRoot":"","sources":["../../src/nl-map-control.ts"],"names":[],"mappings":"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"}

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/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"}

package/dist/src/stable-json.js

@@ -0,0 +1,126 @@
+const MAX_NODES = 8_192;
+const MAX_DEPTH = 32;
+const MAX_BYTES = 1_048_576;
+const MAX_OBJECT_PROPERTIES = 128;
+const MAX_ARRAY_LENGTH = 1_024;
+const MAX_STRING_CODE_UNITS = 65_536;
+const SNAPSHOT_ERRORS = new WeakSet();
+/** Stable boundary error whose message never includes a reflected value or trap error. */
+export class McpJsonSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpJsonSnapshotError";
+        SNAPSHOT_ERRORS.add(this);
+    }
+}
+/**
+ * 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 function snapshotMcpJson(input, label) {
+    try {
+        return snapshot(input, 0, new WeakSet(), { nodes: 0, bytes: 0 });
+    }
+    catch (error) {
+        if (error !== null && typeof error === "object" && SNAPSHOT_ERRORS.has(error))
+            throw error;
+        throw new McpJsonSnapshotError(`${label} could not be safely snapshotted`);
+    }
+}
+function snapshot(value, depth, ancestors, budget) {
+    budget.nodes += 1;
+    if (budget.nodes > MAX_NODES)
+        invalid("MCP JSON exceeds the node limit");
+    if (depth > MAX_DEPTH)
+        invalid("MCP JSON exceeds the depth limit");
+    addBytes(budget, 8);
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        if (value.length > MAX_STRING_CODE_UNITS)
+            invalid("MCP JSON contains an oversized string");
+        addBytes(budget, utf8Bytes(value));
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            invalid("MCP JSON contains a non-finite number");
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== "object")
+        invalid("MCP JSON contains an unsupported value");
+    if (ancestors.has(value))
+        invalid("MCP JSON must not contain cycles");
+    ancestors.add(value);
+    const result = Array.isArray(value)
+        ? snapshotArray(value, depth, ancestors, budget)
+        : snapshotObject(value, depth, ancestors, budget);
+    ancestors.delete(value);
+    return result;
+}
+function snapshotArray(input, depth, ancestors, budget) {
+    if (Object.getPrototypeOf(input) !== Array.prototype)
+        invalid("MCP JSON arrays must use the standard prototype");
+    const lengthDescriptor = Reflect.getOwnPropertyDescriptor(input, "length");
+    const length = lengthDescriptor && "value" in lengthDescriptor ? lengthDescriptor.value : undefined;
+    if (!Number.isSafeInteger(length) || length < 0 || length > MAX_ARRAY_LENGTH) {
+        invalid("MCP JSON contains an invalid or oversized array");
+    }
+    const keys = Reflect.ownKeys(input);
+    if (keys.some((key) => typeof key !== "string"))
+        invalid("MCP JSON must not contain symbol keys");
+    if (keys.length !== length + 1 || !keys.includes("length")) {
+        invalid("MCP JSON arrays must be dense and must not contain extra properties");
+    }
+    const output = [];
+    for (let index = 0; index < length; index += 1) {
+        const descriptor = Reflect.getOwnPropertyDescriptor(input, String(index));
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+            invalid("MCP JSON arrays must contain enumerable data properties");
+        }
+        output.push(snapshot(descriptor.value, depth + 1, ancestors, budget));
+    }
+    return Object.freeze(output);
+}
+function snapshotObject(input, depth, ancestors, budget) {
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid("MCP JSON values must be plain objects");
+    const keys = Reflect.ownKeys(input);
+    if (keys.length > MAX_OBJECT_PROPERTIES)
+        invalid("MCP JSON object exceeds the property limit");
+    if (keys.some((key) => typeof key !== "string"))
+        invalid("MCP JSON must not contain symbol keys");
+    const output = Object.create(null);
+    for (const key of keys.sort()) {
+        if (key.length > MAX_STRING_CODE_UNITS)
+            invalid("MCP JSON contains an oversized property name");
+        addBytes(budget, utf8Bytes(key));
+        const descriptor = Reflect.getOwnPropertyDescriptor(input, key);
+        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+            invalid("MCP JSON objects must contain enumerable data properties");
+        }
+        Object.defineProperty(output, key, {
+            value: snapshot(descriptor.value, depth + 1, ancestors, budget),
+            enumerable: true,
+            writable: false,
+            configurable: false,
+        });
+    }
+    return Object.freeze(output);
+}
+function addBytes(budget, increment) {
+    const next = budget.bytes + increment;
+    if (!Number.isSafeInteger(next) || next > MAX_BYTES)
+        invalid("MCP JSON exceeds the byte limit");
+    budget.bytes = next;
+}
+function utf8Bytes(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function invalid(message) {
+    throw new McpJsonSnapshotError(message);
+}

package/dist/src/tools/explain-capability-gap.d.ts

@@ -1,4 +1,4 @@
-import { type Capability, type Protocol } from "@honua/sdk-js";
+import type { Capability, Protocol } from "@honua/sdk-js";
 import { z } from "zod";
 export declare const schema: z.ZodObject<{
     capability: z.ZodEffects<z.ZodString, Capability, string>;
@@ -7,13 +7,13 @@ export declare const schema: z.ZodObject<{
     declaredCapabilities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, Capability, string>, "many">>;
 }, "strip", z.ZodTypeAny, {
     capability: Capability;
-    protocol?: Protocol | undefined;
     sourceId?: string | undefined;
+    protocol?: Protocol | undefined;
     declaredCapabilities?: Capability[] | undefined;
 }, {
     capability: string;
-    protocol?: string | undefined;
     sourceId?: string | undefined;
+    protocol?: string | undefined;
     declaredCapabilities?: string[] | undefined;
 }>;
 export type Input = z.infer<typeof schema>;

package/dist/src/tools/explain-capability-gap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain-capability-gap.d.ts","sourceRoot":"","sources":["../../../src/tools/explain-capability-gap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAa,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAExF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;EAKjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;;;;;GAI3D"}
+{"version":3,"file":"explain-capability-gap.d.ts","sourceRoot":"","sources":["../../../src/tools/explain-capability-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;EAKjB,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE3C,wBAAsB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK;;;;;GAI3D"}

package/dist/src/tools/explain-capability-gap.js

@@ -1,5 +1,5 @@
-import { CAPABILITIES, PROTOCOLS } from "@honua/sdk-js";
 import { explainHonuaCapabilityGap } from "@honua/sdk-js/agent-tools";
+import { CAPABILITIES, PROTOCOLS } from "@honua/sdk-js/contract";
 import { z } from "zod";
 import { jsonText } from "../helpers.js";
 const capabilitySchema = z.string().refine((value) => CAPABILITIES.includes(value), {

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "@honua/mcp-server",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.1-beta.0",
   "description": "MCP server for Honua geospatial feature services",
   "type": "module",
   "bin": {
     "honua-mcp": "dist/src/index.js",
     "honua-mcp-proxy": "dist/src/proxy.js"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./agent-execution": {
+      "types": "./dist/src/agent-execution.d.ts",
+      "default": "./dist/src/agent-execution.js"
+    },
+    "./nl-map-control": {
+      "types": "./dist/src/nl-map-control.d.ts",
+      "default": "./dist/src/nl-map-control.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "clean": "rm -rf dist coverage",
     "build": "npm run clean --silent && tsc -p tsconfig.json",
@@ -17,6 +32,7 @@
     "test:coverage": "vitest run --coverage",
     "certify": "npm run build --silent && node dist/src/certification/cli.js",
     "certify:standalone": "npm run build --silent && node dist/src/certification/cli.js --target standalone",
+    "test:certification:nl-map-control": "vitest run test/certification/nl-map-control.test.ts",
     "test:certification": "npm run build --silent && vitest run test/certification && node dist/src/certification/cli.js",
     "test:certification:artifact": "npm run build --silent && node dist/src/certification/cli.js --artifact-only",
     "test:certification:standalone": "npm run build --silent && node dist/src/certification/cli.js --target standalone",
@@ -44,7 +60,7 @@
     "hono": "^4.12.21"
   },
   "peerDependencies": {
-    "@honua/sdk-js": "^0.1.0-beta.0"
+    "@honua/sdk-js": "^0.1.1-beta.0"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",