@deepsql/mcp 0.13.0 → 0.14.0

package/src/commands/mcp.js

@@ -25,7 +25,7 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 
 const { resolveSession } = require("./_session");
 
@@ -35,8 +35,28 @@ const SKILL_FOOTER_MARKER = "<!-- END DEEPSQL DBA CONSULT SKILL -->";
 const EDITORS = {
   "claude-code": {
     format: "json",
-    path: () => path.join(os.homedir(), ".claude", "settings.json"),
+    // Claude Code's user-scope MCP server list lives at the top of
+    // ~/.claude.json under `mcpServers`. The older ~/.claude/settings.json
+    // path that this installer used to target is for permissions/hooks/
+    // model settings — Claude Code never reads MCP entries from there.
+    //
+    // Preferred install path: shell out to `claude mcp add --scope user`
+    // (the official CLI handles future storage changes for us). If
+    // `claude` isn't on PATH (e.g. CI, SSH boxes), we fall back to
+    // writing ~/.claude.json directly via the standard JSON merge.
+    path: () => path.join(os.homedir(), ".claude.json"),
     key: "mcpServers",
+    cli: {
+      binary: "claude",
+      // `claude mcp list` is the smoke test: exit 0 means we have a
+      // working Claude Code CLI we can delegate to. We resolve the
+      // command/args via builder fns so SERVER_ENTRY_NAME isn't
+      // forward-referenced.
+      detect: () => ["mcp", "list"],
+      // `claude mcp add --scope user <name> <cmd> [args…]`
+      add: () => ["mcp", "add", "--scope", "user", SERVER_ENTRY_NAME, SERVER_ENTRY.command, ...SERVER_ENTRY.args],
+      remove: () => ["mcp", "remove", SERVER_ENTRY_NAME, "--scope", "user"],
+    },
     skill: {
       kind: "file",
       path: () => path.join(os.homedir(), ".claude", "skills", "deepsql", "SKILL.md"),
@@ -168,20 +188,44 @@ async function runConfig(opts, { stdout = process.stdout, stderr = process.stder
     return;
   }
 
+  // Editor-CLI delegation: if the editor ships its own MCP CLI (Claude
+  // Code's `claude mcp add`) AND it's on PATH, use it. Falls back to
+  // direct file write if the CLI isn't available — useful for CI and
+  // SSH boxes that have @deepsql/mcp installed but no editor.
   const configPath = opts.path || target.path();
-  const configResult = mergeConfig({
-    format: target.format,
-    key: target.key,
-    configPath,
-    force: !!opts.force,
-  });
+  let configResult;
+  let writtenVia = configPath;
+  const usingCli = target.cli && !opts.path && hasEditorCli(target.cli);
+  if (usingCli) {
+    try {
+      configResult = installViaCli({ cli: target.cli, force: !!opts.force });
+      writtenVia = `\`${target.cli.binary} mcp add --scope user\` (user-scope in ~/.claude.json)`;
+    } catch (err) {
+      stderr.write(
+        `\`${target.cli.binary} mcp add\` failed: ${err.message}\nFalling back to direct file write at ${configPath}.\n`,
+      );
+      configResult = mergeConfig({
+        format: target.format,
+        key: target.key,
+        configPath,
+        force: !!opts.force,
+      });
+    }
+  } else {
+    configResult = mergeConfig({
+      format: target.format,
+      key: target.key,
+      configPath,
+      force: !!opts.force,
+    });
+  }
 
   if (configResult.skipped) {
     stderr.write(
-      `DeepSQL is already configured in ${configPath}. Re-run with --force to overwrite, or --print to see the snippet.\n`,
+      `DeepSQL MCP entry already present (${writtenVia}). Re-run with --force to overwrite, or --print to see the snippet.\n`,
     );
   } else {
-    stdout.write(`Installed DeepSQL MCP entry in ${configPath}.\n`);
+    stdout.write(`Installed DeepSQL MCP entry: ${writtenVia}.\n`);
     if (configResult.backupPath) {
       stdout.write(`  backup: ${configResult.backupPath}\n`);
     }
@@ -374,6 +418,111 @@ function mergeConfig({ format, key, configPath, force }) {
   return { written: true, backupPath };
 }
 
+// ─── Editor-CLI delegation (Claude Code) ───────────────────────────────────
+//
+// For editors that ship their own MCP-config CLI (currently just Claude
+// Code via `claude mcp add`), we prefer delegating instead of writing
+// config files ourselves. Three reasons:
+//
+//   1. The on-disk format is documented as private and has changed once
+//      already (settings.json → .claude.json at the top level under
+//      mcpServers, vs. local-scope's keyed-by-project layout).
+//   2. The CLI handles scopes (user / project / local) correctly. Writing
+//      to top-level mcpServers in ~/.claude.json mostly works for user
+//      scope but it's brittle; the CLI is the contract.
+//   3. If Anthropic changes the layout again, the CLI keeps working
+//      without a deepsql release.
+//
+// We only delegate when `claude mcp list` actually exits 0 — that's our
+// proof of life. Otherwise we fall back to direct JSON write.
+
+/**
+ * Return true if `claude mcp list` works on this machine. Tested by
+ * spawning `claude` with `mcp list` and a 5-second timeout — fast enough
+ * to keep the installer snappy, slow enough that a normal cold start
+ * (loading config, listing servers) reliably completes.
+ *
+ * `spawnFn` is overridable for tests.
+ */
+function hasEditorCli({ binary, detect }, { spawnFn = spawnSync } = {}) {
+  if (!binary) return false;
+  try {
+    const result = spawnFn(binary, detect(), {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    return result && result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run `claude mcp list` and check whether `deepsql` is already in the
+ * output. Used to decide between "no-op", "remove + add" (force), and
+ * "add" paths.
+ */
+function isAlreadyConfiguredViaCli({ binary, detect }, { spawnFn = spawnSync } = {}) {
+  try {
+    const result = spawnFn(binary, detect(), {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5000,
+      encoding: "utf8",
+    });
+    if (!result || result.status !== 0) return false;
+    const stdout = String(result.stdout || "");
+    // `claude mcp list` lines look like:
+    //   deepsql: deepsql mcp - ✓ Connected
+    //   deepsql: /path/... - ✗ Failed to connect
+    // We match the entry name at the start of a line, followed by `:`,
+    // which is stable across both states.
+    return new RegExp(`(?:^|\\n)\\s*${SERVER_ENTRY_NAME}\\s*:`).test(stdout);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install the DeepSQL MCP entry by delegating to the editor's CLI.
+ *
+ * Returns:
+ *   { written: true, viaCli: "<binary>" }    on success
+ *   { skipped: true }                         when already present and !force
+ *
+ * On --force: remove first (best-effort; ignore "not found" exits), then
+ * add. The CLI handles backup/atomicity for us.
+ */
+function installViaCli({ cli, force }, { spawnFn = spawnSync } = {}) {
+  if (isAlreadyConfiguredViaCli(cli, { spawnFn }) && !force) {
+    return { skipped: true };
+  }
+
+  if (force && isAlreadyConfiguredViaCli(cli, { spawnFn })) {
+    // Best-effort remove — if the entry was in a different scope, the
+    // remove may fail, but that's the user's problem to disambiguate.
+    spawnFn(cli.binary, cli.remove(), {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5000,
+    });
+  }
+
+  const addResult = spawnFn(cli.binary, cli.add(), {
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10000,
+    encoding: "utf8",
+  });
+  if (!addResult || addResult.status !== 0) {
+    const stderr = String(addResult && addResult.stderr ? addResult.stderr : "").trim();
+    throw new Error(
+      `\`${cli.binary} ${cli.add().join(" ")}\` exited with status ${addResult ? addResult.status : "?"}.${
+        stderr ? ` stderr: ${stderr}` : ""
+      }`,
+    );
+  }
+
+  return { written: true, viaCli: cli.binary };
+}
+
 function mergeJson(originalText, key, force) {
   let parsed = {};
   if (originalText && originalText.trim()) {
@@ -459,5 +608,8 @@ module.exports = {
   upsertGuardedSection,
   renderSkill,
   loadSkillBody,
+  hasEditorCli,
+  isAlreadyConfiguredViaCli,
+  installViaCli,
   EDITORS,
 };

package/src/commands/mcp.test.js

@@ -15,6 +15,9 @@ const {
   upsertGuardedSection,
   renderSkill,
   loadSkillBody,
+  hasEditorCli,
+  isAlreadyConfiguredViaCli,
+  installViaCli,
   EDITORS,
 } = require("./mcp");
 
@@ -221,6 +224,148 @@ test("EDITORS catalog exposes the four supported targets with sensible defaults"
   }
 });
 
+test("claude-code falls back to ~/.claude.json (not ~/.claude/settings.json) for user-scope MCP", () => {
+  // ~/.claude/settings.json is for permissions/hooks/model settings;
+  // Claude Code reads MCP from ~/.claude.json at the top level. Older
+  // installer versions had this wrong, which surfaced as
+  // "deepsql_* tools aren't loaded in this session" reports from users.
+  const p = EDITORS["claude-code"].path();
+  assert.ok(p.endsWith(".claude.json"), `unexpected claude-code fallback path: ${p}`);
+  assert.equal(/\.claude\/settings\.json$/.test(p), false);
+});
+
+test("claude-code prefers CLI delegation (cli descriptor present)", () => {
+  const cli = EDITORS["claude-code"].cli;
+  assert.ok(cli, "claude-code must carry a CLI delegation descriptor");
+  assert.equal(cli.binary, "claude");
+  assert.deepEqual(cli.detect(), ["mcp", "list"]);
+  // `claude mcp add --scope user deepsql deepsql mcp`
+  assert.deepEqual(cli.add(), ["mcp", "add", "--scope", "user", "deepsql", "deepsql", "mcp"]);
+  assert.deepEqual(cli.remove(), ["mcp", "remove", "deepsql", "--scope", "user"]);
+});
+
+test("cursor and codex do not carry a CLI delegation descriptor (no equivalent tooling)", () => {
+  assert.equal(EDITORS["cursor"].cli, undefined);
+  assert.equal(EDITORS["codex"].cli, undefined);
+  assert.equal(EDITORS["claude-desktop"].cli, undefined);
+});
+
+// ─── CLI delegation helpers ────────────────────────────────────────────────
+
+function fakeSpawn(table) {
+  // table is an array of { match: { args: [...] }, result: { status, stdout?, stderr? } }
+  // First match wins; unmatched calls fail loudly so tests catch silent fallthroughs.
+  return (binary, args) => {
+    for (const entry of table) {
+      if (!entry.match) return entry.result;
+      const a = entry.match.args;
+      if (a.length === args.length && a.every((v, i) => v === args[i])) {
+        return entry.result;
+      }
+    }
+    throw new Error(`fakeSpawn: no match for ${binary} ${args.join(" ")}`);
+  };
+}
+
+test("hasEditorCli returns true when the detect command exits 0", () => {
+  const spawnFn = fakeSpawn([{ match: { args: ["mcp", "list"] }, result: { status: 0, stdout: "" } }]);
+  assert.equal(hasEditorCli(EDITORS["claude-code"].cli, { spawnFn }), true);
+});
+
+test("hasEditorCli returns false when the binary errors / isn't found", () => {
+  const spawnFn = () => { throw Object.assign(new Error("ENOENT"), { code: "ENOENT" }); };
+  assert.equal(hasEditorCli(EDITORS["claude-code"].cli, { spawnFn }), false);
+});
+
+test("hasEditorCli returns false when the binary exits non-zero", () => {
+  const spawnFn = fakeSpawn([{ match: { args: ["mcp", "list"] }, result: { status: 1 } }]);
+  assert.equal(hasEditorCli(EDITORS["claude-code"].cli, { spawnFn }), false);
+});
+
+test("isAlreadyConfiguredViaCli matches 'deepsql:' line in claude mcp list output", () => {
+  const stdout = [
+    "claude.ai Gmail: https://gmailmcp.googleapis.com/mcp/v1 - ✓ Connected",
+    "claude.ai Slack: https://mcp.slack.com/mcp - ✓ Connected",
+    "deepsql: deepsql mcp - ✓ Connected",
+    "",
+  ].join("\n");
+  const spawnFn = fakeSpawn([{ match: { args: ["mcp", "list"] }, result: { status: 0, stdout } }]);
+  assert.equal(isAlreadyConfiguredViaCli(EDITORS["claude-code"].cli, { spawnFn }), true);
+});
+
+test("isAlreadyConfiguredViaCli also matches a failed-to-connect deepsql entry (the bug we hit)", () => {
+  // The user's actual diagnostic showed this exact form. The detector
+  // must still classify it as "already configured" so --force can clean
+  // it up before re-adding.
+  const stdout = "deepsql: node /old/stale/path/server.js - ✗ Failed to connect\n";
+  const spawnFn = fakeSpawn([{ match: { args: ["mcp", "list"] }, result: { status: 0, stdout } }]);
+  assert.equal(isAlreadyConfiguredViaCli(EDITORS["claude-code"].cli, { spawnFn }), true);
+});
+
+test("isAlreadyConfiguredViaCli returns false when deepsql isn't in the list", () => {
+  const stdout = "claude.ai Gmail: ... - ✓ Connected\n";
+  const spawnFn = fakeSpawn([{ match: { args: ["mcp", "list"] }, result: { status: 0, stdout } }]);
+  assert.equal(isAlreadyConfiguredViaCli(EDITORS["claude-code"].cli, { spawnFn }), false);
+});
+
+test("installViaCli runs `claude mcp add --scope user` when not already present", () => {
+  const calls = [];
+  const spawnFn = (binary, args) => {
+    calls.push({ binary, args });
+    if (args[0] === "mcp" && args[1] === "list") return { status: 0, stdout: "" };
+    if (args[0] === "mcp" && args[1] === "add") return { status: 0, stdout: "Added MCP server deepsql" };
+    throw new Error(`unexpected: ${args.join(" ")}`);
+  };
+  const result = installViaCli({ cli: EDITORS["claude-code"].cli, force: false }, { spawnFn });
+  assert.equal(result.written, true);
+  assert.equal(result.viaCli, "claude");
+  // First call: list (the isAlreadyConfigured check). Second: add.
+  assert.equal(calls.length, 2);
+  assert.deepEqual(calls[1].args, ["mcp", "add", "--scope", "user", "deepsql", "deepsql", "mcp"]);
+});
+
+test("installViaCli skips when deepsql is already configured and --force is off", () => {
+  const calls = [];
+  const spawnFn = (binary, args) => {
+    calls.push(args);
+    return { status: 0, stdout: "deepsql: deepsql mcp - ✓ Connected\n" };
+  };
+  const result = installViaCli({ cli: EDITORS["claude-code"].cli, force: false }, { spawnFn });
+  assert.equal(result.skipped, true);
+  // We should not have attempted `mcp add` after detecting the entry.
+  assert.equal(calls.some((a) => a[0] === "mcp" && a[1] === "add"), false);
+});
+
+test("installViaCli with --force removes the existing entry then re-adds", () => {
+  const calls = [];
+  const spawnFn = (binary, args) => {
+    calls.push(args);
+    if (args[0] === "mcp" && args[1] === "list") return { status: 0, stdout: "deepsql: foo - ✗ Failed\n" };
+    if (args[0] === "mcp" && args[1] === "remove") return { status: 0 };
+    if (args[0] === "mcp" && args[1] === "add") return { status: 0 };
+    throw new Error(`unexpected: ${args.join(" ")}`);
+  };
+  installViaCli({ cli: EDITORS["claude-code"].cli, force: true }, { spawnFn });
+  // Sequence: list (skip check) → list (force check) → remove → add.
+  const ops = calls.map((a) => `${a[0]} ${a[1]}`);
+  assert.ok(ops.includes("mcp remove"), `expected mcp remove, got: ${ops.join(", ")}`);
+  assert.ok(ops.includes("mcp add"));
+  // Remove must come before add.
+  assert.ok(ops.indexOf("mcp remove") < ops.indexOf("mcp add"));
+});
+
+test("installViaCli throws a clean error when `claude mcp add` exits non-zero (surfaces stderr)", () => {
+  const spawnFn = (binary, args) => {
+    if (args[1] === "list") return { status: 0, stdout: "" };
+    if (args[1] === "add") return { status: 1, stderr: "permission denied: ~/.claude.json" };
+    throw new Error("unexpected");
+  };
+  assert.throws(
+    () => installViaCli({ cli: EDITORS["claude-code"].cli, force: false }, { spawnFn }),
+    /exited with status 1.*permission denied/,
+  );
+});
+
 // ─── skill body + per-editor metadata ──────────────────────────────────────
 
 test("loadSkillBody returns the bundled SKILL_BODY.md content", () => {