@deepsql/mcp 0.18.1 → 0.19.0

package/CLAUDE.md

@@ -33,9 +33,28 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 21 tools. They all take a `connectionId` (UUID
-returned by `list_connections`) except `apply_index_recommendation`,
-which takes a server-resolved `recommendationId`.
+The MCP server exposes **41 tools** as of 0.19.0 — the original 16 +
+0.18.x's 5 slow-query tools + 0.19.0's 20 CLI-parity additions. Most
+take a `connectionId` (UUID returned by `list_connections`); a few
+take server-resolved row ids (`apply_index_recommendation` →
+`recommendationId`, `dismiss_index_recommendation` →
+`recommendationId`, `acknowledge_growth_anomaly` → `anomalyId`,
+`get_digest_by_id` → `digestId`); `get_current_user` and
+`list_connections` take no args.
+
+The surface mirrors the `deepsql` CLI for almost every read/diagnostic
+operation. **Three CLI capabilities are intentionally NOT in MCP**:
+
+1. **Connection write ops** (`add`, `update`, `remove`) — they take
+   plaintext DB credentials, which would land in your conversation
+   history. Tell the user to run `deepsql connections add` at a TTY.
+2. **Auth flows** (`login`, `logout`, `setup`, `mcp config --install`) —
+   interactive by nature.
+3. **Streaming AI optimization** (`slow-queries optimize`) — SSE
+   stream, doesn't fit JSON-RPC tools.
+
+Per-user admin ops (`users`, `access`, `permissions`) are also CLI-only
+in this version; ask before mid-session admin work.
 
 | Tool | Purpose |
 |---|---|

package/README.md

@@ -52,31 +52,99 @@ Restart the editor for the entry to load.
 
 ## What the MCP server exposes
 
-21 tools, all read-only at the schema/retrieval layer and policy-gated
-at the SQL layer (only `execute_sql`, `analyze_query_plan` with
-`useAnalyze=true`, and `apply_index_recommendation` can write):
+**41 tools** as of 0.19.0. Read-only at the schema/retrieval/diagnostics
+layer; policy-gated at the SQL layer (only `execute_sql`,
+`analyze_query_plan` with `useAnalyze=true`, and
+`apply_index_recommendation` can write — the rest are reads or low-stakes
+triggers like `reinit_connection_brain` and `acknowledge_growth_anomaly`).
+
+The surface mirrors the `deepsql` CLI for every read/diagnostic
+operation. **What's intentionally NOT in MCP**: connection write ops
+(`add`/`update`/`remove` — they'd require plaintext DB credentials in
+agent conversation history; manage at a TTY via `deepsql connections
+add` instead), interactive auth flows (`login`/`logout`/`setup`/`mcp
+config --install`), the SSE streaming `slow-queries optimize` flow, and
+per-user admin ops (`users`/`access`/`permissions`).
+
+### Connections + identity (5)
 
 | Tool | Purpose |
 |---|---|
 | `list_connections` | Connections this token has access to |
+| `get_current_user` | Authenticated user + role + bound DeepSQL host |
+| `show_connection` | One connection's saved config, secrets masked |
+| `test_connection` | Run the privilege report (+ SSH check); reuses saved creds — no plaintext crosses the wire |
+| `reinit_connection_brain` | Trigger a fresh schema scan + brain re-embed |
+
+### Schema + retrieval brain (5)
+
+| Tool | Purpose |
+|---|---|
 | `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 |
+
+### Anti-patterns + daily digest (4)
+
+| Tool | Purpose |
+|---|---|
 | `get_anti_patterns` | Schema-level or query-level anti-patterns |
+| `get_latest_digest` | Most recent DeepSQL daily digest (slow queries + AI commentary) |
+| `list_digests` | Recent digest metadata (find one by date) |
+| `get_digest_by_id` | Full digest body |
+
+### Index advisor — workload-weighted + apply tool (5)
+
+| Tool | Purpose |
+|---|---|
 | `get_index_recommendations` | Pre-computed top-N workload-weighted index recommendations |
 | `apply_index_recommendation` | Apply (or dry-run with HypoPG) an index recommendation and measure benefit |
-| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples |
-| `get_slow_query_timeline` | Day-by-day timeline for one fingerprint from the 30-day analytics store |
+| `list_index_recommendations` | Browse the full recommendation history by status |
+| `refresh_index_recommendations` | Force a fresh accumulation cycle (skip 6-hour scheduler wait) |
+| `dismiss_index_recommendation` | Reject a recommendation explicitly |
+
+### Index catalog diagnostics — live pg_stat_* / sys.* probes (5)
+
+| Tool | Purpose |
+|---|---|
+| `get_missing_indexes` | Schema-walk view of suspected missing indexes |
+| `get_index_health` | Total/bloated/unused/duplicate/biggest indexes summary |
+| `get_unused_indexes` | Indexes with zero/near-zero scans (drop candidates) |
+| `get_duplicate_indexes` | Redundant prefix-duplicate indexes |
+| `get_table_index_usage` | Per-table scan/read/fetch counts on every index |
+
+### Slow queries (9)
+
+| Tool | Purpose |
+|---|---|
+| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples (triggers fresh collection) |
+| `get_latest_slow_query_analysis` | Read the most recent persisted analysis (no new work) |
+| `list_slow_query_history` | List past analysis runs (compact metadata) |
+| `get_slow_query_timeline` | Day-by-day timeline for one fingerprint from the 30-day store |
 | `get_query_regressions` | Slow queries that regressed on the latest daily run |
 | `list_tracked_queries` | All fingerprints tracked in the 30-day store |
 | `get_slow_query_customers` | Tenants ranked by total slow-query load |
 | `get_query_samples` | Literal SQL samples (with bind values) for one fingerprint |
 | `get_slow_query_insights` | Pre-computed AI insights — hotspots / remediation / tail-risk / plan-drift / skew |
-| `optimize_slow_query` | AI optimization recommendations (index DDL + query rewrites) for a specific SQL |
+
+(`optimize_slow_query` is also in MCP — see the slow-query family.)
+
+### Growth analytics (5)
+
+| Tool | Purpose |
+|---|---|
 | `get_table_growth` | Per-table size/row growth from persistent stats history |
 | `get_growth_anomalies` | DeepSQL-flagged sudden growth spikes with severity and root-cause hints |
+| `acknowledge_growth_anomaly` | Mark an anomaly as expected (silences `unacknowledgedOnly` queries) |
+| `get_growth_config` | Read current alert thresholds and sensitivity |
+| `set_growth_config` | Update alert thresholds (admin-gated server-side) |
+
+### Plan + execute (2 — the write-capable pair)
+
+| Tool | Purpose |
+|---|---|
 | `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) |
 

package/deepsql-phase1-lib.js

@@ -518,6 +518,352 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+
+  // ─── Phase A symmetry: tools added to match the `deepsql` CLI surface ───
+  //
+  // Each tool below mirrors a CLI subcommand that previously had no MCP
+  // equivalent. Connection write operations (add/update/remove) are
+  // intentionally NOT exposed as MCP tools — they require DB credentials
+  // and we don't want secrets crossing the agent's conversation history.
+  // Customers manage connections via `deepsql connections add` at a TTY.
+
+  {
+    name: "get_current_user",
+    description:
+      "Return the authenticated user behind the current MCP token: username, role, "
+      + "and the DeepSQL host this MCP server is bound to. Use this when the agent "
+      + "needs to know whether the caller is admin-capable before suggesting a "
+      + "DDL/DML run, or when explaining role-based restrictions to the user.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "test_connection",
+    description:
+      "Validate a saved connection: contacts the database, runs the privilege "
+      + "report, and returns whether the connection (and SSH tunnel, if any) is "
+      + "reachable. Read-only on the customer's DB. Use when diagnosing a `?:` "
+      + "Connected status from `list_connections` or before suggesting a SQL run "
+      + "against a connection the agent hasn't touched yet. Takes a saved "
+      + "connectionId only — does NOT accept ad-hoc credentials (those go through "
+      + "`deepsql connections add` at a terminal, not chat).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "show_connection",
+    description:
+      "Return the full saved configuration for one connection with all secret "
+      + "fields masked as `(set)`. Useful for diagnosing connection issues "
+      + "(host/port/SSL/SSH config). Will never echo a password back; use "
+      + "`deepsql connections show` at a TTY if you genuinely need to see "
+      + "a secret value.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "reinit_connection_brain",
+    description:
+      "Trigger a fresh brain initialization for a connection: re-scans the "
+      + "schema, re-runs key-column / FK inference, re-embeds training context. "
+      + "Use after the user reports DeepSQL's schema knowledge is stale (e.g., "
+      + "they just ran a migration). Returns immediately with an init-status "
+      + "row; the actual reinit runs in the background — poll connection state "
+      + "via `list_connections` to see when it transitions back to COMPLETED.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        force: {
+          type: "boolean",
+          description: "Restart even if a previous init is currently RUNNING. Defaults to false.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_latest_digest",
+    description:
+      "Return the most recent DeepSQL daily digest for a connection (or the "
+      + "workspace if no connectionId). Digests are nightly summaries of slow "
+      + "queries + AI commentary written to Slack. Useful for context when the "
+      + "user asks 'what changed in the database recently?' without needing a "
+      + "fresh slow-query analysis.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "Optional. Filter to one connection. Omit for workspace-wide.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_digests",
+    description:
+      "Return the N most recent DeepSQL daily digests (compact metadata, not full "
+      + "body). Use to find the digest id for a date the user references "
+      + "('what was in yesterday's digest?'), then fetch the full content via "
+      + "`get_digest_by_id`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "Optional. Filter to one connection." },
+        count: { type: "integer", minimum: 1, maximum: 100, description: "Defaults to 10." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_digest_by_id",
+    description:
+      "Return the full body of one DeepSQL daily digest by id, including the AI "
+      + "narrative and the slow-query list it was built from.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        digestId: { type: "string", description: "Digest id (from list_digests)." },
+        connectionId: {
+          type: "string",
+          description: "Optional. Required only if multiple connections share digest ids.",
+        },
+      },
+      required: ["digestId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_missing_indexes",
+    description:
+      "Catalog probe: returns indexes the DeepSQL advisor thinks are MISSING "
+      + "based on live workload (joins to unindexed columns, sort/group on big "
+      + "tables, etc.). This is the schema-walk view — for the workload-weighted "
+      + "ROI-ranked recommendations (with HypoPG cost-delta), use "
+      + "`get_index_recommendations` instead.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_index_health",
+    description:
+      "Comprehensive index health report for a connection: total indexes, "
+      + "bloated indexes, unused indexes, duplicate-prefix indexes, biggest "
+      + "indexes by size. Use as the first read when the user says 'audit my "
+      + "indexes' or 'are my indexes healthy?'.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_unused_indexes",
+    description:
+      "Catalog probe: indexes the DB has reported zero (or near-zero) scans "
+      + "against since last reset. Each returned row has the table, index name, "
+      + "size, and scan count. Dropping these is a quick storage + write-cost "
+      + "win, but verify scan counters aren't recent before suggesting.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_duplicate_indexes",
+    description:
+      "Catalog probe: indexes that are redundant prefixes of other indexes on "
+      + "the same table. Returns groups — each group is a set of indexes the "
+      + "optimizer would treat as interchangeable, with the recommendation to "
+      + "keep the longest/widest one.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_table_index_usage",
+    description:
+      "Per-table index usage statistics: every index on the given table with its "
+      + "scan count, tuples read, and tuples fetched. Use to diagnose 'why isn't "
+      + "my index being used?' or to decide which of several composite indexes "
+      + "to drop.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: { type: "string", description: "Table name (case-sensitive on Postgres)." },
+      },
+      required: ["connectionId", "tableName"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_index_recommendations",
+    description:
+      "List ALL index recommendations for a connection, optionally filtered by "
+      + "status (PENDING / APPLIED / DISMISSED). For just the top-N pending ones "
+      + "with full evidence, use `get_index_recommendations` instead — that's the "
+      + "agent-facing entry point. This tool is for browsing the recommendation "
+      + "history (e.g. 'what did we apply last week?').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        status: {
+          type: "string",
+          enum: ["PENDING", "APPLIED", "DISMISSED"],
+          description: "Optional. Defaults to all statuses.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "refresh_index_recommendations",
+    description:
+      "Force a fresh accumulation cycle: rescans the slow-query log for the "
+      + "lookback window and rebuilds the top-N index recommendations. Use when "
+      + "the user just deployed a new query pattern and wants to see if the "
+      + "advisor picks it up without waiting for the next 6-hour scheduler tick.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "dismiss_index_recommendation",
+    description:
+      "Mark a recommendation as DISMISSED so it stops appearing in `top` / "
+      + "default `list` queries. Use when the user explicitly rejects a "
+      + "recommendation (not the same as APPLIED — dismissed means 'we decided "
+      + "not to'). Reversible by an admin editing the row directly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        recommendationId: { type: "string", description: "Recommendation row id." },
+      },
+      required: ["recommendationId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_latest_slow_query_analysis",
+    description:
+      "Return the most recently completed slow-query analysis run for a "
+      + "connection (the persisted result, no fresh collection). Faster than "
+      + "`analyze_slow_queries` because it doesn't trigger new work — use as "
+      + "the first read when investigating 'what's slow right now?', then "
+      + "fall back to `analyze_slow_queries` only if the latest is stale.",
+    inputSchema: {
+      type: "object",
+      properties: { connectionId: { type: "string", description: "DeepSQL connection ID." } },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_slow_query_history",
+    description:
+      "List past slow-query analysis runs for a connection (compact metadata: "
+      + "id, timestamp, count, severity breakdown, AI-summary length). Use to "
+      + "find an older analysis to compare current state against, or to spot "
+      + "trends in how many slow queries are firing day-over-day.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Number of past analyses to return. Defaults to 10.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "acknowledge_growth_anomaly",
+    description:
+      "Mark a detected growth anomaly as acknowledged so it stops appearing "
+      + "in `get_growth_anomalies(unacknowledgedOnly=true)`. Use after the user "
+      + "confirms the growth was expected (e.g., 'yes, we did a big backfill "
+      + "yesterday'). Does NOT delete the anomaly — it remains in history for "
+      + "audit/timeline purposes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        anomalyId: { type: "string", description: "Anomaly row id (from get_growth_anomalies)." },
+      },
+      required: ["anomalyId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_growth_config",
+    description:
+      "Return the alert thresholds and detection sensitivity currently "
+      + "configured for table-growth monitoring on a connection. Useful to "
+      + "explain to the user why a particular growth event did or didn't fire "
+      + "an anomaly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "set_growth_config",
+    description:
+      "Update the alert thresholds / sensitivity for growth monitoring on a "
+      + "connection. Admin-gated. The config body shape matches what "
+      + "`get_growth_config` returns — use that first to fetch current values, "
+      + "then submit a modified copy.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        config: {
+          type: "object",
+          description: "Full config object (see get_growth_config for shape).",
+          additionalProperties: true,
+        },
+      },
+      required: ["connectionId", "config"],
+      additionalProperties: false,
+    },
+  },
 ];
 
 class DeepSqlApiError extends Error {
@@ -1557,6 +1903,211 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
+    // ─── Phase A symmetry — tools added to match the CLI surface ─────────
+
+    case "get_current_user": {
+      const payload = await callDeepSqlApi(config, "/auth/me");
+      return buildToolResult(name, payload);
+    }
+
+    case "test_connection": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      // POST /connections/test with just { id } reuses the saved encrypted
+      // creds server-side — no secrets cross the wire from the MCP client.
+      const payload = await callDeepSqlApi(config, "/connections/test", {
+        method: "POST",
+        json: { id: connectionId },
+      });
+      return buildToolResult(name, payload);
+    }
+
+    case "show_connection": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      // Backend has no GET /connections/{id}; list + filter mirrors CLI behavior.
+      // Server returns secrets already masked.
+      const all = await callDeepSqlApi(config, "/connections");
+      const list = Array.isArray(all) ? all : [];
+      const found = list.find((c) => (c.id || c.connectionId) === connectionId);
+      if (!found) return buildToolError(`Connection ${connectionId} not found.`);
+      return buildToolResult(name, found);
+    }
+
+    case "reinit_connection_brain": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/connections/${encodeURIComponent(connectionId)}/reinit`,
+        { method: "POST", json: { force: args.force === true } },
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_latest_digest": {
+      const params = ["size=1"];
+      if (args.connectionId) params.push(`connectionId=${encodeURIComponent(args.connectionId)}`);
+      const payload = await callDeepSqlApi(config, `/admin/slack/digests?${params.join("&")}`);
+      // Server returns a Page<>; surface the first element so consumers don't
+      // have to know about Spring Data's content array.
+      const first = Array.isArray(payload?.content) ? payload.content[0] : null;
+      return buildToolResult(name, first || null);
+    }
+
+    case "list_digests": {
+      const count = clampInteger(args.count, 1, 100, 10);
+      const params = [`size=${count}`];
+      if (args.connectionId) params.push(`connectionId=${encodeURIComponent(args.connectionId)}`);
+      const payload = await callDeepSqlApi(config, `/admin/slack/digests?${params.join("&")}`);
+      return buildToolResult(name, Array.isArray(payload?.content) ? payload.content : []);
+    }
+
+    case "get_digest_by_id": {
+      const digestId = String(args.digestId || "").trim();
+      if (!digestId) return buildToolError("digestId is required.");
+      // No GET /admin/slack/digests/{id} — pull recent and filter.
+      const params = ["size=100"];
+      if (args.connectionId) params.push(`connectionId=${encodeURIComponent(args.connectionId)}`);
+      const payload = await callDeepSqlApi(config, `/admin/slack/digests?${params.join("&")}`);
+      const list = Array.isArray(payload?.content) ? payload.content : [];
+      const found = list.find((d) => String(d.id) === digestId);
+      if (!found) return buildToolError(`Digest ${digestId} not in the recent 100 digests.`);
+      return buildToolResult(name, found);
+    }
+
+    case "get_missing_indexes": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/advisor/indexes/${encodeURIComponent(connectionId)}`);
+      return buildToolResult(name, payload);
+    }
+
+    case "get_index_health": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/index-advisor/${encodeURIComponent(connectionId)}/health-report`);
+      return buildToolResult(name, payload);
+    }
+
+    case "get_unused_indexes": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/index-advisor/${encodeURIComponent(connectionId)}/unused`);
+      return buildToolResult(name, payload);
+    }
+
+    case "get_duplicate_indexes": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/index-advisor/${encodeURIComponent(connectionId)}/duplicates`);
+      return buildToolResult(name, payload);
+    }
+
+    case "get_table_index_usage": {
+      const connectionId = String(args.connectionId || "").trim();
+      const tableName = String(args.tableName || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!tableName) return buildToolError("tableName is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-advisor/${encodeURIComponent(connectionId)}/usage/${encodeURIComponent(tableName)}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "list_index_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      // The "list ALL" path returns every status; we filter client-side
+      // for PENDING/APPLIED/DISMISSED to match the CLI semantics.
+      const all = await callDeepSqlApi(
+        config, `/index-recommendations/${encodeURIComponent(connectionId)}`);
+      const list = Array.isArray(all) ? all : [];
+      const filtered = args.status
+        ? list.filter((r) => String(r.status || "").toUpperCase() === String(args.status).toUpperCase())
+        : list;
+      return buildToolResult(name, filtered);
+    }
+
+    case "refresh_index_recommendations": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/generate/${encodeURIComponent(connectionId)}`,
+        { method: "POST" },
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "dismiss_index_recommendation": {
+      const recommendationId = String(args.recommendationId || "").trim();
+      if (!recommendationId) return buildToolError("recommendationId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/index-recommendations/${encodeURIComponent(recommendationId)}/dismiss`,
+        { method: "PUT" },
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_latest_slow_query_analysis": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/slow-queries/latest/${encodeURIComponent(connectionId)}`);
+      return buildToolResult(name, payload);
+    }
+
+    case "list_slow_query_history": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const limit = clampInteger(args.limit, 1, 100, 10);
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-queries/history/${encodeURIComponent(connectionId)}?limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "acknowledge_growth_anomaly": {
+      const anomalyId = String(args.anomalyId || "").trim();
+      if (!anomalyId) return buildToolError("anomalyId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/growth-monitoring/anomalies/${encodeURIComponent(anomalyId)}/acknowledge`,
+        { method: "POST" },
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_growth_config": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config, `/growth-monitoring/config/${encodeURIComponent(connectionId)}`);
+      return buildToolResult(name, payload);
+    }
+
+    case "set_growth_config": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!args.config || typeof args.config !== "object") {
+        return buildToolError("config object is required (see get_growth_config for shape).");
+      }
+      const payload = await callDeepSqlApi(
+        config,
+        "/growth-monitoring/config",
+        { method: "POST", json: { ...args.config, connectionId } },
+      );
+      return buildToolResult(name, payload);
+    }
+
     default:
       return buildToolError(`Unknown tool: ${name}`);
   }

package/package.json

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

package/skills/SKILL_BODY.md

@@ -2,13 +2,18 @@
 
 You have two DeepSQL surfaces available:
 
-1. **MCP tools** — JSON-RPC tools loaded into your session (21 of them).
-   Use these for in-session retrieval and SQL execution.
+1. **MCP tools** — JSON-RPC tools loaded into your session (41 of them
+   as of 0.19.0). The MCP surface mirrors the CLI for almost every
+   read/diagnostic operation, plus the two execute tools and the index-
+   apply tool.
 
 2. **`deepsql` CLI** — a shell binary on the user's PATH (~19 commands).
-   Use this for things the MCP doesn't expose (index health, daily
-   digest, slow-query streaming, connection management, admin ops, the
-   plan-analysis `analyze` command, etc.). You can shell out to the CLI
+   Use this for the few things still CLI-only: auth (`login`/`logout`),
+   the MCP installer (`deepsql mcp config --install`), connection
+   CRUD (anything that takes plaintext DB credentials — those must
+   stay out of your conversation history), the `setup` wizard, the
+   streaming `slow-queries optimize` SSE flow, and per-user admin ops
+   (`users`/`access`/`permissions`). You can shell out to the CLI
    yourself when appropriate; you can also point the user at the
    command if it's interactive.
 
@@ -98,6 +103,21 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_growth_anomalies(connectionId, tableName?, unacknowledgedOnly?, days?)` | DeepSQL-flagged sudden growth spikes with severity (CRITICAL/WARNING/INFO), anomaly type, before/after sizes, confidence score. Check this BEFORE walking the user through a slow-query plan — a recent growth anomaly is often the real root cause. |
 | `execute_sql(connectionId, query, ...)` | Run any SQL — SELECT for everyone, DML/DDL for admins (two-step confirm). |
 | `analyze_query_plan(connectionId, query, useAnalyze=false)` | AI-enriched plan analysis (issues + index recs + summary). |
+| `get_current_user()` | Authenticated user + role. Use to know whether the caller is admin-capable before suggesting DDL. |
+| `test_connection(connectionId)` | Validates a saved connection (privilege report + SSH tunnel check). Read-only on the customer's DB. |
+| `show_connection(connectionId)` | Full saved config with secrets masked. Diagnose host/port/SSL/SSH issues. |
+| `reinit_connection_brain(connectionId, force?)` | Trigger a fresh schema scan + brain re-embedding. Use after the user reports stale schema knowledge. |
+| `get_latest_digest(connectionId?)` / `list_digests(...)` / `get_digest_by_id(digestId, ...)` | Daily DeepSQL digests (slow queries + AI commentary written nightly to Slack). |
+| `get_missing_indexes(connectionId)` | Schema-walk view of suspected missing indexes (complements the workload-weighted `get_index_recommendations`). |
+| `get_index_health(connectionId)` | Total/bloated/unused/duplicate/biggest indexes. Use as first read on "audit my indexes". |
+| `get_unused_indexes(connectionId)` / `get_duplicate_indexes(connectionId)` | Catalog probes for storage + write-cost wins. |
+| `get_table_index_usage(connectionId, tableName)` | Per-table index scan/read/fetch counts. Diagnose "why isn't my index being used?". |
+| `list_index_recommendations(connectionId, status?)` | Browse the full recommendation history (PENDING/APPLIED/DISMISSED). |
+| `refresh_index_recommendations(connectionId)` | Force a fresh accumulation cycle (skips the 6-hour scheduler wait). |
+| `dismiss_index_recommendation(recommendationId)` | Reject a recommendation. Use only after the user explicitly says no. |
+| `get_latest_slow_query_analysis(connectionId)` / `list_slow_query_history(...)` | Read persisted slow-query analysis runs (faster than `analyze_slow_queries` which triggers new work). |
+| `acknowledge_growth_anomaly(anomalyId)` | Mark a growth alert as expected. Use after the user confirms the growth was intentional. |
+| `get_growth_config(connectionId)` / `set_growth_config(connectionId, config)` | View/edit growth-monitoring alert thresholds. |
 
 `EXPLAIN` and `EXPLAIN ANALYZE` are just SQL — type them as the query if
 you want raw plan output. Use `analyze_query_plan` when you want the

package/src/cli.js

@@ -383,12 +383,22 @@ const COMMAND_HELP = {
       ["analyze --connection <name> [options]",                       "Trigger a new analysis"],
       ["optimize --connection <name> --query-id <id>",                "Stream AI optimization steps live (SSE)"],
       ["delete (--history-id <id> | --connection <name>) [--yes]",    "Clean up history"],
+      ["trends --connection <name>",                                  "30-day tracked queries with delta metrics"],
+      ["regressions --connection <name> [--min-factor <n>]",          "Queries that got slower on the latest run"],
+      ["timeline <fingerprint> --connection <name>",                  "Day-by-day metrics for one fingerprint"],
+      ["customers --connection <name>",                               "Tenants ranked by total slow-query load"],
+      ["samples <fingerprint> --connection <name> [--limit <n>]",     "Literal SQL samples (with bind values) for a fingerprint"],
+      ["insights --connection <name> [--kind <k>] [--window <w>]",    "AI insights: hotspots, remediation, tail-risk, plan-drift, skew"],
+      ["trigger --connection <name>",                                 "Trigger an immediate analysis run"],
     ],
     options: [
-      ["--time-range LAST_24_HOURS|LAST_HOUR", "Window for analyze"],
-      ["--threshold-ms <n>",                   "Min duration to consider"],
-      ["--limit <n>",                          "Cap results"],
-      ["--json",                               "Raw JSON output"],
+      ["--time-range LAST_24_HOURS|LAST_HOUR",                "Window for analyze"],
+      ["--threshold-ms <n>",                                  "Min duration to consider"],
+      ["--limit <n>",                                         "Cap results"],
+      ["--min-factor <n>",                                    "Min slowdown multiple for regressions (default 1.5)"],
+      ["--kind hotspots|remediation|tail-risk|plan-drift|skew", "Insight category (default: all)"],
+      ["--window LAST_24_HOURS|LAST_7_DAYS|LAST_30_DAYS",     "Insights window (default LAST_7_DAYS)"],
+      ["--json",                                              "Raw JSON output"],
     ],
     notes: "`optimize` follows the SSE protocol from /slow-queries/optimize/stream — step events go to stderr, the final result to stdout. Honors SIGINT.",
   },

package/src/cli.test.js

@@ -116,3 +116,45 @@ test("--no-color suppresses ANSI escapes in help output", async () => {
   // No ESC bytes anywhere.
   assert.equal(/\x1b\[/.test(io.out()), false, "help output should be plain when --no-color is set");
 });
+
+// ─── help/dispatch drift guard ─────────────────────────────────────────────
+//
+// Every command-module SUBCOMMANDS map must be reflected in COMMAND_HELP so
+// `deepsql <command> -h` actually documents what `deepsql <command> <sub>`
+// will dispatch. A previous regression shipped four new slow-query
+// subcommands that worked but weren't listed in -h — users assumed the
+// install was stale. This test catches that class of bug at PR time.
+//
+// To extend: add a `{ command, modulePath }` entry. The module must export
+// a `SUBCOMMANDS` object whose keys are the dispatchable subcommand names.
+const HELP_DRIFT_TARGETS = [
+  { command: "slow-queries", modulePath: "./commands/slow-queries" },
+];
+
+for (const { command, modulePath } of HELP_DRIFT_TARGETS) {
+  test(`COMMAND_HELP["${command}"] documents every dispatchable subcommand`, () => {
+    const mod = require(modulePath);
+    assert.ok(mod.SUBCOMMANDS, `${modulePath} must export SUBCOMMANDS for the drift guard`);
+    const help = COMMAND_HELP[command];
+    assert.ok(help, `COMMAND_HELP["${command}"] is missing`);
+    assert.ok(Array.isArray(help.subcommands), `COMMAND_HELP["${command}"].subcommands must be an array`);
+
+    const dispatchable = Object.keys(mod.SUBCOMMANDS).sort();
+    // Each help row is [usage-string, description]; the first whitespace-
+    // separated token of usage-string is the subcommand name.
+    const documented = help.subcommands
+      .map((row) => String(row[0]).trim().split(/\s+/)[0])
+      .sort();
+    const missing = dispatchable.filter((s) => !documented.includes(s));
+    const stale = documented.filter((s) => !dispatchable.includes(s));
+
+    assert.deepEqual(
+      { missing, stale },
+      { missing: [], stale: [] },
+      `\`deepsql ${command} -h\` is out of sync with src/commands/${command}.js:\n`
+        + `  missing from help (callable but undocumented): ${missing.join(", ") || "none"}\n`
+        + `  stale in help   (documented but not callable): ${stale.join(", ") || "none"}\n`
+        + `Fix: update COMMAND_HELP["${command}"].subcommands in src/cli.js.`,
+    );
+  });
+}

package/src/commands/slow-queries.js

@@ -595,4 +595,4 @@ function trim(text, max) {
   return s.length > max ? s.slice(0, max - 1) + "…" : s;
 }
 
-module.exports = { run };
+module.exports = { run, SUBCOMMANDS };