@deepsql/mcp 0.16.0 → 0.18.0

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 12 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`.
 
@@ -47,6 +47,13 @@ which takes a server-resolved `recommendationId`.
 | `get_relationships` | Inferred + validated foreign keys with confidence scores. Many real DBs lack declared FKs; this fills the gap. |
 | `get_anti_patterns` | Schema-level (`kind=table`) or query-level (`kind=query`) anti-patterns. |
 | `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
+| `get_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. |
@@ -333,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

@@ -217,6 +217,221 @@ const TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "get_slow_query_timeline",
+    description:
+      "Get the day-by-day timeline for one slow query from DeepSQL's 30-day analytics store. "
+      + "The query is identified by its stable fingerprint (the MD5 of the normalized query — "
+      + "the `queryId` field returned by analyze_slow_queries). Returns one point per day with "
+      + "call count, mean/max execution time, and the regression factor versus the previous day. "
+      + "Use this to answer 'is this query getting slower over time'.",
+    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_query_regressions",
+    description:
+      "List slow queries that regressed (got slower) on the most recent daily analysis run. "
+      + "Each result carries the fingerprint, normalized SQL, current mean execution time, and "
+      + "the regression factor (this period's mean / the previous period's mean). Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        minFactor: {
+          type: "number",
+          minimum: 1,
+          description: "Minimum slowdown multiple to report. Defaults to 1.5 (≥50% slower).",
+        },
+      },
+      required: ["connectionId"],
+      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:
+      "Get table size / row-count growth trends for a connection from DeepSQL's persistent stats history. "
+      + "Returns three parallel time series (sizeOverTime, growthOverTime, rowCountOverTime) plus per-table "
+      + "headline rollups suitable for answering questions like \"which tables are growing fastest?\" or "
+      + "\"how much has `orders` grown in the last month?\". Backed by snapshots stored in DeepSQL's "
+      + "`table_stats_history`, not live `pg_total_relation_size()` probes — so it can show growth velocity "
+      + "and bloat over time without re-scanning the customer's database.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: {
+          type: "string",
+          description: "Optional table name to scope the trends to a single table. Omit for all tables.",
+        },
+        days: {
+          type: "integer",
+          minimum: 1,
+          maximum: 365,
+          description: "Lookback window in days. Defaults to 30.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_growth_anomalies",
+    description:
+      "Get growth anomalies DeepSQL flagged on a connection — sudden size or row spikes that exceeded the "
+      + "configured thresholds (percentage growth, absolute byte growth, statistical z-score). Each anomaly "
+      + "carries severity (CRITICAL / WARNING / INFO), the before/after sizes, an anomaly type "
+      + "(PERCENTAGE_GROWTH, ABSOLUTE_GROWTH, STATISTICAL_ANOMALY, ROW_SPIKE, NEW_TABLE), a human-readable "
+      + "description, and a confidence score. Use this BEFORE walking the user through a plan to optimize a "
+      + "table — the anomaly may be the root cause they should investigate first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        tableName: {
+          type: "string",
+          description: "Optional table name to scope to one table. Omit for the whole connection.",
+        },
+        unacknowledgedOnly: {
+          type: "boolean",
+          description: "When true, only return anomalies the operator hasn't acked yet. Defaults to false.",
+        },
+        days: {
+          type: "integer",
+          minimum: 1,
+          maximum: 365,
+          description: "Lookback window in days. Defaults to 30.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "execute_sql",
     description:
@@ -740,6 +955,185 @@ 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
+  // the agent's context — collapse to a per-table headline and a top-3
+  // "growing fastest" list.
+  const trends = payload?.trends || {};
+  const sizeOverTime = Array.isArray(trends.sizeOverTime) ? trends.sizeOverTime : [];
+  if (sizeOverTime.length === 0) {
+    return "No table-growth history for this connection in the requested window. "
+      + "The customer may not have stats-snapshot collection enabled yet.";
+  }
+
+  // Roll up per-table: first vs last snapshot.
+  const byTable = new Map();
+  for (const point of sizeOverTime) {
+    const t = point.table || "(unknown)";
+    if (!byTable.has(t)) byTable.set(t, []);
+    byTable.get(t).push(point);
+  }
+  const rows = [];
+  for (const [table, points] of byTable.entries()) {
+    points.sort((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+    const first = points[0];
+    const last = points[points.length - 1];
+    const firstBytes = first?.sizeBytes ?? 0;
+    const lastBytes = last?.sizeBytes ?? 0;
+    const deltaBytes = lastBytes - firstBytes;
+    rows.push({ table, firstBytes, lastBytes, deltaBytes });
+  }
+  rows.sort((a, b) => Math.abs(b.deltaBytes) - Math.abs(a.deltaBytes));
+
+  const days = payload?.days != null ? `${payload.days}d` : "window";
+  const top = rows.slice(0, 3).map((r) => {
+    const arrow = r.deltaBytes >= 0 ? "↑" : "↓";
+    const pct = r.firstBytes > 0
+      ? ` (${r.deltaBytes >= 0 ? "+" : ""}${((r.deltaBytes / r.firstBytes) * 100).toFixed(1)}%)`
+      : "";
+    return `${r.table} ${arrow} ${formatBytesHumanLib(Math.abs(r.deltaBytes))}${pct}`;
+  });
+  return `${rows.length} table(s) with growth data over ${days}. `
+    + `Most-changed: ${top.join("; ")}.`;
+}
+
+function summarizeGrowthAnomalies(payload) {
+  // Backend returns { success, anomalies[], statistics: { total, warning,
+  // critical, info, acknowledged, unacknowledged } }. Agents should know
+  // BEFORE drilling into a slow query whether a recent growth anomaly is
+  // the real root cause.
+  const list = Array.isArray(payload?.anomalies) ? payload.anomalies : [];
+  if (list.length === 0) {
+    return "No growth anomalies detected in the requested window.";
+  }
+  const stats = payload?.statistics || {};
+  const total = stats.total ?? list.length;
+  const crit = stats.critical ?? 0;
+  const warn = stats.warning ?? 0;
+  const unack = stats.unacknowledged ?? 0;
+
+  // Surface the worst recent one so the agent has something concrete to
+  // reference without having to walk the structured payload.
+  const worst = list.find((a) => a && a.severity === "CRITICAL")
+    || list.find((a) => a && a.severity === "WARNING")
+    || list[0];
+  const worstLine = worst
+    ? ` Top: [${worst.severity || "INFO"}] ${worst.tableName || "?"} — `
+      + `${worst.anomalyType || "growth"}`
+      + (worst.sizeGrowthPercent != null
+        ? ` ${worst.sizeGrowthPercent > 0 ? "+" : ""}${worst.sizeGrowthPercent.toFixed(1)}%`
+        : "")
+    : "";
+  return `${total} growth anomal${total === 1 ? "y" : "ies"} `
+    + `(${crit} critical, ${warn} warning, ${unack} unacknowledged).${worstLine}`;
+}
+
+function formatBytesHumanLib(bytes) {
+  if (bytes == null) return "?";
+  const abs = Math.abs(bytes);
+  if (abs < 1024) return `${bytes} B`;
+  if (abs < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (abs < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (abs < 1024 * 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+  return `${(bytes / (1024 * 1024 * 1024 * 1024)).toFixed(2)} TB`;
+}
+
 function summarizeQueryResult(payload) {
   const result = payload?.result || payload?.data || payload;
   const rowCount = result?.rowCount ?? 0;
@@ -785,6 +1179,27 @@ 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;
+    case "get_growth_anomalies":
+      summary = summarizeGrowthAnomalies(payload);
+      break;
     case "get_index_recommendations":
       summary = summarizeIndexRecommendations(payload);
       break;
@@ -969,6 +1384,126 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
+    case "get_slow_query_timeline": {
+      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)}/timeline/${encodeURIComponent(fingerprint)}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_query_regressions": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const minFactor = args.minFactor != null ? Number(args.minFactor) : 1.5;
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-query-analytics/${encodeURIComponent(connectionId)}/regressions?minFactor=${minFactor}`,
+      );
+      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.");
+      const params = [];
+      const days = clampInteger(args.days, 1, 365, 30);
+      params.push(`days=${days}`);
+      if (args.tableName) {
+        params.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      }
+      const payload = await callDeepSqlApi(
+        config,
+        `/growth-monitoring/trends/${encodeURIComponent(connectionId)}?${params.join("&")}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_growth_anomalies": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const params = [];
+      const days = clampInteger(args.days, 1, 365, 30);
+      params.push(`days=${days}`);
+      if (args.tableName) {
+        params.push(`tableName=${encodeURIComponent(String(args.tableName))}`);
+      }
+      if (args.unacknowledgedOnly === true) {
+        params.push("unacknowledgedOnly=true");
+      }
+      const payload = await callDeepSqlApi(
+        config,
+        `/growth-monitoring/anomalies/${encodeURIComponent(connectionId)}?${params.join("&")}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
     case "execute_sql": {
       const connectionId = String(args.connectionId || "").trim();
       const query = String(args.query || "").trim();
@@ -1075,6 +1610,13 @@ module.exports = {
   stripSqlComments,
   stripSqlStringLiterals,
   summarizeApplyResult,
+  summarizeGrowthAnomalies,
   summarizeIndexRecommendations,
+  summarizeQuerySamples,
+  summarizeSlowQueryCustomers,
+  summarizeSlowQueryInsights,
+  summarizeSlowQueryOptimization,
+  summarizeTableGrowth,
+  summarizeTrackedQueries,
   validateReadOnlySql,
 };

package/package.json

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