@deepsql/mcp 0.11.0 → 0.13.4

package/README.md

@@ -1,42 +1,126 @@
-# DeepSQL MCP
+# DeepSQL CLI + MCP server
 
-DeepSQL MCP V1 is a local stdio server for Claude Desktop, Codex, and similar MCP clients.
+The `@deepsql/mcp` package ships two things in one binary:
 
-## What V1 Supports
+- **`deepsql`** — a CLI for talking to a self-hosted DeepSQL backend from a
+  terminal (auth, connections, SQL execution, plan analysis, index
+  suggestions, slow-query analyses, admin ops).
+- **`deepsql mcp`** — a stdio MCP server that exposes the same backend to
+  editor agents (Claude Code, Cursor, Codex, Claude Desktop) so they can
+  query and reason about the user's databases.
 
-- Local stdio MCP process
-- Remote DeepSQL backend over HTTPS
-- MCP personal access tokens for authentication
-- Read-only SQL execution and explain through backend-enforced MCP endpoints
+Both share one auth file (`~/.config/deepsql/auth.json`, mode 0600). Log
+in once with `deepsql login`; the MCP server uses the same token
+automatically — no token needs to be embedded in your editor's config.
 
-V1 does **not** provide a shared remote MCP server URL. Each user runs the MCP process locally on their own machine.
+## Install
 
-## Environment Variables
-
-| Variable | Required | Example |
-|----------|----------|---------|
-| `DEEPSQL_API_BASE_URL` | yes | `https://customer-deepsql.example.com/api/` |
-| `DEEPSQL_AUTH_TOKEN` | yes | `dsql_mcp_...` |
-| `DEEPSQL_MCP_TIMEOUT_MS` | no | `120000` |
-| `DEEPSQL_MCP_USER_ID` | no | `codex-mcp` |
-| `DEEPSQL_MCP_PROJECT_ID` | no | `codex-mcp` |
+```bash
+npm install -g @deepsql/mcp@latest
+deepsql --version
+```
 
-## Claude Desktop
+Requires Node ≥ 20.
 
-Use `claude_desktop_config.customer.example.json` as a template.
+## Quick start
 
-## Codex
+```bash
+deepsql login --url https://your-deepsql-host.example.com
+deepsql connections list
+deepsql connections use <connection-name>
+deepsql query "SELECT 1 AS ok"
+```
 
-Use `codex_config.customer.example.toml` as a template.
+## Wire into your editor (one command per editor)
 
-## Run
+The installer writes the MCP server entry into the editor's config AND
+installs a "DBA consult" skill that auto-triggers when the user asks
+the agent to do database work:
 
 ```bash
-npx -y @deepsql/mcp
+deepsql mcp config --install --for claude-code      # via `claude mcp add --scope user`
+deepsql mcp config --install --for claude-desktop   # macOS ~/Library/.../Claude/...
+deepsql mcp config --install --for cursor           # ~/.cursor/mcp.json + ~/.cursor/rules/deepsql.mdc
+deepsql mcp config --install --for codex            # ~/.codex/config.toml + ~/.codex/AGENTS.md
 ```
 
-For local repo development, you can also run:
+Pass `--print` to see what would be written without touching disk.
+Pass `--no-skill` to install only the MCP entry. Pass `--force` to
+overwrite a stale entry. See `deepsql mcp --help` for details.
+
+Restart the editor for the entry to load.
+
+## What the MCP server exposes
+
+10 tools, all read-only at the schema/retrieval layer and policy-gated
+at the SQL layer:
+
+| Tool | Purpose |
+|---|---|
+| `list_connections` | Connections this token has access to |
+| `get_schema` | Cached schema metadata (tables, columns, FKs, types) |
+| `get_database_objects` | Tables, views, functions, procedures |
+| `get_brain_context` | Retrieval brain: tables/columns/FKs/training docs/rules for a question |
+| `list_business_rules` | Active business rules and SQL guardrails for a connection |
+| `get_relationships` | Inferred + validated foreign keys with confidence scores |
+| `get_anti_patterns` | Schema-level or query-level anti-patterns |
+| `analyze_slow_queries` | Recent slow queries with fingerprints, durations, examples |
+| `execute_sql` | Run any SQL — backend enforces role-based policy (developers read-only, admins can mutate with two-step confirm) |
+| `analyze_query_plan` | AI-enriched plan analysis (parsed plan tree, performance issues, index recommendations, written summary that uses the connection's schema + business rules) |
+
+EXPLAIN and EXPLAIN ANALYZE are just SQL — pass them as the query to
+`execute_sql`. For the AI-enriched plan analysis with the LLM-written
+summary, use `analyze_query_plan`.
+
+## Runtime guidance for agents
+
+`CLAUDE.md` (bundled in this package, at
+`node_modules/@deepsql/mcp/CLAUDE.md` after install) is the runtime
+guide for editor agents that have these tools loaded. It covers the
+"DBA consult" pattern, decision tree, hard rules around the role-gated
+mutation flow, and common foot-guns. The installer also drops a
+shortened, trigger-focused version of that guide as a native skill so
+the pattern fires automatically on phrases like "add a table", "write
+a migration", "design a schema", "query the database".
+
+## Agent-driven setup (one paste)
+
+For a fresh customer install, paste `AGENT-SETUP.md` (bundled at
+`node_modules/@deepsql/mcp/AGENT-SETUP.md`) into Claude Code / Cursor /
+Codex. The agent walks the user through install, login, connection
+registration, editor integration, and end-to-end validation in ~5
+minutes.
+
+## Manual install (only if you don't want the CLI shim)
+
+If you'd rather skip the `deepsql mcp config --install` flow and wire
+the editor config by hand, see the example files bundled with this
+package: `claude_desktop_config.customer.example.json` and
+`codex_config.customer.example.toml`. The token-embedded shape in
+those examples still works, but `deepsql mcp config --install` is the
+recommended path now.
+
+## Run the server directly (advanced)
 
 ```bash
-npm run mcp:phase1
+deepsql mcp                # uses the saved profile + auth token
+npx -y @deepsql/mcp        # one-off invocation without install
 ```
+
+Both work; the CLI shim is preferred because it shares the saved
+profile and never asks you to paste a token into editor config.
+
+## Environment variables
+
+| Variable | Required | Used by | Example |
+|----------|----------|---------|---------|
+| `DEEPSQL_API_BASE_URL` | for npx-style invocation | `deepsql mcp` if no saved profile | `https://customer-deepsql.example.com/api/` |
+| `DEEPSQL_AUTH_TOKEN` | for npx-style invocation | bearer for backend; `deepsql login` writes one to the profile file | `dsql_mcp_…` |
+| `DEEPSQL_MCP_USER_ID` | no | identifies the editor that invoked the MCP server in audit logs | `claude-desktop` / `cursor-mcp` / `codex-mcp` |
+| `DEEPSQL_CALLER_AGENT` | no | overrides the CLI's audit identity when an agent shells out to `deepsql` | `claude-code` |
+| `DEEPSQL_MCP_TIMEOUT_MS` | no | per-request timeout for MCP server calls | `120000` |
+
+If `deepsql login` has been run, both the CLI and the spawned MCP
+server pick up `DEEPSQL_API_BASE_URL` + `DEEPSQL_AUTH_TOKEN` from
+`~/.config/deepsql/auth.json` automatically — you don't need to set
+the env vars for either.

package/claude_desktop_config.customer.example.json

@@ -1,17 +1,9 @@
 {
+  "_comment": "Manual Claude Desktop config example. Most users should run `deepsql mcp config --install --for claude-desktop` instead — that handles the OS-specific path, backup, and the DBA-consult skill in one shot. Use this template only if you need a custom layout (per-workspace, embedded token, etc.).",
   "mcpServers": {
     "deepsql": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@deepsql/mcp"
-      ],
-      "env": {
-        "DEEPSQL_API_BASE_URL": "https://customer-deepsql.example.com/api/",
-        "DEEPSQL_AUTH_TOKEN": "dsql_mcp_replace_me",
-        "DEEPSQL_MCP_USER_ID": "claude-desktop",
-        "DEEPSQL_MCP_PROJECT_ID": "claude-desktop"
-      }
+      "command": "deepsql",
+      "args": ["mcp"]
     }
   }
 }

package/codex_config.customer.example.toml

@@ -1,9 +1,13 @@
-[mcp_servers.deepsql]
-command = "npx"
-args = ["-y", "@deepsql/mcp"]
+# Manual Codex CLI MCP config example. Most users should run
+#   `deepsql mcp config --install --for codex`
+# instead — that handles the file path, backup, and the DBA-consult skill
+# in one shot. Use this template only if you need a custom layout (e.g.
+# embedded token, alternate `DEEPSQL_*` env vars, non-default profile).
+#
+# The form below uses the `deepsql mcp` shim, which reads auth from
+# ~/.config/deepsql/auth.json (written by `deepsql login`) — no token
+# needs to be embedded in the config.
 
-[mcp_servers.deepsql.env]
-DEEPSQL_API_BASE_URL = "https://customer-deepsql.example.com/api/"
-DEEPSQL_AUTH_TOKEN = "dsql_mcp_replace_me"
-DEEPSQL_MCP_USER_ID = "codex-mcp"
-DEEPSQL_MCP_PROJECT_ID = "codex-mcp"
+[mcp_servers.deepsql]
+command = "deepsql"
+args = ["mcp"]

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;
 }
 
@@ -502,11 +552,56 @@ function summarizeAntiPatterns(payload, kind) {
 }
 
 function summarizeSlowQueries(payload) {
-  const list = Array.isArray(payload?.queries) ? payload.queries : [];
+  // Backend returns SlowQueryAnalysis with `topSlowQueries` (the field name
+  // varies; tolerate both `queries` and `topSlowQueries`).
+  const list = Array.isArray(payload?.topSlowQueries)
+    ? payload.topSlowQueries
+    : Array.isArray(payload?.queries) ? payload.queries : [];
   const total = payload?.totalCount ?? list.length;
   const avg = payload?.avgDurationMs;
   const max = payload?.maxDurationMs;
-  return `${total} slow query/queries${avg != null ? `, avg=${avg}ms` : ""}${max != null ? `, max=${max}ms` : ""}.`;
+
+  // Three counts matter to a calling agent that's about to EXPLAIN one of
+  // these queries:
+  //
+  //   recovered = sourceTruncated AND queryTextRecoveredFromLogs
+  //     → the live stats source truncated this query, but DeepSQL recovered
+  //       the full SQL from previously-ingested slow-log data in
+  //       query_lineage. EXPLAIN will work.
+  //
+  //   stillTruncated = sourceTruncated AND NOT queryTextRecoveredFromLogs
+  //     → still truncated; EXPLAIN will fail or return a partial plan.
+  //
+  //   neither → normal full-text query, no warning needed.
+  const recovered = list.filter((q) =>
+    q && q.sourceTruncated === true && q.queryTextRecoveredFromLogs === true
+  ).length;
+  const stillTruncated = list.filter((q) =>
+    q && q.sourceTruncated === true && q.queryTextRecoveredFromLogs !== true
+  ).length;
+
+  const parts = [];
+  if (recovered > 0) {
+    parts.push(
+      ` ℹ ${recovered} ${recovered === 1 ? "query was" : "queries were"} truncated by `
+      + `the database server (default 1024B) but DeepSQL recovered the full SQL `
+      + `from previously-ingested slow-log data — EXPLAIN against \`queryText\` will work.`
+    );
+  }
+  if (stillTruncated > 0) {
+    parts.push(
+      ` ⚠ ${stillTruncated} ${stillTruncated === 1 ? "query is" : "queries are"} still `
+      + `truncated and DeepSQL has no full-text copy on file. EXPLAIN will be unreliable. `
+      + `Fix: ingest the slow query log file for this connection, OR raise `
+      + `\`pg_stat_statements.track_activity_query_size\` (PG) / `
+      + `\`performance_schema_max_sql_text_length\` (MySQL) and restart, then re-collect.`
+    );
+  }
+
+  return `${total} slow query/queries`
+    + `${avg != null ? `, avg=${avg}ms` : ""}`
+    + `${max != null ? `, max=${max}ms` : ""}.`
+    + parts.join("");
 }
 
 function summarizeQueryResult(payload) {
@@ -554,10 +649,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 +793,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 +855,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/deepsql-phase1-server.js

@@ -193,7 +193,7 @@ class DeepSqlPhase1McpServer {
             },
             serverInfo: SERVER_INFO,
             instructions:
-              "DeepSQL phase 1 MCP exposes read-only database access plus DeepSQL's brain (retrieved context, business rules, inferred relationships, anti-patterns, slow-query analysis). Prefer get_brain_context to ground SQL/answer generation in retrieved schema knowledge, then call execute_readonly_sql / explain_readonly_sql to validate. Mutating SQL is rejected by both client and backend.",
+              "DeepSQL MCP exposes the user's database catalogs plus DeepSQL's retrieval brain (relevant tables/columns/FKs, business rules, inferred relationships, anti-patterns, slow-query analysis). Workflow: call list_connections first to get UUIDs; call get_brain_context with the user's question to ground generation in retrieved schema; call execute_sql to run the query (admins can run DDL/DML with a two-step confirmMutation flow, developers are server-enforced read-only); call analyze_query_plan for AI-enriched plan analysis with the connection's schema + business rules in scope. EXPLAIN and EXPLAIN ANALYZE are valid SQL — pass them as the query to execute_sql; use analyze_query_plan when you want the LLM-written summary, not raw plan rows. Always pass connectionId (UUID), not connection names.",
           });
           return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.11.0",
+  "version": "0.13.4",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "bin/deepsql.js",
@@ -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.