@deepsql/mcp 0.2.0

package/src/auth/store.js

@@ -0,0 +1,152 @@
+"use strict";
+
+/**
+ * Persistent CLI auth store.
+ *
+ * Layout (XDG-friendly):
+ *   ~/.config/deepsql/auth.json   (Linux/macOS)
+ *   %APPDATA%\deepsql\auth.json   (Windows)
+ *
+ * File format:
+ *   {
+ *     "default": "http://localhost:8080",
+ *     "profiles": {
+ *       "<base-url>": { token, username, tokenId, createdAt }
+ *     }
+ *   }
+ *
+ * The file is written with mode 0600 and the parent dir with 0700. We refuse to
+ * read a file with looser perms unless DEEPSQL_INSECURE_AUTH=1 is set, since
+ * tokens grant access to the user's databases.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+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");
+    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");
+}
+
+function authFilePath() {
+  return path.join(configDir(), "auth.json");
+}
+
+function normalizeBaseUrl(url) {
+  if (!url || typeof url !== "string") return url;
+  return url.replace(/\/+$/, "");
+}
+
+function emptyState() {
+  return { default: null, profiles: {} };
+}
+
+function load() {
+  const file = authFilePath();
+  if (!fs.existsSync(file)) {
+    return emptyState();
+  }
+  if (process.platform !== "win32" && process.env.DEEPSQL_INSECURE_AUTH !== "1") {
+    const stat = fs.statSync(file);
+    // Mode 0600 == 0o600. Reject if group/other have any bits set.
+    if ((stat.mode & 0o077) !== 0) {
+      throw new Error(
+        `${file} has insecure permissions (${(stat.mode & 0o777).toString(8)}). ` +
+          "Run `chmod 600` on it, or set DEEPSQL_INSECURE_AUTH=1 to override.",
+      );
+    }
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object") return emptyState();
+    return {
+      default: parsed.default || null,
+      profiles: parsed.profiles || {},
+    };
+  } catch (err) {
+    throw new Error(`Failed to parse ${file}: ${err.message}`);
+  }
+}
+
+function save(state) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") {
+    try {
+      fs.chmodSync(dir, 0o700);
+    } catch {
+      // Best-effort — some filesystems (FAT, network mounts) don't support chmod.
+    }
+  }
+  const file = authFilePath();
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function getProfile(baseUrl) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl) || state.default;
+  if (!key) return null;
+  return state.profiles[key] || null;
+}
+
+function setProfile(baseUrl, profile) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl);
+  state.profiles[key] = profile;
+  if (!state.default) state.default = key;
+  save(state);
+}
+
+function removeProfile(baseUrl) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl);
+  delete state.profiles[key];
+  if (state.default === key) {
+    const remaining = Object.keys(state.profiles);
+    state.default = remaining[0] || null;
+  }
+  save(state);
+}
+
+function setDefault(baseUrl) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl);
+  if (!state.profiles[key]) {
+    throw new Error(`No profile saved for ${key}. Run \`deepsql login --url ${key}\` first.`);
+  }
+  state.default = key;
+  save(state);
+}
+
+function defaultBaseUrl() {
+  const state = load();
+  return state.default || null;
+}
+
+function listProfiles() {
+  return load();
+}
+
+module.exports = {
+  authFilePath,
+  configDir,
+  defaultBaseUrl,
+  getProfile,
+  listProfiles,
+  load,
+  normalizeBaseUrl,
+  removeProfile,
+  save,
+  setDefault,
+  setProfile,
+};

package/src/auth/store.test.js

@@ -0,0 +1,78 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function withTempStore(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "deepsql-store-"));
+  const previous = process.env.DEEPSQL_CONFIG_DIR;
+  process.env.DEEPSQL_CONFIG_DIR = dir;
+  // Force re-resolution of the path each call.
+  delete require.cache[require.resolve("./store")];
+  const store = require("./store");
+  try {
+    return fn(store, dir);
+  } finally {
+    process.env.DEEPSQL_CONFIG_DIR = previous;
+    delete require.cache[require.resolve("./store")];
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("setProfile then getProfile round-trips", () => {
+  withTempStore((store) => {
+    store.setProfile("http://localhost:8080", {
+      token: "dsql_mcp_x.y",
+      username: "alice",
+      tokenId: 7,
+    });
+    const profile = store.getProfile("http://localhost:8080");
+    assert.equal(profile.token, "dsql_mcp_x.y");
+    assert.equal(profile.username, "alice");
+    assert.equal(store.defaultBaseUrl(), "http://localhost:8080");
+  });
+});
+
+test("normalizes trailing slash so http://x and http://x/ share a profile", () => {
+  withTempStore((store) => {
+    store.setProfile("http://localhost:8080/", { token: "t", username: "a" });
+    const profile = store.getProfile("http://localhost:8080");
+    assert.ok(profile);
+    assert.equal(profile.token, "t");
+  });
+});
+
+test("removeProfile clears the profile and reassigns default", () => {
+  withTempStore((store) => {
+    store.setProfile("http://a", { token: "ta", username: "alice" });
+    store.setProfile("http://b", { token: "tb", username: "bob" });
+    store.removeProfile("http://a");
+    assert.equal(store.getProfile("http://a"), null);
+    assert.equal(store.defaultBaseUrl(), "http://b");
+  });
+});
+
+test("auth file is written with mode 0600", { skip: process.platform === "win32" }, () => {
+  withTempStore((store, dir) => {
+    store.setProfile("http://localhost:8080", { token: "t", username: "a" });
+    const stat = fs.statSync(path.join(dir, "auth.json"));
+    assert.equal(stat.mode & 0o777, 0o600);
+  });
+});
+
+test("rejects loose perms unless DEEPSQL_INSECURE_AUTH=1", { skip: process.platform === "win32" }, () => {
+  withTempStore((store, dir) => {
+    store.setProfile("http://localhost:8080", { token: "t", username: "a" });
+    fs.chmodSync(path.join(dir, "auth.json"), 0o644);
+    assert.throws(() => store.load(), /insecure permissions/);
+    process.env.DEEPSQL_INSECURE_AUTH = "1";
+    try {
+      assert.doesNotThrow(() => store.load());
+    } finally {
+      delete process.env.DEEPSQL_INSECURE_AUTH;
+    }
+  });
+});

package/src/cli.js

@@ -0,0 +1,158 @@
+"use strict";
+
+/**
+ * Dispatcher + lightweight argv parser for the `deepsql` CLI.
+ *
+ * Avoids a heavy CLI framework on purpose — keeps the npm install footprint
+ * 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
+ *   - subcommands:    deepsql connections list, deepsql config show
+ *   - positional:     deepsql ask "what tables exist?"
+ */
+
+const COMMANDS = {
+  login: () => require("./commands/login"),
+  logout: () => require("./commands/logout"),
+  whoami: () => require("./commands/whoami"),
+  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"),
+};
+
+const HELP = `deepsql — DeepSQL CLI
+
+Usage:
+  deepsql <command> [options]
+
+Commands:
+  login [--url <url>] [--device|--browser] [--no-browser] [--label <name>]
+                                  Authorize this CLI with a DeepSQL instance.
+  logout [--url <url>]            Revoke and forget the saved token.
+  whoami                          Show the user behind the saved token.
+  config show                     List saved profiles.
+  config set-default <url>        Set the default profile.
+  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 DeepSQL a question.
+  query "<sql>" --connection <id> [--limit <n>] [--timeout-seconds <n>] [--file <path>] [--json]
+                                  Run a read-only SQL query.
+  explain "<sql>" --connection <id> [--file <path>] [--json]
+                                  Get an EXPLAIN plan.
+  schema [tables|objects] --connection <id>
+                                  Dump schema or database objects as JSON.
+
+Global options:
+  --url <url>     Override the DeepSQL base URL.
+  --token <tok>   Override the auth token (also: DEEPSQL_AUTH_TOKEN).
+  -h, --help      Show help.
+  -v, --version   Show version.
+`;
+
+function parseArgs(argv) {
+  const result = { positional: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      result.positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const key = (eq === -1 ? arg.slice(2) : arg.slice(2, eq));
+      let value;
+      if (eq !== -1) {
+        value = arg.slice(eq + 1);
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        value = argv[++i];
+      } else {
+        value = true;
+      }
+      result.flags[normalizeKey(key)] = coerce(value);
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      const key = arg.slice(1);
+      result.flags[normalizeKey(key)] = true;
+    } else {
+      result.positional.push(arg);
+    }
+  }
+  return result;
+}
+
+function normalizeKey(key) {
+  // --no-browser → noBrowser, --timeout-seconds → timeoutSeconds
+  return key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function coerce(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return value;
+}
+
+function buildOpts(parsed) {
+  const f = parsed.flags;
+  return {
+    positional: parsed.positional,
+    url: f.url || null,
+    token: f.token || null,
+    json: !!f.json,
+    device: !!f.device,
+    browser: !!f.browser,
+    noBrowser: !!f.noBrowser,
+    label: f.label || null,
+    connection: f.connection || f.c || null,
+    chat: f.chat || null,
+    user: f.user || null,
+    project: f.project || null,
+    limit: f.limit,
+    timeoutSeconds: f.timeoutSeconds,
+    file: f.file || null,
+  };
+}
+
+async function main(rawArgv = process.argv.slice(2), io = {}) {
+  const stderr = io.stderr || process.stderr;
+  const stdout = io.stdout || process.stdout;
+
+  if (rawArgv.length === 0 || rawArgv[0] === "--help" || rawArgv[0] === "-h") {
+    stdout.write(`${HELP}\n`);
+    return 0;
+  }
+  if (rawArgv[0] === "--version" || rawArgv[0] === "-v") {
+    const pkg = require("../package.json");
+    stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const command = rawArgv[0];
+  const loader = COMMANDS[command];
+  if (!loader) {
+    stderr.write(`Unknown command: ${command}\n\n${HELP}\n`);
+    return 2;
+  }
+
+  const parsed = parseArgs(rawArgv.slice(1));
+  const opts = buildOpts(parsed);
+
+  try {
+    const mod = loader();
+    await mod.run(opts, { stdout, stderr });
+    return 0;
+  } catch (err) {
+    stderr.write(`Error: ${err.message}\n`);
+    if (process.env.DEEPSQL_DEBUG === "1" && err.stack) {
+      stderr.write(`${err.stack}\n`);
+    }
+    return 1;
+  }
+}
+
+module.exports = { main, parseArgs, buildOpts };

package/src/cli.test.js

@@ -0,0 +1,38 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { parseArgs, buildOpts } = require("./cli");
+
+test("parseArgs collects positional args", () => {
+  const { positional, flags } = parseArgs(["how", "many", "rows"]);
+  assert.deepEqual(positional, ["how", "many", "rows"]);
+  assert.deepEqual(flags, {});
+});
+
+test("parseArgs handles --flag value and --flag=value", () => {
+  const a = parseArgs(["--url", "http://x", "--connection=c1"]);
+  assert.equal(a.flags.url, "http://x");
+  assert.equal(a.flags.connection, "c1");
+});
+
+test("parseArgs camelCases dashed flags", () => {
+  const { flags } = parseArgs(["--no-browser", "--timeout-seconds", "30"]);
+  assert.equal(flags.noBrowser, true);
+  assert.equal(flags.timeoutSeconds, "30");
+});
+
+test("parseArgs treats trailing -- as positional separator", () => {
+  const { positional } = parseArgs(["query", "--", "SELECT 1"]);
+  assert.deepEqual(positional, ["query", "SELECT 1"]);
+});
+
+test("buildOpts maps known flags", () => {
+  const parsed = parseArgs(["--connection", "c1", "--json", "--limit", "50", "SELECT 1"]);
+  const opts = buildOpts(parsed);
+  assert.equal(opts.connection, "c1");
+  assert.equal(opts.json, true);
+  assert.equal(opts.limit, "50");
+  assert.deepEqual(opts.positional, ["SELECT 1"]);
+});

package/src/commands/_session.js

@@ -0,0 +1,41 @@
+"use strict";
+
+const store = require("../auth/store");
+
+/**
+ * Resolves the (baseUrl, token) tuple a command should use.
+ *
+ * Precedence — highest first:
+ *   1. --token CLI flag
+ *   2. DEEPSQL_AUTH_TOKEN env var (back-compat with the legacy MCP setup)
+ *   3. Saved profile for --url, or the default profile
+ *
+ * The base URL falls back from --url → DEEPSQL_API_BASE_URL → saved profile.
+ */
+function resolveSession(opts = {}) {
+  const explicitToken = opts.token || process.env.DEEPSQL_AUTH_TOKEN || null;
+
+  let baseUrl = opts.url ? store.normalizeBaseUrl(opts.url) : null;
+  if (!baseUrl && process.env.DEEPSQL_API_BASE_URL) {
+    baseUrl = store.normalizeBaseUrl(stripApiSuffix(process.env.DEEPSQL_API_BASE_URL));
+  }
+  if (!baseUrl) baseUrl = store.defaultBaseUrl();
+
+  let profile = null;
+  if (baseUrl) profile = store.getProfile(baseUrl);
+
+  const token = explicitToken || profile?.token || null;
+  if (!baseUrl) {
+    throw new Error("No DeepSQL URL configured. Run `deepsql login --url <url>`.");
+  }
+  if (!token) {
+    throw new Error(`No auth token for ${baseUrl}. Run \`deepsql login --url ${baseUrl}\`.`);
+  }
+  return { baseUrl, token, profile };
+}
+
+function stripApiSuffix(url) {
+  return url.replace(/\/?api\/?$/, "");
+}
+
+module.exports = { resolveSession };

package/src/commands/ask.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const os = require("node:os");
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+
+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.");
+
+  const session = resolveSession(opts);
+  const userId = opts.user || `cli-${os.userInfo().username}`;
+  const projectId = opts.project || "deepsql-cli";
+
+  const response = await request(session.baseUrl, "/chat", {
+    method: "POST",
+    token: session.token,
+    timeoutMs: 240000,
+    json: {
+      connectionId: opts.connection,
+      message: question,
+      chatId: opts.chat || null,
+      userId,
+      projectId,
+    },
+  });
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+
+  const answer = response?.answer || response?.message || response?.content || null;
+  if (answer) {
+    stdout.write(`${answer}\n`);
+  } else {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+  }
+}
+
+module.exports = { run };

package/src/commands/config.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const store = require("../auth/store");
+
+async function run(args, { stdout = process.stdout } = {}) {
+  const sub = args.positional[0] || "show";
+  switch (sub) {
+    case "show":
+      return showConfig(stdout);
+    case "set-default":
+      return setDefault(args.positional[1], stdout);
+    case "path":
+      stdout.write(`${store.authFilePath()}\n`);
+      return;
+    default:
+      throw new Error(`Unknown config subcommand: ${sub}. Try \`show\`, \`set-default <url>\`, or \`path\`.`);
+  }
+}
+
+function showConfig(stdout) {
+  const state = store.listProfiles();
+  const profiles = Object.keys(state.profiles || {});
+  if (profiles.length === 0) {
+    stdout.write("No saved profiles. Run `deepsql login --url <url>` to add one.\n");
+    return;
+  }
+  stdout.write(`Default: ${state.default || "(none)"}\n`);
+  stdout.write(`Profiles:\n`);
+  for (const url of profiles) {
+    const p = state.profiles[url];
+    const marker = url === state.default ? " *" : "  ";
+    stdout.write(`${marker} ${url}    user=${p.username || "?"}  tokenId=${p.tokenId || "?"}\n`);
+  }
+}
+
+function setDefault(url, stdout) {
+  if (!url) throw new Error("Pass the base URL: `deepsql config set-default <url>`.");
+  store.setDefault(store.normalizeBaseUrl(url));
+  stdout.write(`Default profile is now ${store.normalizeBaseUrl(url)}.\n`);
+}
+
+module.exports = { run };

package/src/commands/connections.js

@@ -0,0 +1,29 @@
+"use strict";
+
+const { request } = require("../api/client");
+const { resolveSession } = require("./_session");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+  const sub = opts.positional[0] || "list";
+  if (sub !== "list") {
+    throw new Error(`Unknown connections subcommand: ${sub}. Try \`list\`.`);
+  }
+  const session = resolveSession(opts);
+  const data = await request(session.baseUrl, "/connections", { token: session.token });
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    return;
+  }
+  if (!Array.isArray(data) || data.length === 0) {
+    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`);
+  }
+}
+
+module.exports = { run };

package/src/commands/explain.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const fs = require("node:fs");
+const { request } = require("../api/client");
+const { validateReadOnlySql } = require("../../deepsql-phase1-lib");
+const { resolveSession } = require("./_session");
+
+async function run(opts, { stdout = process.stdout } = {}) {
+  if (!opts.connection) throw new Error("--connection <id> 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 response = await request(session.baseUrl, "/mcp/explain-readonly", {
+    method: "POST",
+    token: session.token,
+    json: { connectionId: opts.connection, query: validation.normalizedQuery },
+  });
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+    return;
+  }
+  if (response?.plan) {
+    stdout.write(typeof response.plan === "string" ? `${response.plan}\n` : `${JSON.stringify(response.plan, null, 2)}\n`);
+    return;
+  }
+  stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+}
+
+function readSqlInput(opts) {
+  if (opts.file) return fs.readFileSync(opts.file, "utf8");
+  if (opts.positional.length > 0) return opts.positional.join(" ");
+  if (!process.stdin.isTTY) return fs.readFileSync(0, "utf8");
+  throw new Error("Pass SQL as an argument, via --file <path>, or pipe it to stdin.");
+}
+
+module.exports = { run };

package/src/commands/login.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const os = require("node:os");
+const { runBrowserFlow } = require("../auth/browser-flow");
+const { runDeviceFlow } = require("../auth/device-flow");
+const store = require("../auth/store");
+const { ApiError } = require("../api/client");
+
+function defaultClientLabel() {
+  return `deepsql-cli@${process.versions.node}`;
+}
+
+function shouldUseDevice(opts) {
+  if (opts.device) return true;
+  if (opts.browser) return false;
+  // Heuristic: assume browser unless we detect a headless env.
+  if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT) return true;
+  if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
+  return false;
+}
+
+async function run(opts, { stderr = process.stderr, stdout = process.stdout } = {}) {
+  const baseUrl = opts.url ? store.normalizeBaseUrl(opts.url) : store.defaultBaseUrl();
+  if (!baseUrl) {
+    throw new Error(
+      "Pass --url <https://your-deepsql> on first login (no default profile is saved yet).",
+    );
+  }
+  const hostname = os.hostname();
+  const label = opts.label || defaultClientLabel();
+  const useDevice = shouldUseDevice(opts);
+  const log = (msg) => stderr.write(`[deepsql] ${msg}\n`);
+
+  let issued;
+  try {
+    if (useDevice) {
+      log(`Starting device-code login against ${baseUrl}…`);
+      issued = await runDeviceFlow({ baseUrl, hostname, clientLabel: label, log });
+    } else {
+      log(`Starting browser login against ${baseUrl}…`);
+      issued = await runBrowserFlow({
+        baseUrl,
+        hostname,
+        clientLabel: label,
+        log,
+        openBrowser: !opts.noBrowser,
+      });
+    }
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 0) {
+      throw new Error(`Could not reach ${baseUrl}. Is the DeepSQL backend running?`);
+    }
+    throw err;
+  }
+
+  store.setProfile(baseUrl, {
+    token: issued.token,
+    tokenId: issued.token_id,
+    username: issued.username,
+    createdAt: new Date().toISOString(),
+    expiresAt: issued.expires_at || null,
+  });
+
+  stdout.write(`Authorized as ${issued.username} at ${baseUrl}\n`);
+  stdout.write(`Token saved to ${store.authFilePath()}\n`);
+}
+
+module.exports = { run };