@sparkelf/dsh-plugin-mcp-credentials 0.1.0-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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/plus/mcp-credentials/README.md
+README.md: c074ff8dc4ec6e093d36f1ec300eb9009fee7674
+README.zh.md: a07457971bd284f4d7e95eda795c0afd60b00a5d

package/README.md

@@ -0,0 +1,63 @@
+---
+description: "The official MCP client behavior with per-request credential-backed Bearer authentication for Streamable HTTP."
+kind: "package-reference"
+---
+
+# @sparkelf/dsh-plugin-mcp-credentials
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This Host plugin preserves official MCP connection, reconnect, tool publication, image-result, and lifecycle behavior while adding one Streamable HTTP option: `bearerTokenRef`. The transport resolves that DSH credential immediately before every network request and sends the current value as the Bearer token.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use the same stdio or `streamable-http` configuration as the official MCP client. For credential-backed HTTP, set `bearerTokenRef` and compose Credentials; literal `headers.Authorization` and `bearerTokenRef` are mutually exclusive. DataOps mounts this plugin internally so token rotation reaches the next MCP request without a profile remount.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Credential-backed MCP transport
+
+#### What the model sees
+
+The model sees only current namespaced MCP tool schemas authenticated through `bearerTokenRef` and their results. Credential references and values never appear in tool arguments, results, prompts, Session events, manifests, or deployment locks.
+
+#### Token effect
+
+Authentication adds zero tokens. MCP tool schemas and calls retain the token effects owned by the upstream MCP client.
+
+#### KV Cache effect
+
+Credential rotation does not alter model-visible schemas. Tool discovery or connection loss may add or remove schemas and therefore change the tool prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Bearer authentication only**: other HTTP authorization schemes require a proven provider extension point; profile files must not carry literal secret headers.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers, click to expand</summary>
+
+This Dev Note is working context for maintainers; shipped behavior, limits, and rationale live in the sections above, the package code, and the linked Agent Note.
+
+- `src/index.ts` owns credential resolution and MCP transport composition. The [distribution Agent Note](../../../.agents/notes/proposed/architecture/2026-08-29-ranged-plus-patchset-distribution.md) records why this is a complete internal DataOps dependency.
+
+</details>

package/README.zh.md

@@ -0,0 +1,63 @@
+---
+description: "为Streamable HTTP加入per-request credential-backed Bearer authentication的official MCP client behavior。"
+kind: "package-reference"
+---
+
+# @sparkelf/dsh-plugin-mcp-credentials
+
+[English](README.md) | 中文
+
+## 概述
+
+该Host plugin保留official MCP connection、reconnect、tool publication、image-result及lifecycle behavior，同时增加一个Streamable HTTP option：`bearerTokenRef`。Transport会在每次network request前立即resolve该DSH credential，并把current value作为Bearer token发送。
+
+## 目录
+
+- [使用此软件包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制和延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此软件包
+
+使用与official MCP client相同的stdio或`streamable-http` configuration。对于credential-backed HTTP，设置`bearerTokenRef`并compose Credentials；literal `headers.Authorization`与`bearerTokenRef`互斥。DataOps会在内部mount该plugin，因此token rotation无需profile remount即可到达下一次MCP request。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### Credential-backed MCP transport
+
+#### 模型看到什么
+
+模型只看到通过`bearerTokenRef`认证的当前namespaced MCP tool schemas及其results。Credential references及values不会出现在tool arguments、results、prompts、Session events、manifests或deployment locks中。
+
+#### Token 影响
+
+Authentication增加零token。MCP tool schemas及calls保留upstream MCP client持有的token effects。
+
+#### KV Cache 影响
+
+Credential rotation不改变model-visible schemas。Tool discovery或connection loss可能增加或移除schemas，从而改变tool prefix。
+
+## 已知限制和延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅Bearer authentication**：其他HTTP authorization schemes需要proven provider extension point；profile files不得携带literal secret headers。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文，点击展开</summary>
+
+该开发备注是maintainer working context；shipped behavior、limits及rationale以以上sections、package code及linked Agent Note为准。
+
+- `src/index.ts`持有credential resolution及MCP transport composition。[Distribution Agent Note](../../../.agents/notes/proposed/architecture/2026-08-29-ranged-plus-patchset-distribution.zh.md)记录它作为complete internal DataOps dependency的原因。
+
+</details>

package/lib/index.js

@@ -0,0 +1,818 @@
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import z from "@deepseek-ai/schemastery";
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
+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 "@deepseek-ai/dsh-subprocess";
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { z as z$1 } from "zod";
+import { isImageAdmissionError } from "@deepseek-ai/dsh-attachment";
+import { assertSupportedJsonSchema } from "@deepseek-ai/dsh-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
+* `DSH_*` 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 the current bearer credential immediately before each network request. */
+function credentialFetch(ctx, rawRef) {
+	const ref = credentialRef(rawRef);
+	return async (input, init) => {
+		const provider = ctx.get("credentials");
+		if (provider === void 0) throw new Error(`mcp-client: credential service unavailable while resolving "${ref}"`);
+		const resolved = await provider.resolve(ref);
+		if (resolved === void 0) throw new Error(`mcp-client: credential "${ref}" is not configured`);
+		const headers = new Headers(init?.headers);
+		headers.set("Authorization", `Bearer ${resolved.value}`);
+		return globalThis.fetch(input, {
+			...init,
+			headers
+		});
+	};
+}
+/**
+* Create an MCP transport from the resolved plugin config.
+*
+* @param config - Resolved plugin config discriminated on `transport`.
+* @param ctx - Cordis context required only for credential-backed HTTP auth.
+* @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+*/
+function createTransport(config, ctx) {
+	switch (config.transport) {
+		case "stdio": return new StdioClientTransport({
+			command: config.command,
+			args: config.args,
+			env: buildChildEnv(config.env),
+			cwd: config.cwd
+		});
+		case "streamable-http": {
+			const authenticatedFetch = config.bearerTokenRef === void 0 ? void 0 : credentialFetch(ctx, config.bearerTokenRef);
+			return new StreamableHTTPClientTransport(new URL(config.url), {
+				requestInit: { headers: config.headers },
+				...authenticatedFetch === void 0 ? {} : { fetch: authenticatedFetch }
+			});
+		}
+	}
+}
+//#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;
+	/** 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: "dsh-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, ctx));
+			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 @sparkelf/dsh-plugin-mcp-credentials
+*/
+/** 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 per registration scope. Agent-scoped MCP
+* servers may reuse a namespace in another Agent, while global instances and
+* duplicates inside one Agent remain mutually exclusive.
+*/
+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({}),
+	bearerTokenRef: z.string().role("credential-ref"),
+	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+	failOnStartupError: z.boolean().default(false),
+	reconnect: Reconnect
+})]);
+function validateCredentialAuth(ctx, config) {
+	if (config.transport !== "streamable-http" || config.bearerTokenRef === void 0) return;
+	const ref = credentialRef(config.bearerTokenRef);
+	if (Object.keys(config.headers).some((header) => header.toLowerCase() === "authorization")) throw new Error(`mcp-client(${config.serverName}): bearerTokenRef and headers.Authorization cannot be configured together`);
+	if (ctx.get("credentials") === void 0) throw new Error(`mcp-client(${config.serverName}): bearerTokenRef "${ref}" requires the credentials service`);
+}
+/**
+* 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) {
+	validateCredentialAuth(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 };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@sparkelf/dsh-plugin-mcp-credentials`.
+* @module @sparkelf/dsh-plugin-mcp-credentials/invariant
+*/
+const PACKAGE_NAME = "@sparkelf/dsh-plugin-mcp-credentials";
+/** 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,76 @@
+/**
+ * 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 '@deepseek-ai/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. */
+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;
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 @sparkelf/dsh-plugin-mcp-credentials
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ReconnectConfig } from './connection.ts';
+export type { McpResult } 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.
+     */
+    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.
+     */
+    serverName: string;
+    /** MCP endpoint URL. */
+    url: string;
+    /** Additional non-credential headers attached to MCP requests. */
+    headers: Record<string, string>;
+    /** Credential reference resolved immediately before each HTTP request and sent as a Bearer token. */
+    bearerTokenRef?: 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;
+type StdioConfigInput = Omit<StdioConfig, 'args' | 'env' | 'cwd' | 'toolCallTimeoutMs' | 'failOnStartupError'> & Partial<Pick<StdioConfig, 'args' | 'env' | 'cwd' | 'toolCallTimeoutMs' | 'failOnStartupError'>>;
+type StreamableHttpConfigInput = Omit<StreamableHttpConfig, 'headers' | 'toolCallTimeoutMs' | 'failOnStartupError'> & Partial<Pick<StreamableHttpConfig, 'headers' | 'toolCallTimeoutMs' | 'failOnStartupError'>>;
+type ConfigInput = StdioConfigInput | StreamableHttpConfigInput;
+export declare const Config: z<ConfigInput, 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 `@sparkelf/dsh-plugin-mcp-credentials`.
+ * @module @sparkelf/dsh-plugin-mcp-credentials/invariant
+ */
+import type { Context } from '@deepseek-ai/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,56 @@
+/**
+ * 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 '@deepseek-ai/cordis';
+import type { JsonValue } from '@deepseek-ai/dsh-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 PTC mode without discarding protocol blocks. */
+export type McpResult<Structured extends JsonValue = JsonValue> = {
+    content: JsonValue[];
+    structuredContent?: Structured;
+};
+/**
+ * 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,19 @@
+/**
+ * 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 { Context } from '@deepseek-ai/cordis';
+import type { Config } from './index.ts';
+/**
+ * Create an MCP transport from the resolved plugin config.
+ *
+ * @param config - Resolved plugin config discriminated on `transport`.
+ * @param ctx - Cordis context required only for credential-backed HTTP auth.
+ * @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+ */
+export declare function createTransport(config: Config, ctx: Context): Transport;
+//# sourceMappingURL=transport.d.ts.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "dependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.1",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^4.4.3"
+  },
+  "description": "Official MCP client replacement with credential-backed Streamable HTTP Bearer authentication",
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./invariant": {
+      "default": "./lib/invariant.js",
+      "types": "./lib/types/invariant.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "main": "lib/index.js",
+  "name": "@sparkelf/dsh-plugin-mcp-credentials",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-attachment": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-credentials": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-invariants": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-scope": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-subprocess": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-timeout": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/plus/mcp-credentials",
+    "type": "git",
+    "url": "git+https://github.com/SparkElf/deepseek-harness-plus.git"
+  },
+  "type": "module",
+  "types": "lib/types/index.d.ts",
+  "version": "0.1.0-rc.10"
+}