@deepsql/mcp 0.10.2 → 0.13.0

package/deepsql-phase1-lib.js

@@ -168,8 +168,14 @@ const TOOL_DEFINITIONS = [
     },
   },
   {
-    name: "execute_readonly_sql",
-    description: "Execute a read-only SQL query through DeepSQL with client-side and backend safety checks.",
+    name: "execute_sql",
+    description:
+      "Execute a SQL statement through DeepSQL. Routes through the same policy "
+      + "gate as the SQL Editor: developers can run SELECT/WITH/SHOW/EXPLAIN; admins "
+      + "can additionally run DML/DDL with a two-step confirmation. Pass `confirmMutation: "
+      + "true` to confirm a mutation. EXPLAIN and EXPLAIN ANALYZE are valid SQL — just "
+      + "type them as the query, no separate mode flag needed. Multi-statement input "
+      + "and unsafe DELETE/UPDATE without WHERE are still rejected.",
     inputSchema: {
       type: "object",
       properties: {
@@ -179,19 +185,29 @@ const TOOL_DEFINITIONS = [
         },
         query: {
           type: "string",
-          description: "Read-only SQL query. Multi-statement SQL is rejected in phase 1.",
+          description:
+            "SQL to execute. Any single-statement SQL the connection's actor is "
+            + "allowed to run: SELECT/WITH/SHOW/EXPLAIN for any role, plus DML/DDL "
+            + "for admins.",
         },
         limit: {
           type: "integer",
           minimum: 1,
           maximum: 1000,
-          description: "Optional row limit override. Defaults to 100.",
+          description: "Row limit for SELECT results. Defaults to 100.",
         },
         timeoutSeconds: {
           type: "integer",
           minimum: 1,
           maximum: 60,
-          description: "Optional per-query timeout override. Defaults to backend default.",
+          description: "Per-query timeout. Defaults to the backend default.",
+        },
+        confirmMutation: {
+          type: "boolean",
+          description:
+            "Required `true` on the second call when running DML/DDL — the first "
+            + "call returns `requiresConfirmation: true` with a warnings list; "
+            + "review and re-send with confirmMutation=true to actually execute.",
         },
       },
       required: ["connectionId", "query"],
@@ -199,8 +215,14 @@ const TOOL_DEFINITIONS = [
     },
   },
   {
-    name: "explain_readonly_sql",
-    description: "Run EXPLAIN (without ANALYZE) for a read-only SQL query through DeepSQL.",
+    name: "analyze_query_plan",
+    description:
+      "Get DeepSQL's AI-enriched analysis of a query's execution plan. Returns the "
+      + "parsed plan tree, performance issues, index recommendations, and a written "
+      + "summary that takes into account the connection's schema, business rules, "
+      + "and anti-patterns. With `useAnalyze: true` the query is actually executed "
+      + "(EXPLAIN ANALYZE semantics) — mutating statements then go through the same "
+      + "admin/WHERE/confirmation gates as execute_sql.",
     inputSchema: {
       type: "object",
       properties: {
@@ -210,7 +232,21 @@ const TOOL_DEFINITIONS = [
         },
         query: {
           type: "string",
-          description: "Read-only SQL query to explain. Do not include EXPLAIN or EXPLAIN ANALYZE.",
+          description:
+            "The underlying SQL to plan. Do NOT wrap in EXPLAIN — the server does "
+            + "that based on `useAnalyze`.",
+        },
+        useAnalyze: {
+          type: "boolean",
+          description:
+            "If true, run EXPLAIN ANALYZE (actually executes the query for real "
+            + "timings). For mutating statements this requires admin role + confirm.",
+        },
+        confirmMutation: {
+          type: "boolean",
+          description:
+            "Required `true` to confirm a mutating useAnalyze=true call. Same "
+            + "two-step flow as execute_sql.",
         },
       },
       required: ["connectionId", "query"],
@@ -354,6 +390,20 @@ function buildHeaders(config, extraHeaders = {}) {
     headers.Authorization = `Bearer ${config.authToken}`;
   }
 
+  // Origin-tracking headers so the backend audit row can distinguish
+  // CLI/MCP traffic and identify which editor invoked the MCP server.
+  // `clientAgent` carries the value of DEEPSQL_MCP_USER_ID — editor configs
+  // set this to "claude-desktop", "cursor-mcp", "codex-mcp", etc.
+  if (config.clientType) {
+    headers["X-DeepSQL-Client-Type"] = config.clientType;
+  }
+  if (config.clientAgent) {
+    headers["X-DeepSQL-Client-Agent"] = config.clientAgent;
+  }
+  if (config.clientVersion) {
+    headers["X-DeepSQL-Client-Version"] = config.clientVersion;
+  }
+
   return headers;
 }
 
@@ -554,10 +604,10 @@ function buildToolResult(name, payload, extra = {}) {
     case "analyze_slow_queries":
       summary = summarizeSlowQueries(payload);
       break;
-    case "execute_readonly_sql":
+    case "execute_sql":
       summary = summarizeQueryResult(payload);
       break;
-    case "explain_readonly_sql":
+    case "analyze_query_plan":
       summary = summarizeExplain(payload);
       break;
     default:
@@ -698,42 +748,53 @@ async function handleToolCall(config, name, args = {}) {
       return buildToolResult(name, payload);
     }
 
-    case "execute_readonly_sql": {
+    case "execute_sql": {
       const connectionId = String(args.connectionId || "").trim();
-      const validation = validateReadOnlySql(args.query, { allowExplain: true });
-      if (!validation.ok) {
-        return buildToolError(validation.reason);
-      }
+      const query = String(args.query || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!query) return buildToolError("query is required.");
 
+      // Talk to the canonical Editor endpoint. Backend enforces role-based
+      // mutation policy + per-connection ACL + chat data-access policy +
+      // WHERE-clause guard + two-step confirmation, then audits the call.
+      // Client-side parser validation removed in 0.13.0 — the backend is
+      // the source of truth and was always going to be.
       const payload = await callDeepSqlApi(
         config,
-        "/mcp/query-readonly",
+        `/connections/${encodeURIComponent(connectionId)}/query`,
         {
           method: "POST",
           json: {
-            connectionId,
-            query: validation.normalizedQuery,
+            query,
             limit: clampInteger(args.limit, 1, 1000, 100),
             timeoutSeconds: clampInteger(args.timeoutSeconds, 1, 60, null),
+            mutationConfirmed: args.confirmMutation === true,
           },
         },
       );
 
+      // Surface a "requiresConfirmation" response as a non-error structured
+      // payload so the calling agent can read warnings and re-send with
+      // confirmMutation=true without parsing tool-error text.
       return buildToolResult(name, payload);
     }
 
-    case "explain_readonly_sql": {
+    case "analyze_query_plan": {
       const connectionId = String(args.connectionId || "").trim();
-      const validation = validateReadOnlySql(args.query, { allowExplain: false });
-      if (!validation.ok) {
-        return buildToolError(validation.reason);
-      }
+      const query = String(args.query || "").trim();
+      if (!connectionId) return buildToolError("connectionId is required.");
+      if (!query) return buildToolError("query is required.");
 
-      const payload = await callDeepSqlApi(config, "/mcp/explain-readonly", {
+      // Route through the canonical Editor endpoint (ExplainController).
+      // For useAnalyze=true the backend applies the same mutation policy
+      // as execute_sql before wrapping in EXPLAIN ANALYZE.
+      const payload = await callDeepSqlApi(config, "/explain/analyze", {
         method: "POST",
         json: {
           connectionId,
-          query: validation.normalizedQuery,
+          query,
+          useAnalyze: args.useAnalyze === true,
+          mutationConfirmed: args.confirmMutation === true,
         },
       });
 
@@ -749,12 +810,28 @@ function createConfigFromEnv(env = process.env) {
   const rawBaseUrl = env.DEEPSQL_API_BASE_URL || "http://localhost:8080/api/";
   const baseUrl = rawBaseUrl.endsWith("/") ? rawBaseUrl : `${rawBaseUrl}/`;
 
+  // Resolve our npm version once, lazily — `require("./package.json")`
+  // would normally pull it in, but we use a try/catch so the lib still
+  // works in test contexts where the package metadata isn't on disk.
+  let clientVersion = null;
+  try {
+    clientVersion = require("./package.json").version;
+  } catch {
+    // best-effort
+  }
+
   return {
     baseUrl,
     authToken: env.DEEPSQL_AUTH_TOKEN || "",
     timeoutMs: clampInteger(env.DEEPSQL_MCP_TIMEOUT_MS, 1000, 600000, 120000),
     defaultUserId: env.DEEPSQL_MCP_USER_ID || "mcp-phase1",
     defaultProjectId: env.DEEPSQL_MCP_PROJECT_ID || "mcp-phase1",
+    // Origin metadata for the backend audit row. The MCP server always
+    // identifies as `mcp`; the agent name comes from DEEPSQL_MCP_USER_ID
+    // which editor configs set to claude-desktop / cursor-mcp / codex-mcp.
+    clientType: "mcp",
+    clientAgent: env.DEEPSQL_MCP_USER_ID || null,
+    clientVersion,
   };
 }
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.10.2",
+  "version": "0.13.0",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
-    "deepsql": "./bin/deepsql.js",
-    "deepsql-mcp": "./deepsql-phase1-server.js"
+    "deepsql": "bin/deepsql.js",
+    "deepsql-mcp": "deepsql-phase1-server.js"
   },
   "main": "./deepsql-phase1-server.js",
   "files": [
@@ -12,6 +12,7 @@
     "CLAUDE.md",
     "AGENT-SETUP.md",
     "bin",
+    "skills",
     "src",
     "deepsql-phase1-server.js",
     "deepsql-phase1-lib.js",
@@ -19,7 +20,7 @@
     "codex_config.customer.example.toml"
   ],
   "scripts": {
-    "test": "node --test deepsql-phase1-lib.test.js src/**/*.test.js"
+    "test": "node --test deepsql-phase1-lib.test.js src/*.test.js src/**/*.test.js"
   },
   "engines": {
     "node": ">=20"

package/skills/SKILL_BODY.md

@@ -0,0 +1,125 @@
+# DeepSQL — your database DBA consult
+
+You have DeepSQL's MCP tools loaded. **DeepSQL is the source of truth for
+the live schema, business rules, FK relationships, and anti-patterns of
+the database the user is working against.** Treat it the way a thoughtful
+engineer treats a DBA: consult before you commit anything schema-shaped.
+
+This skill triggers any time the user is doing database work. The rules
+below are non-negotiable.
+
+---
+
+## Trigger checklist — before generating any DDL, migration, or non-trivial SQL
+
+The user said something like "add a table", "track this", "write a
+migration", "design a model", "query the database", or "write the SELECT
+for…". Before you generate **any** SQL or schema-shaped output, run:
+
+1. `list_connections` — get the UUID of the connection the user means
+   (don't pass connection names anywhere; tools take UUIDs).
+
+2. `get_brain_context(connectionId, "<one-line description of the feature/question>")`
+   — surfaces the tables, columns, FKs, training docs, and business rules
+   most relevant to the work at hand. **Read the results, don't just
+   regurgitate them.**
+
+3. `get_schema(connectionId)` if you need a full column inventory for any
+   table `get_brain_context` surfaced. Don't infer column types from
+   variable names in the codebase — they drift.
+
+4. `list_business_rules(connectionId, question="<feature>")` — rules the
+   feature MUST respect. If `always_filter_cancelled` is on, your
+   aggregate views inherit that filter from day one. Apply these silently;
+   don't ask the user permission to follow their own rules.
+
+5. `get_relationships(connectionId)` if you're declaring a foreign key —
+   the brain may already infer it with a confidence score, and the FK
+   naming convention this team uses lives here.
+
+6. `get_anti_patterns(connectionId, kind="table")` if you're committing a
+   schema shape — the brain has flagged patterns to avoid in this
+   specific database.
+
+## Then narrate what you found before proposing schema
+
+Don't jump straight to `CREATE TABLE …`. Tell the user what DeepSQL said:
+
+> "DeepSQL says you already have a `customers` table with `email`,
+> `tenant_id`, `created_at`, plus an inferred FK to
+> `accounts.customer_id` at 0.94 confidence. The business rule
+> `always_filter_cancelled` is on `customers.status`. The anti-pattern
+> report flagged 'wide-table' on `customer_profiles` — adding more
+> columns there is discouraged.
+>
+> **I'd extend `customers` with the two new fields you need rather
+> than add a `users` table. Want me to draft the migration?**"
+
+That narration is the difference between an agent that ships features fast
+and an agent that earns the team's trust. **Make it a reflex.**
+
+If the consult tells you to stop — there's already a table that does what
+the user asked for, or the shape they want is on the anti-pattern list —
+**say so**. Push back politely and propose the better path. The user
+usually doesn't know about either; that's exactly why DeepSQL exists.
+
+---
+
+## Running SQL
+
+| You want to… | Use this tool |
+|---|---|
+| Run any SQL (SELECT / EXPLAIN / DML / DDL) | `execute_sql(connectionId, query, ...)` |
+| Get AI-enriched plan analysis for a query | `analyze_query_plan(connectionId, query, useAnalyze=false)` |
+| Actually execute the query AND get the plan (real timings) | `analyze_query_plan(..., useAnalyze=true)` |
+
+`EXPLAIN` and `EXPLAIN ANALYZE` are just SQL — type them as the query if
+you want raw plan output. Use `analyze_query_plan` when you want the
+AI-enriched analysis (issues, index recommendations, written summary).
+
+### Mutations are role-gated and two-step
+
+`execute_sql` enforces the same policy as the SQL Editor:
+
+- **Developer + SELECT/WITH/SHOW/EXPLAIN** → runs immediately.
+- **Developer + DML/DDL** → 403 `EDITOR_MUTATION_FORBIDDEN`. Don't retry.
+  Tell the user: "Your DeepSQL role doesn't allow DML/DDL on this
+  connection; ask the workspace admin to grant write access or to run the
+  change."
+- **Admin + DML/DDL (no `confirmMutation`)** → returns
+  `requiresConfirmation: true` with a `warnings` array. **Show the
+  warnings to the user verbatim. Wait for explicit OK.** Then re-call
+  with `confirmMutation: true`. **Do not silently retry with
+  `confirmMutation: true` on the user's behalf** — that defeats the
+  confirmation step.
+
+### Row limits
+
+`execute_sql` defaults to 100 rows, max 1000. If you asked for "all
+customers" and got 100, that's the limit kicking in — not the real count.
+Either bump `limit` or `SELECT COUNT(*)` first.
+
+---
+
+## Every call is audited
+
+Every tool call you make is logged to the DeepSQL `security_events` table
+with the user's identity, the editor that invoked the MCP server
+(claude-desktop, cursor-mcp, codex-mcp), the connection, the truncated
+statement, and the outcome. Workspace admins can search this. Don't do
+anything through these tools you wouldn't be willing to defend in that
+view.
+
+---
+
+## Full reference
+
+The complete runtime guide — every decision-tree branch, every foot-gun,
+all three session playbooks (answer-a-question, mutation, DBA-consult) —
+lives in `node_modules/@deepsql/mcp/CLAUDE.md`. Read it the first time
+you handle a non-trivial database request.
+
+Capabilities that aren't MCP-exposed yet (index recommendations, daily
+digest, slow-query streaming optimization) live in the CLI: `deepsql
+indexes`, `deepsql digest`, `deepsql slow-queries optimize`. Point the
+user at them.

package/src/api/client.js

@@ -19,6 +19,27 @@ class ApiError extends Error {
   }
 }
 
+/**
+ * Module-level "who is talking to the backend" record. The CLI's entry
+ * point calls setClientContext() once at startup, then every request()
+ * call below stamps X-DeepSQL-Client-{Type,Agent,Version} headers without
+ * each command needing to thread that information through.
+ *
+ *   type    "cli" by default for everything that goes through this module
+ *   agent   "terminal", or the value of --caller-agent / DEEPSQL_CALLER_AGENT
+ *           (set by agents like claude-code when they shell out to `deepsql`)
+ *   version the npm package version, so backend audit shows which CLI build
+ */
+let currentClient = null;
+
+function setClientContext(client) {
+  currentClient = client ? { ...client } : null;
+}
+
+function getClientContext() {
+  return currentClient;
+}
+
 function normalizeBaseUrl(url) {
   if (!url) throw new ApiError("No DeepSQL URL configured. Run `deepsql login --url <url>` first.");
   return url.endsWith("/") ? url : `${url}/`;
@@ -54,6 +75,11 @@ async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, toke
   };
   if (token) requestHeaders.Authorization = `Bearer ${token}`;
   if (json != null) requestHeaders["Content-Type"] = "application/json";
+  if (currentClient) {
+    if (currentClient.type) requestHeaders["X-DeepSQL-Client-Type"] = currentClient.type;
+    if (currentClient.agent) requestHeaders["X-DeepSQL-Client-Agent"] = currentClient.agent;
+    if (currentClient.version) requestHeaders["X-DeepSQL-Client-Version"] = currentClient.version;
+  }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -114,4 +140,12 @@ function parseCookieValue(setCookies, name) {
   return null;
 }
 
-module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl, parseCookieValue };
+module.exports = {
+  ApiError,
+  request,
+  resolveUrl,
+  normalizeBaseUrl,
+  parseCookieValue,
+  setClientContext,
+  getClientContext,
+};

package/src/cli.js

@@ -21,7 +21,8 @@ const COMMANDS = {
   mcp: () => require("./commands/mcp"),
   connections: () => require("./commands/connections"),
   query: () => require("./commands/query"),
-  explain: () => require("./commands/explain"),
+  analyze: () => require("./commands/analyze"),
+  explain: () => require("./commands/explain"), // deprecated alias for `analyze`, removed in 0.14.0
   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.
@@ -30,6 +31,7 @@ const COMMANDS = {
   relationships: () => require("./commands/relationships"),
   "anti-patterns": () => require("./commands/anti-patterns"),
   digest: () => require("./commands/digest"),
+  indexes: () => require("./commands/indexes"),
   users: () => require("./commands/users"),
   access: () => require("./commands/access"),
   permissions: () => require("./commands/permissions"),
@@ -47,16 +49,17 @@ const COMMAND_LIST = [
   ["logout",         false, "Revoke and forget the saved token"],
   ["whoami",         false, "Show the user behind the saved token"],
   ["config",         true,  "Manage saved CLI profiles"],
-  ["mcp",            false, "Run the stdio MCP server using the saved token"],
+  ["mcp",            true,  "Run the MCP server or install it into an editor config"],
   ["connections",    true,  "Manage database connections"],
-  ["query",          false, "Run a read-only SQL statement"],
-  ["explain",        false, "Get an EXPLAIN plan (no ANALYZE)"],
+  ["query",          false, "Execute a SQL statement (admin: DDL/DML with --write)"],
+  ["analyze",        false, "AI-enriched query plan analysis (use --analyze for EXPLAIN ANALYZE)"],
   ["schema",         false, "Dump connection schema or DB objects as JSON"],
   ["digest",         true,  "Show DeepSQL daily digests"],
   ["brain-context",  false, "Retrieve embedding-ranked context for a question"],
   ["business-rules", false, "List active business rules and SQL guardrails"],
   ["relationships",  false, "List inferred and validated FK relationships"],
   ["anti-patterns",  false, "List schema- or query-level anti-patterns"],
+  ["indexes",        true,  "Index suggestions, usage, and health (read-only)"],
   ["users",          true,  "Manage workspace users (admin)"],
   ["access",         true,  "Manage per-connection access grants (admin)"],
   ["permissions",    true,  "Manage role-based permission overrides (admin)"],
@@ -65,12 +68,13 @@ const COMMAND_LIST = [
 ];
 
 const GLOBAL_OPTIONS = [
-  ["--url <url>",         "Override the DeepSQL base URL"],
-  ["--token <tok>",       "Override the auth token (also: DEEPSQL_AUTH_TOKEN)"],
-  ["--connection <name>", "Override the active connection (also: DEEPSQL_CONNECTION)"],
-  ["--no-color",          "Disable ANSI colors"],
-  ["-h, --help",          "Display help for command"],
-  ["-v, --version",       "Show version"],
+  ["--url <url>",          "Override the DeepSQL base URL"],
+  ["--token <tok>",        "Override the auth token (also: DEEPSQL_AUTH_TOKEN)"],
+  ["--connection <name>",  "Override the active connection (also: DEEPSQL_CONNECTION)"],
+  ["--caller-agent <id>",  "Identify the calling agent in audit logs (also: DEEPSQL_CALLER_AGENT)"],
+  ["--no-color",           "Disable ANSI colors"],
+  ["-h, --help",           "Display help for command"],
+  ["-v, --version",        "Show version"],
 ];
 
 // ─── Per-command help blocks ────────────────────────────────────────────────
@@ -110,9 +114,23 @@ const COMMAND_HELP = {
   },
 
   mcp: {
-    description: "Run the stdio MCP server using the saved token.",
-    usage: "deepsql mcp [--url <url>]",
-    notes: "Used by editor MCP configs (Cursor, Claude Desktop) so the config never has to embed a raw token.",
+    description: "Run the stdio MCP server, or install DeepSQL into an editor's MCP config (+ the DBA-consult skill).",
+    usage: "deepsql mcp [--url <url>]\n       deepsql mcp config (--install | --print) --for <editor> [--force] [--no-skill] [--path <p>]",
+    subcommands: [
+      ["(no args)",                                    "Run the stdio MCP server with the saved token"],
+      ["config --install --for <editor>",              "Write a DeepSQL entry into the editor's MCP config AND install the DBA-consult skill (backs up on overwrite)"],
+      ["config --print --for <editor>",                "Print the snippets (config + skill) without touching disk"],
+    ],
+    options: [
+      ["--for <editor>",   "claude-code, claude-desktop, cursor, or codex"],
+      ["--install",        "Write the entry to the editor's default config path AND install the skill"],
+      ["--print",          "Emit the snippets only (no filesystem writes)"],
+      ["--force",          "Overwrite an existing DeepSQL entry/skill"],
+      ["--no-skill",       "Skip the DBA-consult skill install (MCP server config only)"],
+      ["--path <p>",       "Override the default MCP config path (advanced; doesn't affect the skill path)"],
+      ["--url <url>",      "Profile to bind the spawned MCP server to"],
+    ],
+    notes: "The installed entry runs `deepsql mcp`, which uses the saved profile — no token is embedded in the editor config. The skill teaches the agent to consult DeepSQL BEFORE generating DDL or non-trivial SQL.",
   },
 
   config: {
@@ -156,25 +174,30 @@ const COMMAND_HELP = {
   },
 
   query: {
-    description: "Run a read-only SQL statement (parser-enforced, ACL-checked).",
+    description: "Execute a SQL statement against a connection. Same policy gate as the web SQL Editor: developers can run SELECT/WITH/SHOW/EXPLAIN; admins can additionally run DML/DDL with a two-step confirm.",
     usage: 'deepsql query "<sql>" --connection <name> [options]',
     options: [
       ["--connection <name>",    "Connection to run against"],
       ["--limit <n>",            "Row limit (1–1000, default 100)"],
       ["--timeout-seconds <n>",  "Statement timeout in seconds (1–60)"],
       ["--file <path>",          "Read SQL from a file instead of argv"],
+      ["--write",                "Confirm a mutation upfront (skips interactive prompt; scripts/CI)"],
       ["--json",                 "Raw JSON output"],
     ],
+    notes: "EXPLAIN and EXPLAIN ANALYZE are valid SQL — type them directly. For the AI-enriched plan analysis, use `deepsql analyze`.",
   },
 
-  explain: {
-    description: "Get an EXPLAIN plan (no ANALYZE — read-only enforced).",
-    usage: 'deepsql explain "<sql>" --connection <name> [options]',
+  analyze: {
+    description: "AI-enriched query plan analysis. Returns the parsed plan tree, performance issues, index recommendations, and a written summary that takes the connection's schema and business rules into account.",
+    usage: 'deepsql analyze "<sql>" --connection <name> [options]',
     options: [
-      ["--connection <name>", "Connection to run against"],
-      ["--file <path>",       "Read SQL from a file instead of argv"],
-      ["--json",              "Raw JSON output"],
+      ["--connection <name>",    "Connection to run against"],
+      ["--analyze",              "Use EXPLAIN ANALYZE (actually executes the query)"],
+      ["--write",                "Confirm an ANALYZE-of-mutation upfront (skips interactive prompt)"],
+      ["--file <path>",          "Read SQL from a file instead of argv"],
+      ["--json",                 "Raw JSON output"],
     ],
+    notes: "Pass the underlying SQL, not `EXPLAIN <sql>` — the server wraps it. With --analyze on a mutation, the same admin role + WHERE + confirmation gates as `query` apply.",
   },
 
   schema: {
@@ -241,6 +264,26 @@ const COMMAND_HELP = {
     ],
   },
 
+  indexes: {
+    description: "Index suggestions, usage, and health — read-only in V1.",
+    usage: "deepsql indexes <subcommand> [options]",
+    subcommands: [
+      ["list [--all] [--status <s>]", "Index recommendations (defaults to PENDING)"],
+      ["missing",                     "Missing-index suggestions from the advisor"],
+      ["health",                      "Comprehensive index health report"],
+      ["unused",                      "Indexes the engine has not used"],
+      ["duplicates",                  "Duplicate or redundant indexes"],
+      ["usage <table>",               "Per-table index usage statistics"],
+    ],
+    options: [
+      ["--connection <name>",            "Connection to inspect"],
+      ["--all",                          "Include APPLIED and DISMISSED in `list`"],
+      ["--status PENDING|APPLIED|DISMISSED", "Filter `list` by status"],
+      ["--json",                         "Raw JSON output"],
+    ],
+    notes: "V1 is read-only. Apply, dismiss, delete, and generate are not exposed by the CLI yet.",
+  },
+
   users: {
     description: "Manage workspace users (admin).",
     usage: "deepsql users <subcommand> [options]",
@@ -500,6 +543,20 @@ function buildOpts(parsed) {
     queryText: f.queryText || null,
     sampleQuery: f.sampleQuery || null,
     historyId: f.historyId || null,
+    // Indexes
+    all: !!f.all,
+    status: f.status || null,
+    // mcp config installer
+    install: !!f.install,
+    print: !!f.print,
+    for: f.for || null,
+    path: f.path || null,
+    noSkill: !!f.noSkill,
+    // SQL execution
+    write: !!f.write,
+    analyze: !!f.analyze,
+    // Origin tagging for audit
+    callerAgent: f.callerAgent || null,
     // Setup wizard
     force: !!f.force,
     skipEmail: !!f.skipEmail,
@@ -557,6 +614,19 @@ async function main(rawArgv = process.argv.slice(2), io = {}) {
   const parsed = parseArgs(restArgs);
   const opts = buildOpts(parsed);
 
+  // Stamp origin headers on every backend request the command will make.
+  // `clientType` is fixed for CLI traffic; `clientAgent` defaults to
+  // "terminal" but agents that shell out can override via --caller-agent or
+  // the DEEPSQL_CALLER_AGENT env var, so audit rows distinguish "human in a
+  // terminal" from "Claude Code invoked deepsql query."
+  const { setClientContext } = require("./api/client");
+  const pkg = require("../package.json");
+  setClientContext({
+    type: "cli",
+    agent: opts.callerAgent || process.env.DEEPSQL_CALLER_AGENT || "terminal",
+    version: pkg.version,
+  });
+
   try {
     const mod = loader();
     await mod.run(opts, { stdout, stderr });

package/src/cli.test.js

@@ -73,8 +73,8 @@ test("every command in the catalog has a COMMAND_HELP entry", () => {
   const { main: _main } = require("./cli");
   void _main;
   const expected = [
-    "login","logout","whoami","config","mcp","connections","query","explain","schema",
-    "digest","brain-context","business-rules","relationships","anti-patterns",
+    "login","logout","whoami","config","mcp","connections","query","analyze","schema",
+    "digest","brain-context","business-rules","relationships","anti-patterns","indexes",
     "users","access","permissions","slow-queries","setup",
   ];
   for (const name of expected) {