@deepsql/mcp 0.17.0 → 0.18.1

package/CLAUDE.md

@@ -33,7 +33,7 @@ server, and the statement you ran.** Don't be sloppy.
 
 ## The tools you have
 
-The MCP server exposes 14 tools. They all take a `connectionId` (UUID
+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`.
 
@@ -49,6 +49,11 @@ which takes a server-resolved `recommendationId`.
 | `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
 | `get_slow_query_timeline` | Day-by-day timeline for one query from the 30-day analytics store — call count, mean/max time, regression factor per day. Identify the query by its fingerprint (the `queryId` from `analyze_slow_queries`). Answers "is this query getting slower". |
 | `get_query_regressions` | Slow queries that regressed (got slower) on the latest daily analysis run, ranked by slowdown factor. Read-only. |
+| `list_tracked_queries` | All slow-query fingerprints in the 30-day analytics store, with call counts, mean/max exec time, and regression flags. Use to discover what's worth drilling into before pulling a timeline or samples. |
+| `get_slow_query_customers` | Tenants/customers ranked by total slow-query time. Includes resolved customer name when a lookup table is configured. Answers "which customer is driving the load?" |
+| `get_query_samples` | Literal SQL samples (with actual bind values substituted) for a fingerprint, slowest-first. Use to reproduce an execution, get a real EXPLAIN plan, or see how different callers use the same query shape. |
+| `get_slow_query_insights` | Pre-computed AI insights for slow queries grouped by `kind`: `hotspots` (most total DB time), `remediation` (actionable fixes), `tail-risk` (p95/max outliers), `plan-drift` (execution plan changed), `skew` (one tenant disproportionately loaded). Default `all` returns the combined list. Accepts `window` (`LAST_24_HOURS` / `LAST_7_DAYS` / `LAST_30_DAYS`) and `limit`. |
+| `optimize_slow_query` | AI-generated optimization recommendations for a specific SQL — index suggestions, query rewrites, and estimated impact. Synchronous (non-streaming); pass `avgExecutionTimeMs` to anchor the impact estimate. |
 | `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. |
@@ -335,7 +340,11 @@ them at the terminal command rather than trying to fake it through
 | Catalog: per-table index usage stats | `deepsql indexes usage <table>` |
 | Catalog: index health report | `deepsql indexes health` |
 | Daily digest (anomalies + AI commentary) | `deepsql digest`, `deepsql digest 7` |
-| Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` |
+| Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` (or MCP `optimize_slow_query` for a synchronous version) |
+| Customers driving the most slow-query load | `deepsql slow-queries customers --connection <c>` (or MCP `get_slow_query_customers`) |
+| Literal SQL samples for a fingerprint | `deepsql slow-queries samples <fingerprint> --connection <c>` (or MCP `get_query_samples`) |
+| AI-flagged hotspots / tail-risk / plan-drift | `deepsql slow-queries insights --connection <c> [--kind hotspots]` (or MCP `get_slow_query_insights`) |
+| Trigger an immediate daily analysis run | `deepsql slow-queries trigger --connection <c>` |
 
 These are reachable from any terminal where `deepsql` is installed and
 logged in; the saved profile is shared with the MCP server.

package/README.md

@@ -52,8 +52,9 @@ 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:
+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):
 
 | Tool | Purpose |
 |---|---|
@@ -64,7 +65,18 @@ at the SQL layer:
 | `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 |
+| `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 |
+| `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 |
+| `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 |
 | `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

@@ -258,6 +258,120 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "list_tracked_queries",
+    description:
+      "List all slow query fingerprints tracked in DeepSQL's 30-day rolling analytics store. "
+      + "Each entry carries the stable fingerprint (MD5 of normalized SQL), a normalized query "
+      + "sample, delta call count, mean/max execution time, and the regression factor versus the "
+      + "previous day. Use this to discover which queries are worth investigating before pulling "
+      + "timelines or samples.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_slow_query_customers",
+    description:
+      "List all tenants / customers ranked by total slow-query time for a connection. "
+      + "Each entry includes the raw customer id, resolved customer name (when a lookup "
+      + "table is configured), total number of distinct slow queries attributed to them, "
+      + "and the total cumulative execution time. Use this to answer 'which customer is "
+      + "driving the most database load?'",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_query_samples",
+    description:
+      "Retrieve literal SQL samples (with actual bind values substituted in) for a specific "
+      + "query fingerprint, ordered slowest-first. Samples are captured from the slow-query log "
+      + "or performance-schema and stored in DeepSQL's analytics store. Use these to reproduce "
+      + "a slow execution, get a real EXPLAIN plan, or understand how different callers use the "
+      + "same query shape.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        fingerprint: {
+          type: "string",
+          description: "Stable query fingerprint (MD5 of the normalized query).",
+        },
+      },
+      required: ["connectionId", "fingerprint"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_slow_query_insights",
+    description:
+      "Retrieve AI-enriched slow-query insights for a connection. Insights are pre-computed "
+      + "by DeepSQL's daily analysis and grouped into kinds: `hotspots` (queries consuming "
+      + "the most total DB time), `remediation` (actionable fix recommendations), `tail-risk` "
+      + "(high-variance queries with dangerous p95/max outliers), `plan-drift` (queries whose "
+      + "execution plan changed), and `skew` (queries showing disproportionate load from one "
+      + "tenant). Use `kind=all` (default) for the combined list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        kind: {
+          type: "string",
+          enum: ["all", "hotspots", "remediation", "tail-risk", "plan-drift", "skew"],
+          description: "Insight category to fetch. Defaults to 'all'.",
+        },
+        window: {
+          type: "string",
+          enum: ["LAST_24_HOURS", "LAST_7_DAYS", "LAST_30_DAYS"],
+          description: "Time window for the insights. Defaults to 'LAST_7_DAYS'.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Maximum number of insights to return. Defaults to 10.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    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. "
+      + "Pass `avgExecutionTimeMs` to anchor the impact estimate to a real baseline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        queryText: {
+          type: "string",
+          description: "The SQL query to optimize. Literal or normalized form both accepted.",
+        },
+        avgExecutionTimeMs: {
+          type: "number",
+          minimum: 0,
+          description: "Optional observed average execution time in ms — anchors impact estimates.",
+        },
+      },
+      required: ["connectionId", "queryText"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "get_table_growth",
     description:
@@ -841,6 +955,101 @@ function summarizeSlowQueries(payload) {
     + parts.join("");
 }
 
+function summarizeTrackedQueries(payload) {
+  const list = Array.isArray(payload) ? payload : [];
+  if (list.length === 0) {
+    return "No tracked queries yet. The daily analysis runs at 01:30, or trigger one with trigger_slow_query_analysis.";
+  }
+  const top = list
+    .slice()
+    .sort((a, b) => (b.meanExecMs ?? 0) - (a.meanExecMs ?? 0))
+    .slice(0, 5)
+    .map((q) => {
+      const fp = String(q.fingerprint || "").slice(0, 8);
+      const ms = q.meanExecMs != null ? `${Math.round(q.meanExecMs)}ms` : "?ms";
+      const calls = q.callsDelta != null ? ` ×${q.callsDelta}` : "";
+      const reg = q.regressionFactor != null && q.regressionFactor > 1
+        ? ` ⚠ ${q.regressionFactor.toFixed(2)}x slower` : "";
+      const sql = String(q.normalizedSql || "").replace(/\s+/g, " ").slice(0, 60);
+      return `  ${fp}… avg=${ms}${calls}${reg} — ${sql}`;
+    });
+  const regCount = list.filter((q) => q.regressionFactor != null && q.regressionFactor > 1).length;
+  return `${list.length} tracked query/queries (30-day window)${regCount > 0 ? `, ${regCount} regressed` : ""}.\nSlowest:\n${top.join("\n")}`;
+}
+
+function summarizeSlowQueryCustomers(payload) {
+  const list = Array.isArray(payload) ? payload : [];
+  if (list.length === 0) {
+    return "No customer attribution data yet. Configure a tenant column in slow-query analytics settings.";
+  }
+  const top = list.slice(0, 5).map((c, i) => {
+    const name = c.customerName || c.customerId || "unknown";
+    const queries = c.queryCount != null ? `${c.queryCount} queries` : "";
+    const totalMs = c.totalExecMs != null ? `, ${Math.round(c.totalExecMs / 1000)}s total` : "";
+    return `  ${i + 1}. ${name}${queries ? ` — ${queries}` : ""}${totalMs}`;
+  });
+  return `${list.length} customer(s) with slow queries. Top by load:\n${top.join("\n")}`;
+}
+
+function summarizeQuerySamples(payload) {
+  const list = Array.isArray(payload) ? payload : [];
+  if (list.length === 0) {
+    return "No samples found for this query fingerprint.";
+  }
+  const times = list.map((s) => s.execMs).filter((t) => t != null);
+  const minMs = times.length ? Math.min(...times) : null;
+  const maxMs = times.length ? Math.max(...times) : null;
+  const avgMs = times.length ? Math.round(times.reduce((a, b) => a + b, 0) / times.length) : null;
+  const sources = [...new Set(list.map((s) => s.source).filter(Boolean))].join(", ");
+  return `${list.length} sample(s)`
+    + (minMs != null ? `, min=${minMs}ms avg=${avgMs}ms max=${maxMs}ms` : "")
+    + (sources ? `, source: ${sources}` : "")
+    + `. Use rawSql for EXPLAIN.`;
+}
+
+function summarizeSlowQueryInsights(payload) {
+  const list = Array.isArray(payload) ? payload : [];
+  if (list.length === 0) {
+    return "No insights found for the requested window/kind. Run analyze-now or wait for the next daily pass.";
+  }
+  const bySeverity = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+  for (const ins of list) {
+    const sev = (ins.severity || "LOW").toUpperCase();
+    if (sev in bySeverity) bySeverity[sev]++;
+  }
+  const sevLine = Object.entries(bySeverity)
+    .filter(([, n]) => n > 0)
+    .map(([k, n]) => `${n} ${k.toLowerCase()}`)
+    .join(", ");
+  const top = list.slice(0, 3).map((ins, i) => {
+    const sev = ins.severity ? `[${ins.severity}] ` : "";
+    const title = ins.title || ins.insightType || "insight";
+    const desc = String(ins.description || ins.message || "").replace(/\s+/g, " ").slice(0, 120);
+    return `  ${i + 1}. ${sev}${title}${desc ? ` — ${desc}` : ""}`;
+  });
+  return `${list.length} insight(s) (${sevLine || "none by severity"}).\n${top.join("\n")}`;
+}
+
+function summarizeSlowQueryOptimization(payload) {
+  if (!payload) return "No optimization result returned.";
+  const recList = Array.isArray(payload.recommendations) ? payload.recommendations : [];
+  const idxList = Array.isArray(payload.suggestedIndexes) ? payload.suggestedIndexes : [];
+  const parts = [];
+  if (payload.optimizedQuery) {
+    parts.push("Optimized query available in `optimizedQuery`.");
+  }
+  if (idxList.length > 0) {
+    parts.push(`${idxList.length} index suggestion(s): ${idxList.map((x) => x.indexDdl || x.column || JSON.stringify(x)).slice(0, 3).join("; ")}`);
+  }
+  if (recList.length > 0) {
+    parts.push(`${recList.length} recommendation(s): ${recList.map((r) => r.title || r.summary || JSON.stringify(r)).slice(0, 3).join("; ")}`);
+  }
+  if (payload.estimatedImprovementPercent != null) {
+    parts.push(`Estimated improvement: ${payload.estimatedImprovementPercent.toFixed(0)}%`);
+  }
+  return parts.length > 0 ? parts.join(". ") + "." : "Optimization complete. See structuredContent for details.";
+}
+
 function summarizeTableGrowth(payload) {
   // Backend returns { success, trends: { sizeOverTime[], growthOverTime[],
   // rowCountOverTime[] }, days }. We don't want to dump the raw arrays into
@@ -970,6 +1179,21 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(payload);
       break;
+    case "list_tracked_queries":
+      summary = summarizeTrackedQueries(payload);
+      break;
+    case "get_slow_query_customers":
+      summary = summarizeSlowQueryCustomers(payload);
+      break;
+    case "get_query_samples":
+      summary = summarizeQuerySamples(payload);
+      break;
+    case "get_slow_query_insights":
+      summary = summarizeSlowQueryInsights(payload);
+      break;
+    case "optimize_slow_query":
+      summary = summarizeSlowQueryOptimization(payload);
+      break;
     case "get_table_growth":
       summary = summarizeTableGrowth(payload);
       break;
@@ -1183,6 +1407,68 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
+    case "list_tracked_queries": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/queries`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_slow_query_customers": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/customers`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_query_samples": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const fingerprint = String(args.fingerprint || "").trim();
+      if (!fingerprint) return buildToolError("fingerprint is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/query/${encodeURIComponent(fingerprint)}/samples`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_slow_query_insights": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const kind = String(args.kind || "all").toLowerCase();
+      const window = String(args.window || "LAST_7_DAYS").toUpperCase();
+      const limit = clampInteger(args.limit, 1, 100, 10);
+      const subPath = kind === "all" ? "" : `/${encodeURIComponent(kind)}`;
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-queries/insights/${encodeURIComponent(connectionId)}${subPath}?window=${encodeURIComponent(window)}&limit=${limit}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "optimize_slow_query": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const queryText = String(args.queryText || "").trim();
+      if (!queryText) return buildToolError("queryText is required.");
+      const json = { connectionId, queryText };
+      if (args.avgExecutionTimeMs != null) {
+        json.avgExecutionTimeMs = Number(args.avgExecutionTimeMs);
+      }
+      const payload = await callDeepSqlApi(config, "/slow-queries/optimize", {
+        method: "POST",
+        json,
+      });
+      return buildToolResult(name, payload);
+    }
+
     case "get_table_growth": {
       const connectionId = String(args.connectionId || "").trim();
       if (!connectionId) return buildToolError("connectionId is required.");
@@ -1326,6 +1612,11 @@ module.exports = {
   summarizeApplyResult,
   summarizeGrowthAnomalies,
   summarizeIndexRecommendations,
+  summarizeQuerySamples,
+  summarizeSlowQueryCustomers,
+  summarizeSlowQueryInsights,
+  summarizeSlowQueryOptimization,
   summarizeTableGrowth,
+  summarizeTrackedQueries,
   validateReadOnlySql,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
@@ -28,5 +28,8 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@inquirer/prompts": "^8.4.2"
+  },
+  "overrides": {
+    "mute-stream": "^3.0.0"
   }
 }

package/skills/SKILL_BODY.md

@@ -2,7 +2,7 @@
 
 You have two DeepSQL surfaces available:
 
-1. **MCP tools** — JSON-RPC tools loaded into your session (10 of them).
+1. **MCP tools** — JSON-RPC tools loaded into your session (21 of them).
    Use these for in-session retrieval and SQL execution.
 
 2. **`deepsql` CLI** — a shell binary on the user's PATH (~19 commands).
@@ -87,6 +87,13 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 | `get_relationships(connectionId)` | Foreign keys (declared + inferred-with-confidence). |
 | `get_anti_patterns(connectionId, kind="table"\|"query")` | Patterns to avoid in this DB. |
 | `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
+| `get_slow_query_timeline(connectionId, fingerprint)` | Day-by-day timeline for one fingerprint: call count, mean/max time, regression factor per day. Answers "is this query getting slower". |
+| `get_query_regressions(connectionId, minFactor?)` | Slow queries that got slower on the latest daily analysis run, ranked by slowdown factor. |
+| `list_tracked_queries(connectionId)` | All fingerprints in the 30-day analytics store. Browse first, then drill into one with `get_slow_query_timeline` / `get_query_samples`. |
+| `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. |
 | `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). |
@@ -132,7 +139,7 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `deepsql digest [N]\|list\|show <id>` | **CLI-only**: daily digest of slow queries + AI commentary | none |
 | `deepsql growth trends\|history\|anomalies\|ack\|capture\|config` | Table growth analytics (size/row trends, detected anomalies, alert thresholds) | partial: `get_table_growth`, `get_growth_anomalies` |
 | `deepsql indexes list\|missing\|health\|unused\|duplicates\|usage <table>` | **CLI-only**: index recommendations and usage stats | none |
-| `deepsql slow-queries latest\|history\|analyze\|optimize\|delete` | Slow-query analyses; `optimize` streams AI optimization steps live (SSE) | partial: `analyze_slow_queries` |
+| `deepsql slow-queries latest\|history\|analyze\|optimize\|delete\|trends\|regressions\|timeline\|customers\|samples\|insights\|trigger` | Full slow-query toolkit. `optimize` streams AI optimization steps live (SSE); `customers` / `samples` / `insights` mirror the analytics MCP tools; `trigger` runs an immediate daily analysis. | mostly mirrored in MCP — use CLI for streaming optimize and one-shot triggers |
 | `deepsql users list\|get\|add\|set-role\|lock\|unlock\|disable\|resend-invite\|reset-password\|delete` | **Admin-only, CLI-only**: workspace user management | none |
 | `deepsql access list\|grant\|revoke\|policy <user> <conn>` | **Admin-only, CLI-only**: per-connection access grants + chat policy editing in $EDITOR | none |
 | `deepsql permissions list\|override\|reset` | **Admin-only, CLI-only**: role-based permission overrides | none |
@@ -159,7 +166,11 @@ shell-out (with `--caller-agent`) or tell the user the exact command:
 | "Duplicate indexes?" | `deepsql indexes duplicates --connection <c>` |
 | "Index health on this connection" | `deepsql indexes health --connection <c>` |
 | "Indexes on `<table>` and how often they're used" | `deepsql indexes usage <table> --connection <c>` |
-| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` |
+| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` (streamed) — or MCP `optimize_slow_query(connectionId, queryText)` for a one-shot JSON response |
+| "Which customer is driving the most slow queries?" | MCP: `get_slow_query_customers(connectionId)`. CLI: `deepsql slow-queries customers --connection <c>` |
+| "Show me the actual SQL run for this fingerprint" | MCP: `get_query_samples(connectionId, fingerprint)`. CLI: `deepsql slow-queries samples <fingerprint> --connection <c>` |
+| "What slow-query insights / hotspots / tail-risk has DeepSQL found?" | MCP: `get_slow_query_insights(connectionId, kind?, window?)`. CLI: `deepsql slow-queries insights --connection <c> [--kind hotspots]` |
+| "Trigger slow-query analysis now" / "Re-run the daily analysis" | CLI: `deepsql slow-queries trigger --connection <c>` |
 | "Add a new database connection" | `deepsql connections add` (interactive) or `--from-file <path>` |
 | "Test a connection without saving" | `deepsql connections test --from-file <path>` |
 | "Trigger brain re-initialization for this connection" | `deepsql connections init <name> --wait` |

package/src/commands/slow-queries.js

@@ -11,6 +11,15 @@
  *   deepsql slow-queries optimize --connection <name> --query-id <id>
  *       (streams SSE; use --query-text to skip history lookup)
  *   deepsql slow-queries delete --history-id <id> [--yes]
+ *   deepsql slow-queries trends --connection <name> [--json]
+ *   deepsql slow-queries regressions --connection <name> [--min-factor <n>] [--json]
+ *   deepsql slow-queries timeline <fingerprint> --connection <name> [--json]
+ *   deepsql slow-queries customers --connection <name> [--json]
+ *   deepsql slow-queries samples <fingerprint> --connection <name> [--limit <n>] [--json]
+ *   deepsql slow-queries insights --connection <name>
+ *       [--kind hotspots|remediation|tail-risk|plan-drift|skew]
+ *       [--window LAST_7_DAYS|LAST_24_HOURS|LAST_30_DAYS] [--limit <n>] [--json]
+ *   deepsql slow-queries trigger --connection <name> [--json]
  *
  * The optimize subcommand follows the SSE protocol from
  * /slow-queries/optimize/stream — `step` events go to stderr, the final
@@ -32,6 +41,10 @@ const SUBCOMMANDS = {
   trends: cmdTrends,
   regressions: cmdRegressions,
   timeline: cmdTimeline,
+  customers: cmdCustomers,
+  samples: cmdSamples,
+  insights: cmdInsights,
+  trigger: cmdTrigger,
 };
 
 async function run(opts, io = {}) {
@@ -39,7 +52,8 @@ async function run(opts, io = {}) {
   if (!sub) {
     throw new Error(
       "Usage: deepsql slow-queries "
-      + "<latest|history|analyze|optimize|delete|trends|regressions|timeline> ...");
+      + "<latest|history|analyze|optimize|delete|trends|regressions|timeline"
+      + "|customers|samples|insights|trigger> ...");
   }
   const handler = SUBCOMMANDS[sub];
   if (!handler) throw new Error(`Unknown slow-queries subcommand: ${sub}.`);
@@ -374,6 +388,136 @@ async function cmdTimeline(opts, { stdout = process.stdout } = {}) {
   })));
 }
 
+// ─── customers ─────────────────────────────────────────────────────────────
+
+async function cmdCustomers(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/customers`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No customer attribution data yet. Configure a tenant column in analytics settings.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "rank",       label: "#" },
+    { key: "customer",   label: "CUSTOMER" },
+    { key: "name",       label: "NAME" },
+    { key: "queries",    label: "QUERIES" },
+    { key: "totalSec",   label: "TOTAL (s)" },
+  ], items.map((c, i) => ({
+    rank:     String(i + 1),
+    customer: trim(c.customerId || "", 22),
+    name:     trim(c.customerName || "—", 28),
+    queries:  String(c.queryCount ?? "?"),
+    totalSec: c.totalExecMs != null ? (c.totalExecMs / 1000).toFixed(1) : "?",
+  })));
+}
+
+// ─── samples ───────────────────────────────────────────────────────────────
+
+async function cmdSamples(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const fingerprint = opts.positional[0];
+  if (!fingerprint) {
+    throw new Error("Usage: deepsql slow-queries samples <fingerprint> --connection <name>");
+  }
+  const limit = parseNum(opts.limit) || 10;
+  const rows = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}`
+      + `/query/${encodeURIComponent(fingerprint)}/samples`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows.slice(0, limit) : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write("No samples found for that fingerprint.\n");
+    return;
+  }
+  printTable(stdout, [
+    { key: "execMs",   label: "EXEC MS" },
+    { key: "examined", label: "ROWS EXAM" },
+    { key: "sent",     label: "ROWS SENT" },
+    { key: "source",   label: "SOURCE" },
+    { key: "captured", label: "CAPTURED AT" },
+    { key: "sql",      label: "SQL" },
+  ], items.map((s) => ({
+    execMs:   s.execMs != null ? String(Math.round(s.execMs)) : "?",
+    examined: String(s.rowsExamined ?? "?"),
+    sent:     String(s.rowsSent ?? "?"),
+    source:   trim(s.source || "?", 14),
+    captured: formatTime(s.capturedAt),
+    sql:      trim(s.rawSql || "", 60),
+  })));
+}
+
+// ─── insights ──────────────────────────────────────────────────────────────
+
+async function cmdInsights(opts, { stdout = process.stdout } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const kind = (opts.kind || "").toLowerCase();
+  const window = (opts.window || "LAST_7_DAYS").toUpperCase();
+  const limit = parseNum(opts.limit) || 10;
+  const subPath = kind && kind !== "all" ? `/${encodeURIComponent(kind)}` : "";
+  const rows = await request(
+    session.baseUrl,
+    `/slow-queries/insights/${encodeURIComponent(connectionId)}${subPath}`
+      + `?window=${encodeURIComponent(window)}&limit=${limit}`,
+    { token: session.token },
+  );
+  const items = Array.isArray(rows) ? rows : [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No insights for window=${window}${kind ? ` kind=${kind}` : ""}.\n`);
+    return;
+  }
+  for (let i = 0; i < items.length; i++) {
+    const ins = items[i];
+    const sev = ins.severity ? `[${ins.severity}] ` : "";
+    const title = ins.title || ins.insightType || "insight";
+    const desc = String(ins.description || ins.message || "").replace(/\s+/g, " ").trim();
+    stdout.write(`${i + 1}. ${sev}${title}\n`);
+    if (desc) stdout.write(`   ${desc}\n`);
+  }
+}
+
+// ─── trigger ───────────────────────────────────────────────────────────────
+
+async function cmdTrigger(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  stderr.write(`Triggering slow-query analysis for ${opts.connection}…\n`);
+  const result = await request(
+    session.baseUrl,
+    `/slow-query-analytics/${encodeURIComponent(connectionId)}/analyze-now`,
+    { method: "POST", token: session.token, timeoutMs: 300000 },
+  );
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  const runId = result?.analysisRunId || result?.runId || "?";
+  const health = result?.overallHealth || result?.health || "";
+  stdout.write(`Analysis started. Run ID: ${runId}${health ? `  Health: ${health}` : ""}\n`);
+}
+
 function printTrendRows(stdout, items) {
   printTable(stdout, [
     { key: "fingerprint", label: "QUERY ID" },