@deepsql/mcp 0.18.2 → 0.20.0

package/deepsql-phase1-lib.js

@@ -350,9 +350,11 @@ const TOOL_DEFINITIONS = [
   {
     name: "optimize_slow_query",
     description:
-      "Get AI-generated optimization recommendations for a specific slow query — including "
-      + "index suggestions, query rewrites, and expected performance impact. DeepSQL inspects "
-      + "the query against the connection's schema, existing indexes, and workload patterns. "
+      "Get an AI query REWRITE and plan diagnosis for one specific slow query. "
+      + "Single-query scoped: returns a rewritten SQL (validated against the live DB), "
+      + "the plan bottleneck, and an estimated improvement. Does NOT recommend indexes — "
+      + "index and pre-aggregation recommendations require the whole workload and come "
+      + "from the holistic Workload Analysis (and the get_index_recommendations tool). "
       + "Pass `avgExecutionTimeMs` to anchor the impact estimate to a real baseline.",
     inputSchema: {
       type: "object",
@@ -518,6 +520,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 {
@@ -1224,7 +1572,11 @@ function buildToolResult(name, payload, extra = {}) {
         text: summary,
       },
     ],
-    structuredContent: payload,
+    // MCP spec requires `structuredContent` to be a JSON object. Several tools
+    // (list_connections, get_relationships, list_business_rules, …) return a
+    // top-level array from the backend; wrap those so spec-strict clients
+    // (e.g. the `mcp` Python SDK used by Hermes) don't reject the result.
+    structuredContent: Array.isArray(payload) ? { items: payload } : payload,
   };
 }
 
@@ -1557,6 +1909,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,7 +1,7 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.18.2",
-  "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
+  "version": "0.20.0",
+  "description": "DeepSQL CLI, DBA Agent TUI, and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
     "deepsql-mcp": "deepsql-phase1-server.js"
@@ -14,6 +14,7 @@
     "bin",
     "skills",
     "src",
+    "agent-profile",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
     "claude_desktop_config.customer.example.json",

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.
 
@@ -93,11 +98,26 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_slow_query_customers(connectionId)` | Tenants ranked by total slow-query time — answers "which customer is driving the load?" |
 | `get_query_samples(connectionId, fingerprint)` | Literal SQL samples with bind values for a fingerprint, slowest-first. Use to reproduce an execution or run a real EXPLAIN. |
 | `get_slow_query_insights(connectionId, kind?, window?, limit?)` | Pre-computed AI insights — `hotspots`, `remediation`, `tail-risk`, `plan-drift`, `skew`, or `all` (default). |
-| `optimize_slow_query(connectionId, queryText, avgExecutionTimeMs?)` | AI optimization recommendations for a specific SQL — index suggestions, query rewrites, estimated impact. |
+| `optimize_slow_query(connectionId, queryText, avgExecutionTimeMs?)` | AI query REWRITE + plan diagnosis for one SQL (single-query scoped). NOT indexes — those need the whole workload; use `get_index_recommendations` or Workload Analysis. |
 | `get_table_growth(connectionId, tableName?, days?)` | Persistent stats history: per-table size/row time series + headline rollups. Use to answer "which tables are growing fastest?" or "how much has X grown in the last month?" without scanning the live DB. |
 | `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
@@ -118,10 +138,11 @@ called by claude-code via deepsql CLI").
 deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 ```
 
-### Command catalog (19 top-level commands)
+### Command catalog (20 top-level commands)
 
 | Command | What it does | MCP equivalent? |
 |---|---|---|
+| `deepsql agent` (or bare `deepsql` in a terminal) | Launch the **DeepSQL Agent** — an interactive DBA/BI chat TUI. Uses your saved `deepsql login`; the model is proxied by the DeepSQL backend, so no LLM key is needed. First run installs the agent runtime. | none — interactive TUI |
 | `deepsql login` | Authorize CLI against a DeepSQL host (browser PKCE / device code / password) | none — interactive only |
 | `deepsql logout` | Revoke the saved token | none |
 | `deepsql whoami` | Show the logged-in user, role, URL, pinned connection | none |