@honua/mcp-server 0.1.12 → 0.1.13

package/README.md

@@ -256,9 +256,34 @@ atomic approval-use store can opt into two additional tools:
   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
+Embedding the server in your own Node.js host needs the packages as local
+dependencies of that host project:
+
+```bash
+npm install @honua/mcp-server @honua/sdk-js
+```
+
+The map runtime, model callback, approval verifier, receipt signer, and
+approval-use store are yours to supply; the `declare const` lines stand in for them:
+
+```ts doc-test=compile
+import { HonuaClient } from "@honua/sdk-js";
+import type {
+  AgentApprovalUseConsumer,
+  AgentEnvelopeSigner,
+  AgentEnvelopeVerifier,
+} from "@honua/sdk-js/agent-safety";
+import type { CreateNlMapControlOptions, NlMapControlToolsOptions } from "@honua/sdk-js/nl-map-control";
 import { createNlMapControlMcpHost, createServer } from "@honua/mcp-server";
 
+declare const runtime: NlMapControlToolsOptions["runtime"];
+declare const callYourModel: CreateNlMapControlOptions["llm"];
+declare const approvalVerifier: AgentEnvelopeVerifier;
+declare const receiptSigner: AgentEnvelopeSigner;
+declare const approvalUseConsumer: AgentApprovalUseConsumer;
+
+const honuaClient = new HonuaClient({ baseUrl: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" });
+
 const nlMapControl = createNlMapControlMcpHost({
   control: {
     tools: { runtime },
@@ -311,6 +336,24 @@ For each tool the server advertises (over an in-memory MCP transport) it:
 It emits a stable machine-readable JSON report plus a human-readable Markdown
 summary, and exits non-zero on any conformance/round-trip failure.
 
+The certification and eval scripts in this section and the next run from a clone
+of this repository (Node.js `>=20.19` and git). `mcp/` links to the SDK at the
+repository root, so build the SDK first:
+
+```bash
+git clone --depth 1 https://github.com/honua-io/honua-sdk-js.git
+cd honua-sdk-js
+npm ci
+```
+
+```bash
+npm run build   # the SDK that mcp/ links to; takes a few minutes
+cd mcp
+npm ci
+```
+
+From `mcp/`:
+
 ```bash
 # Run the certifier against the offline fixture backend and write artifacts:
 npm run certify
@@ -336,9 +379,13 @@ apportionment layer from `services.arcgis.com`, with **no** Honua surfaces. It
 proves the tools certify **green with honest skips** against a non-Honua endpoint:
 the data tools round-trip against real recorded data, the Honua-only style tools
 degrade to structured "not available" results, and the auth/mutation/job contracts
-skip-with-reason. Fixture-backed and deterministic — no network.
+skip-with-reason. Fixture-backed and deterministic — no network — as long as
+`HONUA_BASE_URL` is unset: when it is set, this lane certifies that live endpoint
+instead (the scheduled live variant). Unset it if you exported it for `honua-mcp`
+above:
 
 ```bash
+unset HONUA_BASE_URL
 npm run certify:standalone            # platform-free cert (plain FeatureServer fixture)
 npm run test:certification:standalone # CI gate variant
 ```
@@ -390,8 +437,8 @@ The honua server exposes one MCP catalog over streamable-HTTP/SSE at `/mcp`.
 Claude-Desktop-style clients speak **stdio**. Rather than reimplement that
 catalog (which is how the HTTP and stdio surfaces historically drifted apart),
 this package ships a **stdio proxy** (`honua-mcp-proxy`) that bridges a local
-stdio MCP client to the remote HTTP-SSE MCP server. It connects upstream as an
-MCP client and re-exposes the *same* catalog downstream over stdio — identical
+stdio MCP client to the remote HTTP-SSE MCP server. It forwards MCP messages
+between the transports and exposes the *same* catalog downstream over stdio — identical
 tools, identical input/output schemas, identical resources and prompts, and live
 `tools/list_changed` notifications. There is one source-of-truth catalog (the
 server's `/mcp`); the SDK proxies it, so the two transports are symmetric by
@@ -417,8 +464,33 @@ or `[::1]` HTTP development endpoints. Userinfo, query parameters, fragments,
 non-HTTP(S) URLs are rejected before connect, and redirect targets are never
 followed or sent credentials.
 
-A parity test (`test/proxy.test.ts`) asserts the tool/resource/template catalog
-the downstream client sees is byte-identical to the upstream surface, that
+The proxy forwards the caller's `initialize` request before opening an initialized
+upstream session, including `_meta["honua.io/workflow-view"]`. That HTTP session
+is retained for subsequent requests, so initializing with `setup` makes a later
+selector-free `tools/list` return the server's setup catalog. A temporary
+per-request catalog override leaves the initialized view intact; separate proxy
+processes have separate sessions.
+
+The view selector is the only `initialize` metadata the server reads, and the
+only metadata the proxy forwards: other `_meta` keys stay local rather than
+entering the credentialed upstream session. The handshake fails closed. A
+request before `initialize`, an `initialize` the server's selector contract
+would refuse (a non-string or longer-than-64-character view), or a second
+`initialize` is answered with JSON-RPC `-32600` without reaching the server,
+and the proxy exits. If `initialize` does not arrive, or the server does not
+answer it, within 30 seconds, the proxy exits as well.
+
+Executable protocol tests (`test/proxy-session.test.ts`) exercise setup/default
+initialization, concurrent sessions, authenticated full-catalog override and
+restoration, `tools/list_changed` relay, and the fail-closed handshake against a
+loopback fixture. The `MCP session contract` workflow also runs them against the
+`honua-mcp-proxy` executable npm installs from the packed tarballs. The
+published 0.1.12 reproduction and exact JSON wire captures are under
+`test/fixtures/initialize-view/`.
+
+A parity test (`test/proxy.test.ts`) runs the same bridge against the canonical
+server over streamable HTTP. It asserts the tool/resource/template catalog the
+downstream client sees is byte-identical to a direct HTTP client's, that
 `tools/call` and resource reads round-trip identically, and that `list_changed`
 notifications are forwarded.
 
@@ -527,6 +599,12 @@ Shared env for every live run:
 Set exactly one of `HONUA_MCP_AUTH_TOKEN` or `HONUA_API_KEY` for authenticated
 live runs; ambiguous authentication fails closed.
 
+The commands below read three values you supply from your own accounts: `HONUA_TOKEN`
+(a bearer token your operator deployment issued), and the model provider's
+`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (the Bedrock driver uses the AWS credential
+chain instead). Export the ones your driver needs before you run it, and run from `mcp/`:
+
+<!-- doc-run: skip reason="billable live-model lane: needs the reader's own operator token and Anthropic, OpenAI or AWS model credentials; the offline control above (npm run eval:offline) is the runnable lane" -->
 ```bash
 # Anthropic Claude (default claude-opus-4-8; override with HONUA_EVAL_ANTHROPIC_MODEL):
 HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \

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

@@ -4,7 +4,7 @@ import { ADMIN_MCP_CONTRACT_SERVER_SHA, ADMIN_MCP_COVERAGE_SHA256, ADMIN_MCP_EXC
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { isMainEntrypoint } from "../entrypoint.js";
-import { connectUpstream, createProxyServer, resolveProxyOptions } from "../proxy.js";
+import { connectProxyTransport, connectUpstream, resolveProxyOptions } from "../proxy.js";
 const DEFAULT_EXPECTATION = {
     publishedToolNames: ADMIN_MCP_PUBLISHED_TOOL_NAMES,
     excludedToolNames: ADMIN_MCP_EXCLUDED_OPERATIONS.map((operation) => operation.toolName),
@@ -202,12 +202,13 @@ export async function runAdminParityCertification(env = process.env, outputPath
     if (ADMIN_MCP_CONTRACT_SERVER_SHA === null) {
         throw new Error("Admin MCP live certification is blocked until config/admin-client.v1.json pins the final server head.");
     }
-    const upstream = await connectUpstream(resolveProxyOptions(env));
-    const proxy = createProxyServer(upstream);
+    const options = resolveProxyOptions(env);
+    const upstream = await connectUpstream(options);
+    // The proxied side runs through the same bridge the stdio executable uses.
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const proxied = new Client({ name: "honua-admin-parity", version: "1.0.0" });
     try {
-        await proxy.connect(serverTransport);
+        await connectProxyTransport(options, serverTransport);
         await proxied.connect(clientTransport);
         const directTools = await listAllTools(upstream);
         const proxiedTools = await listAllTools(proxied);
@@ -219,7 +220,6 @@ export async function runAdminParityCertification(env = process.env, outputPath
     }
     finally {
         await proxied.close().catch(() => { });
-        await proxy.close().catch(() => { });
         await upstream.close().catch(() => { });
     }
 }

package/dist/src/proxy.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type InitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 /**
  * Transport-symmetric stdio proxy for the honua MCP surface (honua-server #1950).
  *
@@ -8,10 +9,12 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
  * `/mcp`. Claude-Desktop-style clients speak stdio. Rather than reimplementing
  * the tool/resource catalog (the older `@honua/mcp-server` discovery surface did
  * exactly that, which is how the two halves drifted apart), this proxy bridges a
- * local stdio MCP client to the remote HTTP-SSE MCP server: it connects upstream
- * as an MCP client, then re-exposes the *same* catalog downstream over stdio.
+ * local stdio MCP client to the remote HTTP-SSE MCP server: each stdio client
+ * gets one upstream streamable-HTTP session, opened by the client's own
+ * initialize, and every later message is relayed over that session.
  *
- * Because every request and notification is forwarded verbatim, the stdio
+ * Because every request and notification is forwarded verbatim (initialize's
+ * `_meta` is narrowed to the workflow-view selector), the stdio
  * surface is transport-symmetric with the HTTP-SSE surface by construction —
  * identical tools, identical input/output schemas, identical resources and
  * prompts, and live `list_changed` notifications. There is one source-of-truth
@@ -28,19 +31,32 @@ export interface ProxyOptions {
 export declare function resolveProxyOptions(env?: NodeJS.ProcessEnv): ProxyOptions;
 /** Build request headers for the upstream connection from the resolved options. */
 export declare function buildUpstreamHeaders(options: ProxyOptions): Record<string, string>;
-/** Connect an upstream MCP client to the remote honua /mcp over streamable HTTP. */
-export declare function connectUpstream(options: ProxyOptions): Promise<Client>;
 /**
- * Build a low-level MCP server that forwards every request and `list_changed`
- * notification to the already-connected upstream client. The proxy advertises
- * exactly the upstream's name, version, and capabilities, so the downstream
- * (stdio) surface mirrors the upstream (HTTP-SSE) surface.
+ * Connect a direct MCP client to the remote honua /mcp over streamable HTTP.
+ * Certification and evals use it as the HTTP reference side; the stdio proxy
+ * does not, because Client.connect would send its own initialize.
  */
-export declare function createProxyServer(upstream: Client): Server;
+export declare function connectUpstream(options: ProxyOptions): Promise<Client>;
+/** The server's only initialize metadata key; the session view selector. */
+export declare const WORKFLOW_VIEW_META_KEY = "honua.io/workflow-view";
+/** Read the optional view selector under the server's own contract. */
+export declare function readWorkflowView(request: InitializeRequest): string | undefined;
+export interface ProxyBridgeOptions {
+    /** Bound on initialize arriving and its upstream response; defaults to 30 s. */
+    initializeTimeoutMs?: number;
+}
 /**
- * Run the stdio proxy end-to-end: resolve the remote `/mcp` from the
- * environment, connect upstream, and expose the mirrored catalog over stdio.
- * Also used by the deprecated `honua-mcp` bin, which now delegates here.
+ * Bridge one downstream transport to one upstream HTTP session. In particular,
+ * forward the caller's initialize instead of letting Client.connect synthesize
+ * an earlier initialize without its metadata. The server owns view selection
+ * and request overrides; the proxy never supplies a tools/list selector.
+ *
+ * The handshake fails closed: traffic before initialize, an initialize the
+ * server's selector contract would refuse, a second initialize, or a handshake
+ * that does not complete within the bound gets a JSON-RPC error (when it has
+ * an id) and closes both transports. Nothing invalid reaches the server.
  */
+export declare function connectProxyTransport(options: ProxyOptions, downstream: Transport, bridge?: ProxyBridgeOptions): Promise<Transport>;
+/** Run the published stdio executable with the caller's initialize intact. */
 export declare function runProxy(env?: NodeJS.ProcessEnv): Promise<void>;
 //# sourceMappingURL=proxy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA0BnE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAsBD,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAqBtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUlF;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+C1D;AAOD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlF"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,EAEL,KAAK,iBAAiB,EAQvB,MAAM,oCAAoC,CAAC;AAK5C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAsBD,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAqBtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUlF;AASD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5E;AAED,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAI/D,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAO/E;AAgBD,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,SAAS,EACrB,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,SAAS,CAAC,CA+FpB;AAED,8EAA8E;AAC9E,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAelF"}

package/dist/src/proxy.js

@@ -1,18 +1,11 @@
 #!/usr/bin/env node
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCode, InitializeRequestSchema, isInitializedNotification, isJSONRPCErrorResponse, isJSONRPCRequest, isJSONRPCResultResponse, } from "@modelcontextprotocol/sdk/types.js";
 import { requireSecureCredentialEndpoint } from "./credential-endpoint.js";
 import { isMainEntrypoint } from "./entrypoint.js";
 import { SERVER_VERSION } from "./index.js";
-// MCP permits server extensions such as Honua's tools/list `view`. The SDK's
-// nested params schema strips unknown keys by default, so preserve them before
-// forwarding or a stdio caller silently receives the default catalog instead.
-const ForwardedListToolsRequestSchema = ListToolsRequestSchema.extend({
-    params: ListToolsRequestSchema.shape.params.unwrap().passthrough().optional(),
-});
 function isConfigured(value) {
     return value !== undefined && value.length > 0;
 }
@@ -58,84 +51,172 @@ export function buildUpstreamHeaders(options) {
     }
     return headers;
 }
-/** Connect an upstream MCP client to the remote honua /mcp over streamable HTTP. */
-export async function connectUpstream(options) {
+function createUpstreamTransport(options) {
     const headers = buildUpstreamHeaders(options);
-    const remoteUrl = validateProxyOptions(options);
-    const transport = new StreamableHTTPClientTransport(remoteUrl, {
+    return new StreamableHTTPClientTransport(validateProxyOptions(options), {
         requestInit: { ...(Object.keys(headers).length > 0 ? { headers } : {}), redirect: "manual" },
     });
+}
+/**
+ * Connect a direct MCP client to the remote honua /mcp over streamable HTTP.
+ * Certification and evals use it as the HTTP reference side; the stdio proxy
+ * does not, because Client.connect would send its own initialize.
+ */
+export async function connectUpstream(options) {
     const client = new Client({ name: "honua-mcp-stdio-proxy", version: SERVER_VERSION });
-    await client.connect(transport);
+    await client.connect(createUpstreamTransport(options));
     return client;
 }
+/** The server's only initialize metadata key; the session view selector. */
+export const WORKFLOW_VIEW_META_KEY = "honua.io/workflow-view";
+const MAX_WORKFLOW_VIEW_LENGTH = 64;
+const INITIALIZE_TIMEOUT_MS = 30_000;
+/** Read the optional view selector under the server's own contract. */
+export function readWorkflowView(request) {
+    const value = request.params._meta?.[WORKFLOW_VIEW_META_KEY];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.length > MAX_WORKFLOW_VIEW_LENGTH) {
+        throw new Error("Invalid workflow view selector");
+    }
+    return value.trim().length === 0 ? undefined : value;
+}
 /**
- * Build a low-level MCP server that forwards every request and `list_changed`
- * notification to the already-connected upstream client. The proxy advertises
- * exactly the upstream's name, version, and capabilities, so the downstream
- * (stdio) surface mirrors the upstream (HTTP-SSE) surface.
+ * Validate the caller's initialize and narrow its `_meta` to the recognised
+ * view selector. Every other field is the caller's own and passes unchanged;
+ * other metadata stays local rather than entering the credentialed session.
  */
-export function createProxyServer(upstream) {
-    const upstreamInfo = upstream.getServerVersion() ?? { name: "honua", version: SERVER_VERSION };
-    const upstreamCapabilities = upstream.getServerCapabilities() ?? {};
-    const server = new Server({ name: upstreamInfo.name, version: upstreamInfo.version }, {
-        capabilities: upstreamCapabilities,
-        instructions: upstream.getInstructions(),
-    });
-    // ── Tools ──────────────────────────────────────────────────────
-    if (upstreamCapabilities.tools) {
-        server.setRequestHandler(ForwardedListToolsRequestSchema, async (request) => upstream.listTools(request.params));
-        server.setRequestHandler(CallToolRequestSchema, async (request) => upstream.callTool(request.params));
-    }
-    // ── Resources ──────────────────────────────────────────────────
-    if (upstreamCapabilities.resources) {
-        server.setRequestHandler(ListResourcesRequestSchema, async (request) => upstream.listResources(request.params));
-        server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) => upstream.listResourceTemplates(request.params));
-        server.setRequestHandler(ReadResourceRequestSchema, async (request) => upstream.readResource(request.params));
-    }
-    // ── Prompts ────────────────────────────────────────────────────
-    if (upstreamCapabilities.prompts) {
-        server.setRequestHandler(ListPromptsRequestSchema, async (request) => upstream.listPrompts(request.params));
-        server.setRequestHandler(GetPromptRequestSchema, async (request) => upstream.getPrompt(request.params));
-    }
-    // ── list_changed notification forwarding ───────────────────────
-    // Keeps the stdio surface live: when the server's catalog changes, the
-    // downstream client is told, exactly as an HTTP-SSE client would be.
-    upstream.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
-        await server.sendToolListChanged();
-    });
-    upstream.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
-        await server.sendResourceListChanged();
-    });
-    upstream.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
-        await server.sendPromptListChanged();
-    });
-    return server;
+function upstreamInitialize(message) {
+    const view = readWorkflowView(InitializeRequestSchema.parse(message));
+    const { _meta: _ignored, ...params } = message.params ?? {};
+    return {
+        ...message,
+        params: { ...params, ...(view === undefined ? {} : { _meta: { [WORKFLOW_VIEW_META_KEY]: view } }) },
+    };
 }
-/* v8 ignore start -- live-process entry: wires the stdio transport to a real
-   remote /mcp upstream; exercised by running the proxy, not by unit tests. The
-   unit-testable logic (option/header resolution, upstream connect, catalog
-   forwarding) lives in the exported functions above and is covered there. */
 /**
- * Run the stdio proxy end-to-end: resolve the remote `/mcp` from the
- * environment, connect upstream, and expose the mirrored catalog over stdio.
- * Also used by the deprecated `honua-mcp` bin, which now delegates here.
+ * Bridge one downstream transport to one upstream HTTP session. In particular,
+ * forward the caller's initialize instead of letting Client.connect synthesize
+ * an earlier initialize without its metadata. The server owns view selection
+ * and request overrides; the proxy never supplies a tools/list selector.
+ *
+ * The handshake fails closed: traffic before initialize, an initialize the
+ * server's selector contract would refuse, a second initialize, or a handshake
+ * that does not complete within the bound gets a JSON-RPC error (when it has
+ * an id) and closes both transports. Nothing invalid reaches the server.
  */
-export async function runProxy(env = process.env) {
-    const options = resolveProxyOptions(env);
-    const upstream = await connectUpstream(options);
-    const server = createProxyServer(upstream);
-    // Tear down both ends together so a dropped upstream surfaces to the client.
+export async function connectProxyTransport(options, downstream, bridge = {}) {
+    const upstream = createUpstreamTransport(options);
+    let closed = false;
+    let refused = false;
+    let initializeSeen = false;
+    let initializeId;
+    let initialized = Promise.resolve();
     const shutdown = async () => {
-        await server.close().catch(() => { });
-        await upstream.close().catch(() => { });
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(handshake);
+        await Promise.all([downstream.close().catch(() => { }), upstream.close().catch(() => { })]);
+    };
+    // Reply before closing so the caller learns why its session ended. The
+    // message is the proxy's own; nothing from upstream is echoed.
+    const refuse = (id, code, reason) => {
+        if (closed || refused)
+            return;
+        refused = true;
+        const reply = id === undefined ? Promise.resolve() : downstream.send({ jsonrpc: "2.0", id, error: { code, message: reason } });
+        void reply.catch(() => { }).finally(() => shutdown());
+    };
+    const handshake = setTimeout(() => refuse(initializeId, ErrorCode.RequestTimeout, "Proxy initialization timed out"), bridge.initializeTimeoutMs ?? INITIALIZE_TIMEOUT_MS);
+    downstream.onclose = upstream.onclose = () => {
+        void shutdown();
     };
-    upstream.onclose = () => {
+    // HTTP/SSE errors can contain credential-bearing response bodies. Close
+    // both transports on synchronous or background failures without echoing
+    // those details. In particular, a failed SSE reader must not strand stdio.
+    upstream.onerror = () => {
         void shutdown();
     };
+    downstream.onmessage = (message) => {
+        if (closed || refused)
+            return;
+        let forwarded = message;
+        const isInitialize = isJSONRPCRequest(message) && message.method === "initialize";
+        if (isJSONRPCRequest(message) && message.method === "initialize") {
+            if (initializeSeen) {
+                refuse(message.id, ErrorCode.InvalidRequest, "Duplicate initialize is not permitted");
+                return;
+            }
+            try {
+                forwarded = upstreamInitialize(message);
+            }
+            catch {
+                refuse(message.id, ErrorCode.InvalidRequest, "Invalid initialize request or workflow view selector");
+                return;
+            }
+            initializeSeen = true;
+            initializeId = message.id;
+        }
+        else if (!initializeSeen) {
+            refuse(isJSONRPCRequest(message) ? message.id : undefined, ErrorCode.InvalidRequest, "Initialize must be the first request");
+            return;
+        }
+        const sending = initialized.then(() => upstream.send(forwarded));
+        // HTTP POSTs may otherwise overtake initialize (which establishes the
+        // session) or the initialized notification. Await their acceptance before
+        // subsequent traffic, while allowing later tool calls and cancellation
+        // notifications to proceed concurrently.
+        if (isInitialize || isInitializedNotification(message))
+            initialized = sending;
+        void sending.catch(() => {
+            void shutdown();
+        });
+    };
+    upstream.onmessage = (message) => {
+        if (initializeId !== undefined &&
+            (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) &&
+            message.id === initializeId) {
+            clearTimeout(handshake);
+            initializeId = undefined;
+            if (isJSONRPCResultResponse(message) && typeof message.result.protocolVersion === "string") {
+                upstream.setProtocolVersion(message.result.protocolVersion);
+                downstream.setProtocolVersion?.(message.result.protocolVersion);
+            }
+        }
+        void downstream.send(message).catch(() => {
+            void shutdown();
+        });
+    };
+    try {
+        await upstream.start();
+        await downstream.start();
+    }
+    catch (error) {
+        await shutdown();
+        throw error;
+    }
+    return upstream;
+}
+/** Run the published stdio executable with the caller's initialize intact. */
+export async function runProxy(env = process.env) {
+    const options = resolveProxyOptions(env);
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    const close = () => {
+        void transport.close().catch(() => { });
+    };
+    process.stdin.once("end", close);
+    process.stdin.once("close", close);
+    try {
+        await connectProxyTransport(options, transport);
+    }
+    catch (error) {
+        process.stdin.off("end", close);
+        process.stdin.off("close", close);
+        throw error;
+    }
 }
+/* v8 ignore start -- process entry; the transport bridge is tested above. */
 if (isMainEntrypoint(import.meta.url)) {
     runProxy().catch((err) => {
         process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honua/mcp-server",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Platform-free MCP server for geospatial services: expose discovery, query, and analysis over any public ArcGIS/Esri FeatureServer or OGC API endpoint to any MCP client, with no platform lock-in",
   "license": "Apache-2.0",
   "author": "Honua",
@@ -85,11 +85,11 @@
   "overrides": {
     "hono": "^4.13.7",
     "@hono/node-server": "^2.0.5",
-    "fast-uri": "^3.1.6",
+    "fast-uri": "^3.1.8",
     "qs": "^6.16.0"
   },
   "peerDependencies": {
-    "@honua/sdk-js": "^0.1.12"
+    "@honua/sdk-js": "^0.1.13"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",

package/release/zero-to-map/configs/claude-code.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "honua": {
       "command": "npx",
-      "args": ["-y", "--package", "@honua/mcp-server@0.1.11-beta.0", "honua-mcp-proxy"],
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.12", "honua-mcp-proxy"],
       "env": {
         "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
       }

package/release/zero-to-map/configs/claude-desktop.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "honua": {
       "command": "npx",
-      "args": ["-y", "--package", "@honua/mcp-server@0.1.11-beta.0", "honua-mcp-proxy"],
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.12", "honua-mcp-proxy"],
       "env": {
         "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
       }

package/release/zero-to-map/configs/cursor.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "honua": {
       "command": "npx",
-      "args": ["-y", "--package", "@honua/mcp-server@0.1.11-beta.0", "honua-mcp-proxy"],
+      "args": ["-y", "--package", "@honua/mcp-server@0.1.12", "honua-mcp-proxy"],
       "env": {
         "HONUA_MCP_REMOTE_URL": "http://localhost:8080/mcp"
       }