@deepsql/mcp 0.13.0 → 0.14.0

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/CLAUDE.md

@@ -33,8 +33,9 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 10 tools. They all take a `connectionId` (UUID
-returned by `list_connections`).
+The MCP server exposes 12 tools. They all take a `connectionId` (UUID
+returned by `list_connections`) except `apply_index_recommendation`,
+which takes a server-resolved `recommendationId`.
 
 | Tool | Purpose |
 |---|---|
@@ -46,6 +47,8 @@ returned by `list_connections`).
 | `get_relationships` | Inferred + validated foreign keys with confidence scores. Many real DBs lack declared FKs; this fills the gap. |
 | `get_anti_patterns` | Schema-level (`kind=table`) or query-level (`kind=query`) anti-patterns. |
 | `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
+| `get_index_recommendations` | **Workload-weighted DBA-grade index advisor.** Pre-computed top-N (default 5) recommendations ranked by net benefit (`Σ calls × mean_exec_time` − write-cost). Each result carries up to 5 contributing query fingerprints, the role each column played, and optional HypoPG cost-delta on Postgres. Covers both `CREATE_INDEX` and `DROP_INDEX` (unused + redundant-prefix) candidates. |
+| **`apply_index_recommendation`** | **The only write-capable MCP tool.** Apply (or dry-run) a recommendation against its target connection and measure the before/after benefit on contributing queries. `DRY_RUN` (default) uses HypoPG (Postgres-only) for zero-write cost-delta. `APPLY` runs real `CREATE/DROP INDEX CONCURRENTLY` (configurable via `concurrent`). `APPLY_AND_MEASURE` additionally runs `EXPLAIN ANALYZE` for wall-clock timings. Write modes require `confirm: true`. The DDL is server-generated from the recommendation row — clients never supply SQL. |
 | **`execute_sql`** | **Run any SQL statement.** Policy is server-enforced: developers can run SELECT/WITH/SHOW/EXPLAIN; admins can also run DML/DDL with a two-step confirmation. EXPLAIN and EXPLAIN ANALYZE are just SQL — no separate flag. |
 | **`analyze_query_plan`** | **AI-enriched plan analysis** for a query. Returns the parsed plan tree, performance issues, index recommendations, and a written summary that takes the connection's schema and business rules into account. Pass `useAnalyze: true` to run `EXPLAIN ANALYZE` (actually executes the query). |
 
@@ -206,9 +209,19 @@ gates that protect `execute_sql` kick in. You'll get back
 get `requiresConfirmation` — surface the warnings to the user verbatim, wait
 for them to say yes, then re-call with `confirmMutation: true`.
 
-**"What indexes should we add?"** → Not exposed via MCP yet. Tell the user
-to run `deepsql indexes missing` or `deepsql indexes health` in their
-terminal.
+**"What indexes should we add?"** → `get_index_recommendations`. Returns
+the workload-weighted top-N (default 5) with net benefit, contributing
+queries, and HypoPG cost-delta when available. Use `deepsql indexes
+missing` / `deepsql indexes health` in the terminal for catalog-level
+counterparts (usage stats, duplicates).
+
+**"How much faster will this index actually make things?"** →
+`apply_index_recommendation` with `mode: "DRY_RUN"` (default). On
+Postgres it uses HypoPG to install a virtual index, EXPLAINs each
+contributing query, and reports the planner cost delta — no writes
+hit the database. If the user wants real timings, pass
+`mode: "APPLY_AND_MEASURE"` plus `confirm: true` to actually create
+the index (CONCURRENTLY) and run `EXPLAIN ANALYZE` before/after.
 
 **"What changed recently / what should I worry about?"** → Tell the user to
 run `deepsql digest` (today) or `deepsql digest 7` (last seven). The digest
@@ -305,10 +318,11 @@ them at the terminal command rather than trying to fake it through
 
 | Capability | CLI command |
 |---|---|
-| Index recommendations / missing-index advisor | `deepsql indexes list`, `deepsql indexes missing` |
+| Catalog-level index stats (counterpart to `get_index_recommendations`) | `deepsql indexes list`, `deepsql indexes missing` |
 | Unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
 | Per-table index usage stats | `deepsql indexes usage <table>` |
 | Index health report | `deepsql indexes health` |
+| Workload-weighted advisor + apply (DBA-grade) | `deepsql index-recommendations top` / `apply <id>` — same surface as the MCP `get_index_recommendations` + `apply_index_recommendation` tools, useful from a terminal |
 | Daily digest (anomalies + AI commentary) | `deepsql digest`, `deepsql digest 7` |
 | Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` |
 

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

@@ -143,6 +143,56 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "apply_index_recommendation",
+    description:
+      "Apply (or dry-run) an index recommendation and measure the before/after benefit on the queries that motivated it. " +
+      "Default mode is DRY_RUN — no writes; uses HypoPG (Postgres-only) to install a virtual index in the session, EXPLAIN-diffs the cost on each contributing query, then resets. " +
+      "APPLY mode runs the real DDL (CREATE INDEX CONCURRENTLY / DROP INDEX CONCURRENTLY on Postgres so the operation doesn't lock the table). " +
+      "APPLY_AND_MEASURE additionally runs EXPLAIN ANALYZE before and after for wall-clock timings — slowest, only opt in when you're OK executing the contributing queries against the target DB. " +
+      "Both APPLY modes require `confirm: true` — write operations don't happen by accident. " +
+      "Returns the executed DDL, the planner-cost delta, per-sample measurements (each contributing query's before/after cost), and an aggregate improvement percentage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recommendationId: { type: "string", description: "Recommendation row id (from get_index_recommendations)." },
+        mode: {
+          type: "string",
+          enum: ["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"],
+          description: "Default DRY_RUN. APPLY mutates the database; APPLY_AND_MEASURE also runs EXPLAIN ANALYZE."
+        },
+        confirm: {
+          type: "boolean",
+          description: "Required `true` for APPLY and APPLY_AND_MEASURE. Defaults to false."
+        },
+        concurrent: {
+          type: "boolean",
+          description: "Postgres-only. When true (default), CREATE/DROP runs CONCURRENTLY (no table lock, but waits for every pre-existing transaction). Set false on small dev tables when the brief ACCESS EXCLUSIVE lock is acceptable."
+        }
+      },
+      required: ["recommendationId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_index_recommendations",
+    description:
+      "Get DeepSQL's pre-computed top index recommendations for a connection. Recommendations are workload-weighted (Σ calls × mean_exec_time, the pganalyze / Microsoft DTA 'total time' ROI metric) and aggregated across many slow-query log fetches over a configurable lookback (default 30 days). Column ordering for composite indexes follows industry rules (equality before range, selectivity-ranked, ORDER BY suffix only with full-equality prefix, capped at 3 columns). Covers both CREATE_INDEX and DROP_INDEX (unused + redundant prefix-duplicate) candidates. Each result carries net benefit (workload − write cost), the contributing query fingerprints, and call/duration metrics — so a caller can audit *why* each suggestion exists rather than trust a heuristic. Returns top N (default 5) PENDING recommendations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 50,
+          description: "Number of recommendations to return. Defaults to 5.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "analyze_slow_queries",
     description:
@@ -551,12 +601,143 @@ function summarizeAntiPatterns(payload, kind) {
   return `${list.length} query anti-pattern(s)${sevStr ? ` (${sevStr})` : ""}.`;
 }
 
+function formatMillisHuman(ms) {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return null;
+  if (ms >= 86_400_000) return `${(ms / 86_400_000).toFixed(1)}d`;
+  if (ms >= 3_600_000) return `${(ms / 3_600_000).toFixed(1)}h`;
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
+  if (ms >= 1_000) return `${(ms / 1_000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+function summarizeApplyResult(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Apply call returned no body.";
+  }
+  const status = payload.status || "?";
+  const mode = payload.mode || "?";
+  if (status === "BLOCKED_NEEDS_CONFIRMATION") {
+    return `[${mode}] blocked — pass confirm=true to mutate the database.`;
+  }
+  if (status === "NOT_FOUND") {
+    return `[${mode}] recommendation not found: ${payload.recommendationId || "?"}`;
+  }
+  if (status === "NO_USABLE_SAMPLES") {
+    return `[${mode}] no literal-bearing contributing queries available; cannot measure.`;
+  }
+  if (status === "FAILED") {
+    return `[${mode}] failed: ${payload.message || "(no message)"}`;
+  }
+
+  const lines = [];
+  lines.push(`[${mode}] ${status} — ${payload.executedDdl || "(no ddl)"}`);
+  if (payload.beforeCost != null && payload.afterCost != null) {
+    const pct = payload.costReductionPct;
+    lines.push(
+      `  planner cost: ${payload.beforeCost.toFixed(0)} → ${payload.afterCost.toFixed(0)}` +
+        (pct != null ? ` (${pct >= 0 ? "−" : "+"}${Math.abs(pct).toFixed(1)}%)` : "")
+    );
+  }
+  if (payload.beforeWallTimeMs != null && payload.afterWallTimeMs != null) {
+    const pct = payload.wallTimeImprovementPct;
+    lines.push(
+      `  wall time: ${payload.beforeWallTimeMs.toFixed(1)}ms → ${payload.afterWallTimeMs.toFixed(1)}ms` +
+        (pct != null ? ` (${pct >= 0 ? "−" : "+"}${Math.abs(pct).toFixed(1)}%)` : "")
+    );
+  }
+  if (Array.isArray(payload.samples) && payload.samples.length) {
+    lines.push(`  ${payload.samples.length} contributing query sample(s):`);
+    for (const s of payload.samples.slice(0, 5)) {
+      const before = s.beforeCost != null ? s.beforeCost.toFixed(0) : "?";
+      const after = s.afterCost != null ? s.afterCost.toFixed(0) : "?";
+      lines.push(
+        `    fp=${(s.fingerprint || "?").slice(0, 12)} cost ${before} → ${after}` +
+          (s.error ? ` (error: ${s.error})` : "")
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+function summarizeIndexRecommendations(payload) {
+  const list = Array.isArray(payload) ? payload : payload?.recommendations || [];
+  if (!list.length) {
+    return "No pending index recommendations. The scheduler may not have run yet, or the workload has none worth flagging.";
+  }
+  const lines = list.slice(0, 10).map((rec, idx) => {
+    const table = rec.tableName || "?";
+    const prio = rec.priority || "?";
+    const occ = rec.occurrenceCount != null ? `seen ${rec.occurrenceCount}×` : "";
+    const net = formatMillisHuman(rec.netBenefitMs);
+    const writeCost = formatMillisHuman(rec.writeCostScore);
+    const evidence = rec.evidenceCount != null && rec.evidenceCount > 0
+      ? `${rec.evidenceCount} ev` : "";
+    const isDrop = rec.kind === "DROP_INDEX";
+    const action = isDrop ? "DROP" : "CREATE";
+    const target = isDrop
+      ? `${table}.${rec.indexName || "?"} (unused)`
+      : `${table}(${rec.columnNames || "?"})`;
+    // Net benefit is the DBA-grade signal — surface it prominently.
+    const benefitClause = net
+      ? `net=${net} saved` + (writeCost ? `, write=${writeCost}` : "")
+      : (rec.estimatedImpact != null ? `impact ${rec.estimatedImpact}` : "");
+    const meta = [prio, occ, benefitClause, evidence].filter(Boolean).join(", ");
+    return `${idx + 1}. [${action}] ${target}${meta ? ` — ${meta}` : ""}`;
+  });
+  return `Top ${list.length} pending index recommendation(s):\n${lines.join("\n")}`;
+}
+
 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) {
@@ -604,6 +785,12 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(payload);
       break;
+    case "get_index_recommendations":
+      summary = summarizeIndexRecommendations(payload);
+      break;
+    case "apply_index_recommendation":
+      summary = summarizeApplyResult(payload);
+      break;
     case "execute_sql":
       summary = summarizeQueryResult(payload);
       break;
@@ -730,6 +917,40 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload, { kind });
     }
 
+    case "get_index_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const limit = clampInteger(args.limit, 1, 50, 5);
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/${encodeURIComponent(connectionId)}/top?limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "apply_index_recommendation": {
+      const recommendationId = String(args.recommendationId || "").trim();
+      if (!recommendationId) return buildToolError("recommendationId is required.");
+      const mode = String(args.mode || "DRY_RUN").toUpperCase();
+      if (!["DRY_RUN", "APPLY", "APPLY_AND_MEASURE"].includes(mode)) {
+        return buildToolError(`Unknown mode: ${mode}. Expected DRY_RUN, APPLY, or APPLY_AND_MEASURE.`);
+      }
+      const confirm = args.confirm === true;
+      if ((mode === "APPLY" || mode === "APPLY_AND_MEASURE") && !confirm) {
+        return buildToolError(
+          `Mode ${mode} mutates the target database. Re-call with confirm=true to proceed.`,
+        );
+      }
+      const concurrent = args.concurrent === false ? false : true;
+      const qs = `?mode=${encodeURIComponent(mode)}&confirm=${confirm}&concurrent=${concurrent}`;
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/${encodeURIComponent(recommendationId)}/apply${qs}`,
+        { method: "POST" },
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "analyze_slow_queries": {
       const connectionId = String(args.connectionId || "").trim();
       if (!connectionId) return buildToolError("connectionId is required.");
@@ -853,5 +1074,7 @@ module.exports = {
   stripTrailingSemicolons,
   stripSqlComments,
   stripSqlStringLiterals,
+  summarizeApplyResult,
+  summarizeIndexRecommendations,
   validateReadOnlySql,
 };

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.14.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",