@deepsql/mcp 0.13.0 → 0.13.4

package/AGENT-SETUP.md

@@ -193,7 +193,8 @@ can switch later with another `connections use`.
 Pick the user's editor and run one of:
 
 ```bash
-deepsql mcp config --install --for claude-code      # MCP: ~/.claude/settings.json
+deepsql mcp config --install --for claude-code      # MCP: `claude mcp add --scope user`
+                                                    #      (falls back to ~/.claude.json if claude CLI missing)
                                                     # Skill: ~/.claude/skills/deepsql/SKILL.md
 deepsql mcp config --install --for claude-desktop   # MCP: ~/Library/Application Support/Claude/...
                                                     # (no skill — Claude Desktop has no skills surface)
@@ -227,11 +228,19 @@ Each invocation does **two** things in one shot:
 
 The installer:
 
-- creates each target file + parent directory if missing,
-- backs up the existing file to `<path>.bak.<timestamp>` before changing it,
-- merges into the existing MCP server list without touching siblings,
-- refuses to overwrite an existing `deepsql` entry unless `--force` is set,
-- for Codex's `AGENTS.md`, wraps the skill in guarded
+- For **Claude Code**, delegates to `claude mcp add --scope user deepsql deepsql mcp`
+  (the official CLI that handles user-vs-project-vs-local scope correctly).
+  Falls back to writing `~/.claude.json` directly if the `claude` CLI isn't
+  on PATH (e.g. SSH boxes, CI). The older installer wrote to
+  `~/.claude/settings.json` which is the wrong file — that's for
+  permissions/hooks, not MCP. If a stale entry exists from a manual setup
+  or older installer, use `--force` to remove + re-add it.
+- For the other editors, creates each target file + parent directory if
+  missing, merges into the existing MCP server list without touching
+  siblings, refuses to overwrite an existing `deepsql` entry unless
+  `--force` is set, and backs up the existing file to
+  `<path>.bak.<timestamp>` before any change.
+- For Codex's `AGENTS.md`, wraps the skill in guarded
   `<!-- BEGIN DEEPSQL ... -->` / `<!-- END DEEPSQL ... -->` markers and
   preserves the user's surrounding content,
 - emits the destination path and any backup path so the user can revert.

package/README.md

@@ -1,42 +1,126 @@
-# DeepSQL MCP
+# DeepSQL CLI + MCP server
 
-DeepSQL MCP V1 is a local stdio server for Claude Desktop, Codex, and similar MCP clients.
+The `@deepsql/mcp` package ships two things in one binary:
 
-## What V1 Supports
+- **`deepsql`** — a CLI for talking to a self-hosted DeepSQL backend from a
+  terminal (auth, connections, SQL execution, plan analysis, index
+  suggestions, slow-query analyses, admin ops).
+- **`deepsql mcp`** — a stdio MCP server that exposes the same backend to
+  editor agents (Claude Code, Cursor, Codex, Claude Desktop) so they can
+  query and reason about the user's databases.
 
-- Local stdio MCP process
-- Remote DeepSQL backend over HTTPS
-- MCP personal access tokens for authentication
-- Read-only SQL execution and explain through backend-enforced MCP endpoints
+Both share one auth file (`~/.config/deepsql/auth.json`, mode 0600). Log
+in once with `deepsql login`; the MCP server uses the same token
+automatically — no token needs to be embedded in your editor's config.
 
-V1 does **not** provide a shared remote MCP server URL. Each user runs the MCP process locally on their own machine.
+## Install
 
-## Environment Variables
-
-| Variable | Required | Example |
-|----------|----------|---------|
-| `DEEPSQL_API_BASE_URL` | yes | `https://customer-deepsql.example.com/api/` |
-| `DEEPSQL_AUTH_TOKEN` | yes | `dsql_mcp_...` |
-| `DEEPSQL_MCP_TIMEOUT_MS` | no | `120000` |
-| `DEEPSQL_MCP_USER_ID` | no | `codex-mcp` |
-| `DEEPSQL_MCP_PROJECT_ID` | no | `codex-mcp` |
+```bash
+npm install -g @deepsql/mcp@latest
+deepsql --version
+```
 
-## Claude Desktop
+Requires Node ≥ 20.
 
-Use `claude_desktop_config.customer.example.json` as a template.
+## Quick start
 
-## Codex
+```bash
+deepsql login --url https://your-deepsql-host.example.com
+deepsql connections list
+deepsql connections use <connection-name>
+deepsql query "SELECT 1 AS ok"
+```
 
-Use `codex_config.customer.example.toml` as a template.
+## Wire into your editor (one command per editor)
 
-## Run
+The installer writes the MCP server entry into the editor's config AND
+installs a "DBA consult" skill that auto-triggers when the user asks
+the agent to do database work:
 
 ```bash
-npx -y @deepsql/mcp
+deepsql mcp config --install --for claude-code      # via `claude mcp add --scope user`
+deepsql mcp config --install --for claude-desktop   # macOS ~/Library/.../Claude/...
+deepsql mcp config --install --for cursor           # ~/.cursor/mcp.json + ~/.cursor/rules/deepsql.mdc
+deepsql mcp config --install --for codex            # ~/.codex/config.toml + ~/.codex/AGENTS.md
 ```
 
-For local repo development, you can also run:
+Pass `--print` to see what would be written without touching disk.
+Pass `--no-skill` to install only the MCP entry. Pass `--force` to
+overwrite a stale entry. See `deepsql mcp --help` for details.
+
+Restart the editor for the entry to load.
+
+## What the MCP server exposes
+
+10 tools, all read-only at the schema/retrieval layer and policy-gated
+at the SQL layer:
+
+| Tool | Purpose |
+|---|---|
+| `list_connections` | Connections this token has access to |
+| `get_schema` | Cached schema metadata (tables, columns, FKs, types) |
+| `get_database_objects` | Tables, views, functions, procedures |
+| `get_brain_context` | Retrieval brain: tables/columns/FKs/training docs/rules for a question |
+| `list_business_rules` | Active business rules and SQL guardrails for a connection |
+| `get_relationships` | Inferred + validated foreign keys with confidence scores |
+| `get_anti_patterns` | Schema-level or query-level anti-patterns |
+| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples |
+| `execute_sql` | Run any SQL — backend enforces role-based policy (developers read-only, admins can mutate with two-step confirm) |
+| `analyze_query_plan` | AI-enriched plan analysis (parsed plan tree, performance issues, index recommendations, written summary that uses the connection's schema + business rules) |
+
+EXPLAIN and EXPLAIN ANALYZE are just SQL — pass them as the query to
+`execute_sql`. For the AI-enriched plan analysis with the LLM-written
+summary, use `analyze_query_plan`.
+
+## Runtime guidance for agents
+
+`CLAUDE.md` (bundled in this package, at
+`node_modules/@deepsql/mcp/CLAUDE.md` after install) is the runtime
+guide for editor agents that have these tools loaded. It covers the
+"DBA consult" pattern, decision tree, hard rules around the role-gated
+mutation flow, and common foot-guns. The installer also drops a
+shortened, trigger-focused version of that guide as a native skill so
+the pattern fires automatically on phrases like "add a table", "write
+a migration", "design a schema", "query the database".
+
+## Agent-driven setup (one paste)
+
+For a fresh customer install, paste `AGENT-SETUP.md` (bundled at
+`node_modules/@deepsql/mcp/AGENT-SETUP.md`) into Claude Code / Cursor /
+Codex. The agent walks the user through install, login, connection
+registration, editor integration, and end-to-end validation in ~5
+minutes.
+
+## Manual install (only if you don't want the CLI shim)
+
+If you'd rather skip the `deepsql mcp config --install` flow and wire
+the editor config by hand, see the example files bundled with this
+package: `claude_desktop_config.customer.example.json` and
+`codex_config.customer.example.toml`. The token-embedded shape in
+those examples still works, but `deepsql mcp config --install` is the
+recommended path now.
+
+## Run the server directly (advanced)
 
 ```bash
-npm run mcp:phase1
+deepsql mcp                # uses the saved profile + auth token
+npx -y @deepsql/mcp        # one-off invocation without install
 ```
+
+Both work; the CLI shim is preferred because it shares the saved
+profile and never asks you to paste a token into editor config.
+
+## Environment variables
+
+| Variable | Required | Used by | Example |
+|----------|----------|---------|---------|
+| `DEEPSQL_API_BASE_URL` | for npx-style invocation | `deepsql mcp` if no saved profile | `https://customer-deepsql.example.com/api/` |
+| `DEEPSQL_AUTH_TOKEN` | for npx-style invocation | bearer for backend; `deepsql login` writes one to the profile file | `dsql_mcp_…` |
+| `DEEPSQL_MCP_USER_ID` | no | identifies the editor that invoked the MCP server in audit logs | `claude-desktop` / `cursor-mcp` / `codex-mcp` |
+| `DEEPSQL_CALLER_AGENT` | no | overrides the CLI's audit identity when an agent shells out to `deepsql` | `claude-code` |
+| `DEEPSQL_MCP_TIMEOUT_MS` | no | per-request timeout for MCP server calls | `120000` |
+
+If `deepsql login` has been run, both the CLI and the spawned MCP
+server pick up `DEEPSQL_API_BASE_URL` + `DEEPSQL_AUTH_TOKEN` from
+`~/.config/deepsql/auth.json` automatically — you don't need to set
+the env vars for either.

package/claude_desktop_config.customer.example.json

@@ -1,17 +1,9 @@
 {
+  "_comment": "Manual Claude Desktop config example. Most users should run `deepsql mcp config --install --for claude-desktop` instead — that handles the OS-specific path, backup, and the DBA-consult skill in one shot. Use this template only if you need a custom layout (per-workspace, embedded token, etc.).",
   "mcpServers": {
     "deepsql": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@deepsql/mcp"
-      ],
-      "env": {
-        "DEEPSQL_API_BASE_URL": "https://customer-deepsql.example.com/api/",
-        "DEEPSQL_AUTH_TOKEN": "dsql_mcp_replace_me",
-        "DEEPSQL_MCP_USER_ID": "claude-desktop",
-        "DEEPSQL_MCP_PROJECT_ID": "claude-desktop"
-      }
+      "command": "deepsql",
+      "args": ["mcp"]
     }
   }
 }

package/codex_config.customer.example.toml

@@ -1,9 +1,13 @@
-[mcp_servers.deepsql]
-command = "npx"
-args = ["-y", "@deepsql/mcp"]
+# Manual Codex CLI MCP config example. Most users should run
+#   `deepsql mcp config --install --for codex`
+# instead — that handles the file path, backup, and the DBA-consult skill
+# in one shot. Use this template only if you need a custom layout (e.g.
+# embedded token, alternate `DEEPSQL_*` env vars, non-default profile).
+#
+# The form below uses the `deepsql mcp` shim, which reads auth from
+# ~/.config/deepsql/auth.json (written by `deepsql login`) — no token
+# needs to be embedded in the config.
 
-[mcp_servers.deepsql.env]
-DEEPSQL_API_BASE_URL = "https://customer-deepsql.example.com/api/"
-DEEPSQL_AUTH_TOKEN = "dsql_mcp_replace_me"
-DEEPSQL_MCP_USER_ID = "codex-mcp"
-DEEPSQL_MCP_PROJECT_ID = "codex-mcp"
+[mcp_servers.deepsql]
+command = "deepsql"
+args = ["mcp"]

package/deepsql-phase1-lib.js

@@ -552,11 +552,56 @@ function summarizeAntiPatterns(payload, kind) {
 }
 
 function summarizeSlowQueries(payload) {
-  const list = Array.isArray(payload?.queries) ? payload.queries : [];
+  // Backend returns SlowQueryAnalysis with `topSlowQueries` (the field name
+  // varies; tolerate both `queries` and `topSlowQueries`).
+  const list = Array.isArray(payload?.topSlowQueries)
+    ? payload.topSlowQueries
+    : Array.isArray(payload?.queries) ? payload.queries : [];
   const total = payload?.totalCount ?? list.length;
   const avg = payload?.avgDurationMs;
   const max = payload?.maxDurationMs;
-  return `${total} slow query/queries${avg != null ? `, avg=${avg}ms` : ""}${max != null ? `, max=${max}ms` : ""}.`;
+
+  // Three counts matter to a calling agent that's about to EXPLAIN one of
+  // these queries:
+  //
+  //   recovered = sourceTruncated AND queryTextRecoveredFromLogs
+  //     → the live stats source truncated this query, but DeepSQL recovered
+  //       the full SQL from previously-ingested slow-log data in
+  //       query_lineage. EXPLAIN will work.
+  //
+  //   stillTruncated = sourceTruncated AND NOT queryTextRecoveredFromLogs
+  //     → still truncated; EXPLAIN will fail or return a partial plan.
+  //
+  //   neither → normal full-text query, no warning needed.
+  const recovered = list.filter((q) =>
+    q && q.sourceTruncated === true && q.queryTextRecoveredFromLogs === true
+  ).length;
+  const stillTruncated = list.filter((q) =>
+    q && q.sourceTruncated === true && q.queryTextRecoveredFromLogs !== true
+  ).length;
+
+  const parts = [];
+  if (recovered > 0) {
+    parts.push(
+      ` ℹ ${recovered} ${recovered === 1 ? "query was" : "queries were"} truncated by `
+      + `the database server (default 1024B) but DeepSQL recovered the full SQL `
+      + `from previously-ingested slow-log data — EXPLAIN against \`queryText\` will work.`
+    );
+  }
+  if (stillTruncated > 0) {
+    parts.push(
+      ` ⚠ ${stillTruncated} ${stillTruncated === 1 ? "query is" : "queries are"} still `
+      + `truncated and DeepSQL has no full-text copy on file. EXPLAIN will be unreliable. `
+      + `Fix: ingest the slow query log file for this connection, OR raise `
+      + `\`pg_stat_statements.track_activity_query_size\` (PG) / `
+      + `\`performance_schema_max_sql_text_length\` (MySQL) and restart, then re-collect.`
+    );
+  }
+
+  return `${total} slow query/queries`
+    + `${avg != null ? `, avg=${avg}ms` : ""}`
+    + `${max != null ? `, max=${max}ms` : ""}.`
+    + parts.join("");
 }
 
 function summarizeQueryResult(payload) {

package/deepsql-phase1-server.js

@@ -193,7 +193,7 @@ class DeepSqlPhase1McpServer {
             },
             serverInfo: SERVER_INFO,
             instructions:
-              "DeepSQL phase 1 MCP exposes read-only database access plus DeepSQL's brain (retrieved context, business rules, inferred relationships, anti-patterns, slow-query analysis). Prefer get_brain_context to ground SQL/answer generation in retrieved schema knowledge, then call execute_readonly_sql / explain_readonly_sql to validate. Mutating SQL is rejected by both client and backend.",
+              "DeepSQL MCP exposes the user's database catalogs plus DeepSQL's retrieval brain (relevant tables/columns/FKs, business rules, inferred relationships, anti-patterns, slow-query analysis). Workflow: call list_connections first to get UUIDs; call get_brain_context with the user's question to ground generation in retrieved schema; call execute_sql to run the query (admins can run DDL/DML with a two-step confirmMutation flow, developers are server-enforced read-only); call analyze_query_plan for AI-enriched plan analysis with the connection's schema + business rules in scope. EXPLAIN and EXPLAIN ANALYZE are valid SQL — pass them as the query to execute_sql; use analyze_query_plan when you want the LLM-written summary, not raw plan rows. Always pass connectionId (UUID), not connection names.",
           });
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.13.0",
+  "version": "0.13.4",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",

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", () => {