@deepsql/mcp 0.5.0 → 0.8.0

package/deepsql-phase1-lib.js

@@ -66,29 +66,104 @@ const TOOL_DEFINITIONS = [
     },
   },
   {
-    name: "answer_question",
-    description: "Ask DeepSQL a natural-language database question using the full chat pipeline.",
+    name: "get_brain_context",
+    description:
+      "Retrieve DeepSQL's brain context for a question: relevant tables, columns, FKs, training docs, business rules, anti-patterns, and embedding-ranked snippets. Use this to give your own coding agent the same retrieval context the DeepSQL agent uses, then have your agent generate the SQL/answer.",
     inputSchema: {
       type: "object",
       properties: {
-        connectionId: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        question: {
           type: "string",
-          description: "DeepSQL connection ID.",
+          description: "Natural-language question used for retrieval ranking.",
+        },
+        topK: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description:
+            "Optional retrieval breadth. When provided, returns ranked diagnostic results from /training/retrieve; otherwise returns the rich /training/context payload.",
         },
+      },
+      required: ["connectionId", "question"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_business_rules",
+    description:
+      "List active business rules and SQL guardrails for a connection. Optional `question` filters to rules applicable to that question.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
         question: {
           type: "string",
-          description: "Natural-language database question.",
+          description: "Optional natural-language question to scope rules.",
         },
-        chatId: {
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_relationships",
+    description:
+      "Get inferred and validated foreign-key relationships for a connection (source/target table+column with confidence and inference method).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_anti_patterns",
+    description:
+      "Get DeepSQL-detected anti-patterns. `kind=table` returns table/schema-level anti-patterns; `kind=query` returns query-level anti-patterns (with optional limit).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        kind: {
           type: "string",
-          description: "Optional DeepSQL chat ID for conversation continuity.",
+          enum: ["table", "query"],
+          description: "Which anti-pattern catalog to fetch. Defaults to 'table'.",
         },
-        userId: {
-          type: "string",
-          description: "Optional user ID for attribution in feedback/history.",
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 500,
+          description: "Optional row limit (only used for kind='query').",
         },
       },
-      required: ["connectionId", "question"],
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "analyze_slow_queries",
+    description:
+      "Analyze recent slow queries for a connection over the last 24 hours, returning fingerprints, durations, and example statements.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: { type: "string", description: "DeepSQL connection ID." },
+        thresholdMs: {
+          type: "number",
+          minimum: 1,
+          description: "Minimum query duration in milliseconds. Defaults to 100.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 500,
+          description: "Maximum queries to return. Defaults to 10.",
+        },
+      },
+      required: ["connectionId"],
       additionalProperties: false,
     },
   },
@@ -374,18 +449,64 @@ function summarizeObjects(payload) {
     : "No database objects were returned.";
 }
 
-function summarizeChat(payload) {
-  const lines = [];
-  if (payload?.chatId) {
-    lines.push(`chatId: ${payload.chatId}`);
+function summarizeBrainContext(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Brain context unavailable.";
   }
-  if (payload?.sql) {
-    lines.push(`sql: ${compactWhitespace(payload.sql)}`);
+  // /training/retrieve diagnostic shape
+  if (Array.isArray(payload?.results) || payload?.totalResults != null) {
+    const total =
+      payload.totalResults ?? (Array.isArray(payload.results) ? payload.results.length : 0);
+    const tableCount = Array.isArray(payload.tablesCovered) ? payload.tablesCovered.length : 0;
+    return `Retrieved ${total} ranked snippet(s) covering ${tableCount} table(s).`;
   }
-  if (payload?.message) {
-    lines.push(`answer: ${payload.message}`);
+  // /training/context rich shape (RetrievedContextResult)
+  const tables = Array.isArray(payload.ragTableNames)
+    ? payload.ragTableNames.length
+    : payload.ragTableNames
+      ? Object.keys(payload.ragTableNames).length
+      : 0;
+  const types = payload.typeCounts
+    ? Object.entries(payload.typeCounts).map(([k, v]) => `${k}=${v}`).join(", ")
+    : "";
+  const intent = payload.retrievalIntent || "n/a";
+  const skipped = payload.skipped ? ` (skipped: ${payload.skipReason || "?"})` : "";
+  return `Brain context: intent=${intent}, topK=${payload.retrievalTopK ?? "?"}, results=${payload.resultCount ?? 0}, tables=${tables}${types ? `, types[${types}]` : ""}${skipped}.`;
+}
+
+function summarizeBusinessRules(payload) {
+  const active = payload?.activeRuleCount ?? (payload?.activeRules?.length ?? 0);
+  const guards = payload?.applicableGuardrailCount ?? (payload?.applicableGuardrails?.length ?? 0);
+  return `Business rules: ${active} active, ${guards} applicable guardrail(s).`;
+}
+
+function summarizeRelationships(payload) {
+  const list = Array.isArray(payload) ? payload : payload?.relationships || [];
+  const high = list.filter((r) => (r.confidence ?? 0) >= 0.8).length;
+  return `${list.length} relationship(s) (${high} high-confidence).`;
+}
+
+function summarizeAntiPatterns(payload, kind) {
+  if (kind === "table") {
+    const tables = payload && typeof payload === "object" ? Object.keys(payload).length : 0;
+    return `Anti-patterns across ${tables} table(s).`;
   }
-  return lines.join("\n");
+  const list = Array.isArray(payload) ? payload : payload?.patterns || [];
+  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(", ");
+  return `${list.length} query anti-pattern(s)${sevStr ? ` (${sevStr})` : ""}.`;
+}
+
+function summarizeSlowQueries(payload) {
+  const list = Array.isArray(payload?.queries) ? payload.queries : [];
+  const total = payload?.totalCount ?? list.length;
+  const avg = payload?.avgDurationMs;
+  const max = payload?.maxDurationMs;
+  return `${total} slow query/queries${avg != null ? `, avg=${avg}ms` : ""}${max != null ? `, max=${max}ms` : ""}.`;
 }
 
 function summarizeQueryResult(payload) {
@@ -405,7 +526,7 @@ function summarizeExplain(payload) {
   return `EXPLAIN completed for ${planType}.`;
 }
 
-function buildToolResult(name, payload) {
+function buildToolResult(name, payload, extra = {}) {
   let summary;
 
   switch (name) {
@@ -418,8 +539,20 @@ function buildToolResult(name, payload) {
     case "get_database_objects":
       summary = summarizeObjects(payload);
       break;
-    case "answer_question":
-      summary = summarizeChat(payload);
+    case "get_brain_context":
+      summary = summarizeBrainContext(payload);
+      break;
+    case "list_business_rules":
+      summary = summarizeBusinessRules(payload);
+      break;
+    case "get_relationships":
+      summary = summarizeRelationships(payload);
+      break;
+    case "get_anti_patterns":
+      summary = summarizeAntiPatterns(payload, extra.kind || "table");
+      break;
+    case "analyze_slow_queries":
+      summary = summarizeSlowQueries(payload);
       break;
     case "execute_readonly_sql":
       summary = summarizeQueryResult(payload);
@@ -484,23 +617,84 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
-    case "answer_question": {
+    case "get_brain_context": {
       const connectionId = String(args.connectionId || "").trim();
       const question = String(args.question || "").trim();
-      const chatId = args.chatId ? String(args.chatId) : null;
-      const userId = args.userId ? String(args.userId) : config.defaultUserId;
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!question) return buildToolError("question is required.");
+
+      // Route based on whether the caller wants ranked diagnostics (topK) or
+      // the rich training-context payload.
+      let payload;
+      if (args.topK != null) {
+        const topK = clampInteger(args.topK, 1, 100, 20);
+        const path =
+          `/training/retrieve/${encodeURIComponent(connectionId)}` +
+          `?q=${encodeURIComponent(question)}&topK=${topK}`;
+        payload = await callDeepSqlApi(config, path);
+      } else {
+        payload = await callDeepSqlApi(
+          config,
+          `/training/context/${encodeURIComponent(connectionId)}`,
+          { method: "POST", json: { question } },
+        );
+      }
+      return buildToolResult(name, payload);
+    }
 
-      const payload = await callDeepSqlApi(config, "/chat", {
-        method: "POST",
-        json: {
-          connectionId,
-          message: question,
-          chatId,
-          userId,
-          projectId: config.defaultProjectId,
-        },
-      });
+    case "list_business_rules": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      let path = `/business-rules/connection/${encodeURIComponent(connectionId)}`;
+      if (args.question) {
+        path += `?question=${encodeURIComponent(String(args.question))}`;
+      }
+      const payload = await callDeepSqlApi(config, path);
+      return buildToolResult(name, payload);
+    }
 
+    case "get_relationships": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const payload = await callDeepSqlApi(
+        config,
+        `/brain/inferred-relationships/${encodeURIComponent(connectionId)}`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_anti_patterns": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const kind = args.kind === "query" ? "query" : "table";
+      let path;
+      if (kind === "query") {
+        path = `/brain/query-anti-patterns/${encodeURIComponent(connectionId)}`;
+        if (args.limit != null) {
+          path += `?limit=${clampInteger(args.limit, 1, 500, 50)}`;
+        }
+      } else {
+        path = `/brain/table-anti-patterns/${encodeURIComponent(connectionId)}`;
+      }
+      const payload = await callDeepSqlApi(config, path);
+      return buildToolResult(name, payload, { kind });
+    }
+
+    case "analyze_slow_queries": {
+      const connectionId = String(args.connectionId || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      const params = [];
+      if (args.thresholdMs != null) {
+        params.push(`threshold=${Number(args.thresholdMs)}`);
+      }
+      if (args.limit != null) {
+        params.push(`limit=${clampInteger(args.limit, 1, 500, 10)}`);
+      }
+      const qs = params.length ? `?${params.join("&")}` : "";
+      const payload = await callDeepSqlApi(
+        config,
+        `/slow-queries/analyze/${encodeURIComponent(connectionId)}${qs}`,
+      );
       return buildToolResult(name, payload);
     }
 

package/deepsql-phase1-server.js

@@ -193,7 +193,7 @@ class DeepSqlPhase1McpServer {
             },
             serverInfo: SERVER_INFO,
             instructions:
-              "DeepSQL phase 1 MCP exposes read-only database access through DeepSQL. Prefer answer_question for high-level tasks. execute_readonly_sql and explain_readonly_sql reject mutating SQL.",
+              "DeepSQL phase 1 MCP exposes read-only database access plus DeepSQL's brain (retrieved context, business rules, inferred relationships, anti-patterns, slow-query analysis). Prefer get_brain_context to ground SQL/answer generation in retrieved schema knowledge, then call execute_readonly_sql / explain_readonly_sql to validate. Mutating SQL is rejected by both client and backend.",
           });
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",
@@ -22,5 +22,8 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.2"
+  }
 }

package/src/api/client.js

@@ -8,7 +8,7 @@
  * needs:
  *   - profile-based base URL resolution (not env-only)
  *   - to talk to the unauthenticated /auth/cli endpoints
- *   - to stream responses for `ask`
+ *   - per-call query string composition for brain endpoints
  */
 
 class ApiError extends Error {

package/src/cli.js

@@ -9,7 +9,7 @@
  *   - boolean flags:  --json, --device, --browser, --no-browser
  *   - value flags:    --url <url>, --token <t>, --connection <name>, --limit 50
  *   - subcommands:    deepsql connections list, deepsql config show
- *   - positional:     deepsql ask "what tables exist?"
+ *   - positional:     deepsql brain-context "which tables hold orders?"
  */
 
 const COMMANDS = {
@@ -19,14 +19,28 @@ const COMMANDS = {
   config: () => require("./commands/config"),
   mcp: () => require("./commands/mcp"),
   connections: () => require("./commands/connections"),
-  ask: () => require("./commands/ask"),
   query: () => require("./commands/query"),
   explain: () => require("./commands/explain"),
   schema: () => require("./commands/schema"),
+  // Brain tools — give a coding agent the same retrieval context the chat
+  // pipeline uses, then let the agent generate SQL/answers itself.
+  "brain-context": () => require("./commands/brain-context"),
+  "business-rules": () => require("./commands/business-rules"),
+  relationships: () => require("./commands/relationships"),
+  "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  users: () => require("./commands/users"),
+  access: () => require("./commands/access"),
+  permissions: () => require("./commands/permissions"),
+  "slow-queries": () => require("./commands/slow-queries"),
+  setup: () => require("./commands/setup"),
 };
 
-const HELP = `deepsql — DeepSQL CLI
+const HELP = `deepsql — ask the database what's wrong. It already knows.
+
+Self-hosted AI for database performance: profile slow queries, stream
+live optimization plans, audit access, and run day-to-day admin ops —
+all from the terminal, without leaving your VPC.
 
 Usage:
   deepsql <command> [options]
@@ -47,14 +61,16 @@ 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 <name> [--chat <id>] [--json]
-                                  Ask DeepSQL a question.
   query "<sql>" --connection <name> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
-                                  Run a read-only SQL query.
+                                  Run a read-only SQL statement. Enforced
+                                  read-only at the backend (parser-level) and
+                                  ACL-checked per connection.
   explain "<sql>" --connection <name> [--file <path>] [--json]
-                                  Get an EXPLAIN plan.
+                                  Get an EXPLAIN plan (no ANALYZE — also
+                                  read-only enforced).
   schema [tables|objects] --connection <name>
-                                  Dump schema or database objects as JSON.
+                                  Dump connection 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).
@@ -63,6 +79,53 @@ Commands:
   digest show <id> [--connection <name>] [--json]
                                   Show one digest by id.
 
+Brain commands (give a coding agent DeepSQL's retrieved context — agentless V1):
+  brain-context "<question>" --connection <name> [--top-k <n>] [--json]
+                                  Retrieve embedding-ranked tables/columns/FKs,
+                                  training docs, and business rules for a
+                                  question. With --top-k, returns ranked
+                                  diagnostic snippets; otherwise returns the
+                                  rich training-context payload.
+  business-rules --connection <name> [--question "..."] [--json]
+                                  List active business rules and SQL guardrails
+                                  for a connection (optionally scoped by
+                                  question).
+  relationships --connection <name> [--json]
+                                  Inferred and validated foreign-key
+                                  relationships with confidence scores.
+  anti-patterns --connection <name> [--kind table|query] [--limit <n>] [--json]
+                                  Schema-level (table) or query-level
+                                  anti-patterns detected by the brain.
+
+Admin commands (require ADMIN role on the calling token):
+  users list | get <ref> | add [<email>] [--role <r>] [--name <n>] [--password-stdin]
+        | set-role <ref> <role> | lock|unlock|disable <ref>
+        | resend-invite <ref> | reset-password <ref> [--password-stdin]
+        | delete <ref> [--yes]
+                                  Manage workspace users.
+  access list --user <ref> | --connection <name>
+        | grant   --user <ref> --connection <name> --level read|write|admin
+        | revoke  --user <ref> --connection <name>
+        | policy  <user> <connection>     (opens $EDITOR)
+                                  Per-connection access grants and chat policies.
+  permissions list [--role <ROLE>] [--json]
+        | override --role <ROLE> --permission <PERM> --grant|--revoke [--reason "..."]
+        | reset    --role <ROLE> --permission <PERM>
+                                  Role-based permission overrides.
+  slow-queries latest --connection <name>
+        | history --connection <name> [N]
+        | analyze --connection <name> [--time-range LAST_24_HOURS|LAST_HOUR]
+                                       [--threshold-ms <n>] [--limit <n>]
+        | optimize --connection <name> --query-id <id>
+                  (streams AI optimization steps to stderr; result to stdout)
+        | delete (--history-id <id> | --connection <name>) [--yes]
+                                  Read, trigger, and clean up slow-query analyses.
+  setup [--skip-email] [--skip-slack] [--skip-complete]
+                                  Post-install wizard: SMTP/email, Slack
+                                  (digests + bot), then mark setup complete.
+                                  Org and LLM config are set at install time
+                                  and are NOT touched by this wizard.
+
 Global options:
   --url <url>     Override the DeepSQL base URL.
   --token <tok>   Override the auth token (also: DEEPSQL_AUTH_TOKEN).
@@ -118,21 +181,54 @@ function buildOpts(parsed) {
     url: f.url || null,
     token: f.token || null,
     json: !!f.json,
+    // Login-flow selectors
     device: !!f.device,
     browser: !!f.browser,
     noBrowser: !!f.noBrowser,
-    password: !!f.password,
+    // password may be `true` (login flow flag) OR a string value (`users add
+    // --password secret`, `users add --password=secret`). Each command
+    // interprets whichever shape it expects.
+    password: f.password ?? null,
     passwordStdin: !!f.passwordStdin,
     email: f.email || null,
     label: f.label || null,
+    // Connection / users / chat
     connection: f.connection || f.c || null,
     chat: f.chat || null,
     user: f.user || null,
     project: f.project || null,
+    name: f.name || null,
+    username: f.username || null,
+    role: f.role || null,
+    // List / pagination
     limit: f.limit,
     count: f.count || f.n || null,
     timeoutSeconds: f.timeoutSeconds,
     file: f.file || null,
+    // RBAC / access
+    level: f.level || null,
+    permission: f.permission || null,
+    grant: !!f.grant,
+    revoke: !!f.revoke,
+    reason: f.reason || null,
+    // Brain tools
+    topK: f.topK ?? null,
+    kind: f.kind || null,
+    question: f.question || null,
+    // Slow queries
+    timeRange: f.timeRange || null,
+    thresholdMs: f.thresholdMs || null,
+    queryId: f.queryId || null,
+    queryText: f.queryText || null,
+    sampleQuery: f.sampleQuery || null,
+    historyId: f.historyId || null,
+    // Setup wizard
+    force: !!f.force,
+    skipEmail: !!f.skipEmail,
+    skipSlack: !!f.skipSlack,
+    skipComplete: !!f.skipComplete,
+    // Confirmations
+    yes: !!f.yes || !!f.y,
   };
 }
 

package/src/commands/_users.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/**
+ * Resolve a user reference (numeric id, email, or username) to a {id, email,
+ * username, role, ...} record.
+ *
+ * Backend `GET /admin/users` returns the full list, so we fetch once per
+ * invocation and match locally. Cheap for typical org sizes.
+ */
+
+const { request } = require("../api/client");
+
+let cachedUsers = null;
+
+async function listUsers(session) {
+  if (cachedUsers) return cachedUsers;
+  cachedUsers = await request(session.baseUrl, "/admin/users", { token: session.token });
+  if (!Array.isArray(cachedUsers)) cachedUsers = [];
+  return cachedUsers;
+}
+
+function clearUserCache() {
+  cachedUsers = null;
+}
+
+async function resolveUser(session, ref) {
+  if (ref == null || String(ref).trim() === "") {
+    throw new Error("Pass a user email, username, or numeric id.");
+  }
+  const trimmed = String(ref).trim();
+
+  // Numeric id — short-circuit if list isn't already cached.
+  if (/^\d+$/.test(trimmed)) {
+    const users = await listUsers(session);
+    const hit = users.find((u) => String(u.id) === trimmed);
+    if (hit) return hit;
+    throw new Error(`User id ${trimmed} not found.`);
+  }
+
+  const users = await listUsers(session);
+  const lower = trimmed.toLowerCase();
+  const exactEmail = users.find((u) => (u.email || "").toLowerCase() === lower);
+  if (exactEmail) return exactEmail;
+  const exactUsername = users.find((u) => (u.username || "").toLowerCase() === lower);
+  if (exactUsername) return exactUsername;
+
+  const available = users
+    .map((u) => u.email || u.username)
+    .filter(Boolean)
+    .slice(0, 20);
+  const hint = available.length ? ` Available: ${available.join(", ")}.` : "";
+  throw new Error(`User "${trimmed}" not found.${hint}`);
+}
+
+module.exports = { listUsers, resolveUser, clearUserCache };