@deepsql/mcp 0.10.1 → 0.11.0

package/CLAUDE.md

@@ -1,330 +0,0 @@
-# DeepSQL — guidance for AI agents (Claude Code / Cursor / Codex / etc.)
-
-> Read this file before invoking DeepSQL tools. It exists because there are
-> **two surfaces** (MCP tools + CLI commands) that look similar and agents
-> tend to pick the wrong one or use the right one inefficiently.
-
-DeepSQL is an autonomous database performance assistant. It exposes itself
-to AI agents in two ways:
-
-| Surface | Where it lives | When you use it |
-|---|---|---|
-| **MCP tools** (programmatic) | The stdio server you connected via `deepsql mcp` | Default. You're an MCP client and these are first-class tool calls. |
-| **CLI** (`deepsql` binary) | The user's `$PATH`, invoked via Bash | Only when an MCP tool can't do it (admin ops, auth, multi-step user flows) **or** the user explicitly asked you to "run `deepsql ...`". |
-
-If you have both available, **prefer MCP tools.** They're structured, typed,
-faster, and don't depend on the user's shell environment.
-
----
-
-## Decision tree — "I want to..."
-
-```
-1. Find which databases I can query
-   → list_connections          (returns id, name, type for each)
-
-2. Understand a database's structure
-   → get_brain_context         (RAG retrieval — best when you have a
-                                natural-language question; returns ranked
-                                tables/columns/FKs/docs/business rules)
-   → get_schema                (full deterministic schema dump — when you
-                                need every table; expensive on large DBs)
-   → get_database_objects      (tables/views/functions/procedures only)
-
-3. Answer a business question about data
-   → get_brain_context first   (retrieves what tables hold what, FK edges,
-                                business rules; gives you grounded context)
-   → then construct SQL yourself, then:
-   → explain_readonly_sql      (validate the plan)
-   → execute_readonly_sql      (run it)
-
-4. Find inferred relationships between tables
-   → get_relationships         (returns FK candidates with confidence scores)
-
-5. Read business rules / data-access policies
-   → list_business_rules       (active rules + guardrails for a connection;
-                                pass `question` to scope to relevant ones)
-
-6. Find anti-patterns
-   → get_anti_patterns kind=table   (schema/structural anti-patterns)
-   → get_anti_patterns kind=query   (slow/expensive query patterns)
-
-7. Investigate slow queries
-   → analyze_slow_queries      (recent slow queries with fingerprints + ms)
-
-8. Run SQL to inspect data
-   → execute_readonly_sql      (read-only — backend rejects mutations)
-```
-
-**Rule of thumb for question-answering:** start with `get_brain_context`,
-not `execute_readonly_sql`. The brain context tells you which tables matter,
-their FKs, what the columns mean, and what business rules apply. Skipping
-straight to SQL is how you write queries against the wrong tables.
-
----
-
-## MCP tool reference (10 tools)
-
-Every tool requires a `connectionId` (string UUID) **except** `list_connections`.
-Always call `list_connections` first if you don't already know the ID.
-
-### Discovery
-
-#### `list_connections`
-- **Args:** none
-- **Returns:** array of `{ id, connectionName, databaseType, ... }`
-- **Use when:** the user mentions a DB by name and you need its ID, or you
-  don't know which DBs are available.
-
-#### `get_schema(connectionId)`
-- **Returns:** the cached schema metadata for the whole DB.
-- **Use when:** you need an exhaustive listing. **Avoid** when the DB is
-  large (hundreds of tables) — `get_brain_context` ranks the relevant
-  subset much faster.
-
-#### `get_database_objects(connectionId)`
-- **Returns:** tables, views, functions, procedures.
-- **Use when:** the user asks "what views/functions exist?" — narrower
-  than `get_schema`.
-
-### RAG / brain retrieval (preferred for question-answering)
-
-#### `get_brain_context(connectionId, question, topK?)`
-- **Args:**
-  - `question` — natural-language question used for retrieval ranking
-  - `topK` (optional, 1–100) — when provided, returns ranked diagnostic
-    snippets (good for "show me the top 5 most relevant tables"). When
-    omitted, returns the rich training-context payload (tables + columns
-    + FKs + business rules + docs assembled for prompt-grounding).
-- **Use when:** the user asks any analytical question. This is the cheapest
-  way to ground yourself before generating SQL.
-- **Output:** typically includes `trainingContext` (text block ready to feed
-  into your own context window) plus structured ranked results.
-
-#### `list_business_rules(connectionId, question?)`
-- **Returns:** `activeRules` + `applicableGuardrails` + `guardrailContext`.
-- **Use when:** before generating SQL that touches sensitive entities. If
-  the rules say "PII columns are blocked," respect that in your output.
-  Pass `question` to filter to rules applicable to the user's intent.
-
-#### `get_relationships(connectionId)`
-- **Returns:** array of `{ sourceTable, sourceColumn, targetTable, targetColumn, confidence, inferenceMethod, validationStatus }`.
-- **Use when:** writing JOINs and the actual FK constraint isn't declared
-  in the schema. Anything `confidence >= 0.8` is safe; lower confidence
-  means inferred from naming patterns or data — verify with the user.
-
-#### `get_anti_patterns(connectionId, kind?, limit?)`
-- **`kind="table"` (default):** schema-level anti-patterns (missing
-  indexes, wide tables, etc.).
-- **`kind="query":** query-level patterns; pass `limit` (1–500).
-- **Use when:** the user asks "what's wrong with this DB?" or you've
-  generated a query and want to sanity-check it.
-
-### Operations
-
-#### `analyze_slow_queries(connectionId, thresholdMs?, limit?)`
-- **Args:** `thresholdMs` defaults 100, `limit` defaults 10.
-- **Returns:** recent slow queries from `pg_stat_statements` with
-  fingerprints, durations, example statements.
-- **Use when:** the user asks "what's slow?" or you're triaging a
-  performance incident.
-
-### Execution
-
-#### `execute_readonly_sql(connectionId, query, limit?, timeoutSeconds?)`
-- **Read-only enforced at four layers:** client SQL parser, backend SQL
-  parser, per-connection ACL on the calling user's token, and the DB
-  role itself usually only has SELECT/EXPLAIN. Mutations (INSERT, UPDATE,
-  DELETE, DDL, etc.) are rejected — **don't try to work around this**.
-- **Multi-statement SQL is rejected** in phase 1. Send one statement.
-- **Defaults:** 100-row `limit`, backend default `timeoutSeconds`.
-- **Use when:** you've grounded yourself with `get_brain_context` and need
-  to fetch concrete numbers.
-
-#### `explain_readonly_sql(connectionId, query)`
-- **Don't include `EXPLAIN` in the query string** — the tool wraps it.
-  `ANALYZE` is also rejected (read-only).
-- **Use when:** you want to validate a plan before running it, or you're
-  diagnosing why a query is slow.
-
----
-
-## CLI commands (run via Bash, only when MCP isn't enough)
-
-The CLI exposes the same data plane plus admin operations the MCP server
-deliberately doesn't expose. **Only run CLI commands when the user explicitly
-asks you to**, or when an MCP tool can't do what's needed (admin, auth,
-multi-step flows).
-
-### Quick reference
-
-```
-# Auth (the user typically did this once; don't re-run unless asked)
-deepsql login --url https://<host>
-deepsql whoami
-deepsql logout
-
-# Connections — the human's "active DB" pin (CLI-only; MCP tools don't read this)
-deepsql connections list                     # marks active with *
-deepsql connections use <name>               # pin
-deepsql connections current                  # show pinned
-deepsql connections unset
-
-# Read-only data ops (mirror MCP tools — same backend, same guardrails)
-deepsql query "SELECT ..." --connection <name>
-deepsql explain "SELECT ..." --connection <name>
-deepsql schema [tables|objects] --connection <name>
-
-# Brain / RAG (mirror the MCP brain tools)
-deepsql brain-context "<question>" --connection <name> [--top-k N]
-deepsql business-rules --connection <name> [--question "..."]
-deepsql relationships --connection <name>
-deepsql anti-patterns --connection <name> [--kind table|query] [--limit N]
-
-# Slack daily digest
-deepsql digest [N] --connection <name>
-
-# Slow-query operations
-deepsql slow-queries latest --connection <name>
-deepsql slow-queries history --connection <name> [N]
-deepsql slow-queries analyze --connection <name>
-deepsql slow-queries optimize --connection <name> --query-id <id>   # SSE stream
-
-# Admin (require ADMIN role)
-deepsql users list | get | add | set-role | lock | unlock | disable | delete
-deepsql access list | grant | revoke | policy
-deepsql permissions list | override | reset
-deepsql setup [--skip-email] [--skip-slack]   # post-install wizard
-```
-
-### When CLI is the right call (vs MCP)
-
-- The user said "run `deepsql ...`" or "use the CLI."
-- The operation is admin (`users`, `access`, `permissions`, `setup`) — these
-  aren't exposed via MCP intentionally.
-- The user wants Slack digest content (`digest`).
-- You're in a script context where structured stdin/stdout is preferable.
-
-### When CLI is the **wrong** call
-
-- For everything in the decision tree above. The MCP equivalents are
-  faster and don't depend on the user's `$PATH`, env, or saved auth.
-- For executing SQL the user is paying you to write — use
-  `execute_readonly_sql`, not `Bash("deepsql query ...")`.
-
----
-
-## Common mistakes — and how to avoid them
-
-### ❌ Generating SQL without retrieving brain context first
-The user asks: *"How many active customers do we have?"*
-
-**Wrong:** call `execute_readonly_sql("SELECT COUNT(*) FROM customers WHERE active = true")` —
-guesses at the table name (`customers` vs `dim_customer` vs `users`),
-guesses at the column (`active` vs `is_active` vs `status='ACTIVE'`),
-ignores any business rule that defines what "active" means.
-
-**Right:**
-1. `get_brain_context(connectionId, "how many active customers")` — returns the
-   right table (`dim_customer`) and the column convention.
-2. `list_business_rules(connectionId, "active customers")` — returns the rule
-   if "active" has a workspace-specific definition.
-3. Generate SQL using the names + rules from #1 and #2.
-4. `explain_readonly_sql(...)` — sanity check.
-5. `execute_readonly_sql(...)` — run it.
-
-### ❌ Calling `get_schema` on every analysis question
-`get_schema` returns the entire DB. On a 200-table OLAP warehouse that's a
-huge response and most of it is irrelevant to the question. **Use
-`get_brain_context` for question-scoped retrieval.** Reserve `get_schema`
-for exhaustive listing tasks.
-
-### ❌ Trying to mutate data
-Every execution path is read-only. INSERT/UPDATE/DELETE/CREATE/DROP/ALTER/
-TRUNCATE are all rejected at the SQL parser layer. If the user asks for a
-mutation, **stop and tell them DeepSQL is read-only**, then offer to draft
-the SQL for them to run themselves.
-
-### ❌ Forgetting the connectionId
-Every tool except `list_connections` requires it. If the user mentions a DB
-by name (e.g., "look at prod-replica"), call `list_connections` first to
-resolve the name → UUID. Don't guess.
-
-### ❌ Re-fetching context on every turn
-Schema and brain context don't change minute-to-minute. If you already
-called `get_brain_context` for a related question this conversation, reuse
-the result. Don't re-call unless the question has shifted topics.
-
-### ❌ Mixing CLI invocations and MCP tool calls in the same session
-Pick one. If you have MCP available, stay in MCP. If you only have Bash,
-use the CLI. Mixing forces the user to debug two surfaces.
-
-### ❌ Calling `analyze_slow_queries` and immediately querying the slow-query log table directly
-The MCP tool already does the right query against `pg_stat_statements` (or
-the equivalent for MySQL) with the right thresholds. Don't reinvent it.
-
----
-
-## Output handling tips
-
-- **`get_brain_context` returns a `trainingContext` text block.** It's
-  designed to drop into your prompt as-is. Don't summarize it before
-  generating SQL — let the structured names flow through.
-- **`execute_readonly_sql` returns `{ result: { columns, rows, rowCount, totalRowCount, isLimited, ... }, success, queryType }`.**
-  `rows` is array-of-arrays (column-positional), not array-of-objects. The
-  CLI's `query` command renders this; if you're consuming the structured
-  response yourself, zip `columns` and `rows[i]` to get an object.
-- **`explain_readonly_sql` returns the plan as JSON.** Postgres-style
-  textual EXPLAIN is in `plan` if available; structured form may be
-  alongside.
-- **`analyze_slow_queries` returns slow queries with fingerprints, not raw
-  SQL.** Fingerprints are normalized (`?` for literals). Use the
-  `queryId` to feed back into `optimize` flows.
-
----
-
-## Multi-database situations
-
-DeepSQL doesn't support cross-connection JOINs at the SQL layer. If the user
-asks a question that spans DBs:
-
-1. Call `list_connections` to enumerate.
-2. For each relevant DB, call `get_brain_context` and/or `execute_readonly_sql`.
-3. Combine the results in your reasoning, not in SQL.
-
-The CLI's "active connection" pin (`deepsql connections use`) is **not** read
-by MCP tools — it only saves typing for human CLI users. As an MCP client,
-always pass `connectionId` explicitly per call.
-
----
-
-## Authentication & security model
-
-You don't need to manage auth — the MCP server was launched with a saved
-token from `~/.config/deepsql/auth.json`. Every tool call carries that
-token. The token is bound to a specific user identity:
-
-- The user's role and per-connection ACLs are enforced **server-side**.
-  If you call a tool and get an authorization error, surface it to the
-  user — don't retry with different parameters.
-- The user may have **chat-access policies** (plain-English rules
-  attached to a connection). The brain context already reflects them; if
-  a query you generate triggers a policy violation, the backend rejects
-  it. Trust the rejection and ask the user how to proceed.
-- **Read-only is enforced at four independent layers** (client parser,
-  backend parser, per-connection ACL, DB role). Don't try to bypass any of
-  them — each rejection is a real signal that the operation isn't safe.
-
----
-
-## When in doubt
-
-1. Call `list_connections` first if you don't have a connectionId.
-2. Call `get_brain_context` second if you have a question.
-3. Generate your SQL using the names and rules from those calls.
-4. Call `explain_readonly_sql` if performance matters.
-5. Call `execute_readonly_sql` last.
-
-That five-step flow handles 80% of legitimate analytical workloads. Anything
-that doesn't fit this pattern probably warrants asking the user a
-clarifying question instead of guessing.