causly-server 0.0.0-stage → 1.5.1

package/tools/cliOps.js

@@ -0,0 +1,233 @@
+// Logic behind the `causly-server` command: init, remove, doctor.
+// bin/causly.js is a thin wrapper so all of this can be tested with temp folders.
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { execFile } from "child_process";
+import { PACKAGE_ROOT, causlyHome, envFiles } from "./paths.js";
+
+export const SERVER_NAME = "causly-server";
+export const CLIENTS = ["claude", "cursor", "windsurf"];
+
+const CLIENT_LABEL = { claude: "Claude Desktop", cursor: "Cursor", windsurf: "Windsurf" };
+
+/** Config file of each editor/app that speaks MCP. */
+export function clientConfigPath(client, { platform = os.platform(), home = os.homedir(), env = process.env } = {}) {
+  switch (client) {
+    case "claude":
+      if (platform === "win32") return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+      if (platform === "darwin") return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+      return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    case "cursor":
+      return path.join(home, ".cursor", "mcp.json");
+    case "windsurf":
+      return path.join(home, ".codeium", "windsurf", "mcp_config.json");
+    default:
+      throw new Error(`Unknown client "${client}". Use one of: ${CLIENTS.join(", ")}, all.`);
+  }
+}
+
+/** A client counts as installed when its config folder exists (Claude Desktop, Cursor, Windsurf create it on first run). */
+export function detectClients(opts = {}) {
+  return CLIENTS.filter((c) => fs.existsSync(path.dirname(clientConfigPath(c, opts))));
+}
+
+/**
+ * What the client should run. From a global install or a git checkout that is
+ * `node <path>/index.js` with the absolute node path (GUI apps often lack node on PATH).
+ * From the temporary npx cache that path would disappear, so use `npx -y causly-server`.
+ */
+export function serverEntry({ root = PACKAGE_ROOT, platform = os.platform(), execPath = process.execPath, workspace, toolsets } = {}) {
+  const fromNpxCache = root.split(/[\\/]/).includes("_npx");
+  const entry = fromNpxCache
+    ? platform === "win32"
+      ? { command: "cmd", args: ["/c", "npx", "-y", SERVER_NAME] }
+      : { command: "npx", args: ["-y", SERVER_NAME] }
+    : { command: execPath, args: [path.join(root, "index.js")] };
+  const env = {};
+  if (workspace) env.CAUSLY_WORKSPACE = path.resolve(workspace);
+  if (toolsets) env.CAUSLY_TOOLSETS = toolsets;
+  if (Object.keys(env).length) entry.env = env;
+  return entry;
+}
+
+export function readJson(file) {
+  if (!fs.existsSync(file)) return { config: {}, existed: false, broken: false };
+  const raw = fs.readFileSync(file, "utf8");
+  if (!raw.trim()) return { config: {}, existed: true, broken: false };
+  try {
+    const config = JSON.parse(raw);
+    if (config && typeof config === "object" && !Array.isArray(config)) return { config, existed: true, broken: false };
+  } catch {
+    // fall through
+  }
+  return { config: {}, existed: true, broken: true };
+}
+
+export function backup(file) {
+  const copy = `${file}.backup-${Date.now()}`;
+  fs.copyFileSync(file, copy);
+  return copy;
+}
+
+/** Add or update our entry, keeping every other server and setting in the file. */
+export function upsertServerEntry(file, entry) {
+  const { config, existed, broken } = readJson(file);
+  let backedUp;
+  if (existed) backedUp = backup(file);
+  if (!config.mcpServers || typeof config.mcpServers !== "object") config.mcpServers = {};
+  const had = SERVER_NAME in config.mcpServers;
+  config.mcpServers[SERVER_NAME] = entry;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  return { updated: had, created: !had, backup: backedUp, replacedBrokenFile: broken };
+}
+
+export function removeServerEntry(file) {
+  const { config, existed, broken } = readJson(file);
+  if (!existed || broken || !config.mcpServers || !(SERVER_NAME in config.mcpServers)) return { removed: false };
+  const copy = backup(file);
+  delete config.mcpServers[SERVER_NAME];
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  return { removed: true, backup: copy };
+}
+
+export function pickClients(client, opts) {
+  if (!client || client === "auto") {
+    const found = detectClients(opts);
+    return found.length ? found : ["claude"];
+  }
+  if (client === "all") return [...CLIENTS];
+  return String(client)
+    .split(",")
+    .map((c) => c.trim())
+    .filter(Boolean)
+    .map((c) => {
+      if (!CLIENTS.includes(c)) throw new Error(`Unknown client "${c}". Use one of: ${CLIENTS.join(", ")}, all.`);
+      return c;
+    });
+}
+
+/**
+ * Set the server up for the user's editors. Creates ~/.causly/.env from the template
+ * (unless a checkout already has a .env) and registers the server with each client.
+ */
+// Claude Desktop and others do not refresh tools mid-chat, so everyday packs load at startup.
+export const DEFAULT_TOOLSETS = "research,leads,seo,pipeline,reminders,meetings";
+
+export function runInit({ client, workspace, toolsets, platform, home, env, root = PACKAGE_ROOT } = {}) {
+  const where = { platform, home, env };
+  const clients = pickClients(client, where);
+  const lines = [];
+
+  if (workspace && !fs.existsSync(workspace)) throw new Error(`The workspace folder does not exist: ${workspace}`);
+
+  const envFile = path.join(causlyHome(), ".env");
+  const template = path.join(root, ".env.example");
+  const checkoutEnv = path.join(root, ".env");
+  let envPath = fs.existsSync(checkoutEnv) ? checkoutEnv : envFile;
+  if (!fs.existsSync(envPath)) {
+    fs.mkdirSync(path.dirname(envFile), { recursive: true });
+    if (fs.existsSync(template)) fs.copyFileSync(template, envFile);
+    else fs.writeFileSync(envFile, "# causly-server settings: KEY=value, one per line\n");
+    lines.push(`Created ${envFile} (add your API keys there)`);
+  } else {
+    lines.push(`Using existing ${envPath}`);
+  }
+
+  const entry = serverEntry({ root, platform, workspace, toolsets: toolsets ?? DEFAULT_TOOLSETS });
+  const results = [];
+  for (const c of clients) {
+    const file = clientConfigPath(c, where);
+    const r = upsertServerEntry(file, entry);
+    results.push({ client: c, file, ...r });
+    lines.push(`${r.updated ? "Updated" : "Added"} ${CLIENT_LABEL[c]}: ${file}${r.replacedBrokenFile ? " (the old file was not valid JSON; kept a backup)" : ""}`);
+  }
+  lines.push(`Restart ${clients.map((c) => CLIENT_LABEL[c]).join(" and ")} to load it.`);
+  lines.push(`Claude Code: claude mcp add ${SERVER_NAME} -- ${[entry.command, ...entry.args].map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(" ")}`);
+  if (!workspace) lines.push("Tip: limit file access to one folder with --workspace <folder> (re-run init).");
+  return { env_file: envPath, entry, clients: results, lines };
+}
+
+/** Shown after init: what to try first. */
+export function welcomeLines() {
+  return [
+    "",
+    "Try asking your agent:",
+    '  "Find companies hiring React developers and add the best three to my pipeline."',
+    '  "Save notes from my call with Acme: they want a demo next week, follow up on Friday."',
+    '  "What is due this week? Include meeting action items and reminders."',
+    '  "Prep me for my next meeting." (needs Google Calendar: causly-server login google)',
+    "",
+    "Useful commands: causly-server status | setup | login google | toolsets | backup | doctor --test",
+  ];
+}
+
+export function runRemove({ client, platform, home, env } = {}) {
+  const where = { platform, home, env };
+  const clients = client ? pickClients(client, where) : [...CLIENTS];
+  const lines = [];
+  const results = clients.map((c) => {
+    const file = clientConfigPath(c, where);
+    const r = removeServerEntry(file);
+    if (r.removed) lines.push(`Removed from ${CLIENT_LABEL[c]}: ${file}`);
+    return { client: c, file, ...r };
+  });
+  if (!lines.length) lines.push("Nothing to remove: causly-server is not set up in any client.");
+  else lines.push(`Your settings in ${causlyHome()} were left alone; delete that folder to remove them too.`);
+  return { clients: results, lines };
+}
+
+// ---------------------------------------------------------------- doctor
+
+const SERVICES = [
+  ["GitHub", ["GITHUB_TOKEN"]],
+  ["Slack", ["SLACK_BOT_TOKEN"]],
+  ["Gmail", ["GMAIL_CLIENT_ID", "GMAIL_CLIENT_SECRET", "GMAIL_REFRESH_TOKEN"]],
+  ["Google Calendar", ["CALENDAR_REFRESH_TOKEN"]],
+  ["Telegram", ["TELEGRAM_BOT_TOKEN", "TELEGRAM_CHAT_ID"]],
+  ["Linear", ["LINEAR_API_KEY"]],
+  ["Stripe", ["STRIPE_API_KEY"]],
+  ["Discord", ["DISCORD_BOT_TOKEN"]],
+  ["Groq (meeting transcription)", ["GROQ_API_KEY"]],
+  ["Notion", ["NOTION_API_KEY"]],
+  ["Sentry", ["SENTRY_AUTH_TOKEN"]],
+];
+
+const versionAtLeast = (v, [maj, min]) => {
+  const [a, b] = String(v).replace(/^v/, "").split(".").map(Number);
+  return a > maj || (a === maj && b >= min);
+};
+
+function probe(exec, cmd, args) {
+  return new Promise((resolve) => exec(cmd, args, { timeout: 8000, windowsHide: true }, (err, stdout) => resolve(err ? null : String(stdout).split("\n")[0].trim())));
+}
+
+export async function runDoctor({ env = process.env, exec = execFile, nodeVersion = process.versions.node, platform, home } = {}) {
+  const checks = [];
+  const add = (name, ok, detail) => checks.push({ name, ok, detail });
+
+  add("Node.js", versionAtLeast(nodeVersion, [20, 0]), `${nodeVersion}${versionAtLeast(nodeVersion, [22, 13]) ? "" : " (22.13+ is needed for pipeline, meetings and reminders)"}`);
+
+  const files = envFiles().filter((f) => fs.existsSync(f));
+  add("Settings file", files.length > 0, files.length ? files.join(", ") : `none found; run "causly-server init" or create ${path.join(causlyHome(), ".env")}`);
+
+  const loaded = (keys) => keys.every((k) => env[k]);
+  const configured = SERVICES.filter(([, keys]) => loaded(keys)).map(([n]) => n);
+  const missing = SERVICES.filter(([, keys]) => !loaded(keys)).map(([n]) => n);
+  add("Integrations configured", configured.length > 0, configured.length ? configured.join(", ") : "none yet (add keys to the settings file)");
+
+  const ff = await probe(exec, "ffmpeg", ["-version"]);
+  add("ffmpeg (large recordings)", Boolean(ff), ff ? ff.slice(0, 40) : "not found; only needed for recordings over 25 MB");
+
+  add("Workspace limit", Boolean(env.CAUSLY_WORKSPACE), env.CAUSLY_WORKSPACE || "off: file tools can reach any folder (set with: causly-server init --workspace <folder>)");
+
+  const where = { platform, home, env };
+  const registered = CLIENTS.filter((c) => {
+    const { config } = readJson(clientConfigPath(c, where));
+    return config.mcpServers && SERVER_NAME in config.mcpServers;
+  });
+  add("Set up in", registered.length > 0, registered.length ? registered.map((c) => CLIENT_LABEL[c]).join(", ") : 'no editor yet; run "causly-server init"');
+
+  return { ok: checks.filter((c) => c.name === "Node.js" || c.name === "Settings file").every((c) => c.ok), checks, not_configured: missing };
+}

package/tools/commandOps.js

@@ -0,0 +1,198 @@
+import { exec, execFile } from "child_process";
+import { promisify } from "util";
+import os from "os";
+import { classifyCommandRisk } from "./security.js";
+
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+
+const IS_WINDOWS = os.platform() === "win32";
+
+// Resolve PowerShell by absolute path instead of relying on PATH lookup —
+// Claude Desktop's spawned environment has an unreliable/stripped PATH on
+// some machines, which made `execFile("powershell.exe", ...)` fail with
+// ENOENT even though PowerShell was installed. The System32 location is
+// standard on every Windows install; SystemRoot env var (or C:\Windows as
+// a fallback) makes it correct even on non-C drive Windows installs.
+const POWERSHELL_PATH = IS_WINDOWS
+  ? `${process.env.SystemRoot || "C:\\Windows"}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`
+  : null;
+
+// cmd.exe is used as a last-resort fallback below. Resolve it by absolute
+// path too — the same stripped-environment issue that breaks PATH lookup
+// for powershell.exe also breaks lookup of "cmd.exe" (via a missing/broken
+// ComSpec env var), so execAsync(command) with the default shell option
+// can ENOENT even though cmd.exe is present on every Windows install.
+const CMD_PATH = IS_WINDOWS
+  ? `${process.env.SystemRoot || "C:\\Windows"}\\System32\\cmd.exe`
+  : null;
+
+// Claude Desktop launches this server with a stripped-down environment —
+// on Windows, PATHEXT in particular often arrives missing .EXE/.CMD/.BAT,
+// which makes PowerShell unable to resolve commands like `node` or `npm`
+// even though their directory is present in PATH and the file exists.
+// Restore a sane default so command resolution works the way it would in
+// a normal interactive terminal.
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC";
+
+// Find the actual casing of an env var key (Windows env keys can be
+// "Path", "PATH", "PathExt", etc. depending on how they were originally
+// set). Returns the real key if found, otherwise undefined.
+function findKey(env, name) {
+  return Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
+}
+
+function buildEnv() {
+  if (!IS_WINDOWS) return process.env;
+  const env = { ...process.env };
+
+  // IMPORTANT: always read/write through the env's *actual* existing key
+  // casing (e.g. "Path" vs "PATH"). Setting env.PATH when the real key is
+  // "Path" creates two distinct keys in the plain JS object. Node then
+  // serializes BOTH into the child process's environment block. Nested
+  // processes (cmd.exe spawned by npm, which then spawns node) can end up
+  // reading the wrong/empty duplicate for their own command resolution —
+  // this was the actual cause of "'node' is not recognized" inside
+  // `npm run <script>`, even though PATH looked correct when echoed at
+  // the top level.
+  const pathExtKey = findKey(env, "PATHEXT") || "PATHEXT";
+  const currentExt = env[pathExtKey] || "";
+  // Normalize: split, drop empty segments (a stray leading/trailing/double
+  // semicolon produces an empty entry, e.g. ";.COM;.EXE"). An empty entry
+  // here silently breaks Windows' extension-less command resolution
+  // (`node`, `npm`, `where`, etc.) inside nested cmd.exe processes — this
+  // was the actual root cause of "'node' is not recognized" inside
+  // `npm run <script>` (npm spawns its own cmd.exe internally), even
+  // though the PATHEXT value looked fine when echoed at the top level.
+  const currentExtList = currentExt.split(";").map((e) => e.trim()).filter(Boolean);
+  const missingExt = DEFAULT_PATHEXT.split(";").filter(
+    (ext) => !currentExtList.some((e) => e.toUpperCase() === ext)
+  );
+  env[pathExtKey] = [...currentExtList, ...missingExt].join(";") || DEFAULT_PATHEXT;
+
+  // Claude Desktop's spawned environment also carries a stripped-down PATH
+  // on some machines — missing the Node.js install dir and the npm global
+  // bin dir. This breaks any subprocess spawned BY a tool we run (e.g.
+  // `npm install`'s own internal `node postinstall.js` calls, or
+  // `npm run <script>`'s nested cmd.exe -> node.exe spawn), even though
+  // our own top-level `node`/`npm` calls succeed via PowerShell's separate
+  // system-PATH resolution. Ensure these are always present.
+  const pathKey = findKey(env, "PATH") || "PATH";
+  const home = env.USERPROFILE || env.HOME || "C:\\Users\\nihal";
+  const criticalPaths = [
+    "C:\\Program Files\\nodejs",
+    `${home}\\AppData\\Roaming\\npm`,
+  ];
+  const currentPath = env[pathKey] || "";
+  const currentPathList = currentPath.split(";").map((p) => p.trim()).filter(Boolean);
+  const missingPaths = criticalPaths.filter(
+    (p) => !currentPathList.some((existing) => existing.toLowerCase() === p.toLowerCase())
+  );
+  env[pathKey] = [...currentPathList, ...missingPaths].join(";");
+
+  return env;
+}
+
+// Commands containing these patterns are blocked outright — no override.
+// Keeps a single mistaken/careless call from wiping a drive or the OS.
+const BLOCKED_PATTERNS = [
+  /rm\s+-rf\s+\/(?!\S)/i, // rm -rf /
+  /rm\s+-rf\s+[a-z]:\\?\s*$/i, // rm -rf C:\ or D:\
+  /format\s+[a-z]:/i, // format C:
+  /del\s+\/s\s+\/q\s+[a-z]:\\?\s*$/i, // del /s /q C:\
+  /:\(\)\{.*\};:/, // fork bomb
+  /shutdown|restart-computer/i,
+  /reg\s+delete/i,
+];
+
+const DEFAULT_TIMEOUT_MS = 60_000; // 1 minute
+const MAX_OUTPUT_CHARS = 20_000;
+
+function truncate(str) {
+  if (!str) return str;
+  return str.length > MAX_OUTPUT_CHARS
+    ? str.slice(0, MAX_OUTPUT_CHARS) + `\n... [truncated, ${str.length - MAX_OUTPUT_CHARS} more chars]`
+    : str;
+}
+
+/**
+ * Run a shell command in a given working directory.
+ * Blocks a short list of catastrophic patterns; everything else is allowed
+ * since this server runs with full trusted access on the user's own machine.
+ */
+export async function runCommand({ command, cwd, timeout_ms = DEFAULT_TIMEOUT_MS }) {
+  for (const pattern of BLOCKED_PATTERNS) {
+    if (pattern.test(command)) {
+      throw new Error(
+        `Blocked: this command matches a destructive pattern (${pattern}) and was not run. If this is a false positive, rephrase the command.`
+      );
+    }
+  }
+
+  const riskInfo = classifyCommandRisk(command);
+
+  const runOpts = {
+    cwd,
+    timeout: timeout_ms,
+    maxBuffer: 10 * 1024 * 1024, // 10MB
+    windowsHide: true,
+    env: buildEnv(),
+  };
+
+  async function runOnWindows() {
+    const psArgs = ["-NoProfile", "-NonInteractive", "-Command", command];
+    try {
+      // Preferred: absolute path, bypasses any PATH resolution issues.
+      return await execFileAsync(POWERSHELL_PATH, psArgs, runOpts);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      try {
+        // Fallback 1: let the OS resolve "powershell.exe" via PATH.
+        return await execFileAsync("powershell.exe", psArgs, runOpts);
+      } catch (err2) {
+        if (err2.code !== "ENOENT") throw err2;
+        try {
+          // Fallback 2: let the OS resolve "cmd.exe" via PATH/ComSpec.
+          return await execAsync(command, runOpts);
+        } catch (err3) {
+          if (err3.code !== "ENOENT") throw err3;
+          // Fallback 3: absolute path to cmd.exe, bypasses ComSpec/PATH
+          // entirely. Runs the command as-is (loses PowerShell-specific
+          // syntax, but covers plain commands like npm/node/git).
+          return await execFileAsync(CMD_PATH, ["/d", "/s", "/c", command], runOpts);
+        }
+      }
+    }
+  }
+
+  try {
+    // On Windows, spawn powershell.exe directly as the target process
+    // (not via exec's "shell" option) — this is what makes windowsHide
+    // actually suppress the console window. Using exec's shell option
+    // with a custom shell path leaves windowsHide ineffective on Windows,
+    // which was popping up (and auto-closing) a visible terminal window
+    // on every single tool call.
+    const { stdout, stderr } = IS_WINDOWS ? await runOnWindows() : await execAsync(command, runOpts);
+
+    return {
+      command,
+      cwd,
+      stdout: truncate(stdout),
+      stderr: truncate(stderr),
+      exit_code: 0,
+      risk: riskInfo,
+    };
+  } catch (err) {
+    // exec/execFile reject on non-zero exit code — surface it as data, not
+    // a hard throw, so the caller can see stdout/stderr even on failure.
+    return {
+      command,
+      cwd,
+      stdout: truncate(err.stdout || ""),
+      stderr: truncate(err.stderr || err.message),
+      exit_code: err.code ?? 1,
+      timed_out: err.killed && err.signal === "SIGTERM",
+      risk: riskInfo,
+    };
+  }
+}

package/tools/dbOps.js

@@ -0,0 +1,117 @@
+import pg from "pg";
+import mysql from "mysql2/promise";
+
+const { Pool: PgPool } = pg;
+
+// Connection pools cached by connection_string so repeated calls reuse them.
+const pgPools = new Map();
+const mysqlPools = new Map();
+
+function getPgPool(connection_string) {
+  if (!pgPools.has(connection_string)) {
+    pgPools.set(connection_string, new PgPool({ connectionString: connection_string, max: 5 }));
+  }
+  return pgPools.get(connection_string);
+}
+
+function getMysqlPool(connection_string) {
+  if (!mysqlPools.has(connection_string)) {
+    mysqlPools.set(connection_string, mysql.createPool(connection_string));
+  }
+  return mysqlPools.get(connection_string);
+}
+
+function requireConnString(connection_string) {
+  if (!connection_string) {
+    throw new Error(
+      "connection_string is required, e.g. postgres://user:pass@host:5432/dbname or mysql://user:pass@host:3306/dbname"
+    );
+  }
+}
+
+// ---------- Postgres ----------
+
+/** Run a read or write SQL query against a Postgres database. */
+export async function postgresQuery({ connection_string, sql, params }) {
+  requireConnString(connection_string);
+  const pool = getPgPool(connection_string);
+  const result = await pool.query(sql, params || []);
+  return {
+    rows: result.rows,
+    row_count: result.rowCount,
+    fields: result.fields?.map((f) => f.name),
+  };
+}
+
+/** List all tables in a Postgres database (public schema by default). */
+export async function postgresListTables({ connection_string, schema = "public" }) {
+  requireConnString(connection_string);
+  const pool = getPgPool(connection_string);
+  const result = await pool.query(
+    `SELECT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name`,
+    [schema]
+  );
+  return { tables: result.rows.map((r) => r.table_name) };
+}
+
+/** Get column names, types, and nullability for a Postgres table. */
+export async function postgresDescribeTable({ connection_string, table, schema = "public" }) {
+  requireConnString(connection_string);
+  const pool = getPgPool(connection_string);
+  const result = await pool.query(
+    `SELECT column_name, data_type, is_nullable, column_default
+     FROM information_schema.columns
+     WHERE table_schema = $1 AND table_name = $2
+     ORDER BY ordinal_position`,
+    [schema, table]
+  );
+  return { columns: result.rows };
+}
+
+/** Test a Postgres connection string — returns server version on success. */
+export async function postgresTestConnection({ connection_string }) {
+  requireConnString(connection_string);
+  const pool = getPgPool(connection_string);
+  const result = await pool.query("SELECT version()");
+  return { connected: true, version: result.rows[0].version };
+}
+
+// ---------- MySQL ----------
+
+/** Run a read or write SQL query against a MySQL database. */
+export async function mysqlQuery({ connection_string, sql, params }) {
+  requireConnString(connection_string);
+  const pool = getMysqlPool(connection_string);
+  const [rows, fields] = await pool.query(sql, params || []);
+  return {
+    rows: Array.isArray(rows) ? rows : [],
+    affected_rows: rows?.affectedRows,
+    insert_id: rows?.insertId,
+    fields: fields?.map((f) => f.name),
+  };
+}
+
+/** List all tables in a MySQL database. */
+export async function mysqlListTables({ connection_string }) {
+  requireConnString(connection_string);
+  const pool = getMysqlPool(connection_string);
+  const [rows] = await pool.query("SHOW TABLES");
+  const tables = rows.map((r) => Object.values(r)[0]);
+  return { tables };
+}
+
+/** Get column names, types, and nullability for a MySQL table. */
+export async function mysqlDescribeTable({ connection_string, table }) {
+  requireConnString(connection_string);
+  const pool = getMysqlPool(connection_string);
+  const [rows] = await pool.query(`DESCRIBE \`${table}\``);
+  return { columns: rows };
+}
+
+/** Test a MySQL connection string — returns server version on success. */
+export async function mysqlTestConnection({ connection_string }) {
+  requireConnString(connection_string);
+  const pool = getMysqlPool(connection_string);
+  const [rows] = await pool.query("SELECT VERSION() as version");
+  return { connected: true, version: rows[0].version };
+}

package/tools/directoryOps.js

@@ -0,0 +1,96 @@
+import fs from "fs/promises";
+import path from "path";
+import { isPathDenied } from "./security.js";
+
+function assertPathAllowed(targetPath) {
+  const check = isPathDenied(targetPath);
+  if (check.denied) throw new Error(check.reason);
+}
+
+/** List immediate contents (files + folders) of a directory. */
+export async function listDirectory({ path: dirPath }) {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  return {
+    path: dirPath,
+    entries: entries.map((e) => ({
+      name: e.name,
+      type: e.isDirectory() ? "directory" : "file",
+    })),
+  };
+}
+
+/** Recursively build a tree view of a directory, up to max_depth. */
+export async function directoryTree({ path: dirPath, max_depth = 5, _currentDepth = 0 }) {
+  if (_currentDepth >= max_depth) {
+    return { name: path.basename(dirPath), type: "directory", truncated: true };
+  }
+
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const children = [];
+
+  for (const entry of entries) {
+    // Skip common noise directories.
+    if (entry.name === "node_modules" || entry.name === ".git") continue;
+
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      children.push(
+        await directoryTree({ path: fullPath, max_depth, _currentDepth: _currentDepth + 1 })
+      );
+    } else {
+      children.push({ name: entry.name, type: "file" });
+    }
+  }
+
+  return { name: path.basename(dirPath), type: "directory", children };
+}
+
+/** Create a new directory (and any missing parents). */
+export async function createDirectory({ path: dirPath }) {
+  assertPathAllowed(dirPath);
+  await fs.mkdir(dirPath, { recursive: true });
+  return { path: dirPath, created: true };
+}
+
+/** Delete a directory. Recursive by default so nested folders can be removed. */
+export async function deleteDirectory({ path: dirPath, recursive = true }) {
+  assertPathAllowed(dirPath);
+  await fs.rm(dirPath, { recursive, force: false });
+  return { path: dirPath, deleted: true };
+}
+
+/**
+ * Search for files/folders by name pattern (case-insensitive substring
+ * match) starting from a root directory.
+ */
+export async function searchFiles({ root_path, pattern, max_results = 100 }) {
+  const results = [];
+  const lowerPattern = pattern.toLowerCase();
+
+  async function walk(currentPath) {
+    if (results.length >= max_results) return;
+
+    let entries;
+    try {
+      entries = await fs.readdir(currentPath, { withFileTypes: true });
+    } catch {
+      return; // permission denied or path vanished — skip silently
+    }
+
+    for (const entry of entries) {
+      if (results.length >= max_results) return;
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+
+      const fullPath = path.join(currentPath, entry.name);
+      if (entry.name.toLowerCase().includes(lowerPattern)) {
+        results.push({ path: fullPath, type: entry.isDirectory() ? "directory" : "file" });
+      }
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      }
+    }
+  }
+
+  await walk(root_path);
+  return { root_path, pattern, matches: results, truncated: results.length >= max_results };
+}