dsh-claude-compat 0.3.0 → 0.7.0

package/src/index.js

@@ -1,13 +1,15 @@
 // dsh-claude-compat — bridge Claude Code's .claude/ into DSH.
 //
-// Two contributions to the live runtime:
-//   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md
-//      and <projectRoot>/.claude/commands/*.md (plus the user-level
-//      ~/.claude/skills and ~/.claude/commands), surfaces them as DSH skills so
-//      the `/skill-name` slash trigger, the `skill` tool, and the model-visible
-//      catalog pick them up natively. Only name+description load at discovery;
-//      the body loads on demand — same contract as the shipped filesystem
-//      provider.
+// Contributions to the live runtime:
+//   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md,
+//      <projectRoot>/.claude/commands/*.md and <projectRoot>/.claude/agents/*.md
+//      (plus the user-level ~/.claude equivalents), surfaces them as DSH skills
+//      so the `/skill-name` slash trigger, the `skill` tool, and the
+//      model-visible catalog pick them up natively. Only name+description load
+//      at discovery; the body loads on demand — same contract as the shipped
+//      filesystem provider. Agents are a delegation shim: DSH has no markdown
+//      subagent format, so each agent file becomes a skill whose body leads
+//      with an explicit "delegate with this persona" instruction.
 //   2. Rules message-stream injection — injects <projectRoot>/.claude/rules/*.md
 //      and ~/.claude/rules/*.md as ONE user-role <system-reminder> message
 //      prepended at the front of the message array, once per session
@@ -16,6 +18,11 @@
 //      project .claude winning over ~/.claude.
 //      CLAUDE.md / AGENTS.md are already handled by dsh-agent-instructions,
 //      so we do NOT re-inject them here.
+//   3. Hooks (Claude Code subset PreToolUse/PostToolUse/UserPromptSubmit) from
+//      .claude/settings.json — bridged onto tools/pre-execute,
+//      tools/post-execute and agent/pre-step (see src/hooks.js).
+//   4. MCP servers from <projectRoot>/.mcp.json — mounted as dsh-mcp-client
+//      plugin instances at startup from the launch workspace (see src/mcp.js).
 //
 // Skill name flattening: .claude/skills/gitnexus/gitnexus-guide/SKILL.md →
 // "gitnexus-gitnexus-guide" (DSH skill names must be kebab-case; the shipped
@@ -36,14 +43,25 @@
 // launched from anywhere). Editing a rule mid-session takes effect in the
 // next session.
 
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, dirname, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { parse } from 'yaml';
 import { isSkillName } from '@deepseek-ai/dsh-skill';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { discoverAgents, renderAgentContent } from './agents.js';
+import { registerHooks } from './hooks.js';
+import { mountMcpServers, mountMcpConfigs } from './mcp.js';
+import { discoverPluginContent, readInstalledClaudePlugins, translatePluginMcp } from './plugins.js';
+import {
+  findProjectRoot,
+  findProjectRootSync,
+  listMdFilesSync,
+  parseFrontmatter,
+  readTextSafe,
+  resolveUserClaudeDir,
+  stringField,
+} from './lib.js';
 
 export const name = 'claude-compat';
 export const inject = ['skills'];
@@ -63,6 +81,20 @@ export const Config = z.object({
   userRulesMaxBytes: z.number().default(65536),
   enableRules: z.boolean().default(true),
   enableSkills: z.boolean().default(true),
+  enableMcp: z.boolean().default(true),
+  mcpFailOnStartupError: z.boolean().default(false),
+  enableHooks: z.boolean().default(true),
+  hooksTimeoutMs: z.number().default(60000),
+  enableAgents: z.boolean().default(true),
+  // Claude Code plugin-marketplace installs (~/.claude/plugins). Skills,
+  // commands and agents surface at pluginSkillRank (750: the long tail —
+  // everything else wins collisions). Plugin MCP servers are opt-in via
+  // enablePluginMcp (mounting third-party MCP is a bigger trust step).
+  enablePlugins: z.boolean().default(true),
+  pluginSkillRank: z.number().default(750),
+  pluginSkillSource: z.string().default('claude-plugin'),
+  pluginsRoot: z.string().default('~/.claude/plugins'),
+  enablePluginMcp: z.boolean().default(false),
 });
 
 export function apply(ctx, config = {}) {
@@ -73,6 +105,36 @@ export function apply(ctx, config = {}) {
   if (config.enableRules !== false) {
     registerRulesSection(ctx, config);
   }
+  if (config.enableHooks !== false) {
+    registerHooks(ctx, config);
+  }
+  if (config.enableMcp !== false) {
+    // Process-lifetime mount — deliberately NOT session-scoped (see src/mcp.js).
+    mountMcpServers(ctx, config).catch((error) => {
+      console.warn('dsh-claude-compat: MCP mount failed:', error?.message ?? error);
+    });
+    if (config.enablePlugins !== false && config.enablePluginMcp === true) {
+      mountPluginMcp(ctx, config).catch((error) => {
+        console.warn('dsh-claude-compat: plugin MCP mount failed:', error?.message ?? error);
+      });
+    }
+  }
+}
+
+// Opt-in: translate every installed plugin's MCP config and mount alongside
+// the project .mcp.json servers (see src/mcp.js mountMcpConfigs).
+async function mountPluginMcp(ctx, config) {
+  for (const plugin of readInstalledClaudePlugins(config.pluginsRoot)) {
+    const raw = await readTextSafe(join(plugin.installPath, '.claude-plugin', 'plugin.json'));
+    if (raw === undefined) continue;
+    let manifest;
+    try { manifest = JSON.parse(raw); } catch { continue; }
+    const { servers, warns } = translatePluginMcp(manifest, plugin.installPath, {
+      failOnStartupError: config.mcpFailOnStartupError ?? false,
+    });
+    warns.forEach((w) => console.warn(`dsh-claude-compat: plugin ${plugin.key}: ${w}`));
+    if (servers.length > 0) await mountMcpConfigs(ctx, servers);
+  }
 }
 
 // ─── skill provider ──────────────────────────────────────────────────────────
@@ -87,6 +149,7 @@ class ClaudeCompatSkillProvider {
     this.userSkillRank = config.userSkillRank ?? 700;
     this.userSkillSource = config.userSkillSource ?? 'user-claude';
     this.userClaudeDir = resolveUserClaudeDir(config.userClaudeDir);
+    this.control = control;
     control.signal.addEventListener('abort', () => {}, { once: true });
   }
 
@@ -103,17 +166,86 @@ class ClaudeCompatSkillProvider {
       }
     }
     await this.addRootCandidates(candidates, this.userClaudeDir, this.userSkillSource, this.userSkillRank);
+    if (this.config.enablePluginManager !== false) {
+      candidates.push(this.managerSkillCandidate('cc-plugin',
+        'Manage Claude Code plugins and marketplaces: list, install, uninstall, enable, disable, update, search.',
+        'User wants to install, list, enable/disable, update, or uninstall Claude Code plugins, or manage plugin marketplaces. Usage: /cc-plugin, /cc-plugin <name>[@marketplace], /cc-plugin install|uninstall|enable|disable|update|search ..., /cc-plugin marketplace list|add|remove|update.',
+        (await import('./plugin-manager.js')).PLUGIN_SKILL_BODY));
+      candidates.push(this.reloadSkillDef('reload-cc-plugins',
+        'Hot-reload the skill catalog: pick up newly installed/removed Claude Code plugin skills without a new session.'));
+      candidates.push(this.reloadSkillDef('reload-skills',
+        'Hot-reload the skill catalog (alias of /reload-cc-plugins).'));
+      candidates.push(this.managerSkillCandidate('cc-resume',
+        'List and import Claude Code sessions into DSH: browse ~/.claude/projects history and resume any conversation.',
+        'User wants to resume, list, or import a Claude Code conversation/session into DSH. Usage: /cc-resume list, /cc-resume import <sessionId>.',
+        (await import('./cc-resume-skill.mjs')).CC_RESUME_SKILL_BODY));
+    }
+    if (this.config.enablePlugins !== false) {
+      const pluginCandidates = await discoverPluginContent(
+        this.config.pluginsRoot, this.name, this.config.pluginSkillSource ?? 'claude-plugin',
+        this.config.pluginSkillRank ?? 750, { enableAgents: this.config.enableAgents });
+      candidates.push(...pluginCandidates);
+    }
     return candidates;
   }
 
+  // Invalidate fires when the definition is actually loaded (get()), not at
+  // list() time — loading the reload skill IS the reload.
+  reloadSkillDef(name, description) {
+    return {
+      name,
+      description,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'claude-compat',
+      source: 'claude-compat-manager',
+      rank: this.config.pluginManagerRank ?? 40,
+      locator: { kind: 'inline', path: import.meta.url },
+      get: async () => {
+        try { this.control?.invalidate?.(); } catch { /* best-effort */ }
+        return {
+          name,
+          description,
+          body: `# Catalog reloaded ✅
+
+The DSH skill catalog cache was just dropped and observers notified.
+Freshly installed/removed skills are now visible in this session (the skill
+picker refreshes automatically on the next catalog read).
+
+Notes:
+- New skills from \`/plugin install\` or edits under \`.claude\` are live now.
+- MCP servers shipped by plugins still require a DSH restart (process-lifetime mount).
+- \`/reload-cc-plugins\` and \`/reload-skills\` are aliases.`,
+        };
+      },
+    };
+  }
+
+  managerSkillCandidate(name, description, whenToUse, body) {
+    return {
+      name,
+      description,
+      whenToUse,
+      invocation: { modelInvocable: true, userInvocable: true },
+      provider: 'claude-compat',
+      source: 'claude-compat-manager',
+      rank: this.config.pluginManagerRank ?? 40,
+      locator: { kind: 'inline', path: import.meta.url },
+      get: async () => ({ name, description, body }),
+    };
+  }
+
   async addRootCandidates(candidates, claudeDir, source, rank) {
-    if (!(await pathExists(claudeDir))) return;
-    for (const c of await discoverSkills(join(claudeDir, 'skills'), this.name, source, rank)) {
-      candidates.push(c);
-    }
-    for (const c of await discoverCommands(join(claudeDir, 'commands'), this.name, source, rank)) {
-      candidates.push(c);
+    const provider = this.name;
+    const tasks = [discoverSkills(join(claudeDir, 'skills'), provider, source, rank)];
+    for (const [dir, fn] of [
+      ['commands', discoverCommands],
+      ['agents', discoverAgents],
+    ]) {
+      if (dir === 'agents' && this.config.enableAgents === false) continue;
+      tasks.push(fn(join(claudeDir, dir), provider, source, rank));
     }
+    const batches = await Promise.all(tasks);
+    for (const batch of batches) candidates.push(...batch);
   }
 
   async get(candidate) {
@@ -121,7 +253,13 @@ class ClaudeCompatSkillProvider {
     const raw = await readTextSafe(locator.path);
     if (raw === undefined) return undefined;
     const parsed = parseFrontmatter(raw);
-    const content = parsed === undefined ? raw.trim() : parsed.body.trim();
+    let content;
+    if (candidate.agentTools !== undefined) {
+      // Agent-backed candidate: lead the body with the delegation instruction.
+      content = renderAgentContent(candidate, (parsed?.body ?? raw).trim());
+    } else {
+      content = parsed === undefined ? raw.trim() : parsed.body.trim();
+    }
     return {
       name: candidate.name,
       description: candidate.description,
@@ -138,9 +276,10 @@ class ClaudeCompatSkillProvider {
 
 // ─── discovery: <root>/.claude/skills (recursive, ≤3 levels) ─────────────────
 
-async function discoverSkills(rootDir, providerName, source, rank) {
+export async function discoverSkills(rootDir, providerName, source, rank) {
+  const { readdir } = await import('node:fs/promises');
   const out = [];
-  if (!(await pathExists(rootDir))) return out;
+  if (!(await pathExistsSafe(rootDir))) return out;
   await walk(rootDir, '', 0);
   return out;
 
@@ -167,9 +306,10 @@ async function discoverSkills(rootDir, providerName, source, rank) {
 
 // ─── discovery: <root>/.claude/commands (flat) ───────────────────────────────
 
-async function discoverCommands(rootDir, providerName, source, rank) {
+export async function discoverCommands(rootDir, providerName, source, rank) {
+  const { readdir } = await import('node:fs/promises');
   const out = [];
-  if (!(await pathExists(rootDir))) return out;
+  if (!(await pathExistsSafe(rootDir))) return out;
   let entries;
   try {
     entries = await readdir(rootDir, { withFileTypes: true, encoding: 'utf8' });
@@ -307,106 +447,12 @@ ${parts.join('\n')}
       </system-reminder>`;
 }
 
-function findProjectRootSync(cwd, markers = ['.git']) {
-  let current = resolve(cwd);
-  while (true) {
-    for (const marker of markers) {
-      if (existsSync(join(current, marker))) return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}
-
-function listMdFilesSync(dir) {
-  let entries;
-  try { entries = readdirSync(dir); } catch { return []; }
-  const files = [];
-  for (const name of entries) {
-    if (!name.endsWith('.md')) continue;
-    const p = join(dir, name);
-    try { if (statSync(p).isFile()) files.push(p); } catch {}
-  }
-  files.sort();
-  return files;
-}
-
 // ─── helpers ─────────────────────────────────────────────────────────────────
 
-function resolveUserClaudeDir(dir) {
-  if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
-  if (dir === '~') return homedir();
-  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
-  return resolve(dir);
-}
-
-async function findProjectRoot(cwd, markers = ['.git']) {
-  let current = resolve(cwd);
-  while (true) {
-    for (const marker of markers) {
-      if (await pathExists(join(current, marker))) return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return undefined;
-    current = parent;
-  }
-}
-
-async function pathExists(path) {
+async function pathExistsSafe(path) {
   try { await stat(path); return true; } catch { return false; }
 }
 
-async function readTextSafe(path) {
-  try { return await readFile(path, { encoding: 'utf8' }); }
-  catch { return undefined; }
-}
-
-async function listMdFiles(dir) {
-  let entries;
-  try { entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' }); }
-  catch { return []; }
-  const files = [];
-  for (const e of entries) {
-    if (e.isFile() && e.name.endsWith('.md')) files.push(join(dir, e.name));
-  }
-  files.sort();
-  return files;
-}
-
-function parseFrontmatter(raw) {
-  const firstLineEnd = raw.indexOf('\n');
-  if (firstLineEnd < 0) return undefined;
-  if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined;
-  const start = firstLineEnd + 1;
-  const closing = findClosingFrontmatter(raw, start);
-  if (closing === undefined) return undefined;
-  let parsed;
-  try { parsed = parse(raw.slice(start, closing.start)); }
-  catch { return undefined; }
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
-  return { data: parsed, body: raw.slice(closing.bodyStart) };
-}
-
-function findClosingFrontmatter(raw, start) {
-  let lineStart = start;
-  while (lineStart <= raw.length) {
-    const nextNewline = raw.indexOf('\n', lineStart);
-    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
-    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
-      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
-    }
-    if (nextNewline < 0) return undefined;
-    lineStart = nextNewline + 1;
-  }
-  return undefined;
-}
-
-function stringField(data, key) {
-  const v = data[key];
-  return typeof v === 'string' && v.length > 0 ? v : undefined;
-}
-
 function parseInvocationPolicy(data) {
   const miv = data['disable-model-invocation'];
   const uiv = data['user-invocable'];
@@ -424,4 +470,4 @@ function truthy(v) {
   }
   if (typeof v === 'number') return v !== 0;
   return false;
-}
+}

package/src/lib.js

@@ -0,0 +1,123 @@
+// Shared helpers for dsh-claude-compat (path resolution, sync/async root
+// discovery, reader utilities, frontmatter parsing). Extracted from index.js
+// so mcp.js / hooks.js / agents.js can reuse them without circular imports.
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { parse } from 'yaml';
+
+export function resolveUserClaudeDir(dir) {
+  if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
+  if (dir === '~') return homedir();
+  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
+  return resolve(dir);
+}
+
+export async function findProjectRoot(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (await pathExists(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+export function findProjectRootSync(cwd, markers = ['.git']) {
+  let current = resolve(cwd);
+  while (true) {
+    for (const marker of markers) {
+      if (existsSync(join(current, marker))) return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+export async function pathExists(path) {
+  try { await stat(path); return true; } catch { return false; }
+}
+
+export async function readTextSafe(path) {
+  try { return await readFile(path, { encoding: 'utf8' }); }
+  catch { return undefined; }
+}
+
+export function readTextSafeSync(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return undefined; }
+}
+
+export async function listMdFiles(dir) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' }); }
+  catch { return []; }
+  const files = [];
+  for (const e of entries) {
+    if (e.isFile() && e.name.endsWith('.md')) files.push(join(dir, e.name));
+  }
+  files.sort();
+  return files;
+}
+
+export function listMdFilesSync(dir) {
+  let entries;
+  try { entries = readdirSync(dir); } catch { return []; }
+  const files = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const p = join(dir, name);
+    try { if (statSync(p).isFile()) files.push(p); } catch {}
+  }
+  files.sort();
+  return files;
+}
+
+// Frontmatter: `---` line, YAML block, closing `---` line, body after. Returns
+// { data, body } on success, undefined on anything malformed.
+export function parseFrontmatter(raw) {
+  const firstLineEnd = raw.indexOf('\n');
+  if (firstLineEnd < 0) return undefined;
+  if (raw.slice(0, firstLineEnd).replace(/\r$/, '') !== '---') return undefined;
+  const start = firstLineEnd + 1;
+  const closing = findClosingFrontmatter(raw, start);
+  if (closing === undefined) return undefined;
+  let parsed;
+  try { parsed = parse(raw.slice(start, closing.start)); }
+  catch { return undefined; }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
+  return { data: parsed, body: raw.slice(closing.bodyStart) };
+}
+
+export function stringField(data, key) {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+export function truthy(v) {
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'string') {
+    const s = v.toLowerCase();
+    return s === 'true' || s === 'yes' || s === 'on' || s === '1';
+  }
+  if (typeof v === 'number') return v !== 0;
+  return false;
+}
+
+function findClosingFrontmatter(raw, start) {
+  let lineStart = start;
+  while (lineStart <= raw.length) {
+    const nextNewline = raw.indexOf('\n', lineStart);
+    const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+    if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return { start: lineStart, bodyStart: nextNewline < 0 ? raw.length : nextNewline + 1 };
+    }
+    if (nextNewline < 0) return undefined;
+    lineStart = nextNewline + 1;
+  }
+  return undefined;
+}

package/src/mcp.js

@@ -0,0 +1,133 @@
+// dsh-claude-compat: MCP servers from <projectRoot>/.mcp.json (Claude Code
+// format). Read once at DSH startup from the launch workspace; each server is
+// mounted as an @deepseek-ai/dsh-mcp-client plugin instance (stdio for
+// `command` entries, streamable-http for `url`/`type:'http'|'sse'` entries).
+//
+// Failure handling is deliberately non-fatal: an unreadable/malformed .mcp.json
+// or an absent dsh-mcp-client package logs a warning and skips, never crashing
+// the harness. failOnStartupError only forwards to the mcp-client plugin.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  findProjectRootSync,
+  pathExists,
+} from './lib.js';
+
+// Pure translation of Claude Code's .mcp.json body into dsh-mcp-client plugin
+// configs, keyed by server name. Malformed entries are skipped and reported.
+export function translateMcpServers(rawJson, { failOnStartupError = false } = {}) {
+  let parsed;
+  try { parsed = JSON.parse(rawJson); }
+  catch {
+    return { servers: [], warns: [`invalid-json: ${String(rawJson).slice(0, 100)}`] };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { servers: [], warns: ['invalid-json: root must be an object'] };
+  }
+  const servers = parsed.mcpServers;
+  if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) {
+    return { servers: [], warns: ['mcpServers: missing or not an object'] };
+  }
+  const out = [];
+  const warns = [];
+  for (const [name, entry] of Object.entries(servers)) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      warns.push(`${name}: malformed entry, skipped`);
+      continue;
+    }
+    // serverName must match /^[A-Za-z0-9_-]{1,32}$/ (dsh-mcp-client contract).
+    const serverName = name.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 32);
+    if (serverName.length === 0) {
+      warns.push(`${name}: empty server name, skipped`);
+      continue;
+    }
+    const base = {
+      serverName,
+      toolCallTimeoutMs: 60_000,
+      failOnStartupError,
+    };
+    if (typeof entry.command === 'string' && entry.command.length > 0) {
+      out.push({
+        ...base,
+        transport: 'stdio',
+        command: entry.command,
+        args: Array.isArray(entry.args) ? entry.args.filter((a) => typeof a === 'string') : [],
+        env: stringDict(entry.env),
+        cwd: typeof entry.cwd === 'string' ? entry.cwd : '',
+      });
+    } else if (typeof entry.url === 'string' && entry.url.length > 0) {
+      out.push({
+        ...base,
+        transport: 'streamable-http',
+        url: entry.url,
+        headers: stringDict(entry.headers),
+      });
+    } else if (entry.type === 'http' || entry.type === 'sse') {
+      warns.push(`${name}: type '${entry.type}' without a url, skipped`);
+    } else {
+      warns.push(`${name}: neither command nor url, skipped`);
+    }
+  }
+  return { servers: out, warns };
+}
+
+function stringDict(v) {
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return {};
+  const out = {};
+  for (const [k, val] of Object.entries(v)) {
+    if (typeof val === 'string') out[k] = val;
+    else if (typeof val === 'number' || typeof val === 'boolean') out[k] = String(val);
+  }
+  return out;
+}
+
+// Mount one mcp-client per server listed in <projectRoot>/.mcp.json. Lifecycle:
+// process-lifetime by design — the file is read once at DSH startup from the
+// launch workspace via process.cwd()-based root discovery; deviating from the
+// per-session cwd rules (which are session-scoped) is intended and documented.
+export async function mountMcpServers(ctx, config) {
+  const projectRoot = findProjectRootSync(process.cwd(), config.projectRootMarkers);
+  if (projectRoot === undefined) return;
+  const mcpPath = join(projectRoot, '.mcp.json');
+  if (!(await pathExists(mcpPath))) return;
+  let raw;
+  try { raw = readFileSync(mcpPath, 'utf8'); } catch (error) {
+    console.warn(`dsh-claude-compat: .mcp.json unreadable: ${error?.message ?? error}`, '(skipping MCP)');
+    return;
+  }
+  const { servers, warns } = translateMcpServers(raw, {
+    failOnStartupError: config.mcpFailOnStartupError ?? false,
+  });
+  warns.forEach((w) => console.warn(`dsh-claude-compat: .mcp.json: ${w}`));
+  await mountMcpConfigs(ctx, servers);
+}
+
+// Mount pre-translated server configs (shared by .mcp.json and plugin MCP).
+export async function mountMcpConfigs(ctx, servers) {
+  if (servers.length === 0) return;
+  let mcpClientModule;
+  try {
+    mcpClientModule = await import('@deepseek-ai/dsh-mcp-client');
+  } catch (error) {
+    console.warn('dsh-claude-compat: @deepseek-ai/dsh-mcp-client not installed', '(MCP disabled)', error?.message ?? error);
+    return;
+  }
+  const mcpClient = mcpClientModule.default ?? mcpClientModule;
+  const mounted = new Set();
+  for (const server of servers) {
+    if (mounted.has(server.serverName)) {
+      console.warn(`dsh-claude-compat: duplicate serverName "${server.serverName}" skipped`);
+      continue;
+    }
+    mounted.add(server.serverName);
+    // ctx.plugin returns a Fiber (PromiseLike) in real cordis; guard for
+    // non-promise returns in tests/embeddings.
+    const fiber = ctx.plugin(mcpClient, server);
+    if (fiber && typeof fiber.catch === 'function') {
+      fiber.catch((error) => {
+        console.warn(`dsh-claude-compat: server "${server.serverName}" failed to mount: ${error?.message ?? error}`);
+      });
+    }
+  }
+}