dsh-cc-mcp 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# dsh-cc-mcp
+
+Load Claude Code MCP server configs into DeepSeek Harness as **runtime-registered
+tools** — no config-row writes, no restarts for config changes.
+
+把 Claude Code 的 MCP 配置(`.mcp.json` / plugin.json 内联 `mcpServers`)以运行时注册工具的形式加载进 DSH。
+
+## What it does
+
+| Source | Tool namespace | Notes |
+|---|---|---|
+| Project root `.mcp.json` | `mcp__<server>__<tool>` | DSH-native name, same as `dsh-mcp-client` rows |
+| Plugin root `.mcp.json` / `plugin.json` inline | `mcp__plugin_<name>_<server>__<tool>` | Official CC plugin naming (e.g. `mcp__plugin_asana_asana__asana_create_task`) |
+
+- **Dual-form parsing** (shared `dsh-cc-loader`): accepts both the
+  `{"mcpServers": {...}}` wrapper (project level / community plugins) and the
+  bare server map (official plugin form).
+- **Transports**: `stdio` (command) and `http` (url → streamable-http) register
+  as tools. `sse` / `ws` are reported as unsupported (DSH has no such
+  transport) and never crash anything.
+- **Env secrets stay out of configs**: `${NAME}` placeholders are kept verbatim
+  in the IR and expanded at runtime from `process.env`; `${CLAUDE_PLUGIN_ROOT}`
+  expands to the plugin directory. Nothing is written to disk.
+- **Lazy connections**: tool schemas register eagerly (the model must see the
+  list), the actual server process connects on first call, and disconnects
+  after `idleTimeoutMs` without calls. Dead connections reconnect on the next
+  call.
+- **Hot reload**: editing the project `.mcp.json` rebuilds running sessions'
+  project MCP surface (~1 s).
+- **Conflict semantics**: a server already provided by a preset/host
+  `dsh-mcp-client` row is skipped by default; `"override": true` in the server
+  entry forces the project/plugin connection (agent layer shadows upper
+  layers).
+
+## Trust model ⚠️
+
+`.mcp.json` is **executable project content** — the same trust as
+`package.json` scripts. Installing this plugin enables that. Children run with a
+scrubbed environment (credential-shaped and stale `DSH_*` variables dropped),
+mirroring the official bridge.
+
+## Install (dev / local checkout)
+
+```sh
+# in packages/cc-mcp: install deps (official MCP SDK + shared loader)
+npm install
+
+# user patch layer (hot, no bundle reconcile):
+# append to ~/.dsh/profiles/<profile>/cordis.patch.yml
+- insert:
+    - id: cc-mcp
+      name: 'dsh-cc-mcp'
+      config:
+        enableProject: true
+        pluginRoots: []          # absolute paths to plugin dirs (future M4 feeds this)
+        idleTimeoutMs: 300000
+        toolCallTimeoutMs: 60000
+        watchProject: true
+```
+
+Windows absolute paths in `pluginRoots` need `file:///`? No — these are plain
+directory paths inside the config, not module specifiers.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enableProject` | `true` | read `<projectRoot>/.mcp.json` per session |
+| `pluginRoots` | `[]` | extra plugin directories to scan (`.mcp.json` + `plugin.json`) |
+| `idleTimeoutMs` | `300000` | idle disconnect (0 = never) |
+| `toolCallTimeoutMs` | `60000` | per-call timeout |
+| `watchProject` | `true` | hot-reload the project `.mcp.json` |
+
+## Example
+
+`<project>/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
+    }
+  }
+}
+```
+
+Sessions in that project get `mcp__github__create_issue` etc. on first tool
+list assembly.
+
+## License
+
+MIT — runtime registration pattern ported from
+[dsh-project-mcp-bridge](https://github.com/KYinCode/dsh-project-mcp-bridge)
+(MIT, © KYinCode); parsing lives in `dsh-cc-loader`.

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+- insert:
+    - id: cc-mcp
+      name: 'dsh-cc-mcp'
+      config:
+        enableProject: true
+        pluginRoots: []
+        idleTimeoutMs: 300000
+        toolCallTimeoutMs: 60000
+        watchProject: true

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "dsh-cc-mcp",
+  "version": "0.1.0",
+  "description": "Load Claude Code MCP server configs (.mcp.json / plugin.json inline mcpServers) into DSH as runtime-registered tools: project-root .mcp.json → mcp__<server>__<tool>, plugin MCP → mcp__plugin_<name>_<server>__<tool> (official CC naming). Client bridge on the official @modelcontextprotocol/sdk — no config-row writes, zero-write path preserved.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "claude-code",
+    "mcp",
+    "claude"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "dsh-cc-loader": "^0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-subprocess": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-subprocess": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-subprocess": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": "git+https://github.com/Bcy2020/dsh-cc-ecosystem.git",
+  "homepage": "https://github.com/Bcy2020/dsh-cc-ecosystem"
+}

package/src/index.js

@@ -0,0 +1,334 @@
+// dsh-cc-mcp — load Claude Code MCP configs into DSH as runtime-registered
+// tools, on the official @modelcontextprotocol/sdk.
+//
+// Sources (parsed by the shared dsh-cc-loader):
+//   - project root .mcp.json            → mcp__<server>__<tool> (DSH-native)
+//   - plugin roots (config.pluginRoots) → mcp__plugin_<name>_<server>__<tool>
+//     (official CC plugin naming), from each plugin's .mcp.json / plugin.json
+//
+// Modeled on dsh-project-mcp-bridge (MIT): tools register eagerly into the
+// agent scope layer (agent/created), connections are lazy with an idle
+// timeout, and project .mcp.json changes hot-reload. Env values are expanded
+// at runtime from process.env — nothing is written to disk.
+//
+// Safety: apply() never throws synchronously; per-agent failures are logged,
+// never fatal to the host.
+
+import { readFile, mkdir, appendFile } from 'node:fs/promises'
+import { watchFile, unwatchFile } from 'node:fs'
+import { join } from 'node:path'
+import Schema from '@deepseek-ai/schemastery'
+import { findProjectRoot, discoverProjectMcp, discoverPluginRoot } from 'dsh-cc-loader'
+
+// Re-exported for callers that need the dir-basename fallback name without a
+// manifest (discoverPluginRoot prefers manifest `name`; pluginNameOf is the
+// no-manifest fallback).
+export { pluginNameOf } from 'dsh-cc-loader'
+import {
+  publicToolName, connectAndList, createDefinition, clearIdle,
+} from './register.js'
+
+export const name = 'dsh-cc-mcp'
+export const inject = []
+
+export const Config = Schema.object({
+  enableProject: Schema.boolean().default(true),
+  pluginRoots: Schema.array(Schema.string()).default([]),
+  idleTimeoutMs: Schema.number().default(300000),
+  toolCallTimeoutMs: Schema.number().default(60000),
+  watchProject: Schema.boolean().default(true),
+})
+
+const DEFAULT_CALL_TIMEOUT_MS = 60000
+const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60 * 1000
+const WATCH_DEBOUNCE_MS = 300
+
+// Per-agent live controllers; module-level because agent/created wiring must
+// outlive one listener call. Cleanup on agent/disposed and plugin unload.
+const agentStates = new Map()
+const projectWatchers = new Map() // projectRoot -> { controllers: Set, timer }
+
+function log(ctx, level, message) {
+  try { ctx.logger?.[level]?.(`dsh-cc-mcp: ${message}`) } catch { /* logger absence is not fatal */ }
+}
+
+// ─── per-agent controller ────────────────────────────────────────────────────
+
+function createController(ctx, agent, agentCtx, baseCwd, config) {
+  return {
+    ctx, agent, agentCtx, baseCwd, config,
+    servers: new Map(),
+    queue: Promise.resolve(),
+    disposed: false,
+    watcherRef: null,
+  }
+}
+
+function enqueue(state, fn) {
+  state.queue = state.queue.then(fn).catch((error) => {
+    if (!state.disposed) log(state.ctx, 'error', `agent ${state.agent.id}: ${String(error)}`)
+  })
+  return state.queue
+}
+
+function cleanupState(ctx, state, reason) {
+  if (state.disposed) return
+  state.disposed = true
+  agentStates.delete(state.agent.id)
+  for (const record of [...state.servers.values()]) teardownServer(state, record, reason).catch(() => {})
+  detachWatcher(state)
+  log(ctx, 'info', `agent ${state.agent.id} (${state.baseCwd}): cleanup (${reason})`)
+}
+
+// ─── discovery → normalized entries ─────────────────────────────────────────
+
+/** ${CLAUDE_PLUGIN_ROOT} expansion for plugin entries; project entries untouched. */
+function expandEntry(entry, pluginRoot) {
+  if (!pluginRoot) return entry
+  const command = entry.command?.includes('${CLAUDE_PLUGIN_ROOT}')
+    ? entry.command.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot) : entry.command
+  const args = entry.args.map((a) => a.includes('${CLAUDE_PLUGIN_ROOT}')
+    ? a.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot) : a)
+  const cwd = entry.cwd?.includes('${CLAUDE_PLUGIN_ROOT}')
+    ? entry.cwd.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot) : entry.cwd
+  return { ...entry, command, args, cwd }
+}
+
+/** Fold loader entries into bridge-style runtime entries (defaults + expansion). */
+export function toRuntimeEntries(servers, opts = {}) {
+  const { pluginRoot, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS, toolCallTimeoutMs = DEFAULT_CALL_TIMEOUT_MS } = opts
+  const out = []
+  for (const s of servers) {
+    if (s.status !== 'DIRECT') continue // UNSUPPORTED (sse/ws) reported, not registered
+    out.push({
+      ...expandEntry(s, pluginRoot),
+      toolCallTimeoutMs: s.toolCallTimeoutMs ?? toolCallTimeoutMs,
+      idleTimeoutMs: s.idleTimeoutMs ?? idleTimeoutMs,
+    })
+  }
+  return out
+}
+
+async function collectEntries(state) {
+  const cfg = state.config
+  const entries = []
+  const sources = []
+  if (cfg.enableProject && state.projectRoot !== undefined) {
+    const found = await discoverProjectMcp(state.projectRoot, { warn: (m) => log(state.ctx, 'warn', `agent ${state.agent.id}: ${m}`) })
+    entries.push(...toRuntimeEntries(found.servers, { idleTimeoutMs: cfg.idleTimeoutMs, toolCallTimeoutMs: cfg.toolCallTimeoutMs }))
+    sources.push(...found.sources)
+  }
+  for (const root of cfg.pluginRoots) {
+    // discoverPluginRoot inventories the whole plugin (M4): manifest name
+    // wins over the directory name for the tool namespace, and manifest
+    // `mcpServers` path/inline configs are included alongside .mcp.json.
+    const plugin = await discoverPluginRoot(root, { warn: (m) => log(state.ctx, 'warn', `agent ${state.agent.id}: ${m}`) })
+    entries.push(...toRuntimeEntries(plugin.components.mcp.servers, {
+      pluginRoot: root,
+      idleTimeoutMs: cfg.idleTimeoutMs,
+      toolCallTimeoutMs: cfg.toolCallTimeoutMs,
+    }))
+    sources.push(...plugin.components.mcp.sources)
+  }
+  return { entries, sources }
+}
+
+// ─── schema sync + registration ──────────────────────────────────────────────
+
+function hasUpperServerTools(state, prefix) {
+  try {
+    const schemas = state.agentCtx.tools.schemas(state.agent)
+    return Array.isArray(schemas) && schemas.some((s) => typeof s.name === 'string' && s.name.startsWith(prefix))
+  } catch {
+    return false
+  }
+}
+
+async function syncSchema(state, entry) {
+  const { client, tools } = await connectAndList(entry, state.baseCwd)
+  try {
+    const definitions = new Map()
+    const prefix = entry.pluginName ? `mcp__plugin_${entry.pluginName}_${entry.serverName}__` : `mcp__${entry.serverName}__`
+    for (const tool of tools) {
+      const publicName = publicToolName(
+        { serverName: entry.serverName, pluginName: entry.pluginName },
+        tool.name,
+      )
+      if (definitions.has(publicName)) {
+        throw new Error(`server listed tool "${tool.name}" more than once — invalid tool list`)
+      }
+      definitions.set(publicName, createDefinition(state, entry, tool.name, publicName, tool))
+    }
+    const disposers = []
+    for (const [publicName, definition] of definitions) {
+      try {
+        disposers.push(state.agentCtx.tools.register(definition))
+      } catch (error) {
+        log(state.ctx, 'error', `agent ${state.agent.id}: registering ${publicName} failed: ${String(error)}`)
+      }
+    }
+    return {
+      toolCount: disposers.length,
+      prefix,
+      unregister: () => {
+        for (const dispose of disposers) {
+          try { dispose() } catch { /* best effort */ }
+        }
+      },
+    }
+  } finally {
+    try { await client.close() } catch { /* best effort */ }
+  }
+}
+
+async function setupServer(state, entry) {
+  const serverName = entry.serverName
+  const prefix = entry.pluginName ? `mcp__plugin_${entry.pluginName}_${serverName}__` : `mcp__${serverName}__`
+  const upper = hasUpperServerTools(state, prefix)
+  if (!entry.override && upper) {
+    log(state.ctx, 'info', `agent ${state.agent.id}: server ${serverName} already provided by preset/host MCP — skipped (set "override": true to force)`)
+    return
+  }
+  try {
+    const { toolCount, unregister } = await syncSchema(state, entry)
+    if (state.disposed) {
+      unregister()
+      return
+    }
+    state.servers.set(serverName, { entry, unregister, conn: null, connecting: null })
+    const shadowed = upper ? ' (agent layer shadows upper-layer registration(s))' : ''
+    log(state.ctx, 'info', `agent ${state.agent.id}: registered ${toolCount} tool(s) from server ${serverName}${shadowed}`)
+  } catch (error) {
+    log(state.ctx, 'error', `agent ${state.agent.id}: server ${serverName} not loaded: ${String(error)}`)
+  }
+}
+
+async function teardownServer(state, record, reason) {
+  state.servers.delete(record.entry.serverName)
+  try { record.unregister() } catch { /* best effort */ }
+  const conn = record.conn
+  if (conn !== null) {
+    record.conn = null
+    clearIdle(conn)
+    try { await conn.client.close() } catch { /* best effort */ }
+  }
+  log(state.ctx, 'info', `agent ${state.agent.id}: server ${record.entry.serverName}: ${reason}`)
+}
+
+// ─── config application (initial load + hot reload share one path) ──────────
+
+async function applyConfig(state) {
+  if (state.disposed) return
+  const { entries } = await collectEntries(state)
+  for (const record of [...state.servers.values()]) {
+    await teardownServer(state, record, 'config change — rebuilding')
+  }
+  for (const entry of entries) {
+    await setupServer(state, entry)
+  }
+}
+
+async function reloadFromDisk(state) {
+  if (state.disposed) return
+  try {
+    await applyConfig(state)
+  } catch (error) {
+    log(state.ctx, 'error', `agent ${state.agent.id}: reload failed: ${String(error)}`)
+  }
+}
+
+// ─── watcher (project .mcp.json hot reload) ──────────────────────────────────
+
+function attachWatcher(state) {
+  if (!state.config.watchProject || state.projectRoot === undefined) return
+  const root = state.projectRoot
+  let w = projectWatchers.get(root)
+  if (w === undefined) {
+    w = { controllers: new Set(), timer: null }
+    projectWatchers.set(root, w)
+    const configPath = join(root, '.mcp.json')
+    const onChange = () => {
+      if (w.timer !== null) clearTimeout(w.timer)
+      w.timer = setTimeout(() => {
+        w.timer = null
+        for (const controller of [...w.controllers]) {
+          if (!controller.disposed) enqueue(controller, () => reloadFromDisk(controller))
+        }
+      }, WATCH_DEBOUNCE_MS)
+    }
+    try {
+      watchFile(configPath, { interval: 500 }, onChange)
+    } catch (error) {
+      log(state.ctx, 'warn', `watch ${configPath} failed: ${String(error)} — hot reload disabled`)
+    }
+  }
+  w.controllers.add(state)
+  state.watcherRef = w
+}
+
+function detachWatcher(state) {
+  const w = state.watcherRef
+  if (w === undefined) return
+  state.watcherRef = undefined
+  w.controllers.delete(state)
+  if (w.controllers.size === 0 && state.projectRoot !== undefined) {
+    if (w.timer !== null) clearTimeout(w.timer)
+    try { unwatchFile(join(state.projectRoot, '.mcp.json')) } catch { /* best effort */ }
+    projectWatchers.delete(state.projectRoot)
+  }
+}
+
+// ─── agent wiring ────────────────────────────────────────────────────────────
+
+function agentCwd(agent) {
+  return (agent && agent.session && agent.session.header && agent.session.header.cwd) ||
+    (agent && agent.header && agent.header.cwd) ||
+    undefined
+}
+
+async function wireAgent(ctx, agent, config) {
+  const cwd = agentCwd(agent)
+  if (!cwd) {
+    log(ctx, 'warn', `agent ${agent.id}: no session cwd found — project MCP skipped`)
+    return
+  }
+  const agentCtx = agent.ctx
+  if (!agentCtx || typeof agentCtx.tools?.register !== 'function' || typeof agentCtx.tools?.schemas !== 'function') {
+    log(ctx, 'warn', `agent ${agent.id} (${cwd}): agent tools service unavailable — project MCP skipped`)
+    return
+  }
+  const state = createController(ctx, agent, agentCtx, cwd, config)
+  const projectRoot = config.enableProject ? await findProjectRoot(cwd) : undefined
+  state.projectRoot = projectRoot
+  agentStates.set(agent.id, state)
+  attachWatcher(state)
+  enqueue(state, () => reloadFromDisk(state))
+}
+
+export function apply(ctx, config) {
+  // apply() must never throw synchronously: a throw here kills the host.
+  const wire = async (payload) => {
+    const agent = payload && payload.agent
+    if (!agent) return
+    try {
+      await wireAgent(ctx, agent, config)
+    } catch (error) {
+      log(ctx, 'error', `agent ${agent.id}: unexpected failure: ${String(error)}`)
+    }
+  }
+  try {
+    ctx.on('agent/created', (payload) => { void wire(payload) })
+    ctx.on('agent/disposed', (payload) => {
+      const agent = payload && payload.agent
+      if (!agent) return
+      const state = agentStates.get(agent.id)
+      if (state !== undefined) cleanupState(ctx, state, 'agent disposed')
+    })
+    ctx.effect(() => () => {
+      for (const state of [...agentStates.values()]) cleanupState(ctx, state, 'plugin reloaded')
+    })
+    log(ctx, 'info', `plugin active — project .mcp.json ${config.enableProject ? 'enabled' : 'disabled'}, ${config.pluginRoots.length} plugin root(s)`)
+  } catch (error) {
+    log(ctx, 'error', `apply failed: ${String(error)}`)
+  }
+}

package/src/register.js

@@ -0,0 +1,266 @@
+// dsh-cc-mcp — tool definition / MCP client plumbing (ported from
+// dsh-project-mcp-bridge, MIT, KYinCode, with plugin-namespace support).
+//
+// All functions here are pure-ish (no plugin wiring): they build tool
+// definitions from MCP tool schemas and drive the official MCP SDK client.
+// Env values are expanded at runtime from process.env (never inlined into
+// any config); `${CLAUDE_PLUGIN_ROOT}` expands to the plugin directory.
+
+import { createHash } from 'node:crypto'
+import { isAbsolute, join } from 'node:path'
+import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+
+export const MAX_PUBLIC_NAME_LENGTH = 64
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g
+const HASH_LENGTH = 12
+
+/**
+ * CC tool naming: plugin MCP → mcp__plugin_<plugin>_<server>__<tool>;
+ * project MCP → mcp__<server>__<tool> (DSH-native). Normalized per the
+ * DeepSeek name contract: illegal chars → `_`, overlong → sha256 hash suffix.
+ * @param {{serverName: string, pluginName?: string}} scope
+ * @param {string} rawName
+ * @returns {string}
+ */
+export function publicToolName(scope, rawName) {
+  const prefix = scope.pluginName
+    ? `mcp__plugin_${scope.pluginName}_${scope.serverName}__`
+    : `mcp__${scope.serverName}__`
+  const joined = prefix + rawName
+  const normalized = joined.replace(INVALID_NAME_CHARS, '_')
+  if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized
+  const hash = createHash('sha256').update(`${prefix}\0${rawName}`).digest('hex').slice(0, HASH_LENGTH)
+  return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`
+}
+
+/** Replace ${NAME} with process.env.NAME; missing vars are left verbatim and warned. */
+export function interpolateEnv(value, warn) {
+  return String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, key) => {
+    const v = process.env[key]
+    if (v === undefined) {
+      warn(`environment variable ${key} is not set`)
+      return match
+    }
+    return v
+  })
+}
+
+/**
+ * Expand ${CLAUDE_PLUGIN_ROOT} (plugin dir) in a command/arg/cwd string.
+ * @param {string} value
+ * @param {string} pluginRoot - absolute plugin directory
+ * @returns {string}
+ */
+export function expandPluginRoot(value, pluginRoot) {
+  if (!value.includes('${CLAUDE_PLUGIN_ROOT}')) return value
+  return value.replaceAll('${CLAUDE_PLUGIN_ROOT}', pluginRoot)
+}
+
+function createTransport(entry, baseCwd) {
+  if (entry.transport === 'stdio') {
+    const cwd = entry.cwd === undefined
+      ? baseCwd
+      : isAbsolute(entry.cwd) ? entry.cwd : join(baseCwd, entry.cwd)
+    const warn = () => {}
+    const env = {}
+    for (const [k, v] of Object.entries(entry.env ?? {})) env[k] = interpolateEnv(v, warn)
+    return new StdioClientTransport({
+      command: entry.command,
+      args: entry.args,
+      // Privilege reduction (mirrors the official bridge): credential-shaped
+      // and stale DSH_* variables dropped, then the config's explicit env on top.
+      env: { ...scrubbedParentEnv(), ...env },
+      cwd,
+    })
+  }
+  return new StreamableHTTPClientTransport(new URL(entry.url), {
+    headers: Object.fromEntries(
+      Object.entries(entry.headers ?? {}).map(([k, v]) => [k, interpolateEnv(v, () => {})]),
+    ),
+  })
+}
+
+/** Connect a fresh client and drain tools/list; closes it on failure. */
+export async function connectAndList(entry, baseCwd, onClose) {
+  const client = new Client({ name: 'dsh-cc-mcp', version: '0.1.0' })
+  const transport = createTransport(entry, baseCwd)
+  let closed = false
+  client.onclose = () => {
+    closed = true
+    if (onClose) onClose()
+  }
+  try {
+    await client.connect(transport)
+    const tools = []
+    let cursor
+    do {
+      const page = await client.listTools({ cursor })
+      tools.push(...page.tools)
+      cursor = page.nextCursor
+    } while (cursor)
+    return { client, tools, closed }
+  } catch (error) {
+    try { await client.close() } catch { /* best effort */ }
+    throw error
+  }
+}
+
+/** MCP content blocks → model-facing text (mirrors dsh-mcp-client). */
+export function extractText(mcpContent) {
+  const parts = []
+  for (const value of mcpContent) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      parts.push('[unsupported content type: unknown]')
+      continue
+    }
+    switch (value.type) {
+      case 'text':
+        parts.push(typeof value.text === 'string' ? value.text : '')
+        break
+      case 'image':
+        parts.push(`[image: ${value.mimeType ?? 'unknown'}]`)
+        break
+      case 'audio':
+        parts.push(`[audio: ${value.mimeType ?? 'unknown'}]`)
+        break
+      case 'resource':
+        parts.push(`[resource: ${value.resource?.uri ?? 'unknown'}]`)
+        break
+      default:
+        parts.push(`[unsupported content type: ${value.type ?? 'unknown'}]`)
+    }
+  }
+  return parts.join('\n')
+}
+
+/** callTool result → model-facing content (isError results throw). */
+export function mapResult(result) {
+  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 !== undefined ? { structuredContent: result.structuredContent } : {}) }
+  }
+  const text = extractText(result.content)
+  if (result.isError === true) throw new Error(text)
+  return { content: result.content, ...(result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}) }
+}
+
+/** Build the canonical output declaration (structured content falls back to JsonValue). */
+export function createOutput(rawName) {
+  return {
+    schema: {
+      type: 'object',
+      properties: {
+        content: { type: 'array', items: {} },
+        structuredContent: {},
+      },
+      required: ['content'],
+      additionalProperties: false,
+    },
+    render(_args, value) {
+      return [{ type: 'text', text: extractText(value.content) }]
+    },
+  }
+}
+
+/**
+ * One tool definition. `execute` lazily connects (first call) and re-arms the
+ * per-connection idle timer around the call. `state.servers` holds the live
+ * records; see the controller in index.js.
+ */
+export function createDefinition(state, entry, rawName, publicName, tool) {
+  return {
+    name: publicName,
+    description: typeof tool.description === 'string' ? tool.description : '',
+    parameters: tool.inputSchema,
+    output: createOutput(rawName),
+    async execute(args, exec) {
+      const record = state.servers.get(entry.serverName)
+      if (record === undefined) throw new Error(`server ${entry.serverName} is no longer configured — reload the project config`)
+      const conn = await ensureConnected(state, record)
+      conn.busy++
+      try {
+        armIdle(state, record, conn)
+        const signal = exec && exec.signal
+          ? AbortSignal.any([exec.signal, AbortSignal.timeout(record.entry.toolCallTimeoutMs)])
+          : AbortSignal.timeout(record.entry.toolCallTimeoutMs)
+        const result = await conn.client.callTool(
+          { name: rawName, arguments: typeof args === 'object' && args !== null ? args : {} },
+          undefined,
+          { signal },
+        )
+        return mapResult(result)
+      } finally {
+        conn.busy--
+        armIdle(state, record, conn)
+      }
+    },
+  }
+}
+
+// ─── connection lifecycle helpers (shared with the controller) ──────────────
+
+const MAX_TIMER_DELAY_MS = 0x7fffffff
+
+export function armIdle(state, record, conn) {
+  clearIdle(conn)
+  if (conn.busy > 0) return
+  const timeout = record.entry.idleTimeoutMs
+  if (timeout <= 0) return
+  conn.idleTimer = setTimeout(() => {
+    conn.idleTimer = null
+    if (record.conn !== conn) return
+    record.conn = null
+    conn.client.close().catch(() => {})
+  }, Math.min(timeout, MAX_TIMER_DELAY_MS))
+  conn.idleTimer.unref?.()
+}
+
+export function clearIdle(conn) {
+  if (conn.idleTimer !== null) {
+    clearTimeout(conn.idleTimer)
+    conn.idleTimer = null
+  }
+}
+
+/** Get the live connection for a record, connecting lazily when absent. */
+export function ensureConnected(state, record) {
+  if (record.conn !== null) return Promise.resolve(record.conn)
+  if (record.connecting === null) {
+    const attempt = openConnection(state, record)
+    record.connecting = attempt
+    attempt.catch(() => {}).finally(() => {
+      if (record.connecting === attempt) record.connecting = null
+    })
+  }
+  return record.connecting
+}
+
+export async function openConnection(state, record) {
+  const entry = record.entry
+  const conn = { client: null, idleTimer: null, busy: 0 }
+  const { client, closed } = await connectAndList(entry, state.baseCwd, () => {
+    if (record.conn === conn) {
+      record.conn = null
+      clearIdle(conn)
+    }
+  })
+  conn.client = client
+  if (state.disposed || state.servers.get(entry.serverName) !== record) {
+    try { await client.close() } catch { /* best effort */ }
+    throw new Error(`agent disposed or config reloaded during connect`)
+  }
+  record.conn = conn
+  if (closed) {
+    record.conn = null
+    clearIdle(conn)
+    try { await client.close() } catch { /* best effort */ }
+    throw new Error(`connection closed during connect`)
+  }
+  armIdle(state, record, conn)
+  return conn
+}