@deepsql/mcp 0.8.0 → 0.10.1

package/AGENT-SETUP.md

@@ -0,0 +1,289 @@
+# DeepSQL — agent-driven setup
+
+> Paste this file's content into Claude Code, Codex CLI, Cursor, or any
+> agent capable of running shell commands. The agent will install, log in,
+> register your databases, and wire DeepSQL into your editor — typically in
+> under 5 minutes. Each step has a clear "exit on failure" so the agent
+> won't paper over real problems.
+
+You are setting up DeepSQL for the user. DeepSQL is a self-hosted AI database
+performance assistant. The goal of this conversation is to install the CLI,
+authorize it against the user's DeepSQL host, register one or more database
+connections, and wire the MCP integration into the user's editor.
+
+**Throughout setup, never echo passwords back to the user, never write
+secrets to a tracked file, and clean up tempfiles you create.** When you
+need credentials, ask one question at a time and stop typing them in
+clear text once they're in your head.
+
+---
+
+## Step 1 — Install the CLI
+
+```bash
+npm install -g @deepsql/mcp@latest
+deepsql --version
+```
+
+Confirm Node ≥ 20. If the install fails, ask the user about their npm
+permissions and recommend `npm config set prefix '~/.npm-global'` if it's
+an EACCES on `/usr/local`.
+
+---
+
+## Step 2 — Log in to DeepSQL
+
+Ask the user for their DeepSQL host URL (e.g., `https://deepsql.example.com`).
+Then:
+
+```bash
+deepsql login --url <host>
+```
+
+This opens a browser tab against the user's DeepSQL host. The user clicks
+**Approve** on the device-authorization page; the CLI receives a token and
+saves it to `~/.config/deepsql/auth.json` (mode 0600).
+
+If the user is on a remote/SSH box without a browser, fall back to:
+
+```bash
+deepsql login --url <host> --device
+```
+
+The CLI prints a code; the user opens the URL on their laptop and approves.
+
+Verify:
+
+```bash
+deepsql whoami
+```
+
+Should print the username, role, URL. If it doesn't, stop and surface the
+error to the user — don't proceed with setup.
+
+---
+
+## Step 3 — Inspect the connection config schema
+
+```bash
+deepsql connections schema --json
+```
+
+This prints the JSON Schema for the connection config. Use it as the
+contract for the next step. **Required fields:** `connectionName`, `dbType`
+(`postgres` | `mysql`), `host`, `port`, `database`, `username`, `password`.
+**Conditional fields:** `sshEnabled` triggers `sshHost`/`sshUsername` and
+either `sshPassword` or `sshPrivateKey`. `sslMode` (`server-only` |
+`server-client`) triggers SSL-cert fields.
+
+---
+
+## Step 4 — Gather credentials
+
+Ask the user about each database they want to connect to. For each one:
+
+1. **Friendly name** (will be shown in the CLI everywhere)
+2. **Database engine** — `postgres` or `mysql`
+3. **Host** and **port** (defaults: 5432 for postgres, 3306 for mysql)
+4. **Database name** and **username**
+5. **Password** — collect securely; do not paste it back into chat
+6. **SSH bastion?** If yes: SSH host, port (22), user, key path or password
+7. **SSL?** If yes: which mode, and the cert paths if `server-client`
+8. **Cloud metadata** (optional but improves DeepSQL's tuning advice):
+   AWS / Azure / GCP / self-hosted, managed service (RDS / Aurora / etc.),
+   instance class, vCPU / memory / storage type / IOPS
+
+For each connection, write a tempfile with `mktemp`, set mode 0600, and
+keep it short-lived. **Never write the JSON to a path the user has open in
+their editor or that lives inside a git repo.** Use this exact pattern:
+
+```bash
+tmp=$(mktemp /tmp/deepsql-conn-XXXXXX.json)
+chmod 600 "$tmp"
+cat > "$tmp" <<'EOF'
+{
+  "connectionName": "prod-mysql",
+  "dbType": "mysql",
+  "host": "db.example.com",
+  "port": 3306,
+  "database": "myapp",
+  "username": "deepsql_reader",
+  "password": "REPLACE_BEFORE_RUNNING",
+
+  "sshEnabled": true,
+  "sshAuthType": "PRIVATE_KEY",
+  "sshHost": "bastion.example.com",
+  "sshPort": 22,
+  "sshUsername": "ec2-user",
+  "sshPrivateKey": "@file:~/.ssh/bastion_ed25519",
+
+  "sslMode": "server-only",
+
+  "cloudProvider": "aws",
+  "managedService": "rds",
+  "instanceClass": "db.r6g.xlarge",
+  "instanceVcpus": 4,
+  "instanceMemoryGb": 32.0,
+  "storageType": "gp3"
+}
+EOF
+```
+
+Notes on the secret refs supported in any string field:
+
+- `"$VAR_NAME"` — pulled from `process.env` at CLI runtime, never persisted.
+- `"@file:<path>"` — file contents read at runtime; mode 0600 enforced.
+- Plaintext is allowed but warns if the JSON file is in a git tree.
+
+The `mktemp` path is guaranteed to be outside any tracked directory, so the
+plaintext warning won't fire — and the file gets deleted next.
+
+---
+
+## Step 5 — Test, save, wait
+
+Always test before saving:
+
+```bash
+deepsql connections test --from-file "$tmp"
+```
+
+The output is a privilege report: `✓` for granted privileges, `✗` for
+missing ones, plus `connectionSuccessful` and `sshTunnelSuccessful` flags.
+**Stop if `connectionSuccessful=false`.** Common causes:
+
+- Wrong host / port → user fixes the JSON
+- Bad SSH key path → check `@file:~/.ssh/...` permissions (must be 0600)
+- Bad password → user re-enters
+- Missing privileges → DeepSQL still saves (read-only privileges are
+  enough), but flag the warning to the user so they know which features
+  may be limited
+
+If the test passes, save it:
+
+```bash
+deepsql connections add --from-file "$tmp" --delete-after --wait
+```
+
+`--delete-after` removes the tempfile on success. `--wait` polls
+`GET /connections/{id}/init-status` until brain initialization completes
+(or fails). This can take a few minutes on large databases — DeepSQL is
+ingesting the schema and indexing it for retrieval. Don't proceed until
+this finishes successfully.
+
+---
+
+## Step 6 — Pin the primary connection
+
+```bash
+deepsql connections use <connectionName>
+```
+
+This sets the active default for the profile. Every subsequent command
+(`deepsql brain-context`, `deepsql query`, `deepsql digest`, etc.) uses it
+automatically — the user no longer has to pass `--connection`.
+
+If the user has more than one connection, ask which they want pinned. They
+can switch later with another `connections use`.
+
+---
+
+## Step 7 — Wire the MCP integration into the editor
+
+> *Coming in `0.11.0`: `deepsql mcp config --install --for cursor|claude-code|codex`.*
+> *Until then, use the manual steps below.*
+
+For **Claude Code**: edit `~/.claude/settings.json` and add an `mcpServers`
+entry:
+
+```json
+{
+  "mcpServers": {
+    "deepsql": {
+      "command": "deepsql",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+For **Cursor**: edit `~/.cursor/mcp.json` with the same shape.
+
+For **Codex CLI**: see `~/.codex/config.toml` — a `[mcp_servers.deepsql]`
+section with `command = "deepsql"` and `args = ["mcp"]`.
+
+The CLI's saved auth token at `~/.config/deepsql/auth.json` is used
+automatically — no token needs to be embedded in the editor config.
+
+---
+
+## Step 8 — Validate end-to-end
+
+```bash
+deepsql brain-context "list a few tables on this database" --top-k 5 --json
+```
+
+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:
+
+```bash
+deepsql brain-context "what is the primary fact table for orders" --top-k 5
+```
+
+If retrieval works, 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`,
+  `analyze_slow_queries`, etc. are all available there).
+- 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.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Diagnose with |
+|---|---|---|
+| `deepsql login` opens browser but never returns | User closed the tab without clicking Approve | Re-run `deepsql login`. Tell the user to click **Approve** on the page. |
+| `whoami` shows wrong user | Stale cached profile from a prior install | `deepsql logout` then `deepsql login --url <host>` |
+| `connections test` fails: "DNS resolution" | Host typo or VPC-local hostname not reachable | Verify the host with `dig`/`nslookup`, or set up SSH tunnel |
+| `connections test` fails: "SSH tunnel connection failed" | Wrong SSH host, wrong key file path, or key file mode > 600 | `ssh -i ~/.ssh/<key> ec2-user@<host>` to validate the bastion manually |
+| `connections add` returns "Missing privileges: SELECT, ..." | DB user has insufficient grants | Save still succeeds; ask the user to grant the missing privileges |
+| `connections add --wait` polls forever | Brain init is genuinely running on a huge DB | Default cap is 30 min. Pass `--wait-timeout 60m` or just `Ctrl-C` (init keeps running on the backend) |
+| `brain-context` returns `skipped: simple_schema_question` | The question was too short / too schema-y | Ask a more semantic question, or pass `--top-k 5` to force ranked retrieval |
+| `connections add` errors before contacting the backend | JSON validation failed | Read the `path: message` lines in the error; fix the JSON; re-run |
+
+---
+
+## Idempotency / re-runs
+
+This entire flow is safe to re-run. `connections use` is idempotent. To
+update an existing connection:
+
+```bash
+deepsql connections add --from-file "$tmp" --upsert --delete-after --wait
+```
+
+`--upsert` does PUT instead of POST when a name collision exists; the
+backend's PATCH-style merge preserves any secrets you don't include in
+the new JSON.
+
+To remove a connection:
+
+```bash
+deepsql connections remove <connectionName> --yes
+```
+
+If it was the active default, the pin is cleared automatically.
+
+---
+
+## Reference
+
+- `deepsql --help` — full command list
+- `deepsql connections schema [--json]` — full input contract
+- `node_modules/@deepsql/mcp/CLAUDE.md` — runtime guidance for AI agents
+  using DeepSQL's MCP tools
+- `https://github.com/DeepSQLAI/dba-agent` — source repo (private)

package/CLAUDE.md

@@ -0,0 +1,330 @@
+# 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepsql/mcp",
-  "version": "0.8.0",
+  "version": "0.10.1",
   "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
   "bin": {
     "deepsql": "./bin/deepsql.js",
@@ -9,6 +9,8 @@
   "main": "./deepsql-phase1-server.js",
   "files": [
     "README.md",
+    "CLAUDE.md",
+    "AGENT-SETUP.md",
     "bin",
     "src",
     "deepsql-phase1-server.js",

package/src/auth/store.js

@@ -11,10 +11,18 @@
  *   {
  *     "default": "http://localhost:8080",
  *     "profiles": {
- *       "<base-url>": { token, username, tokenId, createdAt }
+ *       "<base-url>": {
+ *         token, username, tokenId, createdAt,
+ *         defaultConnection?: "<connection-name-or-uuid>"
+ *       }
  *     }
  *   }
  *
+ * `defaultConnection` is the active connection for commands that need one
+ * (query/explain/schema/digest/slow-queries/brain-*). Set via
+ * `deepsql connections use <name>`. Resolution order in commands:
+ *   --connection flag  →  DEEPSQL_CONNECTION env  →  profile.defaultConnection
+ *
  * The file is written with mode 0600 and the parent dir with 0700. We refuse to
  * read a file with looser perms unless DEEPSQL_INSECURE_AUTH=1 is set, since
  * tokens grant access to the user's databases.
@@ -133,6 +141,27 @@ function defaultBaseUrl() {
   return state.default || null;
 }
 
+function getDefaultConnection(baseUrl) {
+  const profile = getProfile(baseUrl);
+  return profile && profile.defaultConnection ? profile.defaultConnection : null;
+}
+
+function setDefaultConnection(baseUrl, connectionName) {
+  const state = load();
+  const key = normalizeBaseUrl(baseUrl);
+  if (!state.profiles[key]) {
+    throw new Error(
+      `No profile saved for ${key}. Run \`deepsql login --url ${key}\` first.`,
+    );
+  }
+  if (connectionName == null || connectionName === "") {
+    delete state.profiles[key].defaultConnection;
+  } else {
+    state.profiles[key].defaultConnection = connectionName;
+  }
+  save(state);
+}
+
 function listProfiles() {
   return load();
 }
@@ -141,6 +170,7 @@ module.exports = {
   authFilePath,
   configDir,
   defaultBaseUrl,
+  getDefaultConnection,
   getProfile,
   listProfiles,
   load,
@@ -148,5 +178,6 @@ module.exports = {
   removeProfile,
   save,
   setDefault,
+  setDefaultConnection,
   setProfile,
 };