@deepsql/mcp 0.3.0 → 0.5.0

package/package.json

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

package/src/cli.js

@@ -7,7 +7,7 @@
  * small for the self-hosted distribution and makes it trivial to embed in
  * scripts. Supports:
  *   - boolean flags:  --json, --device, --browser, --no-browser
- *   - value flags:    --url <url>, --token <t>, --connection <id>, --limit 50
+ *   - value flags:    --url <url>, --token <t>, --connection <name>, --limit 50
  *   - subcommands:    deepsql connections list, deepsql config show
  *   - positional:     deepsql ask "what tables exist?"
  */
@@ -23,6 +23,7 @@ const COMMANDS = {
   query: () => require("./commands/query"),
   explain: () => require("./commands/explain"),
   schema: () => require("./commands/schema"),
+  digest: () => require("./commands/digest"),
 };
 
 const HELP = `deepsql — DeepSQL CLI
@@ -46,14 +47,21 @@ Commands:
   config path                     Print the auth file path.
   mcp                             Run the stdio MCP server using the saved token.
   connections list [--json]       List database connections.
-  ask "<question>" --connection <id> [--chat <id>] [--json]
+  ask "<question>" --connection <name> [--chat <id>] [--json]
                                   Ask DeepSQL a question.
-  query "<sql>" --connection <id> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
+  query "<sql>" --connection <name> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
                                   Run a read-only SQL query.
-  explain "<sql>" --connection <id> [--file <path>] [--json]
+  explain "<sql>" --connection <name> [--file <path>] [--json]
                                   Get an EXPLAIN plan.
-  schema [tables|objects] --connection <id>
+  schema [tables|objects] --connection <name>
                                   Dump schema or database objects as JSON.
+  digest [N] [--connection <name>] [--json]
+                                  Show the latest DeepSQL digest, or pass a
+                                  number to list the last N (e.g. digest 5).
+  digest list [--count N] [--connection <name>] [--json]
+                                  Explicit list form (same as digest <N>).
+  digest show <id> [--connection <name>] [--json]
+                                  Show one digest by id.
 
 Global options:
   --url <url>     Override the DeepSQL base URL.
@@ -122,6 +130,7 @@ function buildOpts(parsed) {
     user: f.user || null,
     project: f.project || null,
     limit: f.limit,
+    count: f.count || f.n || null,
     timeoutSeconds: f.timeoutSeconds,
     file: f.file || null,
   };

package/src/commands/_connections.js

@@ -0,0 +1,66 @@
+"use strict";
+
+/**
+ * Resolve a user-supplied connection identifier (name or UUID) to the
+ * canonical connection ID the backend expects.
+ *
+ * Backend `/connections` returns rows shaped roughly like:
+ *   { id: "<uuid>", connectionName: "mylocalpg", databaseType: "postgresql", ... }
+ *
+ * Resolution rules:
+ *   - If input matches a UUID pattern, treat it as an ID (one fetch saved).
+ *     We still verify it exists so we can fail fast with a useful message,
+ *     but only if a list fetch is cheap — for now, trust UUIDs.
+ *   - Otherwise, fetch the list and match `connectionName` case-insensitively.
+ *   - On ambiguous matches (rare — names are not unique by schema constraint),
+ *     prefer an exact-case match; otherwise raise.
+ */
+
+const { request } = require("../api/client");
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+let cachedList = null;
+
+async function listConnections(session) {
+  if (cachedList) return cachedList;
+  cachedList = await request(session.baseUrl, "/connections", { token: session.token });
+  if (!Array.isArray(cachedList)) cachedList = [];
+  return cachedList;
+}
+
+async function resolveConnectionId(session, input) {
+  if (!input || typeof input !== "string") {
+    throw new Error("Pass a connection name or id with --connection.");
+  }
+  const trimmed = input.trim();
+  if (UUID_RE.test(trimmed)) return trimmed;
+
+  const connections = await listConnections(session);
+  const exact = connections.filter((c) => (c.connectionName || c.name) === trimmed);
+  if (exact.length === 1) return exact[0].id || exact[0].connectionId;
+
+  const ciMatches = connections.filter(
+    (c) => String(c.connectionName || c.name || "").toLowerCase() === trimmed.toLowerCase(),
+  );
+  if (ciMatches.length === 1) return ciMatches[0].id || ciMatches[0].connectionId;
+
+  if (ciMatches.length > 1) {
+    const names = ciMatches.map((c) => `${c.connectionName} (${c.id})`).join(", ");
+    throw new Error(
+      `Multiple connections match "${trimmed}" by case-insensitive name: ${names}. Pass the exact name or the id.`,
+    );
+  }
+
+  // No match — show what's available so the user can pick.
+  const available = connections
+    .map((c) => c.connectionName || c.name)
+    .filter(Boolean)
+    .slice(0, 20);
+  const hint = available.length
+    ? ` Available: ${available.join(", ")}.`
+    : " (no connections visible to this token).";
+  throw new Error(`Connection "${trimmed}" not found.${hint}`);
+}
+
+module.exports = { resolveConnectionId, listConnections };

package/src/commands/_connections.test.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+// We mock api/client.request before requiring the resolver so its cached
+// module reference points at our stub.
+const apiClientPath = require.resolve("../api/client");
+const realApiClient = require("../api/client");
+
+function withMockedRequest(connections, fn) {
+  delete require.cache[require.resolve("./_connections")];
+  require.cache[apiClientPath] = {
+    ...require.cache[apiClientPath],
+    exports: {
+      ...realApiClient,
+      request: async () => connections,
+    },
+  };
+  try {
+    const mod = require("./_connections");
+    return fn(mod);
+  } finally {
+    require.cache[apiClientPath].exports = realApiClient;
+    delete require.cache[require.resolve("./_connections")];
+  }
+}
+
+const session = { baseUrl: "http://x", token: "t" };
+
+test("resolves UUID input as-is without a backend roundtrip", async () => {
+  await withMockedRequest([], async ({ resolveConnectionId }) => {
+    const id = await resolveConnectionId(session, "a273f43a-a844-44a3-9026-1b0de1167e8f");
+    assert.equal(id, "a273f43a-a844-44a3-9026-1b0de1167e8f");
+  });
+});
+
+test("matches by exact connection name", async () => {
+  const connections = [
+    { id: "id-prod", connectionName: "prod" },
+    { id: "id-staging", connectionName: "staging" },
+  ];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    assert.equal(await resolveConnectionId(session, "prod"), "id-prod");
+    assert.equal(await resolveConnectionId(session, "staging"), "id-staging");
+  });
+});
+
+test("matches case-insensitively when no exact match exists", async () => {
+  const connections = [{ id: "id-prod", connectionName: "MyLocalPG" }];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    assert.equal(await resolveConnectionId(session, "mylocalpg"), "id-prod");
+  });
+});
+
+test("throws a useful error listing available names when no match", async () => {
+  const connections = [
+    { id: "1", connectionName: "alpha" },
+    { id: "2", connectionName: "beta" },
+  ];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    await assert.rejects(
+      () => resolveConnectionId(session, "missing"),
+      (err) => err.message.includes("alpha") && err.message.includes("beta"),
+    );
+  });
+});
+
+test("requires non-empty input", async () => {
+  await withMockedRequest([], async ({ resolveConnectionId }) => {
+    await assert.rejects(() => resolveConnectionId(session, ""), /connection name/);
+    await assert.rejects(() => resolveConnectionId(session, null), /connection name/);
+  });
+});

package/src/commands/ask.js

@@ -3,13 +3,15 @@
 const os = require("node:os");
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
   const question = opts.positional.join(" ").trim();
-  if (!question) throw new Error("Pass a question: `deepsql ask \"why is this query slow?\" --connection <id>`.");
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!question) throw new Error("Pass a question: `deepsql ask \"why is this query slow?\" --connection <name>`.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const userId = opts.user || `cli-${os.userInfo().username}`;
   const projectId = opts.project || "deepsql-cli";
 
@@ -18,7 +20,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     token: session.token,
     timeoutMs: 240000,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       message: question,
       chatId: opts.chat || null,
       userId,

package/src/commands/connections.js

@@ -18,11 +18,23 @@ async function run(opts, { stdout = process.stdout } = {}) {
     stdout.write("No connections.\n");
     return;
   }
-  for (const conn of data) {
-    const id = conn.id || conn.connectionId;
-    const name = conn.connectionName || conn.name || "(unnamed)";
-    const dbType = conn.databaseType || conn.dbType || "?";
-    stdout.write(`${id}  ${dbType.padEnd(10)}  ${name}\n`);
+  // Name first — it's what users will pass to --connection. ID kept on the
+  // right for back-compat / scripting.
+  const rows = data.map((conn) => ({
+    name: conn.connectionName || conn.name || "(unnamed)",
+    type: conn.databaseType || conn.dbType || "?",
+    id: conn.id || conn.connectionId || "",
+  }));
+  const widths = {
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    type: Math.max(4, ...rows.map((r) => r.type.length)),
+  };
+  stdout.write(
+    `${"NAME".padEnd(widths.name)}  ${"TYPE".padEnd(widths.type)}  ID\n` +
+      `${"-".repeat(widths.name)}  ${"-".repeat(widths.type)}  ${"-".repeat(36)}\n`,
+  );
+  for (const row of rows) {
+    stdout.write(`${row.name.padEnd(widths.name)}  ${row.type.padEnd(widths.type)}  ${row.id}\n`);
   }
 }
 

package/src/commands/digest.js

@@ -0,0 +1,197 @@
+"use strict";
+
+/**
+ * `deepsql digest` — surface the daily DeepSQL digest from the terminal.
+ *
+ *   deepsql digest                   → show the single most recent digest, full body
+ *   deepsql digest <N>               → list the last N digests (compact, one per row)
+ *   deepsql digest list [--count N]  → same as above; explicit form
+ *   deepsql digest show <id>         → show a specific digest by id
+ *   --connection <id>                → filter to one connection
+ *   --json                           → raw JSON output
+ *
+ * Backend: GET /admin/slack/digests?connectionId=&page=0&size=N
+ *   Returns a Spring Data Page<SlackDigestLog>: { content: [...], totalElements, ... }
+ *   Requires ADMIN role on the calling user's MCP token.
+ */
+
+const { ApiError, request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+const DEFAULT_LIST_COUNT = 10;
+const MAX_COUNT = 100;
+
+async function run(opts, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (!opts.connection) {
+    throw new Error(
+      "--connection <name> is required. Digests are per-connection — pick one from `deepsql connections list`.",
+    );
+  }
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+  const sub = opts.positional[0];
+
+  // `deepsql digest <N>` shorthand — first positional is a number.
+  if (sub && /^\d+$/.test(sub)) {
+    return runList(session, connectionId, parseCount(sub), opts, { stdout, stderr });
+  }
+  if (!sub || sub === "latest") {
+    return runLatest(session, connectionId, opts, { stdout, stderr });
+  }
+  if (sub === "list") {
+    const count = parseCount(opts.count) || parseCount(opts.positional[1]) || DEFAULT_LIST_COUNT;
+    return runList(session, connectionId, count, opts, { stdout, stderr });
+  }
+  if (sub === "show") {
+    const id = opts.positional[1];
+    if (!id) throw new Error("Pass the digest id: `deepsql digest show <id> --connection <name>`.");
+    return runShow(session, connectionId, id, opts, { stdout, stderr });
+  }
+  throw new Error(`Unknown digest subcommand: ${sub}. Try \`latest\`, \`list\`, \`show <id>\`, or pass a number.`);
+}
+
+async function runLatest(session, connectionId, opts, { stdout }) {
+  const page = await fetchPage(session, connectionId, 0, 1);
+  const digest = page.content?.[0];
+  if (!digest) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(digest, null, 2)}\n`);
+    return;
+  }
+  printFull(stdout, digest);
+}
+
+async function runList(session, connectionId, requestedCount, opts, { stdout }) {
+  const count = Math.min(requestedCount, MAX_COUNT);
+  const page = await fetchPage(session, connectionId, 0, count);
+  const items = page.content || [];
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+  if (items.length === 0) {
+    stdout.write(`No digests yet for connection "${opts.connection}".\n`);
+    return;
+  }
+  printTable(stdout, items);
+  if (page.totalElements && page.totalElements > items.length) {
+    stdout.write(`\n${items.length} of ${page.totalElements} shown — pass a larger N to see more.\n`);
+  }
+}
+
+async function runShow(session, connectionId, id, opts, { stdout }) {
+  // No single-digest backend endpoint exists yet, so locate by paging.
+  // Cheap enough for typical digest counts; we cap at a few pages.
+  const target = String(id);
+  for (let page = 0; page < 10; page++) {
+    const result = await fetchPage(session, connectionId, page, 50);
+    const hit = (result.content || []).find((d) => String(d.id) === target);
+    if (hit) {
+      if (opts.json) {
+        stdout.write(`${JSON.stringify(hit, null, 2)}\n`);
+        return;
+      }
+      printFull(stdout, hit);
+      return;
+    }
+    if (result.last || (result.content || []).length === 0) break;
+  }
+  throw new Error(`Digest ${id} not found in the most recent 500 entries for "${opts.connection}".`);
+}
+
+async function fetchPage(session, connectionId, page, size) {
+  try {
+    return await request(session.baseUrl, "/admin/slack/digests", {
+      token: session.token,
+      query: {
+        connectionId,
+        page,
+        size,
+      },
+    });
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 403) {
+      throw new Error(
+        "Access denied — fetching digests requires ADMIN role. Ask an administrator to mint a token, or run `deepsql login` as an admin.",
+      );
+    }
+    throw err;
+  }
+}
+
+function printTable(stdout, items) {
+  const rows = items.map((d) => ({
+    id: String(d.id ?? ""),
+    sentAt: formatTimestamp(d.sentAt),
+    status: d.status || "?",
+    connection: trim(d.connectionName || d.connectionId || "—", 24),
+    headline: trim(d.headline || firstLine(d.content) || "(no headline)", 60),
+  }));
+  const cols = [
+    { key: "id", label: "ID" },
+    { key: "sentAt", label: "Sent" },
+    { key: "status", label: "Status" },
+    { key: "connection", label: "Connection" },
+    { key: "headline", label: "Headline" },
+  ];
+  const widths = cols.map((c) => Math.max(c.label.length, ...rows.map((r) => r[c.key].length)));
+  const header = cols.map((c, i) => c.label.padEnd(widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  stdout.write(`${header}\n${sep}\n`);
+  for (const row of rows) {
+    stdout.write(`${cols.map((c, i) => row[c.key].padEnd(widths[i])).join("  ")}\n`);
+  }
+}
+
+function printFull(stdout, d) {
+  const sent = formatTimestamp(d.sentAt);
+  stdout.write(`Digest #${d.id}  ·  ${sent}  ·  ${d.status || "?"}\n`);
+  if (d.connectionName || d.connectionId) {
+    stdout.write(`Connection: ${d.connectionName || d.connectionId}\n`);
+  }
+  if (d.headline) {
+    stdout.write(`Headline:   ${d.headline}\n`);
+  }
+  stdout.write("\n");
+  if (d.status === "FAILED" && d.errorMessage) {
+    stdout.write(`Error: ${d.errorMessage}\n`);
+    return;
+  }
+  stdout.write(`${d.content || "(empty)"}\n`);
+}
+
+function parseCount(value) {
+  if (value == null) return null;
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n;
+}
+
+function formatTimestamp(value) {
+  if (!value) return "—";
+  try {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return String(value);
+    return d.toISOString().replace("T", " ").slice(0, 16) + "Z";
+  } catch {
+    return String(value);
+  }
+}
+
+function trim(text, maxLen) {
+  if (!text) return "";
+  const s = String(text).replace(/\s+/g, " ").trim();
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + "…" : s;
+}
+
+function firstLine(text) {
+  if (!text) return "";
+  const idx = text.indexOf("\n");
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+module.exports = { run };

package/src/commands/explain.js

@@ -4,19 +4,21 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const sql = readSqlInput(opts);
   // EXPLAIN ANALYZE is mutating; require plain EXPLAIN.
   const validation = validateReadOnlySql(sql, { allowExplain: false });
   if (!validation.ok) throw new Error(validation.reason);
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const response = await request(session.baseUrl, "/mcp/explain-readonly", {
     method: "POST",
     token: session.token,
-    json: { connectionId: opts.connection, query: validation.normalizedQuery },
+    json: { connectionId, query: validation.normalizedQuery },
   });
 
   if (opts.json) {

package/src/commands/query.js

@@ -4,14 +4,16 @@ const fs = require("node:fs");
 const { request } = require("../api/client");
 const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const sql = readSqlInput(opts);
   const validation = validateReadOnlySql(sql, { allowExplain: true });
   if (!validation.ok) throw new Error(validation.reason);
 
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const limit = clampInt(opts.limit, 1, 1000, 100);
   const timeout = opts.timeoutSeconds == null ? null : clampInt(opts.timeoutSeconds, 1, 60, null);
 
@@ -19,7 +21,7 @@ async function run(opts, { stdout = process.stdout } = {}) {
     method: "POST",
     token: session.token,
     json: {
-      connectionId: opts.connection,
+      connectionId,
       query: validation.normalizedQuery,
       limit,
       timeoutSeconds: timeout,
@@ -48,19 +50,49 @@ function clampInt(value, min, max, fallback) {
 }
 
 function printRows(stdout, response) {
-  const rows = response?.rows || response?.data || [];
-  const columns = response?.columns || (rows[0] ? Object.keys(rows[0]) : []);
-  if (columns.length === 0) {
+  // Backend returns: { result: { columns: [...], rows: [[v1,v2,...], ...],
+  //                            rowCount, totalRowCount, isLimited, ... },
+  //                   success, queryType }
+  // Tolerate older shapes too — `rows` directly on the response, with rows as
+  // either arrays or row-objects.
+  const result = response?.result ?? response ?? {};
+  const rawRows = result.rows ?? result.data ?? [];
+  let columns = result.columns;
+  if (!Array.isArray(columns) || columns.length === 0) {
+    columns = rawRows[0] && !Array.isArray(rawRows[0]) ? Object.keys(rawRows[0]) : [];
+  }
+  if (columns.length === 0 || rawRows.length === 0) {
     stdout.write("(no rows)\n");
     return;
   }
-  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+  const cellAt = (row, idx, col) =>
+    Array.isArray(row) ? row[idx] : row?.[col];
+  const widths = columns.map((c, i) =>
+    Math.max(
+      String(c).length,
+      ...rawRows.map((r) => String(cellAt(r, i, c) ?? "").length),
+    ),
+  );
   const sep = widths.map((w) => "-".repeat(w)).join("  ");
-  stdout.write(`${columns.map((c, i) => c.padEnd(widths[i])).join("  ")}\n${sep}\n`);
-  for (const row of rows) {
-    stdout.write(`${columns.map((c, i) => String(row[c] ?? "").padEnd(widths[i])).join("  ")}\n`);
+  stdout.write(
+    `${columns.map((c, i) => String(c).padEnd(widths[i])).join("  ")}\n${sep}\n`,
+  );
+  for (const row of rawRows) {
+    stdout.write(
+      `${columns
+        .map((c, i) => String(cellAt(row, i, c) ?? "").padEnd(widths[i]))
+        .join("  ")}\n`,
+    );
+  }
+  if (result.isLimited || result.truncated) {
+    const shown = rawRows.length;
+    const total = result.totalRowCount;
+    stdout.write(
+      total != null && total > shown
+        ? `(showing ${shown} of ${total} rows)\n`
+        : `(result limited to ${shown} rows)\n`,
+    );
   }
-  if (response?.truncated) stdout.write(`(truncated to ${rows.length} rows)\n`);
 }
 
 module.exports = { run };

package/src/commands/schema.js

@@ -2,15 +2,17 @@
 
 const { request } = require("../api/client");
 const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
 
 async function run(opts, { stdout = process.stdout } = {}) {
-  if (!opts.connection) throw new Error("--connection <id> is required.");
+  if (!opts.connection) throw new Error("--connection <name> is required.");
   const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
   const sub = opts.positional[0] || "tables";
   const path =
     sub === "objects"
-      ? `/connections/${encodeURIComponent(opts.connection)}/objects`
-      : `/connections/${encodeURIComponent(opts.connection)}/schema`;
+      ? `/connections/${encodeURIComponent(connectionId)}/objects`
+      : `/connections/${encodeURIComponent(connectionId)}/schema`;
   const response = await request(session.baseUrl, path, { token: session.token });
   stdout.write(`${JSON.stringify(response, null, 2)}\n`);
 }