@deepsql/mcp 0.13.0 → 0.14.0

package/skills/SKILL_BODY.md

@@ -1,12 +1,22 @@
 # 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.
+You have two DeepSQL surfaces available:
 
-This skill triggers any time the user is doing database work. The rules
-below are non-negotiable.
+1. **MCP tools** — JSON-RPC tools loaded into your session (10 of them).
+   Use these for in-session retrieval and SQL execution.
+
+2. **`deepsql` CLI** — a shell binary on the user's PATH (~19 commands).
+   Use this for things the MCP doesn't expose (index health, daily
+   digest, slow-query streaming, connection management, admin ops, the
+   plan-analysis `analyze` command, etc.). You can shell out to the CLI
+   yourself when appropriate; you can also point the user at the
+   command if it's interactive.
+
+**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.
 
 ---
 
@@ -65,21 +75,115 @@ usually doesn't know about either; that's exactly why DeepSQL exists.
 
 ---
 
-## Running SQL
+## MCP tools — your in-session toolkit
 
-| You want to… | Use this tool |
+| Tool | When to call |
 |---|---|
-| 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)` |
+| `list_connections` | Always first; get the UUID. |
+| `get_brain_context(connectionId, question)` | Step 2 of the checklist above. The most important tool. |
+| `get_schema(connectionId)` | Full column inventory for the tables you're touching. |
+| `get_database_objects(connectionId)` | Tables/views/functions/procedures (broader than schema). |
+| `list_business_rules(connectionId, question?)` | Rules the SQL must respect. |
+| `get_relationships(connectionId)` | Foreign keys (declared + inferred-with-confidence). |
+| `get_anti_patterns(connectionId, kind="table"\|"query")` | Patterns to avoid in this DB. |
+| `analyze_slow_queries(connectionId, thresholdMs?, limit?)` | Snapshot of slow queries from live stats. |
+| `execute_sql(connectionId, query, ...)` | Run any SQL — SELECT for everyone, DML/DDL for admins (two-step confirm). |
+| `analyze_query_plan(connectionId, query, useAnalyze=false)` | AI-enriched plan analysis (issues + index recs + summary). |
 
 `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).
+AI-enriched analysis.
 
-### Mutations are role-gated and two-step
+---
 
-`execute_sql` enforces the same policy as the SQL Editor:
+## `deepsql` CLI — for everything the MCP doesn't expose
+
+The CLI is the user's primary interface to DeepSQL. As a coding agent,
+**you can shell out to it** to do things the MCP doesn't have, or to
+help the user when interactive setup is required (login, MCP install,
+new connection registration). Always pass `--caller-agent <your-name>`
+on shell-outs so the audit log captures the chain ("deepsql query
+called by claude-code via deepsql CLI").
+
+```bash
+deepsql query "SELECT 1" --connection prod-pg --caller-agent claude-code --json
+```
+
+### Command catalog (19 top-level commands)
+
+| Command | What it does | MCP equivalent? |
+|---|---|---|
+| `deepsql login` | Authorize CLI against a DeepSQL host (browser PKCE / device code / password) | none — interactive only |
+| `deepsql logout` | Revoke the saved token | none |
+| `deepsql whoami` | Show the logged-in user, role, URL, pinned connection | none |
+| `deepsql config show\|set-default <url>\|path` | Manage saved profiles | none |
+| `deepsql mcp` | Run the stdio MCP server | this skill spawns it |
+| `deepsql mcp config --install --for <editor>` | Install MCP entry + this skill into editor config | none — interactive |
+| `deepsql connections list\|use\|current\|unset\|schema\|add\|update\|remove\|test\|show\|init` | Full connection CRUD | partial: `list_connections`, `get_schema` |
+| `deepsql query "<sql>" --connection <c>` | Execute SQL (admin: `--write` for mutations) | `execute_sql` |
+| `deepsql analyze "<sql>" --connection <c>` | AI plan analysis (`--analyze` for EXPLAIN ANALYZE) | `analyze_query_plan` |
+| `deepsql schema [tables\|objects] --connection <c>` | Dump full schema as JSON | `get_schema` / `get_database_objects` |
+| `deepsql brain-context "<question>" --connection <c>` | Same retrieval as the MCP tool | `get_brain_context` |
+| `deepsql business-rules --connection <c>` | List active business rules | `list_business_rules` |
+| `deepsql relationships --connection <c>` | Inferred + validated FKs | `get_relationships` |
+| `deepsql anti-patterns --connection <c> [--kind table\|query]` | Anti-patterns | `get_anti_patterns` |
+| `deepsql digest [N]\|list\|show <id>` | **CLI-only**: daily digest of slow queries + AI commentary | none |
+| `deepsql indexes list\|missing\|health\|unused\|duplicates\|usage <table>` | **CLI-only**: index recommendations and usage stats | none |
+| `deepsql slow-queries latest\|history\|analyze\|optimize\|delete` | Slow-query analyses; `optimize` streams AI optimization steps live (SSE) | partial: `analyze_slow_queries` |
+| `deepsql users list\|get\|add\|set-role\|lock\|unlock\|disable\|resend-invite\|reset-password\|delete` | **Admin-only, CLI-only**: workspace user management | none |
+| `deepsql access list\|grant\|revoke\|policy <user> <conn>` | **Admin-only, CLI-only**: per-connection access grants + chat policy editing in $EDITOR | none |
+| `deepsql permissions list\|override\|reset` | **Admin-only, CLI-only**: role-based permission overrides | none |
+| `deepsql setup` | **Admin-only**: post-install wizard for SMTP/email + Slack | none |
+
+Run `deepsql <command> --help` for option-level detail. Run
+`deepsql --help` for the live catalog (the CLI is the source of truth
+if this table goes stale).
+
+### CLI-only capabilities — point the user at these or run them
+
+When the user asks for something only the CLI does, either run it via
+shell-out (with `--caller-agent`) or tell the user the exact command:
+
+| User asks for | Run / suggest |
+|---|---|
+| "What changed in the database recently?" / "Today's report" | `deepsql digest` (most recent) or `deepsql digest 7` (last week) |
+| "What indexes are we missing?" / "Index advice" | `deepsql indexes missing --connection <c>` |
+| "Are any indexes unused?" / "Index bloat" | `deepsql indexes unused --connection <c>` |
+| "Duplicate indexes?" | `deepsql indexes duplicates --connection <c>` |
+| "Index health on this connection" | `deepsql indexes health --connection <c>` |
+| "Indexes on `<table>` and how often they're used" | `deepsql indexes usage <table> --connection <c>` |
+| "Optimize this slow query with AI" / "Stream me a fix" | `deepsql slow-queries optimize --connection <c> --query-id <id>` |
+| "Add a new database connection" | `deepsql connections add` (interactive) or `--from-file <path>` |
+| "Test a connection without saving" | `deepsql connections test --from-file <path>` |
+| "Trigger brain re-initialization for this connection" | `deepsql connections init <name> --wait` |
+| "Add a user / change a user's role" | `deepsql users add` / `deepsql users set-role <ref> <role>` |
+| "Grant / revoke connection access" | `deepsql access grant --user <ref> --connection <c> --level read\|write\|admin` |
+| "Edit the chat data-access policy for `<user>` on `<conn>`" | `deepsql access policy <user> <conn>` (opens `$EDITOR`) |
+
+### Shelling out from the agent — the convention
+
+When you run `deepsql` yourself:
+
+```bash
+deepsql <command> [options] --caller-agent <your-agent-id> --json
+```
+
+- **Always pass `--caller-agent`** (or set `DEEPSQL_CALLER_AGENT` env
+  var once) so the audit row captures the chain. Use a stable id like
+  `claude-code`, `cursor`, or `codex`.
+- **Prefer `--json`** for parseable output. Without it, output is
+  pretty-printed for humans and harder to parse.
+- **Don't chain destructive ops without confirmation.** `deepsql
+  connections remove`, `deepsql users delete`, `deepsql permissions
+  override --revoke`, etc. all support `--yes` to skip the prompt — but
+  YOU should not pass `--yes` unless the user has explicitly approved
+  the specific action.
+
+---
+
+## Mutations are role-gated and two-step (both MCP and CLI)
+
+`execute_sql` (MCP) and `deepsql query` (CLI) enforce the same policy:
 
 - **Developer + SELECT/WITH/SHOW/EXPLAIN** → runs immediately.
 - **Developer + DML/DDL** → 403 `EDITOR_MUTATION_FORBIDDEN`. Don't retry.
@@ -89,26 +193,51 @@ AI-enriched analysis (issues, index recommendations, written summary).
 - **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
+  with `confirmMutation: true` (MCP) or `--write` (CLI). **Do not
+  silently retry on the user's behalf** — that defeats the
   confirmation step.
 
-### Row limits
+## Row limits
+
+`execute_sql` / `deepsql query` 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`/`limit:` or `SELECT COUNT(*)`
+first.
 
-`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.
+---
+
+## Helping the user when DeepSQL itself isn't set up
+
+The user might not have DeepSQL fully wired up when they ask their
+first database question. If you get a clear "not configured" error,
+run / suggest these:
+
+| Symptom | Fix |
+|---|---|
+| `deepsql --version` not found / not on PATH | `npm install -g @deepsql/mcp@latest` (Node ≥ 20). |
+| MCP tools missing from your session | Run `deepsql mcp config --install --for claude-code` (or `cursor`/`codex`/`claude-desktop`) on the user's machine. They restart the editor. |
+| CLI says "No saved DeepSQL profile" | `deepsql login --url https://<their-deepsql-host>` (browser flow on desktop, `--device` for SSH boxes). |
+| MCP tools error with 401 | Token expired. `deepsql logout && deepsql login --url <host>` then restart the editor. |
+| `connections list` is empty | Walk the user through `deepsql connections add` interactively, or use `--from-file <path>` with a JSON config file. |
+| `connections test` reports "Missing privileges: SELECT, ..." | The DB user has insufficient grants. The connection saves anyway (read access is enough for some features), but flag it. |
+| Connection config schema | `deepsql connections schema --json` (JSON Schema for the input format). |
 
 ---
 
-## Every call is audited
+## Every call is audited (both surfaces)
 
-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.
+Every MCP tool call AND every `deepsql` CLI invocation that hits the
+backend is logged to the DeepSQL `security_events` table with:
+
+- the user's identity (from the bearer token or saved profile)
+- the editor / agent that originated the request (`claude-code`,
+  `cursor`, `codex`, etc. — from the `--caller-agent` flag or
+  `DEEPSQL_MCP_USER_ID` env var)
+- the surface (`mcp` vs `cli`)
+- 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.
 
 ---
 
@@ -116,10 +245,17 @@ view.
 
 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.
+lives in the package's `CLAUDE.md`. After install:
+
+```
+node_modules/@deepsql/mcp/CLAUDE.md       # local install
+$(npm root -g)/@deepsql/mcp/CLAUDE.md     # global install
+```
+
+The CLI is its own source of truth too — if this table drifts from
+reality, run:
 
-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.
+```bash
+deepsql --help                            # live command list
+deepsql <command> --help                  # full options for one command
+```

package/src/cli.js

@@ -36,6 +36,7 @@ const COMMANDS = {
   access: () => require("./commands/access"),
   permissions: () => require("./commands/permissions"),
   "slow-queries": () => require("./commands/slow-queries"),
+  "index-recommendations": () => require("./commands/index-recommendations"),
   setup: () => require("./commands/setup"),
 };
 
@@ -60,6 +61,7 @@ const COMMAND_LIST = [
   ["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)"],
+  ["index-recommendations", true, "Workload-weighted index advisor + HypoPG-validated apply tool"],
   ["users",          true,  "Manage workspace users (admin)"],
   ["access",         true,  "Manage per-connection access grants (admin)"],
   ["permissions",    true,  "Manage role-based permission overrides (admin)"],
@@ -360,6 +362,34 @@ const COMMAND_HELP = {
     ],
     notes: "Org and LLM config are set at install time and are NOT touched by this wizard.",
   },
+
+  "index-recommendations": {
+    description:
+      "DBA-grade workload-weighted index advisor. Default `top` shows pending " +
+      "recommendations ranked by net benefit (workload − write-cost). `apply` " +
+      "is the only mutation — dry-run uses HypoPG (Postgres-only) so no writes " +
+      "leak; the two write modes require --confirm.",
+    usage:
+      "deepsql index-recommendations <top|list|show|refresh|apply|dismiss> [options]",
+    subcommands: [
+      ["top    --connection <name> [--limit N]",     "Pre-computed top-N (default 5, max 50), evidence-bearing"],
+      ["list   --connection <name>",                  "All pending recommendations for the connection"],
+      ["show   <id> --connection <name>",             "Full detail: workload, HypoPG cost, contributing queries"],
+      ["refresh --connection <name>",                 "Force a fresh accumulation cycle (POST /generate)"],
+      ["apply  <id> [--mode <m>] [--confirm]",        "Run / dry-run with before/after measurement"],
+      ["dismiss <id>",                                 "Mark a recommendation as DISMISSED"],
+    ],
+    options: [
+      ["--limit <n>",        "top: number of recommendations (default 5, max 50)"],
+      ["--mode <m>",         "apply: dry-run (default) | apply | apply-and-measure"],
+      ["--confirm",          "apply: required for apply / apply-and-measure (write modes)"],
+      ["--no-concurrent",    "apply: skip CREATE/DROP INDEX CONCURRENTLY (dev / small tables)"],
+      ["--json",             "Emit raw backend JSON instead of the terminal-friendly table"],
+    ],
+    notes:
+      "Complements `deepsql indexes` (catalog-level usage / health). " +
+      "This namespace surfaces the workload-weighted advisor + the apply tool.",
+  },
 };
 
 // ─── Color helpers ──────────────────────────────────────────────────────────
@@ -564,6 +594,10 @@ function buildOpts(parsed) {
     skipComplete: !!f.skipComplete,
     // Confirmations
     yes: !!f.yes || !!f.y,
+    // Index recommendations (apply tool)
+    mode: f.mode || null,
+    confirm: !!f.confirm,
+    noConcurrent: !!f.noConcurrent,
     // Connection management
     fromFile: f.fromFile || null,
     fromStdin: !!f.fromStdin,