@deepsql/mcp 0.11.0 → 0.13.0

package/AGENT-SETUP.md

@@ -188,54 +188,97 @@ can switch later with another `connections use`.
 
 ---
 
-## Step 7 — Wire the MCP integration into the editor
+## Step 7 — Wire the MCP integration + the DBA-consult skill into the editor
 
-> *Coming in `0.11.0`: `deepsql mcp config --install --for cursor|claude-code|codex`.*
-> *Until then, use the manual steps below.*
+Pick the user's editor and run one of:
 
-For **Claude Code**: edit `~/.claude/settings.json` and add an `mcpServers`
-entry:
-
-```json
-{
-  "mcpServers": {
-    "deepsql": {
-      "command": "deepsql",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+deepsql mcp config --install --for claude-code      # MCP: ~/.claude/settings.json
+                                                    # Skill: ~/.claude/skills/deepsql/SKILL.md
+deepsql mcp config --install --for claude-desktop   # MCP: ~/Library/Application Support/Claude/...
+                                                    # (no skill — Claude Desktop has no skills surface)
+deepsql mcp config --install --for cursor           # MCP: ~/.cursor/mcp.json
+                                                    # Skill: ~/.cursor/rules/deepsql.mdc
+deepsql mcp config --install --for codex            # MCP: ~/.codex/config.toml
+                                                    # Skill: ~/.codex/AGENTS.md (guarded section appended)
 ```
 
-For **Cursor**: edit `~/.cursor/mcp.json` with the same shape.
+Each invocation does **two** things in one shot:
+
+1. **MCP server config** — writes a `deepsql` entry into the editor's MCP
+   config file. The entry is intentionally tiny:
+
+   ```json
+   { "command": "deepsql", "args": ["mcp"] }
+   ```
+
+   The spawned `deepsql mcp` process reads the saved auth token from
+   `~/.config/deepsql/auth.json` (mode 0600), so **no token is embedded
+   in the editor config**.
 
-For **Codex CLI**: see `~/.codex/config.toml` — a `[mcp_servers.deepsql]`
-section with `command = "deepsql"` and `args = ["mcp"]`.
+2. **DBA-consult skill** — installs an editor-native skill file that
+   auto-triggers when the user does database work. The skill encodes the
+   "consult DeepSQL before generating DDL or non-trivial SQL" pattern, so
+   the agent reaches for `get_brain_context` / `get_schema` /
+   `list_business_rules` reflexively rather than inventing schema in a
+   vacuum. Trigger phrases the skill recognizes: "add a table", "write a
+   migration", "create a column", "design a model", "schema change",
+   "query the database", "SQL", "ORM model", "foreign key", "index".
 
-The CLI's saved auth token at `~/.config/deepsql/auth.json` is used
-automatically — no token needs to be embedded in the editor config.
+The installer:
+
+- creates each target file + parent directory if missing,
+- backs up the existing file to `<path>.bak.<timestamp>` before changing it,
+- merges into the existing MCP server list without touching siblings,
+- refuses to overwrite an existing `deepsql` entry unless `--force` is set,
+- for Codex's `AGENTS.md`, wraps the skill in guarded
+  `<!-- BEGIN DEEPSQL ... -->` / `<!-- END DEEPSQL ... -->` markers and
+  preserves the user's surrounding content,
+- emits the destination path and any backup path so the user can revert.
+
+If the user wants to see the snippets before installing, swap `--install`
+for `--print`. If they want the MCP server config but NOT the skill (e.g.,
+they have their own DBA prompt), pass `--no-skill`. For a non-default
+MCP config path, pass `--path <p>`.
+
+Restart the editor for the entries to load.
 
 ---
 
 ## Step 8 — Validate end-to-end
 
+Two quick checks — one for retrieval, one for execution:
+
 ```bash
 deepsql brain-context "list a few tables on this database" --top-k 5 --json
+deepsql query "SELECT 1 AS deepsql_ok"
 ```
 
-You should see 5 ranked results pointing at real tables. If the response
-is empty or the pipeline returned `skipped: simple_schema_question`,
-re-run with a more semantic question:
+The first should return 5 ranked results pointing at real tables. If the
+response is empty, re-run with a more semantic question
+(`"what is the primary fact table for orders"`).
 
-```bash
-deepsql brain-context "what is the primary fact table for orders" --top-k 5
-```
+The second runs through the canonical Editor SQL endpoint — same policy
+gate, audit log, and RBAC the web UI uses. A successful row confirms the
+auth token, the connection, and the policy pipeline are all wired up.
 
-If retrieval works, setup is complete. Tell the user that:
+If both work, setup is complete. Tell the user that:
 
-- They can now use DeepSQL from their editor (the MCP tools `list_connections`,
-  `get_brain_context`, `execute_readonly_sql`, `explain_readonly_sql`,
+- They can now use DeepSQL from their editor (the MCP tools
+  `list_connections`, `get_brain_context`, `execute_sql`, `analyze_query_plan`,
   `analyze_slow_queries`, etc. are all available there).
+- **From now on, when the user asks the agent to add a table, add a
+  column, write a migration, or design a new query against this database,
+  the agent will consult DeepSQL first** — checking existing schema,
+  business rules, and inferred relationships before generating any DDL.
+  This is the explicit pattern in `CLAUDE.md` ("Treat DeepSQL like your
+  DBA"). Users should expect the agent to narrate what DeepSQL found
+  ("there's already a `customers` table — I'll extend that instead of
+  adding `users`") before proposing schema. If the agent skips that step,
+  it's a bug in the agent's prompt handling, not in DeepSQL.
+- For mutations (DDL/DML), admins can pass `--write` to `deepsql query` to
+  skip the interactive confirmation, or just run without it and confirm
+  when prompted.
 - The companion file `CLAUDE.md` (in this same npm package, at
   `node_modules/@deepsql/mcp/CLAUDE.md`) covers the day-to-day usage
   patterns and common mistakes for editor agents.

package/CLAUDE.md

@@ -0,0 +1,382 @@
+# DeepSQL — runtime guidance for AI agents
+
+> You are an AI agent (Claude Code, Cursor, Codex, etc.) with DeepSQL's MCP
+> tools loaded. This file tells you how to use them well. Read once; the
+> patterns here will save you and your user real pain.
+
+DeepSQL is a self-hosted AI database performance assistant. It indexes the
+user's schemas into a retrieval brain, audits query workloads, and exposes
+two SQL surfaces through MCP plus a `deepsql` CLI.
+
+You'll use it in two distinct modes, and you need to recognize which one
+you're in:
+
+1. **Answer a question about the data.** The user asked something like
+   "how many orders did we ship last week?" You write SQL, run it, return
+   the answer. The "decision tree" below covers this flow.
+
+2. **Build a feature against an existing database.** The user is in their
+   codebase asking you to add a table, add a column, write a migration,
+   model a new relationship, design a query for the new ORM model, etc.
+   **This is where most agents fail silently** — they generate plausible
+   schema without consulting the existing one, and the developer ends up
+   with `users` next to `customers` and `cancelled_at` next to a
+   `status_history` table that already tracks the same thing. The "DBA
+   consult" section below covers this flow. **Read it before you generate
+   any DDL.**
+
+**Every call you make runs through the same policy gate as the web SQL
+Editor and is logged with your identity, the editor that invoked the MCP
+server, and the statement you ran.** Don't be sloppy.
+
+---
+
+## The tools you have
+
+The MCP server exposes 10 tools. They all take a `connectionId` (UUID
+returned by `list_connections`).
+
+| Tool | Purpose |
+|---|---|
+| `list_connections` | List databases the user has access to. Always call this first — you need IDs for everything else. |
+| `get_schema` | Cached schema metadata (tables, columns, FKs, types). Cheap and fast — call freely. |
+| `get_database_objects` | Tables, views, functions, procedures. Use when you need DDL-level objects, not just columns. |
+| `get_brain_context` | **Your primary retrieval tool.** Given a question, returns the tables/columns/FKs/training docs/business rules/anti-patterns most relevant to it. |
+| `list_business_rules` | Active business rules and SQL guardrails. Honor these — they encode domain semantics. |
+| `get_relationships` | Inferred + validated foreign keys with confidence scores. Many real DBs lack declared FKs; this fills the gap. |
+| `get_anti_patterns` | Schema-level (`kind=table`) or query-level (`kind=query`) anti-patterns. |
+| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples. Read-only; doesn't trigger new work. |
+| **`execute_sql`** | **Run any SQL statement.** Policy is server-enforced: developers can run SELECT/WITH/SHOW/EXPLAIN; admins can also run DML/DDL with a two-step confirmation. EXPLAIN and EXPLAIN ANALYZE are just SQL — no separate flag. |
+| **`analyze_query_plan`** | **AI-enriched plan analysis** for a query. Returns the parsed plan tree, performance issues, index recommendations, and a written summary that takes the connection's schema and business rules into account. Pass `useAnalyze: true` to run `EXPLAIN ANALYZE` (actually executes the query). |
+
+---
+
+## Hard rules
+
+1. **One execution tool, one analysis tool — that's it.** If you find yourself
+   reaching for `execute_sql` to get a plan, stop. Use `analyze_query_plan`.
+   If you find yourself wrapping queries in `EXPLAIN` by hand to avoid running
+   them, stop. Plain EXPLAIN is read-only on every database engine; just type
+   the SQL.
+
+2. **The policy gate is real.** If `execute_sql` returns
+   `{ requiresConfirmation: true, warnings: [...] }`, the statement is a
+   mutation that needs admin confirmation. Show the warnings to the user,
+   wait for their explicit OK, then re-call with `confirmMutation: true`.
+   Do not silently retry with `confirmMutation: true` on the user's behalf —
+   that defeats the whole point of the gate.
+
+3. **Developers cannot run mutations.** If the user's token has
+   `Role.DEVELOPER` and they ask you to `UPDATE users …`, the server will
+   return `EDITOR_MUTATION_FORBIDDEN`. Don't try to work around it. 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."
+
+4. **Pass `connectionId`, not names.** Names are user-facing; tools take UUIDs.
+   Get them from `list_connections` once and cache for the session.
+
+5. **Always call `get_brain_context` before generating non-trivial SQL.** The
+   brain knows about business rules, anti-patterns, and inferred FKs that
+   aren't in the raw schema. Skipping it produces "technically valid,
+   semantically wrong" SQL — the worst kind of failure.
+
+6. **`execute_sql` limits matter.** Default 100 rows, max 1000. Asking for
+   "all customers" and getting 100 is the limit kicking in — not the real
+   count. Either bump `limit` (max 1000) or `SELECT COUNT(*)` first.
+
+7. **Honor business rules silently.** If `list_business_rules` returns
+   `always_filter_cancelled` for a connection, your `SELECT * FROM orders`
+   suggestion is wrong without `WHERE status != 'CANCELLED'`. Apply the rule
+   in the SQL you generate; don't ask the user permission to follow their
+   own rules.
+
+8. **Treat DeepSQL like the DBA. Consult before you commit schema.** This
+   is the most important rule for feature-development work — it gets its
+   own section below.
+
+---
+
+## Treat DeepSQL like your DBA — consult before you commit
+
+If you're helping a developer build a feature, **the moment they say "add
+a table for X," "track Y," "save Z somewhere," or "let's write a
+migration" is the moment to call DeepSQL.** The brain has things the raw
+codebase doesn't:
+
+- business rules the team's previous DBA encoded
+- foreign-key relationships the schema infers but doesn't declare
+- anti-patterns that have already burned this team in this database
+- columns and tables that exist but live on parts of the schema the
+  developer hasn't seen yet
+
+Skipping the consult is the most common way agents make a database worse:
+
+- The developer asks for a `users` table. You create one. There's already
+  a `customers` table doing 90% of the same thing, and now half the new
+  feature's data lives in the wrong place forever.
+- The developer asks to "track when an order was cancelled." You add a
+  `cancelled_at` column. The team's existing pattern is `status` +
+  `order_status_history` — your column is now an inconsistent third
+  source of truth.
+- The developer asks for "an index on `email`." There's already a unique
+  constraint on `(tenant_id, email)` covering most lookups, and your
+  single-column index is dead weight that the optimizer will rarely pick.
+
+The consult takes one to three tool calls and saves the user months of
+cleanup. **Make it a reflex.**
+
+### The before-you-commit checklist
+
+Run these *before* you generate any DDL, migration file, ORM model, or
+schema-shaped design proposal:
+
+1. **`get_brain_context(connectionId, "<one-line description of the feature>")`** —
+   surfaces the tables, columns, FKs, training docs, and business rules
+   most relevant. Read the results, don't just regurgitate them.
+
+2. **`get_schema(connectionId)`** if you need the full column inventory
+   for the tables `get_brain_context` surfaced. Confirm exact column names
+   and types before you reference them.
+
+3. **`list_business_rules(connectionId, question="<feature>")`** — active
+   rules the new feature MUST respect. `always_filter_cancelled` means
+   your new aggregate view inherits that filter from day one.
+
+4. **`get_relationships(connectionId)`** if you're about to declare a new
+   foreign key. The brain may already infer the relationship — and the
+   inferred FK column has a confidence score telling you whether the
+   convention is reliable enough to follow without explicitly declaring.
+
+5. **`get_anti_patterns(connectionId, kind="table")`** if you're about to
+   commit a schema shape (single fat table, denormalized JSON column,
+   unindexed FK, …). The brain has flagged these patterns elsewhere in
+   this exact database; don't add to the pile.
+
+### Narrate what you found, then propose
+
+When the checklist is done, **explain to the developer what you found
+before you propose schema**. Example:
+
+> "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 team's business rule `always_filter_cancelled`
+> is on `customers.status`. The `kind=table` 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 adding a `users` table. Want me to draft the migration?**"
+
+That explicit handoff is the difference between an agent that ships
+features fast and an agent that earns the DBA's trust.
+
+### When the consult tells you to stop
+
+Sometimes the right answer is "don't add this." If `get_brain_context`
+surfaces an existing table that already does what the user is asking for,
+say so. If `get_anti_patterns` flags the shape they're about to add, say
+so. The user usually doesn't know about either; that's exactly why
+DeepSQL exists. Push back politely and propose the better path.
+
+---
+
+## The "I need to…" decision tree
+
+**"What tables exist?"** → `get_schema` (or `list_connections` first if you
+don't know which connection). Don't ask `execute_sql` to query
+`information_schema` — `get_schema` is faster and cached.
+
+**"Write a SQL query to answer X."** → `get_brain_context` with X as the
+question, then generate SQL using only the columns/tables it surfaced.
+
+**"Run this SQL and tell me what it returns."** → `execute_sql`. If you're
+unsure whether the query is correct, call `analyze_query_plan` first (plain
+EXPLAIN, no execution) — costs nothing and catches bad joins.
+
+**"Why is this query slow?"** → `analyze_query_plan`. The AI summary points
+at the slow nodes, missing indexes, and bad estimates. For workload-level
+problems use `analyze_slow_queries`.
+
+**"What's the real execution time for this query?"** → `analyze_query_plan`
+with `useAnalyze: true`. **This actually runs the query**, so if the
+statement mutates the database, the same admin role + WHERE-clause + confirm
+gates that protect `execute_sql` kick in. You'll get back
+`requiresConfirmation` if you forgot.
+
+**"Apply this migration"** / **"Add this column"** / **"Delete these rows"**
+→ `execute_sql` with the DDL/DML. Only admins can do it. On first call you'll
+get `requiresConfirmation` — surface the warnings to the user verbatim, wait
+for them to say yes, then re-call with `confirmMutation: true`.
+
+**"What indexes should we add?"** → Not exposed via MCP yet. Tell the user
+to run `deepsql indexes missing` or `deepsql indexes health` in their
+terminal.
+
+**"What changed recently / what should I worry about?"** → Tell the user to
+run `deepsql digest` (today) or `deepsql digest 7` (last seven). The digest
+isn't MCP-exposed.
+
+**"Are there foreign keys between X and Y?"** → `get_relationships`. Many
+real-world DBs lack declared FKs but DeepSQL's brain infers them; check the
+`confidence` field and `validationStatus`.
+
+### Feature-development questions (the DBA-consult flow)
+
+**"I'm building a feature that needs a `<thing>` table."** → STOP. Call
+`get_brain_context(connectionId, "<thing>")` first. Read the "Treat
+DeepSQL like your DBA" section above before generating any DDL. There's
+almost always an existing table or column to extend instead of
+duplicate.
+
+**"I'm about to write a migration."** → STOP. Run the before-you-commit
+checklist (`get_brain_context` + `list_business_rules` +
+`get_anti_patterns`). Walk the developer through what you found, THEN
+write the migration. The user should see your reasoning, not just the
+final SQL.
+
+**"I'm adding a new column to `<table>`."** → STOP. `get_schema` first to
+confirm the column doesn't already exist (sometimes under a different
+name — `cancelled_at` vs `voided_at` vs `status_history.changed_at`).
+`list_business_rules` to check whether nullability, default, or naming
+conventions are constrained.
+
+**"I'm naming a foreign key / index."** → `get_relationships` for the FK
+convention this team uses, and `get_schema` to see how existing indexes
+on the parent table are named. Pick the convention; don't invent a new
+one.
+
+**"I'm designing an ORM model / type definition for table `X`."** →
+`get_schema(connectionId)` and pull the exact column list, types, and
+nullability. Don't infer column types from variable names in the
+codebase — they're often stale.
+
+---
+
+## Foot-guns we've watched agents step on
+
+**"I'll write a 4-statement script to set up some temp tables, run my
+analysis, and clean up."** → `execute_sql` rejects multi-statement input.
+Run each statement separately, or use CTEs (`WITH foo AS (...) SELECT ...`).
+
+**"I'll skip the confirmation step and re-call with `confirmMutation: true`
+right away."** → That's an end-run around safety. The confirmation step
+exists so a human gets a chance to see the warnings (especially the
+"this DELETE has no WHERE clause"-style ones). Always surface the warnings,
+always wait for the human.
+
+**"`EXPLAIN ANALYZE` is just better EXPLAIN, I'll always use it."** → No.
+ANALYZE executes the query. For SELECTs it's just slower; for mutations it
+actually mutates. Default to `useAnalyze: false` and only bump to `true`
+when the user actually wants real timings.
+
+**"I don't trust the cached schema; let me query `information_schema`
+fresh."** → The cache is invalidated whenever the brain re-indexes the
+connection. Trust it. If you really suspect drift, ask the user to run
+`deepsql connections init <name> --wait`.
+
+**"I'll just retry on 403."** → A 403 from DeepSQL means the user's token
+doesn't have access to that specific connection (RBAC) or role doesn't
+allow the action (developer trying to mutate). Surface the error verbatim;
+don't pretend it's transient.
+
+**"The SQL looks fine; I'll skip the plan check."** → A cheap
+`analyze_query_plan` call has saved more bad joins than any other habit.
+Always check the plan before suggesting a query to a user, especially
+against unfamiliar schemas.
+
+**"The developer asked for table X, so I'll just create it."** → That's
+how databases get fragmented over a year. The brain almost always has a
+table doing most of what the new feature needs; you'll find it in 30
+seconds with `get_brain_context`. Skipping that step makes you the agent
+future engineers curse when they're refactoring around your duplicate
+schema. Run the before-you-commit checklist every single time.
+
+**"I read the codebase's models, I know the schema."** → Codebase models
+drift from the live schema. Columns get renamed in a migration, the model
+class doesn't update. A `User.email` field in TypeScript can be
+`users.email_address` in Postgres. `get_schema` is the source of truth;
+trust it over `grep`.
+
+---
+
+## What lives in the CLI but not the MCP (yet)
+
+A few categories are CLI-only for now — if the user asks for them, point
+them at the terminal command rather than trying to fake it through
+`execute_sql`:
+
+| Capability | CLI command |
+|---|---|
+| Index recommendations / missing-index advisor | `deepsql indexes list`, `deepsql indexes missing` |
+| Unused / duplicate index detection | `deepsql indexes unused`, `deepsql indexes duplicates` |
+| Per-table index usage stats | `deepsql indexes usage <table>` |
+| Index health report | `deepsql indexes health` |
+| Daily digest (anomalies + AI commentary) | `deepsql digest`, `deepsql digest 7` |
+| Streaming AI optimization for a slow query | `deepsql slow-queries optimize --query-id <id>` |
+
+These are reachable from any terminal where `deepsql` is installed and
+logged in; the saved profile is shared with the MCP server.
+
+---
+
+## A typical session
+
+1. `list_connections` → grab the UUID for the connection the user means.
+2. `get_brain_context(connectionId, "the question")` → harvest tables,
+   columns, business rules.
+3. Write SQL using only the columns the brain surfaced; respect the rules.
+4. `analyze_query_plan(connectionId, sql)` → sanity-check the plan
+   (`useAnalyze: false`).
+5. `execute_sql(connectionId, sql, limit=…)` → fetch results.
+6. Summarize, citing which tables you used and which rules you applied.
+
+If you need to mutate (DDL/DML, admin role required):
+
+1–3. Same as above.
+4. Show the user the SQL you intend to run, in plain text. **Get their OK.**
+5. `execute_sql(connectionId, sql)` → expect `requiresConfirmation: true`
+   with warnings.
+6. Show the warnings to the user verbatim. Get their **second** OK.
+7. `execute_sql(connectionId, sql, confirmMutation: true)` → executes.
+8. Tell the user it succeeded; show the `rowCount` of affected rows.
+
+If you're helping a developer build a feature (the DBA-consult flow):
+
+1. Have the developer describe the feature in one or two sentences.
+2. `get_brain_context(connectionId, "<feature in one line>")` → surfaces
+   existing tables, columns, FKs, and rules in scope.
+3. Fill in any gaps: `get_schema(connectionId)` for full column lists,
+   `list_business_rules(connectionId, …)` for constraints,
+   `get_relationships(connectionId)` for FK conventions,
+   `get_anti_patterns(connectionId, kind="table")` for shapes to avoid.
+4. **Narrate to the developer what you found before proposing schema.**
+   "There's already an X. The team's convention is Y. Anti-pattern Z is
+   on watch. Here's what I'd propose, given all that."
+5. Once the developer agrees on the *shape*, generate the migration. For
+   admins this lands via `execute_sql`; follow the mutation playbook
+   above to actually run it. For developers without write access, hand
+   the SQL to the user to commit through your codebase's migration
+   tooling instead — but make sure the schema you generate already
+   reflects everything DeepSQL told you in step 2–3.
+6. After the migration runs, `get_schema(connectionId)` to verify the new
+   columns exist with the expected types, and optionally re-run
+   `analyze_query_plan` on the canonical queries the new feature will
+   issue.
+
+If any step returns nothing useful, ask the user to be more specific
+rather than guessing. DeepSQL is conservative by design — empty results
+from `get_brain_context` usually mean the question was too short or too
+schema-y, not that the brain is broken.
+
+---
+
+## Audit, in case you wondered
+
+Every call you make is logged to `security_events` with:
+
+- the user's identity (from the bearer token)
+- the editor that invoked the MCP (claude-desktop, cursor-mcp, codex-mcp —
+  whatever `DEEPSQL_MCP_USER_ID` is set to in the editor config)
+- the connection, statement hash, truncated text, outcome
+- whether confirmation was required and given
+
+Workspace admins can search this via the Security tab. Don't do anything
+through the MCP that you wouldn't be willing to defend in that view.