@deepsql/mcp 0.6.0 → 0.10.0

package/src/commands/_connections.test.js

@@ -66,9 +66,26 @@ test("throws a useful error listing available names when no match", async () =>
   });
 });
 
-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/);
+test("falls back through env and saved default before erroring", async () => {
+  const connections = [{ id: "id-default", connectionName: "saved" }];
+  await withMockedRequest(connections, async ({ resolveConnectionId }) => {
+    // No flag, no env, no saved default → error mentioning all three escape hatches.
+    delete process.env.DEEPSQL_CONNECTION;
+    await assert.rejects(
+      () => resolveConnectionId({ baseUrl: "http://x", token: "t" }, ""),
+      /No connection specified.*--connection.*DEEPSQL_CONNECTION.*connections use/s,
+    );
+
+    // DEEPSQL_CONNECTION is consulted next.
+    process.env.DEEPSQL_CONNECTION = "saved";
+    try {
+      assert.equal(await resolveConnectionId({ baseUrl: "http://x", token: "t" }, ""), "id-default");
+    } finally {
+      delete process.env.DEEPSQL_CONNECTION;
+    }
+
+    // Otherwise, the session's defaultConnection is the final fallback.
+    const session = { baseUrl: "http://x", token: "t", defaultConnection: "saved" };
+    assert.equal(await resolveConnectionId(session, null), "id-default");
   });
 });

package/src/commands/_session.js

@@ -31,7 +31,10 @@ function resolveSession(opts = {}) {
   if (!token) {
     throw new Error(`No auth token for ${baseUrl}. Run \`deepsql login --url ${baseUrl}\`.`);
   }
-  return { baseUrl, token, profile };
+  // Surface the saved active connection so the connection resolver can fall
+  // back to it when --connection isn't passed. Set via `deepsql connections use`.
+  const defaultConnection = profile?.defaultConnection || null;
+  return { baseUrl, token, profile, defaultConnection };
 }
 
 function stripApiSuffix(url) {

package/src/commands/access.js

@@ -94,7 +94,6 @@ async function cmdList(opts, { stdout = process.stdout } = {}) {
 
 async function cmdGrant(opts, { stdout = process.stdout } = {}) {
   if (!opts.user) throw new Error("--user <ref> is required.");
-  if (!opts.connection) throw new Error("--connection <name> is required.");
   const level = (opts.level || "READ").toUpperCase();
   if (!["READ", "WRITE", "ADMIN"].includes(level)) {
     throw new Error(`Invalid --level "${level}". Pick read, write, or admin.`);
@@ -122,7 +121,6 @@ async function cmdGrant(opts, { stdout = process.stdout } = {}) {
 
 async function cmdRevoke(opts, { stdout = process.stdout } = {}) {
   if (!opts.user) throw new Error("--user <ref> is required.");
-  if (!opts.connection) throw new Error("--connection <name> is required.");
 
   const session = resolveSession(opts);
   const user = await resolveUser(session, opts.user);

package/src/commands/admin.test.js

@@ -133,3 +133,40 @@ test("--password=secret keeps the string value (still truthy)", () => {
   const o = opts(["--password=secret"]);
   assert.equal(o.password, "secret");
 });
+
+// connections add/test flags ----------------------------------------------
+
+test("connections add --from-file with --upsert/--no-test/--wait/--delete-after", () => {
+  const o = opts([
+    "add",
+    "--from-file",
+    "/tmp/conn.json",
+    "--upsert",
+    "--no-test",
+    "--wait",
+    "--delete-after",
+  ]);
+  assert.equal(o.fromFile, "/tmp/conn.json");
+  assert.equal(o.upsert, true);
+  assert.equal(o.noTest, true);
+  assert.equal(o.wait, true);
+  assert.equal(o.deleteAfter, true);
+});
+
+test("connections add --from-stdin + --allow-plaintext-secrets", () => {
+  const o = opts(["add", "--from-stdin", "--allow-plaintext-secrets"]);
+  assert.equal(o.fromStdin, true);
+  assert.equal(o.allowPlaintextSecrets, true);
+});
+
+test("connections add --cloud triggers cloud-prompt path", () => {
+  const o = opts(["add", "--cloud"]);
+  assert.equal(o.cloud, true);
+});
+
+test("connections init <name> --force --wait", () => {
+  const o = opts(["init", "prod", "--force", "--wait"]);
+  assert.deepEqual(o.positional, ["init", "prod"]);
+  assert.equal(o.force, true);
+  assert.equal(o.wait, true);
+});

package/src/commands/anti-patterns.js

@@ -0,0 +1,76 @@
+"use strict";
+
+/**
+ * `deepsql anti-patterns --connection <name> [--kind table|query] [--limit N] [--json]`
+ *
+ * Returns DeepSQL-detected anti-patterns. Two flavors:
+ *   - kind=table (default) → GET /brain/table-anti-patterns/{cid}
+ *   - kind=query           → GET /brain/query-anti-patterns/{cid}?limit=
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const kind = opts.kind === "query" ? "query" : "table";
+  const path =
+    kind === "query"
+      ? `/brain/query-anti-patterns/${encodeURIComponent(connectionId)}`
+      : `/brain/table-anti-patterns/${encodeURIComponent(connectionId)}`;
+
+  const query = {};
+  if (kind === "query" && opts.limit != null) query.limit = opts.limit;
+
+  const response = await request(session.baseUrl, path, {
+    token: session.token,
+    query,
+  });
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  if (kind === "table") {
+    const tableMap =
+      response && typeof response === "object" && !Array.isArray(response) ? response : {};
+    const tables = Object.keys(tableMap);
+    if (tables.length === 0) {
+      stdout.write("No table-level anti-patterns detected.\n");
+      return;
+    }
+    const noun = tables.length === 1 ? "table" : "tables";
+    stdout.write(`${tables.length} ${noun} with anti-patterns:\n`);
+    for (const t of tables) {
+      const entry = tableMap[t] || {};
+      const patterns = entry.patterns || entry.antiPatterns || entry || [];
+      const n = Array.isArray(patterns) ? patterns.length : 0;
+      stdout.write(`  • ${t}: ${n} ${n === 1 ? "pattern" : "patterns"}\n`);
+    }
+    return;
+  }
+
+  const list = Array.isArray(response) ? response : response?.patterns || [];
+  if (list.length === 0) {
+    stdout.write("No query anti-patterns detected.\n");
+    return;
+  }
+  const sev = list.reduce((acc, p) => {
+    const s = p.severity || "UNKNOWN";
+    acc[s] = (acc[s] || 0) + 1;
+    return acc;
+  }, {});
+  const sevStr = Object.entries(sev).map(([k, v]) => `${k}=${v}`).join(", ");
+  const noun = list.length === 1 ? "anti-pattern" : "anti-patterns";
+  stdout.write(`${list.length} query ${noun}${sevStr ? ` (${sevStr})` : ""}:\n`);
+  for (const p of list.slice(0, 20)) {
+    stdout.write(`  • [${p.severity || "?"}] ${p.patternType || p.name || "pattern"}: ${p.description || ""}\n`);
+  }
+}
+
+module.exports = { run };

package/src/commands/brain-context.js

@@ -0,0 +1,87 @@
+"use strict";
+
+/**
+ * `deepsql brain-context "<question>" --connection <name> [--top-k N] [--json]`
+ *
+ * Returns DeepSQL's retrieval context for a question — relevant tables,
+ * columns, FK relationships, training docs, business rules, and embedding-
+ * ranked snippets — without invoking the chat agent. Coding agents (Claude
+ * Code, Cursor, Codex) feed this into their own LLM to generate SQL or prose.
+ *
+ *   - Without --top-k → POST /training/context/{cid}  (rich payload)
+ *   - With --top-k    → GET  /training/retrieve/{cid}?q=&topK= (ranked snippets)
+ */
+
+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 brain-context "which tables hold customer orders?" --connection <name>`.',
+    );
+  }
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const topK = opts.topK == null ? null : Number.parseInt(opts.topK, 10);
+  let response;
+  if (topK != null && Number.isFinite(topK)) {
+    response = await request(
+      session.baseUrl,
+      `/training/retrieve/${encodeURIComponent(connectionId)}`,
+      { token: session.token, query: { q: question, topK } },
+    );
+  } else {
+    response = await request(
+      session.baseUrl,
+      `/training/context/${encodeURIComponent(connectionId)}`,
+      { method: "POST", token: session.token, json: { question } },
+    );
+  }
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  // Default: print the most useful fields directly so output can be piped
+  // into a coding agent. /context returns one or more of:
+  //   - trainingContext (the rich, prompt-ready RAG block)
+  //   - companyKnowledgeContext (workspace hints — populated even when the
+  //     pipeline detects a "simple_schema_question" and skips RAG)
+  //   - ragTableNames, retrievalIntent, resultCount, etc. (diagnostic)
+  // /retrieve (--top-k) returns ranked snippets — fall back to JSON for that.
+  const isContextPayload =
+    response &&
+    typeof response === "object" &&
+    ("trainingContext" in response ||
+      "companyKnowledgeContext" in response ||
+      "skipped" in response);
+
+  if (isContextPayload) {
+    if (response.skipped) {
+      stdout.write(`# (retrieval skipped: ${response.skipReason || "n/a"})\n\n`);
+    }
+    if (response.trainingContext) {
+      stdout.write(`${response.trainingContext}\n`);
+    }
+    if (response.companyKnowledgeContext) {
+      stdout.write(
+        `${response.trainingContext ? "\n" : ""}${response.companyKnowledgeContext}\n`,
+      );
+    }
+    if (!response.trainingContext && !response.companyKnowledgeContext) {
+      stdout.write(
+        "(no retrieval results — pass --top-k <n> to fetch ranked snippets, or `--json` for the full payload)\n",
+      );
+    }
+    return;
+  }
+  stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+}
+
+module.exports = { run };

package/src/commands/business-rules.js

@@ -0,0 +1,58 @@
+"use strict";
+
+/**
+ * `deepsql business-rules --connection <name> [--question "..."] [--json]`
+ *
+ * Lists active business rules and SQL guardrails for a connection. Wraps
+ * GET /business-rules/connection/{connectionId}?question=...
+ */
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+const { resolveConnectionId } = require("./_connections");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+
+  const session = resolveSession(opts);
+  const connectionId = await resolveConnectionId(session, opts.connection);
+
+  const query = {};
+  if (opts.question) query.question = opts.question;
+  const response = await request(
+    session.baseUrl,
+    `/business-rules/connection/${encodeURIComponent(connectionId)}`,
+    { token: session.token, query },
+  );
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const active = response?.activeRules || [];
+  const guards = response?.applicableGuardrails || [];
+
+  if (active.length === 0 && guards.length === 0) {
+    stdout.write("No business rules or guardrails configured for this connection.\n");
+    return;
+  }
+
+  stdout.write(
+    `${plural(active.length, "active business rule", "active business rules")}, ` +
+      `${plural(guards.length, "applicable guardrail", "applicable guardrails")}.\n`,
+  );
+  for (const r of active) {
+    const name = r.name || r.ruleName || `rule#${r.id}`;
+    const desc = r.description || r.ruleText || "";
+    stdout.write(`  • ${name}${desc ? `: ${desc}` : ""}\n`);
+  }
+  if (guards.length) {
+    stdout.write(`\nGuardrail context:\n${response?.guardrailContext || "(none)"}\n`);
+  }
+}
+
+function plural(n, singular, many) {
+  return `${n} ${n === 1 ? singular : many}`;
+}
+
+module.exports = { run };