@deepsql/mcp 0.16.0 → 0.17.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 14 tools. They all take a `connectionId` (UUID
 returned by `list_connections`) except `apply_index_recommendation`,
 which takes a server-resolved `recommendationId`.
 
@@ -47,6 +47,8 @@ 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. |
 | `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. |

package/deepsql-phase1-lib.js

@@ -217,6 +217,107 @@ 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: "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 +841,90 @@ function summarizeSlowQueries(payload) {
     + parts.join("");
 }
 
+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 +970,12 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(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 +1160,64 @@ 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 "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 +1324,8 @@ module.exports = {
   stripSqlComments,
   stripSqlStringLiterals,
   summarizeApplyResult,
+  summarizeGrowthAnomalies,
   summarizeIndexRecommendations,
+  summarizeTableGrowth,
   validateReadOnlySql,
 };

package/package.json

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

package/skills/SKILL_BODY.md

@@ -87,6 +87,8 @@ 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_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). |
 
@@ -128,6 +130,7 @@ deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
 | `deepsql relationships --connection <c>` | Inferred + validated FKs | `get_relationships` |
 | `deepsql anti-patterns --connection <c> [--kind table\|query]` | Anti-patterns | `get_anti_patterns` |
 | `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 users list\|get\|add\|set-role\|lock\|unlock\|disable\|resend-invite\|reset-password\|delete` | **Admin-only, CLI-only**: workspace user management | none |
@@ -147,6 +150,10 @@ shell-out (with `--caller-agent`) or tell the user the exact command:
 | User asks for | Run / suggest |
 |---|---|
 | "What changed in the database recently?" / "Today's report" | `deepsql digest` (most recent) or `deepsql digest 7` (last week) |
+| "Which tables are growing fastest?" / "How big is `<table>` now vs a month ago?" | MCP: `get_table_growth(connectionId, days=30)`. CLI: `deepsql growth trends --connection <c>` (or `--table <name> --days 30`) |
+| "Did any table spike in size recently?" / "Anything weird in growth?" | MCP: `get_growth_anomalies(connectionId, unacknowledgedOnly=true)`. CLI: `deepsql growth anomalies --connection <c> --unack` |
+| "Force a fresh stats snapshot" (admin) | `deepsql growth capture --connection <c>` |
+| "Set / view growth alert thresholds" (admin) | `deepsql growth config show --connection <c>` / `set --file <p>` |
 | "What indexes are we missing?" / "Index advice" | `deepsql indexes missing --connection <c>` |
 | "Are any indexes unused?" / "Index bloat" | `deepsql indexes unused --connection <c>` |
 | "Duplicate indexes?" | `deepsql indexes duplicates --connection <c>` |

package/src/auth/store.js

@@ -30,18 +30,18 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const os = require("node:os");
+const { userHome } = require("../user-home");
 
 function configDir() {
   const override = process.env.DEEPSQL_CONFIG_DIR;
   if (override) return override;
   if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    const base = process.env.APPDATA || path.join(userHome(), "AppData", "Roaming");
     return path.join(base, "deepsql");
   }
   const xdg = process.env.XDG_CONFIG_HOME;
   if (xdg) return path.join(xdg, "deepsql");
-  return path.join(os.homedir(), ".config", "deepsql");
+  return path.join(userHome(), ".config", "deepsql");
 }
 
 function authFilePath() {

package/src/cli.js

@@ -31,6 +31,7 @@ const COMMANDS = {
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  growth: () => require("./commands/growth"),
   indexes: () => require("./commands/indexes"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
@@ -55,6 +56,7 @@ const COMMAND_LIST = [
   ["analyze",        false, "AI-enriched query plan analysis (use --analyze for EXPLAIN ANALYZE)"],
   ["schema",         false, "Dump connection schema or DB objects as JSON"],
   ["digest",         true,  "Show DeepSQL daily digests"],
+  ["growth",         true,  "Table growth analytics — trends, history, anomalies, alert config"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
@@ -224,6 +226,29 @@ const COMMAND_HELP = {
     ],
   },
 
+  growth: {
+    description: "Table growth analytics — size/row trends, detected anomalies, alert thresholds.",
+    usage: "deepsql growth <subcommand> [options]",
+    subcommands: [
+      ["trends    [--table <t>] [--days N=30]",     "Per-table growth headline over the last N days (default)"],
+      ["history   [--table <t>] [--days N=7]",      "Raw snapshot history rows"],
+      ["anomalies [--table <t>] [--unack] [--days N=30]", "Sudden growth spikes flagged by severity"],
+      ["ack       <anomalyId>",                     "Acknowledge an anomaly"],
+      ["capture",                                   "Trigger a fresh stats snapshot (admin; async)"],
+      ["config    show [--table <t>]",              "Show alert thresholds for the connection"],
+      ["config    set --file <path>",               "POST a GrowthAlertConfiguration JSON (admin)"],
+    ],
+    options: [
+      ["--connection <name>",  "Connection to inspect"],
+      ["--table <name>",       "Filter to one table"],
+      ["--days <N>",           "Lookback window in days (max 365)"],
+      ["--unack",              "anomalies: only unacknowledged ones"],
+      ["--file <path>",        "config set: path to GrowthAlertConfiguration JSON"],
+      ["--json",               "Raw JSON output"],
+    ],
+    notes: "`capture` and `config set` are the only mutations; both are admin-level but neither writes user data. Trends + anomalies are the agent-facing subcommands and are also exposed via the MCP tools `get_table_growth` and `get_growth_anomalies`.",
+  },
+
   "brain-context": {
     description: "Retrieve embedding-ranked tables/columns/FKs, training docs, and business rules for a question.",
     usage: 'deepsql brain-context "<question>" --connection <name> [options]',
@@ -565,6 +590,11 @@ function buildOpts(parsed) {
     // Indexes
     all: !!f.all,
     status: f.status || null,
+    // Growth analytics (also re-used wherever a per-table / lookback filter
+    // is useful — kept generic on purpose)
+    table: f.table || null,
+    days: f.days || null,
+    unack: !!f.unack,
     // mcp config installer
     install: !!f.install,
     print: !!f.print,