@crazx/dsh-mcp-client 0.1.0-rc.7.zw.2

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-mcp-client`.
+* @module @deepseek-ai/dsh-mcp-client/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-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,101 @@
+/**
+ * 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';
+import type { McpClientStatus } from './types.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>;
+}
+/** Supervisor state facts {@link computeMcpClientStatus} derives a status from. */
+export interface McpStatusFacts {
+    /** Disposal started; the supervisor makes no further transitions. */
+    readonly disposed: boolean;
+    /** A client generation currently holds the connection slot. */
+    readonly hasClient: boolean;
+    /** A reconnect backoff timer is armed. */
+    readonly hasTimer: boolean;
+    /** The current generation finished connect plus its initial tool sync. */
+    readonly connected: boolean;
+    /** Consecutive failed attempts within the current outage. */
+    readonly failedAttempts: number;
+}
+/**
+ * Derive the observable connection status from supervisor state facts.
+ *
+ * Evaluation order is load-bearing: `failed` is judged before `reconnecting`
+ * because a give-up leaves `failedAttempts` above zero with no client and no
+ * timer, and `connected` is judged before the in-flight branches because the
+ * outage budget resets from that mark.
+ *
+ * @param facts - the supervisor's current state facts.
+ * @returns the committed status those facts represent.
+ */
+export declare function computeMcpClientStatus(facts: McpStatusFacts): McpClientStatus;
+/**
+ * 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,83 @@
+/**
+ * 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 @deepseek-ai/dsh-mcp-client
+ */
+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';
+export type { McpClientStatus } from './types.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 headers attached to MCP requests. */
+    headers: Record<string, 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 `@deepseek-ai/dsh-mcp-client`.
+ * @module @deepseek-ai/dsh-mcp-client/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,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 '@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 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/lib/types/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Observable connection state of one mcp-client instance and the Cordis event
+ * that publishes it. Types only — the connection supervisor in `connection.ts`
+ * owns the runtime state and emits at each commit point.
+ *
+ * @module @deepseek-ai/dsh-mcp-client
+ */
+/** Connection state of one supervised MCP server connection. */
+export type McpClientStatus = 'connecting' | 'connected' | 'reconnecting' | 'failed' | 'disposed';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * One MCP server connection reached a new committed state, or its live
+         * tool registration count changed. Emitted only after the supervisor
+         * mutated its state, never before. The emitting fiber's context and every
+         * ancestor context observe this through the shared event bus; `serverName`
+         * disambiguates concurrent instances. Listener failures are contained and
+         * logged by the emitter, so an observer defect cannot disrupt the
+         * supervisor's own state machine.
+         * @param serverName - the configured namespace of the emitting instance.
+         * @param status - the connection state at this commit point.
+         * @param toolCount - number of tools this server currently has registered on `ctx.tools`.
+         * @mode emit
+         */
+        'mcp-client/status'(serverName: string, status: McpClientStatus, toolCount: number): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@crazx/dsh-mcp-client",
+  "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
+  "version": "0.1.0-rc.7.zw.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aka-danielZhang/deepseek-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": {
+    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@deepseek-ai/schemastery": "^0.1.0-rc.7",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-attachment-local": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@modelcontextprotocol/server-everything": "^2026.7.4",
+    "@modelcontextprotocol/server-filesystem": "^2026.7.4",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  }
+}