@hydraharness/harness-mcp-client 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @hydraharness/harness-mcp-client
+
+MCP client bridge plugin: connects to external [Model Context Protocol](https://modelcontextprotocol.io/) servers and registers their tools on `ctx.tools`, making them available to the model as native tools under server-qualified names (`mcp__<serverName>__<rawName>`).
+
+## Usage
+
+One plugin instance per MCP server in `cordis.yml`:
+
+```yaml
+- id: mcp-github
+  name: '@hydraharness/harness-mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@hydraharness/harness-mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
+```
+
+The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged `serverName` reproduces identical tool names.
+
+## Config
+
+| Field | Transport | Required | Description |
+|---|---|---|---|
+| `transport` | both | yes | `"stdio"` or `"streamable-http"` |
+| `serverName` | both | yes | Namespace for this server's model-facing tool names; `[A-Za-z0-9_-]{1,32}`, unique within one registration scope |
+| `command` | stdio | yes | Executable to spawn |
+| `args` | stdio | no | Arguments passed to the command |
+| `env` | stdio | no | Extra env vars merged on top of scrubbed ambient env |
+| `cwd` | stdio | no | Working directory for the child process |
+| `url` | http | yes | MCP server URL |
+| `headers` | http | no | Extra headers (e.g. auth tokens) |
+| `bearerTokenEnvVar` | http | no | Environment variable resolved to a bearer token when each HTTP connection starts; its value is never stored in the config |
+| `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+| `failOnStartupError` | both | no | Reject plugin activation when initial connection or tool synchronization fails (default `false`) |
+| `reconnect.enabled` | both | no | Reconnect automatically after a lost connection (default `true`) |
+| `reconnect.initialDelayMs` | both | no | First reconnect delay in ms; doubles per consecutive failed attempt (default 500) |
+| `reconnect.maxDelayMs` | both | no | Backoff ceiling in ms; also the uptime after which the attempt budget resets (default 30000) |
+| `reconnect.maxAttempts` | both | no | Consecutive failed attempts per outage before giving up for good (default 10) |
+
+## Tool naming
+
+Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`) and the public name `mcp__<serverName>__<rawName>` registered on `ctx.tools`. Public names are normalized to the DeepSeek function-name contract (64 chars, `[A-Za-z0-9_-]`); when replacement or truncation changes the name, a deterministic 12-hex-char hash of `(serverName, rawName)` is appended so distinct tools never collapse into one name. Names are pure functions of `(serverName, rawName)` — connection order, re-syncs, and other servers never rename a tool.
+
+- Two servers publishing the same raw name (e.g. `search`) coexist under their namespaces.
+- A duplicate `serverName` in one registration scope fails the later plugin instance at load. Independent workspace scopes can reuse the name; unscoped clients share the app-root reservation.
+- A server listing the same tool name twice is rejected as an invalid tool list.
+- A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.
+
+## Behavior
+
+`publicToolName(serverName, rawName)` is exported for consumers that match raw MCP identities to registered tool names. Consumers must apply this same normalization instead of parsing a public name to recover the raw name.
+
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection, discovery, or registration failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
+- Listens for `notifications/tools/list_changed` → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
+- Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
+- Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
+- Native/model rendering preserves MCP block order. Text-like runs join with newlines; resource links keep their name and URI as text; supported images become durable core image blocks only when `ctx.attachments` is mounted and the exact calling model route explicitly declares image input. The whole image batch is decoded and admitted before any member is saved. A malformed/refused image batch, audio, embedded resources, and unsupported blocks become explicit diagnostic text rather than disappearing.
+- On disconnect/crash: the supervisor restarts the original server config with exponential backoff (`reconnect.initialDelayMs` doubling up to `reconnect.maxDelayMs`) and re-runs discovery on success — the recovered generation replaces the previous one, so tools neither duplicate nor leak. During the outage the last good generation stays registered; calls against it fail until recovery.
+- Reconnection is budgeted per outage: after `reconnect.maxAttempts` consecutive failures the server's tools are unregistered and reconnection stops until an HMR reload or Host restart. A connection that survives past `maxDelayMs` resets the budget, so an occasionally-crashing server recovers indefinitely while a crash-looping one — even with briefly successful connects — still exhausts the cap instead of restarting forever.
+- Reconnect states are user-visible in logs: reconnecting (warn, with attempt count and delay), recovered (info), final failure and disabled-loss (error). Disposal cancels any pending reconnect. With `reconnect.enabled: false`, a lost connection keeps tools registered but failing until a reload — the manual-recovery behavior.
+
+## Services consumed
+
+| Service | Usage |
+|---|---|
+| `ctx.tools` | Register/unregister MCP tools |
+| `ctx.attachments` | Optionally validate and persist image result batches before model projection |
+| `ctx.llm` | Optionally prove the exact calling route explicitly supports image input |
+
+## Model Experience
+
+### Discovered MCP tools
+
+#### What the model sees
+
+After initial discovery succeeds, each advertised MCP tool appears as a native tool named `mcp__<serverName>__<rawName>` (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync — including the one after an automatic reconnect — replaces the generation; plugin disposal or an exhausted reconnect budget removes it.
+
+#### Token effect
+
+Data-dependent schema cost is paid on every request while the tools are registered. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.
+
+#### KV Cache effect
+
+Prefix-stable while the discovered tool set and schemas are unchanged. A re-sync that adds, removes, renames, or changes a tool replaces definitions and may invalidate reuse from the first changed schema token; a reconnect that recovers an unchanged list reproduces identical definitions and stays prefix-stable.
+
+### Tool-call history and results
+
+#### What the model sees
+
+The public tool name and JSON arguments remain in assistant history. The execution-local canonical value always retains the complete JSON MCP blocks and optional structured content for programmatic and Code Mode callers. In Native context, supported image blocks are durably projected beside text in their original order after exact route-capability proof; Code Mode additionally ferries that settled rich projection through the outer `run_code` result without changing the canonical binding value. Refused images, audio, embedded resources, resource links, and unknown blocks remain visible as bounded text diagnostics, and MCP `isError` rejects the call before image persistence.
+
+#### Token effect
+
+Arguments, mapped text, and durable image references are retained until compaction. Inline MCP base64 stays only in the execution-local canonical value and is never copied into a session event; the provider reads verified bytes from the attachment store. Audio and embedded-resource payloads stay out of model context.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumer and are deferred.
+- **Startup timeout is inherited from the MCP SDK** — Hydra harness does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
+- **Reconnect triggers on transport close** — a crashed stdio child fires it; Streamable HTTP failures surface per request and through the SDK transport's own SSE-stream recovery, so an unreachable HTTP server is retried per call rather than respawned by the supervisor.
+- **Image is the only durable rich-result bridge** — PNG, JPEG, WebP, and GIF can enter Native context after exact capability proof. Audio and embedded-resource payloads remain execution-local with explicit diagnostics, while resource links preserve only their name and URI as text.
+- **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.

package/lib/index.js

@@ -0,0 +1,826 @@
+import z from "@hydraharness/schemastery";
+import { MAX_TIMER_DELAY_MS } from "@hydraharness/harness-timeout";
+import { scopeOf } from "@hydraharness/harness-scope";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ListToolsResultSchema, ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { scrubbedParentEnv } from "@hydraharness/harness-subprocess";
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { z as z$1 } from "zod";
+import { isImageAdmissionError } from "@hydraharness/harness-attachment";
+import { assertSupportedJsonSchema } from "@hydraharness/harness-tools";
+//#region lib/types/transport.js
+/**
+* Transport factory: creates the appropriate MCP transport based on the
+* plugin's resolved config. Stdio spawns a child process (with credential
+* scrubbing); Streamable HTTP connects to a URL.
+*
+* @module
+*/
+/**
+* The subprocess seam's scrubbed parent env (credential-shaped and stale
+* `HYDRA_*` names dropped), plus the spec's explicit env. The MCP SDK owns the
+* actual spawn, so this transport shares the scrub definition rather than the
+* spawn path.
+*/
+function buildChildEnv(extra) {
+	return {
+		...scrubbedParentEnv(),
+		...extra
+	};
+}
+/** Resolve a configured bearer environment variable without exposing its value to callers. */
+function httpHeaders(config) {
+	const headers = { ...config.headers };
+	const envName = config.bearerTokenEnvVar;
+	if (envName === void 0) return headers;
+	const token = process.env[envName]?.trim();
+	if (token === void 0 || token === "") return headers;
+	if (/[\u0000-\u001F\u007F]/u.test(token)) throw new Error(`mcp-client: bearer token environment variable ${envName} contains control characters`);
+	headers.Authorization = `Bearer ${token}`;
+	return headers;
+}
+/**
+* Create an MCP transport from the resolved plugin config.
+*
+* @param config - Resolved plugin config discriminated on `transport`.
+* @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+*/
+function createTransport(config) {
+	switch (config.transport) {
+		case "stdio": return new StdioClientTransport({
+			command: config.command,
+			args: config.args,
+			env: buildChildEnv(config.env),
+			cwd: config.cwd
+		});
+		case "streamable-http": return new StreamableHTTPClientTransport(new URL(config.url), { requestInit: { headers: httpHeaders(config) } });
+	}
+}
+//#endregion
+//#region lib/types/tools.js
+/**
+* Tool bridge: discovers MCP tools, registers them on the harness ToolRuntime
+* under deterministic server-qualified public names, and handles re-sync when
+* the server's tool list changes.
+*
+* Naming contract (see the mcp-client Agent Note "Naming invariants"): every MCP tool
+* has the stable identity `(serverName, rawName)`; the model-facing public name
+* is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+* constraints. The raw name is only ever sent on the wire (`tools/call`); the
+* public name is never parsed to recover it.
+*
+* @module
+*/
+/**
+* DeepSeek function-name contract: at most 64 characters. Wire-protocol
+* constant, not configuration.
+*/
+const MAX_PUBLIC_NAME_LENGTH = 64;
+/** DeepSeek function-name contract: only `[A-Za-z0-9_-]` is allowed. */
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
+/** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
+const HASH_LENGTH = 12;
+/** Raw result record: the bridge owns JSON-value validation after transport. */
+const RawCallToolResultSchema = z$1.record(z$1.string(), z$1.unknown());
+/** Raster formats supported by the durable attachment vocabulary. */
+const IMAGE_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
+/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** List without mutating the SDK's per-page output-validator cache. */
+function listToolsUncached(client, cursor) {
+	return client.request({
+		method: "tools/list",
+		...cursor === void 0 ? {} : { params: { cursor } }
+	}, ListToolsResultSchema);
+}
+/** Call without the SDK pre-validating an output schema the bridge may not support. */
+function callToolUncached(client, rawName, args, exec, opts) {
+	return client.request({
+		method: "tools/call",
+		params: {
+			name: rawName,
+			arguments: args
+		}
+	}, RawCallToolResultSchema, {
+		signal: exec.signal,
+		timeout: opts.toolCallTimeoutMs
+	});
+}
+/**
+* Derive the model-facing public name for one MCP tool.
+*
+* Deterministic pure function of `(serverName, rawName)`: the clean case is
+* `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+* truncation to the DeepSeek function-name contract (64 chars,
+* `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+* identity is appended so distinct MCP identities never collapse into the
+* same public name.
+*
+* @param serverName - Stable local namespace from plugin config.
+* @param rawName - The MCP server's own tool name.
+* @returns The globally unique, model-facing ToolRuntime name.
+*/
+function publicToolName(serverName, rawName) {
+	const joined = `mcp__${serverName}__${rawName}`;
+	const normalized = joined.replace(INVALID_NAME_CHARS, "_");
+	if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized;
+	const hash = createHash("sha256").update(`${serverName}\0${rawName}`).digest("hex").slice(0, HASH_LENGTH);
+	return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`;
+}
+/**
+* Sync the MCP server's tool list into the harness ToolRuntime.
+*
+* Two phases keep the swap safe:
+*
+* 1. Fetch: drain uncached `tools/list` pagination and build the full next
+*    generation of `ToolDefinition`s under public names. Any failure here
+*    (network error, duplicate raw name in the server's list) rejects and
+*    leaves the previous generation registered untouched.
+* 2. Swap: dispose the previous generation, register the new one. A registry
+*    conflict here can only mean a foreign registration squats on this
+*    server's `mcp__<serverName>__` namespace — the partial generation is
+*    rolled back (zero tools from this server) and logged. Initial strict
+*    synchronization may propagate the conflict so its parent transaction
+*    rejects; ordinary clients and later re-syncs return an empty map.
+*
+* @param client - Connected MCP Client instance used to list and call tools.
+* @param ctx - Cordis context providing the `tools` service for registration.
+* @param opts - Bridge options: server namespace and per-call timeout.
+* @param previous - Disposer map from the prior sync generation; disposed
+*   during the swap phase (only after the fetch phase succeeded).
+* @returns A map of registered public tool names to their unregister
+*   disposers — the exact set of live registrations owned by this server.
+*/
+async function syncTools(client, ctx, opts, previous) {
+	const definitions = /* @__PURE__ */ new Map();
+	let cursor;
+	do {
+		const response = await listToolsUncached(client, cursor);
+		for (const tool of response.tools) {
+			const publicName = publicToolName(opts.serverName, tool.name);
+			if (definitions.has(publicName)) throw new Error(`mcp-client(${opts.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`);
+			definitions.set(publicName, createDefinition(client, ctx, publicName, tool.name, tool.description ?? "", tool.inputSchema, supportedOutputSchema(tool.outputSchema), tool.execution?.taskSupport === "required", opts));
+		}
+		cursor = response.nextCursor;
+	} while (cursor);
+	for (const dispose of previous.values()) dispose();
+	const disposers = /* @__PURE__ */ new Map();
+	try {
+		for (const [publicName, definition] of definitions) disposers.set(publicName, ctx.tools.register(definition));
+	} catch (error) {
+		for (const dispose of disposers.values()) dispose();
+		ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`);
+		if (opts.registrationFailure === "throw") throw error;
+		return /* @__PURE__ */ new Map();
+	}
+	return disposers;
+}
+/** Keep a supported advertised schema; unsupported MCP vocabulary falls back to JsonValue. */
+function supportedOutputSchema(candidate) {
+	if (candidate === void 0) return void 0;
+	try {
+		assertSupportedJsonSchema(candidate);
+		return candidate;
+	} catch {
+		return;
+	}
+}
+/**
+* Build one generation-local tool definition and its execution-local rich projections.
+* @param client - connected MCP client used for calls.
+* @param ctx - plugin context carrying optional attachment and model services.
+* @param publicName - registry-qualified public tool name.
+* @param rawName - MCP wire tool name.
+* @param description - model-facing tool description.
+* @param parameters - MCP input schema.
+* @param structuredSchema - supported structured-output schema, when advertised.
+* @param taskRequired - whether this MCP tool requires unsupported task execution.
+* @param opts - bridge timeout and namespace options.
+* @returns a complete ToolRuntime definition.
+*/
+function createDefinition(client, ctx, publicName, rawName, description, parameters, structuredSchema, taskRequired, opts) {
+	const projections = /* @__PURE__ */ new WeakMap();
+	return {
+		name: publicName,
+		description,
+		parameters,
+		output: createOutput(rawName, structuredSchema),
+		execute: createExecutor(client, ctx, rawName, taskRequired, opts, projections),
+		finalizeContent(exec, result) {
+			const projection = projections.get(exec);
+			if (projection === void 0) return void 0;
+			projections.delete(exec);
+			if (result.isError) return void 0;
+			if (!isDeepStrictEqual(result.value, projection.value)) return void 0;
+			if (!isDeepStrictEqual(result.content, projection.fallback)) return void 0;
+			return projection.content;
+		}
+	};
+}
+/** Build the canonical result schema and existing Native text projection. */
+function createOutput(rawName, structuredSchema) {
+	return {
+		schema: {
+			type: "object",
+			properties: {
+				content: {
+					type: "array",
+					items: {}
+				},
+				structuredContent: structuredSchema ?? {}
+			},
+			required: structuredSchema === void 0 ? ["content"] : ["content", "structuredContent"],
+			additionalProperties: false
+		},
+		render(_args, value) {
+			return [{
+				type: "text",
+				text: extractText(value.content, rawName)
+			}];
+		}
+	};
+}
+/**
+* Create an execute function for one MCP tool. The executor closes over the
+* raw MCP tool name and sends an uncached `tools/call` request with it (never
+* the public name), with abort signal and timeout, then maps the result to
+* harness ContentBlocks. Owning the raw request prevents the SDK's internal
+* per-page schema cache from pre-validating a different contract.
+*
+* When the MCP server returns `isError: true`, the executor throws so that
+* the ToolRuntime's catch path produces an `isError` result for the model.
+*/
+function createExecutor(client, ctx, rawName, taskRequired, opts, projections) {
+	return async (args, exec) => {
+		if (taskRequired) throw new Error(`Tool "${rawName}" requires task-based execution, which this bridge does not support`);
+		const result = await callToolUncached(client, rawName, typeof args === "object" && args !== null ? args : {}, exec, opts);
+		if (!Array.isArray(result.content)) {
+			const rendered = "toolResult" in result ? JSON.stringify(result.toolResult) : "(no output)";
+			const text = typeof rendered === "string" ? rendered : "(no output)";
+			if (result.isError === true) throw new Error(text);
+			return {
+				content: [{
+					type: "text",
+					text
+				}],
+				...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+			};
+		}
+		const content = result.content;
+		const text = extractText(content, rawName);
+		if (result.isError === true) throw new Error(text);
+		const value = {
+			content,
+			...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
+		};
+		if (containsImage(content)) {
+			const fallback = [{
+				type: "text",
+				text: extractText(content, rawName)
+			}];
+			const projected = await prepareImageProjection(ctx, exec, content, rawName);
+			projections.set(exec, {
+				value,
+				fallback,
+				content: projected
+			});
+		}
+		return value;
+	};
+}
+/** Whether an untrusted MCP content array contains a declared image block. */
+function containsImage(content) {
+	return content.some((value) => isRecord(value) && value.type === "image");
+}
+/** Narrow one JSON value to a string-keyed object. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrow a declared MIME string to the durable image vocabulary. */
+function isImageMediaType(value) {
+	return IMAGE_MEDIA_TYPES.includes(value);
+}
+/** Decode one untrusted MCP image block without accepting base64 aliases. */
+function decodeImage(block) {
+	if (block.mimeType === void 0 || !isImageMediaType(block.mimeType)) throw new Error("the declared media type is not PNG, JPEG, WebP, or GIF");
+	if (block.data === void 0 || !CANONICAL_BASE64.test(block.data)) throw new Error("the image data is not canonical base64");
+	const data = Buffer.from(block.data, "base64");
+	if (data.toString("base64") !== block.data) throw new Error("the image data is not canonical base64");
+	return {
+		data,
+		mediaType: block.mimeType
+	};
+}
+/**
+* Resolve the active model route and durable store for an image-bearing result.
+* @param ctx - plugin context with optional services.
+* @param exec - exact tool execution whose agent supplies the latest route.
+* @returns the attachment store after exact positive image-capability proof.
+*/
+async function resolveImageAdmission(ctx, exec) {
+	const attachments = ctx.get("attachments");
+	if (attachments === void 0) throw new Error("no attachment store is mounted");
+	const routed = exec.agent?.session.requestHeader()?.config;
+	const provider = routed?.provider ?? exec.agent?.options.provider;
+	const model = routed?.model ?? exec.agent?.options.model;
+	const llm = ctx.get("llm");
+	if (provider === void 0 || model === void 0 || llm === void 0) throw new Error("the current model route could not be resolved");
+	let info;
+	try {
+		info = await llm.resolveModelInfo(provider, model, exec.signal);
+	} catch {
+		throw new Error("the current model route could not be verified");
+	}
+	if (info.inputModalities === void 0 || !info.inputModalities.includes("image")) throw new Error(`model "${model}" does not declare image input`);
+	if (exec.signal.aborted) throw new Error("the tool call was canceled before image storage");
+	return attachments;
+}
+/** Stable diagnostic text for an image block that was not admitted. */
+function imageDiagnostic(block, reason) {
+	return `[image unavailable: ${block.mimeType ?? "unknown media type"}; ${reason}; raw image data remains available to programmatic callers]`;
+}
+/**
+* Decode, preflight, and durably save one MCP result's ordered image batch.
+* Any refusal projects every image as text while retaining the canonical raw
+* value for programmatic callers.
+*/
+async function prepareImageProjection(ctx, exec, content, toolName) {
+	const decoded = [];
+	const validationErrors = /* @__PURE__ */ new Map();
+	const imageIndexes = [];
+	for (const [index, value] of content.entries()) {
+		if (!isRecord(value) || value.type !== "image") continue;
+		imageIndexes.push(index);
+		try {
+			decoded.push(decodeImage(value));
+		} catch (error) {
+			validationErrors.set(index, error.message);
+		}
+	}
+	if (validationErrors.size > 0) return projectContent(content, toolName, (block, index) => ({
+		type: "text",
+		text: imageDiagnostic(block, validationErrors.get(index) ?? "another image in the same result was invalid")
+	}));
+	let attachments;
+	try {
+		attachments = await resolveImageAdmission(ctx, exec);
+	} catch (error) {
+		const reason = error.message;
+		return projectContent(content, toolName, (block) => ({
+			type: "text",
+			text: imageDiagnostic(block, reason)
+		}));
+	}
+	try {
+		const refs = await attachments.saveImages(decoded);
+		const byIndex = new Map(imageIndexes.map((index, offset) => [index, refs[offset]]));
+		return projectContent(content, toolName, (_block, index) => ({
+			type: "image",
+			attachment: byIndex.get(index)
+		}));
+	} catch (error) {
+		const reason = isImageAdmissionError(error) ? `image admission rejected the result: ${error.message}` : "durable image storage rejected the result";
+		return projectContent(content, toolName, (block) => ({
+			type: "text",
+			text: imageDiagnostic(block, reason)
+		}));
+	}
+}
+/**
+* Extract text from an MCP content array into a single string.
+* - text blocks: join with '\n'
+* - image/audio/resource blocks: replaced with a placeholder
+*
+* Defensive: fields that the MCP spec declares required (mimeType, text) are
+* guarded with fallbacks because this is a network trust boundary.
+*/
+function extractText(mcpContent, toolName) {
+	return projectContent(mcpContent, toolName).map((block) => block.text).join("\n");
+}
+/**
+* Project ordered MCP blocks into the core content vocabulary.
+* Text-like runs are newline-coalesced; admitted images split those runs at
+* their original position.
+*/
+function projectContent(mcpContent, toolName, image = (block) => ({
+	type: "text",
+	text: imageDiagnostic(block, "this result was not admitted to durable model context")
+})) {
+	const projected = [];
+	const text = [];
+	const flushText = () => {
+		if (text.length === 0) return;
+		projected.push({
+			type: "text",
+			text: text.splice(0).join("\n")
+		});
+	};
+	for (const [index, value] of mcpContent.entries()) {
+		if (!isRecord(value)) {
+			text.push("[unsupported MCP content block: expected an object]");
+			continue;
+		}
+		const block = value;
+		switch (block.type) {
+			case "text":
+				if (block.text !== void 0) text.push(block.text);
+				break;
+			case "image":
+				flushText();
+				projected.push(image(block, index));
+				break;
+			case "resource_link":
+				if (block.name === void 0 || block.uri === void 0) text.push("[resource link unavailable: the MCP block is missing its name or URI]");
+				else text.push(`Resource link: ${block.name} (${block.uri})`);
+				break;
+			case "audio":
+				text.push(`[audio result unsupported: ${block.mimeType ?? "unknown media type"}; raw audio data remains available to programmatic callers]`);
+				break;
+			case "resource":
+				text.push("[embedded resource unsupported; raw resource data remains available to programmatic callers]");
+				break;
+			default: text.push(`[unsupported MCP content type: ${block.type}]`);
+		}
+	}
+	flushText();
+	return projected.length > 0 ? projected : [{
+		type: "text",
+		text: `(${toolName} returned no model-visible content)`
+	}];
+}
+//#endregion
+//#region lib/types/connection.js
+/**
+* Connection supervisor: owns the MCP client/transport generations for one
+* plugin instance, keeps the harness tool registry in sync with the live
+* generation, and — when the connection drops — restarts the configured
+* server with bounded exponential backoff.
+*
+* One outage shares one attempt budget (`maxAttempts` consecutive failed
+* attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+* connection that stays up past the stability window closes the outage, so
+* the next disconnect starts a fresh budget while a crash-looping server —
+* even one whose connects briefly succeed — still exhausts the cap instead of
+* restarting forever. Exhaustion unregisters the server's tools and stops;
+* disposal (including HMR) is the only way back from that state.
+*
+* @module
+*/
+/** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
+const RECONNECT_DEFAULTS = Object.freeze({
+	enabled: true,
+	initialDelayMs: 500,
+	maxDelayMs: 3e4,
+	maxAttempts: 10
+});
+const GENERATION_CLOSE_TIMEOUT_MS = 5e3;
+/**
+* The one explicit resolve step from raw reconnect config to the policy the
+* supervisor runs. Programmatic construction may bypass Schemastery
+* normalization, so every default and bound is re-judged here — misconfiguration
+* fails the plugin instance at load.
+*
+* @param config - Raw `reconnect` config; omission uses the defaults.
+* @param path - Diagnostic prefix naming the config location in thrown messages.
+* @returns The frozen resolved policy.
+*/
+function resolveReconnectPolicy(config, path) {
+	if (config !== void 0) {
+		for (const key of Object.keys(config)) if (!Object.hasOwn(RECONNECT_DEFAULTS, key)) throw new Error(`${path}.${key} is not a reconnect option`);
+	}
+	const enabled = config?.enabled ?? RECONNECT_DEFAULTS.enabled;
+	const initialDelayMs = config?.initialDelayMs ?? RECONNECT_DEFAULTS.initialDelayMs;
+	const maxDelayMs = config?.maxDelayMs ?? RECONNECT_DEFAULTS.maxDelayMs;
+	const maxAttempts = config?.maxAttempts ?? RECONNECT_DEFAULTS.maxAttempts;
+	if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (initialDelayMs > maxDelayMs) throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 1) throw new Error(`${path}.maxAttempts must be a positive integer`);
+	return Object.freeze({
+		enabled,
+		initialDelayMs,
+		maxDelayMs,
+		maxAttempts
+	});
+}
+/**
+* Start the supervised connection for one MCP server and keep it alive per
+* the reconnect policy.
+*
+* @param ctx - Cordis context providing the `tools` registry and logger.
+* @param config - Resolved plugin config selecting the transport and server identity.
+* @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+* @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+*/
+function startConnection(ctx, config, policy) {
+	const label = `mcp-client(${config.serverName})`;
+	const opts = {
+		registrationFailure: "contain",
+		serverName: config.serverName,
+		toolCallTimeoutMs: config.toolCallTimeoutMs
+	};
+	const startupOpts = config.failOnStartupError ? {
+		...opts,
+		registrationFailure: "throw"
+	} : opts;
+	let disposed = false;
+	/** Current generation: the connecting or connected client; undefined during backoff waits and after final failure. */
+	let client;
+	ctx.inject(["suggestedPrompts"], (sctx) => {
+		sctx.effect(() => sctx.suggestedPrompts.registerSource({
+			name: `MCP ${config.serverName}`,
+			scope: scopeOf(ctx),
+			async read(_agent, signal, maxBytes, maxResources) {
+				const generation = client;
+				if (generation?.getServerCapabilities()?.resources === void 0) return "";
+				const resources = await generation.listResources({}, { signal });
+				const parts = [];
+				let remaining = maxBytes;
+				for (const resource of resources.resources.slice(0, maxResources)) {
+					signal.throwIfAborted();
+					const result = await generation.readResource({ uri: resource.uri }, { signal });
+					for (const content of result.contents) {
+						if (!("text" in content) || typeof content.text !== "string") continue;
+						const text = `${resource.name}:\n${content.text}`;
+						const size = Buffer.byteLength(text);
+						if (size > remaining) throw new Error("MCP resource exceeded the suggestion data budget");
+						parts.push(text);
+						remaining -= size;
+					}
+				}
+				const text = parts.join("\n");
+				if (Buffer.byteLength(text) > maxBytes) throw new Error("MCP resources exceeded the suggestion data budget");
+				return text;
+			}
+		}), "mcp-client: suggestion source");
+	});
+	/** Close signal paired with {@link client}; captured by dispose before current ownership is cleared. */
+	let clientClosed;
+	/** Live tool registrations owned by this server; only {@link enqueueSync} and dispose swap it. */
+	let disposers = /* @__PURE__ */ new Map();
+	let reconnectTimer;
+	/** Consecutive failed connection attempts within the current outage. */
+	let failedAttempts = 0;
+	/** When the current generation finished connect + initial sync; undefined while down. */
+	let connectedAt;
+	/** The real error from the first connection attempt, for startup-await diagnostics. */
+	let firstAttemptError;
+	/** A generation may act only while it is the current one on a live plugin. */
+	const isCurrent = (generation) => !disposed && client === generation;
+	/**
+	* Serializes every syncTools call — initial syncs and notification re-syncs
+	* across all generations — so two syncs can never interleave their
+	* dispose-previous/register-next swap (which would double-dispose one
+	* generation and leak another).
+	*/
+	let syncChain = Promise.resolve();
+	function enqueueSync(generation, syncOpts = opts) {
+		const run = syncChain.then(async () => {
+			if (!isCurrent(generation)) return;
+			disposers = await syncTools(generation, ctx, syncOpts, disposers);
+		});
+		syncChain = run.catch(() => {});
+		return run;
+	}
+	/** One disconnect decision per generation: the isCurrent guard makes racing close/error signals idempotent. */
+	function generationDown(generation) {
+		if (!isCurrent(generation)) return;
+		client = void 0;
+		clientClosed = void 0;
+		scheduleReconnect();
+	}
+	/** Wait for the transport-owned close signal without letting a broken transport wedge teardown forever. */
+	function waitForClose(closed) {
+		return new Promise((resolve) => {
+			const timeout = setTimeout(() => {
+				resolve(false);
+			}, GENERATION_CLOSE_TIMEOUT_MS);
+			timeout.unref();
+			closed.then(() => {
+				clearTimeout(timeout);
+				resolve(true);
+			});
+		});
+	}
+	function scheduleReconnect() {
+		const lostEstablishedConnection = connectedAt !== void 0;
+		if (!policy.enabled) {
+			const message = lostEstablishedConnection ? "connection lost and reconnect is disabled — registered tools will fail until an HMR reload or Host restart" : "connection failed and reconnect is disabled — no tools were registered; reload the plugin or restart the Host to connect";
+			ctx.logger.error(`${label}: ${message}`);
+			return;
+		}
+		if (connectedAt !== void 0 && Date.now() - connectedAt >= policy.maxDelayMs) failedAttempts = 0;
+		connectedAt = void 0;
+		failedAttempts += 1;
+		if (failedAttempts > policy.maxAttempts) {
+			syncChain = syncChain.then(() => {
+				for (const dispose of disposers.values()) dispose();
+				disposers = /* @__PURE__ */ new Map();
+			});
+			ctx.logger.error(`${label}: giving up after ${policy.maxAttempts} consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect`);
+			return;
+		}
+		const delayMs = Math.min(policy.maxDelayMs, policy.initialDelayMs * 2 ** (failedAttempts - 1));
+		const action = lostEstablishedConnection ? "connection lost; reconnecting" : "connection failed; retrying";
+		ctx.logger.warn(`${label}: ${action} in ${delayMs}ms (attempt ${failedAttempts}/${policy.maxAttempts})`);
+		reconnectTimer = setTimeout(() => {
+			reconnectTimer = void 0;
+			settling = connectGeneration(false);
+		}, delayMs);
+		reconnectTimer.unref();
+	}
+	/**
+	* One connection attempt: fresh transport + client (the MCP SDK binds a
+	* Protocol to one transport for life), connect, then queue the initial tool
+	* sync. The startup flag belongs to the attempt rather than the shared sync
+	* queue, so an early notification cannot consume strict startup semantics.
+	* Every failure funnels through {@link generationDown}; success arms the
+	* onclose-driven disconnect path. Never rejects.
+	*
+	* @param startup - Whether this is the plugin's activation attempt.
+	*/
+	async function connectGeneration(startup) {
+		const generation = new Client({
+			name: "hydra-mcp-client",
+			version: "0.0.1"
+		}, { capabilities: {} });
+		const closed = Promise.withResolvers();
+		let attemptSettled = false;
+		let closeObserved = false;
+		const hasClosed = () => closeObserved;
+		client = generation;
+		clientClosed = closed.promise;
+		generation.onclose = () => {
+			closeObserved = true;
+			closed.resolve();
+			if (attemptSettled) generationDown(generation);
+		};
+		generation.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+			if (!isCurrent(generation)) return;
+			ctx.logger.info(`${label}: tool list changed, re-syncing`);
+			try {
+				await enqueueSync(generation);
+			} catch (error) {
+				if (!disposed) ctx.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
+			}
+		});
+		try {
+			await generation.connect(createTransport(config));
+			if (hasClosed()) {
+				attemptSettled = true;
+				generationDown(generation);
+				return;
+			}
+			await enqueueSync(generation, startup ? startupOpts : opts);
+		} catch (error) {
+			if (firstAttemptError === void 0) firstAttemptError = error;
+			if (isCurrent(generation)) ctx.logger.warn(`${label}: connection attempt failed: ${String(error)}`);
+			try {
+				await generation.close();
+			} catch {}
+			const quiesced = hasClosed() || await waitForClose(closed.promise);
+			attemptSettled = true;
+			if (!isCurrent(generation)) return;
+			if (!quiesced) {
+				client = void 0;
+				clientClosed = void 0;
+				ctx.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+				return;
+			}
+			generationDown(generation);
+			return;
+		}
+		attemptSettled = true;
+		if (hasClosed()) {
+			generationDown(generation);
+			return;
+		}
+		if (!isCurrent(generation)) return;
+		connectedAt = Date.now();
+		if (failedAttempts > 0) ctx.logger.info(`${label}: reconnected and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
+	}
+	/** The in-flight (or last settled) connection attempt; dispose awaits it for quiescence. */
+	let settling = connectGeneration(true);
+	return {
+		ready: settling.then(() => {
+			if (client !== void 0) return {};
+			/* v8 ignore next -- defensive: firstAttemptError is always set when connect/sync fails */
+			return { error: firstAttemptError ?? /* @__PURE__ */ new Error(`${label}: initial connection failed`) };
+		}),
+		async dispose() {
+			disposed = true;
+			if (reconnectTimer !== void 0) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = void 0;
+			}
+			const current = client;
+			const currentClosed = clientClosed;
+			client = void 0;
+			clientClosed = void 0;
+			if (current !== void 0) {
+				try {
+					await current.close();
+				} catch {}
+				if (currentClosed !== void 0 && !await waitForClose(currentClosed)) ctx.logger.error(`${label}: generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms during disposal — server shutdown may be incomplete`);
+			}
+			await settling;
+			await syncChain;
+			for (const dispose of disposers.values()) dispose();
+			disposers = /* @__PURE__ */ new Map();
+		}
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* MCP client bridge plugin: connects to an external MCP server and registers
+* its tools on `ctx.tools` under server-qualified public names
+* (`mcp__<serverName>__<rawName>`). Each plugin instance connects to one MCP
+* server; load multiple instances in `cordis.yml` for multiple servers.
+*
+* Namespace plugin (named exports, no default export). Lifecycle is
+* effect-scoped: disposal disconnects from the server, unregisters all tools,
+* and releases the `serverName` namespace reservation. HMR hot-swaps by
+* disposing the old instance and creating a new one; identical `serverName`
+* reproduces identical public tool names.
+*
+* @module @hydraharness/harness-mcp-client
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "mcp-client";
+/** Services required by this plugin. */
+const inject = ["tools"];
+/** Default timeout for individual MCP tool calls (ms). */
+const DEFAULT_TOOL_CALL_TIMEOUT_MS = 6e4;
+/** Valid `serverName`, kept below the public tool-name budget. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+/**
+* Live `serverName` reservations within one registration scope, or the app
+* root for unscoped clients. Independent workspace scopes may reuse a name.
+* A duplicate in one scope is a configuration error surfaced at plugin load.
+*/
+const activeServerNames = /* @__PURE__ */ new WeakMap();
+const Reconnect = z.object({
+	enabled: z.boolean().default(RECONNECT_DEFAULTS.enabled),
+	initialDelayMs: z.number().min(1).max(MAX_TIMER_DELAY_MS).default(RECONNECT_DEFAULTS.initialDelayMs),
+	maxDelayMs: z.number().min(1).max(MAX_TIMER_DELAY_MS).default(RECONNECT_DEFAULTS.maxDelayMs),
+	maxAttempts: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(RECONNECT_DEFAULTS.maxAttempts)
+});
+const Config = z.union([z.object({
+	transport: z.const("stdio"),
+	serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+	command: z.string().required(),
+	args: z.array(String).default([]),
+	env: z.dict(String).default({}),
+	cwd: z.string().default(""),
+	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+	failOnStartupError: z.boolean().default(false),
+	reconnect: Reconnect
+}), z.object({
+	transport: z.const("streamable-http"),
+	serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+	url: z.string().required(),
+	headers: z.dict(String).default({}),
+	bearerTokenEnvVar: z.union([z.const(void 0), z.string().min(1)]),
+	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+	failOnStartupError: z.boolean().default(false),
+	reconnect: Reconnect
+})]);
+/**
+* Connect one MCP server and publish its initial tool generation before activation.
+* This entry remains explicitly `async`: Cordis treats a prototype-bearing
+* ordinary function as a constructor, whose returned Promise is not startup work.
+* @param ctx - plugin context carrying the tool registry.
+* @param config - resolved transport and server namespace configuration.
+* @returns startup readiness after connection and initial tool discovery settle.
+*/
+async function apply(ctx, config) {
+	const reconnect = resolveReconnectPolicy(config.reconnect, `mcp-client(${config.serverName}): reconnect`);
+	ctx.effect(() => {
+		const owner = scopeOf(ctx) ?? ctx.root;
+		let names = activeServerNames.get(owner);
+		if (!names) {
+			names = /* @__PURE__ */ new Set();
+			activeServerNames.set(owner, names);
+		}
+		if (names.has(config.serverName)) throw new Error(`mcp-client: serverName "${config.serverName}" is already in use by another mcp-client instance — pick a unique serverName in cordis.yml`);
+		names.add(config.serverName);
+		return () => void names.delete(config.serverName);
+	}, "mcp-client.serverName");
+	const connection = startConnection(ctx, config, reconnect);
+	ctx.effect(() => {
+		return () => connection.dispose();
+	}, "mcp-client.connection");
+	const outcome = await connection.ready;
+	if (outcome.error !== void 0 && config.failOnStartupError) throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error });
+}
+//#endregion
+export { Config, apply, inject, name, publicToolName };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-mcp-client`.
+* @module @hydraharness/harness-mcp-client/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-mcp-client";
+/** Cordis companion plugin name. */
+const name = "mcp-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: MCP generations contribute through the tool registry, but the bridge
+* exposes no independent server-to-tool snapshot after an asynchronous resync.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/connection.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Connection supervisor: owns the MCP client/transport generations for one
+ * plugin instance, keeps the harness tool registry in sync with the live
+ * generation, and — when the connection drops — restarts the configured
+ * server with bounded exponential backoff.
+ *
+ * One outage shares one attempt budget (`maxAttempts` consecutive failed
+ * attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+ * connection that stays up past the stability window closes the outage, so
+ * the next disconnect starts a fresh budget while a crash-looping server —
+ * even one whose connects briefly succeed — still exhausts the cap instead of
+ * restarting forever. Exhaustion unregisters the server's tools and stops;
+ * disposal (including HMR) is the only way back from that state.
+ *
+ * @module
+ */
+import type { Context } from '@hydraharness/cordis';
+import type { Config } from './index.ts';
+/** Automatic reconnect policy for one MCP server connection. */
+export interface ReconnectConfig {
+    /** Reconnect automatically after a lost connection (default true). */
+    enabled?: boolean;
+    /** First reconnect delay in milliseconds; doubles per consecutive failed attempt (default 500). */
+    initialDelayMs?: number;
+    /** Backoff ceiling in milliseconds; also the uptime after which the attempt budget resets (default 30000). */
+    maxDelayMs?: number;
+    /** Consecutive failed attempts per outage before giving up for good (default 10). */
+    maxAttempts?: number;
+}
+/** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
+export declare const RECONNECT_DEFAULTS: Required<ReconnectConfig>;
+/** Fully resolved reconnect policy captured at plugin load. */
+export type ResolvedReconnectPolicy = Readonly<Required<ReconnectConfig>>;
+/**
+ * The one explicit resolve step from raw reconnect config to the policy the
+ * supervisor runs. Programmatic construction may bypass Schemastery
+ * normalization, so every default and bound is re-judged here — misconfiguration
+ * fails the plugin instance at load.
+ *
+ * @param config - Raw `reconnect` config; omission uses the defaults.
+ * @param path - Diagnostic prefix naming the config location in thrown messages.
+ * @returns The frozen resolved policy.
+ */
+export declare function resolveReconnectPolicy(config: ReconnectConfig | undefined, path: string): ResolvedReconnectPolicy;
+/** Result from the initial connection attempt, for startup-await semantics. */
+export interface ConnectionOutcome {
+    /** If the initial connection or tool sync failed, the error; otherwise absent. */
+    error?: unknown;
+}
+/** Handle for one plugin instance's supervised connection. */
+export interface ConnectionHandle {
+    /**
+     * Settles when the first connection attempt completes (success or failure).
+     * The supervisor enters its reconnect loop regardless; the caller decides
+     * whether a failed startup is fatal via `failOnStartupError`.
+     */
+    ready: Promise<ConnectionOutcome>;
+    /**
+     * Stop reconnection, close the live client, wait for the in-flight attempt
+     * and queued tool syncs to quiesce, then unregister every tool this server
+     * still owns.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Start the supervised connection for one MCP server and keep it alive per
+ * the reconnect policy.
+ *
+ * @param ctx - Cordis context providing the `tools` registry and logger.
+ * @param config - Resolved plugin config selecting the transport and server identity.
+ * @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+ * @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+ */
+export declare function startConnection(ctx: Context, config: Config, policy: ResolvedReconnectPolicy): ConnectionHandle;
+//# sourceMappingURL=connection.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * MCP client bridge plugin: connects to an external MCP server and registers
+ * its tools on `ctx.tools` under server-qualified public names
+ * (`mcp__<serverName>__<rawName>`). Each plugin instance connects to one MCP
+ * server; load multiple instances in `cordis.yml` for multiple servers.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is
+ * effect-scoped: disposal disconnects from the server, unregisters all tools,
+ * and releases the `serverName` namespace reservation. HMR hot-swaps by
+ * disposing the old instance and creating a new one; identical `serverName`
+ * reproduces identical public tool names.
+ *
+ * @module @hydraharness/harness-mcp-client
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { ReconnectConfig } from './connection.ts';
+export type { McpResult } from './tools.ts';
+export { publicToolName } from './tools.ts';
+export type { ReconnectConfig, ResolvedReconnectPolicy } from './connection.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "mcp-client";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+    /** Selects child-process stdio transport. */
+    transport: 'stdio';
+    /**
+     * Stable local namespace for this server's model-facing tool names
+     * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+     * unique across live mcp-client instances in the same registration scope.
+     */
+    serverName: string;
+    /** Executable used to start the server. */
+    command: string;
+    /** Arguments passed directly, without shell interpolation. */
+    args: string[];
+    /** Extra env vars merged on top of scrubbed ambient env. */
+    env: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd: string;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+    /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
+    reconnect?: ReconnectConfig;
+}
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+    /** Selects Streamable HTTP transport. */
+    transport: 'streamable-http';
+    /**
+     * Stable local namespace for this server's model-facing tool names
+     * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+     * unique across live mcp-client instances in the same registration scope.
+     */
+    serverName: string;
+    /** MCP endpoint URL. */
+    url: string;
+    /** Additional headers attached to MCP requests. */
+    headers: Record<string, string>;
+    /** Optional environment variable resolved to a bearer token at connection time. */
+    bearerTokenEnvVar?: string;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+    /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
+    reconnect?: ReconnectConfig;
+}
+/** Configuration for one stdio or Streamable HTTP MCP server. */
+export type Config = StdioConfig | StreamableHttpConfig;
+export declare const Config: z<Config>;
+/**
+ * Connect one MCP server and publish its initial tool generation before activation.
+ * This entry remains explicitly `async`: Cordis treats a prototype-bearing
+ * ordinary function as a constructor, whose returned Promise is not startup work.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-mcp-client`.
+ * @module @hydraharness/harness-mcp-client/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "mcp-client-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/tools.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tool bridge: discovers MCP tools, registers them on the harness ToolRuntime
+ * under deterministic server-qualified public names, and handles re-sync when
+ * the server's tool list changes.
+ *
+ * Naming contract (see the mcp-client Agent Note "Naming invariants"): every MCP tool
+ * has the stable identity `(serverName, rawName)`; the model-facing public name
+ * is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+ * constraints. The raw name is only ever sent on the wire (`tools/call`); the
+ * public name is never parsed to recover it.
+ *
+ * @module
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Context } from '@hydraharness/cordis';
+import type { JsonValue } from '@hydraharness/harness-tools';
+/** Resolved options relevant to tool bridging. */
+export interface ToolBridgeOptions {
+    /** Whether a registry conflict is contained or rejects this synchronization. */
+    registrationFailure: 'contain' | 'throw';
+    serverName: string;
+    toolCallTimeoutMs: number;
+}
+/** State for one sync generation: the current set of disposers keyed by public name. */
+export type ToolDisposers = Map<string, () => void>;
+/** Canonical MCP result exposed to Code Mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+    content: JsonValue[];
+    structuredContent?: Structured;
+};
+/**
+ * Derive the model-facing public name for one MCP tool.
+ *
+ * Deterministic pure function of `(serverName, rawName)`: the clean case is
+ * `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+ * truncation to the DeepSeek function-name contract (64 chars,
+ * `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+ * identity is appended so distinct MCP identities never collapse into the
+ * same public name.
+ *
+ * @param serverName - Stable local namespace from plugin config.
+ * @param rawName - The MCP server's own tool name.
+ * @returns The globally unique, model-facing ToolRuntime name.
+ */
+export declare function publicToolName(serverName: string, rawName: string): string;
+/**
+ * Sync the MCP server's tool list into the harness ToolRuntime.
+ *
+ * Two phases keep the swap safe:
+ *
+ * 1. Fetch: drain uncached `tools/list` pagination and build the full next
+ *    generation of `ToolDefinition`s under public names. Any failure here
+ *    (network error, duplicate raw name in the server's list) rejects and
+ *    leaves the previous generation registered untouched.
+ * 2. Swap: dispose the previous generation, register the new one. A registry
+ *    conflict here can only mean a foreign registration squats on this
+ *    server's `mcp__<serverName>__` namespace — the partial generation is
+ *    rolled back (zero tools from this server) and logged. Initial strict
+ *    synchronization may propagate the conflict so its parent transaction
+ *    rejects; ordinary clients and later re-syncs return an empty map.
+ *
+ * @param client - Connected MCP Client instance used to list and call tools.
+ * @param ctx - Cordis context providing the `tools` service for registration.
+ * @param opts - Bridge options: server namespace and per-call timeout.
+ * @param previous - Disposer map from the prior sync generation; disposed
+ *   during the swap phase (only after the fetch phase succeeded).
+ * @returns A map of registered public tool names to their unregister
+ *   disposers — the exact set of live registrations owned by this server.
+ */
+export declare function syncTools(client: Client, ctx: Context, opts: ToolBridgeOptions, previous: ToolDisposers): Promise<ToolDisposers>;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/transport.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Transport factory: creates the appropriate MCP transport based on the
+ * plugin's resolved config. Stdio spawns a child process (with credential
+ * scrubbing); Streamable HTTP connects to a URL.
+ *
+ * @module
+ */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Config } from './index.ts';
+/**
+ * Create an MCP transport from the resolved plugin config.
+ *
+ * @param config - Resolved plugin config discriminated on `transport`.
+ * @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+ */
+export declare function createTransport(config: Config): Transport;
+//# sourceMappingURL=transport.d.ts.map

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@hydraharness/harness-mcp-client",
+  "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/mcp/mcp-client"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-attachment": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.10",
+    "@hydraharness/harness-timeout": "^0.1.1-rc.10",
+    "@hydraharness/harness-tools": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-scope": "^0.1.1-rc.10",
+    "@hydraharness/harness-suggested-prompts": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^4.4.3",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server-everything": "^2026.7.4",
+    "@modelcontextprotocol/server-filesystem": "^2026.7.4",
+    "@hydraharness/harness-attachment": "^0.1.1-rc.10",
+    "@hydraharness/harness-attachment-local": "^0.1.1-rc.10",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/harness-llm": "^0.1.1-rc.10",
+    "@hydraharness/harness-scope": "^0.1.1-rc.10",
+    "@hydraharness/harness-tools": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-timeout": "^0.1.1-rc.10",
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.10",
+    "@hydraharness/harness-suggested-prompts": "^0.1.1-rc.10"
+  }
+}