db-conn-mcp 0.1.0__tar.gz

db_conn_mcp-0.1.0/.cursorrules

@@ -0,0 +1,57 @@
+# AI Agent Rules (CLAUDE.md / .cursorrules)
+
+Welcome, AI Agent (Claude, Agy, Cursor, or otherwise)! 
+When assisting the user with the `db-conn-mcp` project, please strictly adhere to the following rules to maintain the project's core philosophy.
+
+> **Note:** This file is canonical. `CLAUDE.md` and `.cursorrules` are exact copies — when you change a rule, update all three so they stay byte-identical.
+
+## 1. Simplicity First (No Over-engineering)
+- **DO NOT** introduce complex architectures, custom OAuth servers, or JWT minting.
+- **DO NOT** use complex AST parsers to validate read vs. write queries. 
+- **DO** rely on native database features. Read-only enforcement lives inside each dialect (for Postgres v1: set the session read-only with `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;`).
+
+## 2. Code Quality & Standards (Production Grade)
+- **Ruff:** Use `ruff` as the strict standard for all linting and formatting. Ensure all code passes `ruff check` and `ruff format`.
+- **SOLID & KISS:** Code must be highly modular but radically simple. Follow SOLID principles to keep concerns separated (e.g., config parsing vs. database connection vs. MCP transport), but never at the expense of KISS (Keep It Simple, Stupid).
+- **DevX & AgentX:** The codebase must be highly readable and easy to modify for *both* human developers and AI agents. Keep files reasonably small, avoid deep nesting, and use explicit typing (`typing` module) everywhere.
+- **Documentation:** Well-documented from day one. Every class, module, and non-trivial function must have a clear Python docstring.
+
+## 3. Configuration via JSON
+- The single source of truth for database connections is `connections.json`.
+- The schema is a top-level object `{ "connections": [ ... ] }`; each connection has `name`, `dsn`, `mode` (`"read"` or `"write"`), and an optional `yolo` (boolean, default `false`).
+- Feel free to programmatically read, update, or create `connections.json` for the user if they ask you to add a database.
+
+## 4. Technology Stack
+- Keep the project in Python.
+- Use the official `mcp` SDK (`pip install mcp`).
+- Use standard, modern async libraries where applicable (e.g., `asyncpg`).
+- **`pyproject.toml` is the single source of truth for dependencies** — declare all packages there. Do NOT maintain a separate `requirements.txt`.
+- **v1 ships PostgreSQL only**, but all DB-specific code lives behind a `Dialect` abstraction (`dialects/`) so adding MySQL/SQLite later is a single new file. Never leak a specific database's SQL above the dialect layer.
+
+## 5. MCP Transport Modes
+- The application must support both `stdio` and `http` (SSE) transports.
+- Ensure command-line arguments (using `argparse`) dictate which transport is launched.
+
+## 6. Security & Safety
+- **Never log DSNs** or passwords to the console. Connection diagnostics must be **sanitized** — describe the *category* of failure and how to fix it, never echo the DSN, host, user, or password.
+- Treat the `mode` attribute in `connections.json` as an absolute security boundary. If `mode` is `read`, the AI must not be able to bypass it.
+- Writes are gated server-side in this order: `mode` (hard, native) → `yolo` (per-database persisted trust) → `user_consent` (explicit per-operation approval). `yolo` and `user_consent` only relax the *prompt* on a DB that is already `write`; they can NEVER make a `read` DB writable.
+
+## 7. Living Documentation (Always Keep Docs Updated)
+- **ALWAYS, ALWAYS, ALWAYS** keep the docs in sync with decisions. The moment a design, scope, or architecture decision is made or accepted, update the relevant docs in the SAME change — never defer it:
+  - `PRD.md` — product scope, features, tools.
+  - `PLAN.md` — implementation roadmap / phases.
+  - `ARCHITECTURE.md` — components, flows, diagrams.
+  - These rule files (`AGENT_RULES.md` → copied to `CLAUDE.md` and `.cursorrules`) when a rule itself changes.
+- Docs and code must never drift. A change that alters behavior or scope without updating the docs is **incomplete**.
+
+## 8. Commit Hygiene (No Agent Watermarks)
+- **NEVER** add agent/AI watermarks, attributions, or trailers to commits, PRs, or any other output — e.g. no `Co-Authored-By: Claude …`, no "Generated with Claude Code", no 🤖 lines. Commits and messages must read like a normal human developer's work.
+
+## 9. Environment & Sanitation
+- **Always work inside a project-local virtual environment** (`.venv`): `python -m venv .venv`, activate it, and install there. NEVER install dependencies into the global/system Python. `.venv` is git-ignored.
+- **Install from `pyproject.toml`** (the single source of truth — see Rule 4): `pip install -e .`. Do not hand-maintain a `requirements.txt`.
+- **Input sanitation:** validate and safely quote any identifier (database/table/column names) before placing it into catalog/introspection queries — never naive string concatenation. Route user-supplied *values* through driver parameterization. (Raw SQL in `execute_read_query`/`execute_write_query` is intentional and governed by the `mode` → `yolo` → `user_consent` gate.)
+- **Secrets sanitation:** never commit `connections.json` or `.env` (both git-ignored); never print or log DSNs, hosts, or credentials; keep all error/diagnostic output sanitized (see Rule 6).
+
+Follow these rules rigidly to ensure `db-conn-mcp` remains the cleanest, most straightforward open-source database MCP server available.

db_conn_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token stored.
+# Triggers when a GitHub Release is published (create one from a vX.Y.Z tag).
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

db_conn_mcp-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# ---- Local-only files ----
+progress.txt
+
+# ---- Secrets / local config (NEVER commit real DSNs or credentials) ----
+connections.json
+.env
+.env.*
+
+# ---- Python bytecode / caches ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# ---- Virtual environments ----
+.venv/
+venv/
+env/
+ENV/
+
+# ---- Packaging / build artifacts ----
+build/
+dist/
+*.egg
+*.egg-info/
+.eggs/
+wheels/
+
+# ---- Tooling caches ----
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# ---- IDE / OS noise ----
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

db_conn_mcp-0.1.0/AGENT_RULES.md

@@ -0,0 +1,57 @@
+# AI Agent Rules (CLAUDE.md / .cursorrules)
+
+Welcome, AI Agent (Claude, Agy, Cursor, or otherwise)! 
+When assisting the user with the `db-conn-mcp` project, please strictly adhere to the following rules to maintain the project's core philosophy.
+
+> **Note:** This file is canonical. `CLAUDE.md` and `.cursorrules` are exact copies — when you change a rule, update all three so they stay byte-identical.
+
+## 1. Simplicity First (No Over-engineering)
+- **DO NOT** introduce complex architectures, custom OAuth servers, or JWT minting.
+- **DO NOT** use complex AST parsers to validate read vs. write queries. 
+- **DO** rely on native database features. Read-only enforcement lives inside each dialect (for Postgres v1: set the session read-only with `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;`).
+
+## 2. Code Quality & Standards (Production Grade)
+- **Ruff:** Use `ruff` as the strict standard for all linting and formatting. Ensure all code passes `ruff check` and `ruff format`.
+- **SOLID & KISS:** Code must be highly modular but radically simple. Follow SOLID principles to keep concerns separated (e.g., config parsing vs. database connection vs. MCP transport), but never at the expense of KISS (Keep It Simple, Stupid).
+- **DevX & AgentX:** The codebase must be highly readable and easy to modify for *both* human developers and AI agents. Keep files reasonably small, avoid deep nesting, and use explicit typing (`typing` module) everywhere.
+- **Documentation:** Well-documented from day one. Every class, module, and non-trivial function must have a clear Python docstring.
+
+## 3. Configuration via JSON
+- The single source of truth for database connections is `connections.json`.
+- The schema is a top-level object `{ "connections": [ ... ] }`; each connection has `name`, `dsn`, `mode` (`"read"` or `"write"`), and an optional `yolo` (boolean, default `false`).
+- Feel free to programmatically read, update, or create `connections.json` for the user if they ask you to add a database.
+
+## 4. Technology Stack
+- Keep the project in Python.
+- Use the official `mcp` SDK (`pip install mcp`).
+- Use standard, modern async libraries where applicable (e.g., `asyncpg`).
+- **`pyproject.toml` is the single source of truth for dependencies** — declare all packages there. Do NOT maintain a separate `requirements.txt`.
+- **v1 ships PostgreSQL only**, but all DB-specific code lives behind a `Dialect` abstraction (`dialects/`) so adding MySQL/SQLite later is a single new file. Never leak a specific database's SQL above the dialect layer.
+
+## 5. MCP Transport Modes
+- The application must support both `stdio` and `http` (SSE) transports.
+- Ensure command-line arguments (using `argparse`) dictate which transport is launched.
+
+## 6. Security & Safety
+- **Never log DSNs** or passwords to the console. Connection diagnostics must be **sanitized** — describe the *category* of failure and how to fix it, never echo the DSN, host, user, or password.
+- Treat the `mode` attribute in `connections.json` as an absolute security boundary. If `mode` is `read`, the AI must not be able to bypass it.
+- Writes are gated server-side in this order: `mode` (hard, native) → `yolo` (per-database persisted trust) → `user_consent` (explicit per-operation approval). `yolo` and `user_consent` only relax the *prompt* on a DB that is already `write`; they can NEVER make a `read` DB writable.
+
+## 7. Living Documentation (Always Keep Docs Updated)
+- **ALWAYS, ALWAYS, ALWAYS** keep the docs in sync with decisions. The moment a design, scope, or architecture decision is made or accepted, update the relevant docs in the SAME change — never defer it:
+  - `PRD.md` — product scope, features, tools.
+  - `PLAN.md` — implementation roadmap / phases.
+  - `ARCHITECTURE.md` — components, flows, diagrams.
+  - These rule files (`AGENT_RULES.md` → copied to `CLAUDE.md` and `.cursorrules`) when a rule itself changes.
+- Docs and code must never drift. A change that alters behavior or scope without updating the docs is **incomplete**.
+
+## 8. Commit Hygiene (No Agent Watermarks)
+- **NEVER** add agent/AI watermarks, attributions, or trailers to commits, PRs, or any other output — e.g. no `Co-Authored-By: Claude …`, no "Generated with Claude Code", no 🤖 lines. Commits and messages must read like a normal human developer's work.
+
+## 9. Environment & Sanitation
+- **Always work inside a project-local virtual environment** (`.venv`): `python -m venv .venv`, activate it, and install there. NEVER install dependencies into the global/system Python. `.venv` is git-ignored.
+- **Install from `pyproject.toml`** (the single source of truth — see Rule 4): `pip install -e .`. Do not hand-maintain a `requirements.txt`.
+- **Input sanitation:** validate and safely quote any identifier (database/table/column names) before placing it into catalog/introspection queries — never naive string concatenation. Route user-supplied *values* through driver parameterization. (Raw SQL in `execute_read_query`/`execute_write_query` is intentional and governed by the `mode` → `yolo` → `user_consent` gate.)
+- **Secrets sanitation:** never commit `connections.json` or `.env` (both git-ignored); never print or log DSNs, hosts, or credentials; keep all error/diagnostic output sanitized (see Rule 6).
+
+Follow these rules rigidly to ensure `db-conn-mcp` remains the cleanest, most straightforward open-source database MCP server available.

db_conn_mcp-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,312 @@
+# Architecture: `db-conn-mcp`
+
+This document shows how `db-conn-mcp` is structured and traces the **end-to-end flow**, from a user setting up a connection on the CLI, through an AI agent exploring and querying the database, to the write-safety gate that protects their data.
+
+> **v1 scope:** PostgreSQL only. The code is built around a **dialect seam** so adding MySQL / SQLite later is a *one-file* job. See [Extensibility](#extensibility-adding-a-database).
+
+---
+
+## 1. Component Overview
+
+```
+                            ┌──────────────────────────────────────────┐
+   ┌──────────────┐         │              db-conn-mcp                  │
+   │  AI Agent    │  MCP    │  server.py  ── 8 tools + 1 prompt        │
+   │ (Claude,     │◄───────►│      │                                   │
+   │  Cursor, …)  │ stdio/  │      ├─► safety.py      ── write-gate     │
+   └──────────────┘  http   │      │                                   │
+                            │      ├─► diagnostics.py ── doctor /       │
+   ┌──────────────┐         │      │     sanitized error → cause + fix  │
+   │  Human user  │  CLI    │      ▼                                   │
+   │ (terminal)   │────────►│  dialects/   ── Postgres SQL + RO guard  │
+   └──────────────┘ setup   │   (registry) │        config.py ◄─ conns │
+                            └──────┼───────────────────────│──────────┘
+                                   ▼                        ▼
+                            ┌─────────────┐         ┌────────────────┐
+                            │ PostgreSQL  │         │connections.json│
+                            └─────────────┘         └────────────────┘
+```
+
+### Module responsibilities (single-purpose layers)
+
+| Module | Responsibility | Knows about Postgres? |
+|---|---|---|
+| `cli.py` | Parse args (`--config`, `--transport`); run server or a management subcommand (`setup`/`status`/`add`/`clients`/`remove`/`yolo`); detect & inject MCP clients | No |
+| `config.py` | Resolve, load, validate, **and save** `connections.json` | No |
+| `models.py` | Pydantic types: `Connection{name, dsn, mode, yolo}`, `Config` | No |
+| `dialects/base.py` | The `Dialect` ABC — the extensibility contract | No |
+| `dialects/postgres.py` | `asyncpg` impl + native read-only enforcement | **Yes (only here)** |
+| `dialects/registry.py` | Map DSN scheme → `Dialect`; clear error on unknown scheme | No |
+| `safety.py` | Pure write-gate decision (`mode` + `yolo` + `consent`) | No |
+| `diagnostics.py` | Classify driver errors → **sanitized** cause + fix; the doctor | No |
+| `handlers.py` | The 8 tool handlers as plain async methods (transport-free, unit-testable) | No |
+| `server.py` | `FastMCP` app: registers the 8 tools + the prompt onto `handlers`, transport wiring | No |
+
+The **dialect layer is the only place that knows a database is PostgreSQL.** Everything above it speaks the abstract `Dialect` contract.
+
+---
+
+## 2. The Tools an Agent Sees
+
+| # | Tool | Kind | Safety |
+|---|---|---|---|
+| 1 | `list_databases` | Explore | safe — names + mode + yolo |
+| 2 | `list_tables` | Explore | safe |
+| 3 | `get_table_schema` | Explore | safe |
+| 4 | `sample_table_rows` | Explore | safe (first N rows) |
+| 5 | `execute_read_query` | Execute | runs inside a **read-only transaction** |
+| 6 | `execute_write_query` | Execute | **gated** (mode → yolo → consent) |
+| 7 | `set_yolo_mode` | Config | persists `yolo` flag for one named DB |
+| 8 | `check_database` | Doctor | tests one DB (or all) → `OK` or sanitized cause + fix |
+
+Plus **one MCP prompt** — `troubleshoot_connection` — a discoverable, full connection-gotchas checklist the agent can pull when a DB won't connect (see [§7](#7-flow-e--self-diagnosing-connections-the-doctor)).
+
+---
+
+## 3. Flow A — Setup (human, on the CLI)
+
+A human runs the wizard once to register a database. This is the *only* step that handles a raw DSN.
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant CLI as setup wizard (cli.py)
+    participant Cfg as config.py
+    participant FS as connections.json
+
+    User->>CLI: python -m db_conn_mcp setup
+    CLI->>User: Scope? (global ~/.db-conn-mcp  |  repo ./)
+    User-->>CLI: global
+    CLI->>User: Name? DSN? Mode (read/write)?
+    User-->>CLI: "prod", "postgresql://…", "read"
+    CLI->>Cfg: add_connection(Connection)
+    Cfg->>Cfg: validate (pydantic + scheme is known)
+    Cfg->>FS: write connections.json  (yolo defaults to false)
+    CLI->>User: ✅ registered. Inject into Claude/Cursor config? (y/n)
+    Note over CLI,FS: DSN is never logged — only the name is echoed.
+```
+
+Resulting `connections.json`:
+```json
+{
+  "connections": [
+    { "name": "prod", "dsn": "postgresql://…", "mode": "read" },
+    { "name": "dev",  "dsn": "postgresql://…", "mode": "write", "yolo": false }
+  ]
+}
+```
+
+**Config resolution order** (first match wins): `--config <path>` → `./connections.json` → `~/.db-conn-mcp/connections.json`.
+
+---
+
+## 4. Flow B — Agent explores, then runs a READ query
+
+The everyday safe path. The agent discovers what exists, learns the schema, then queries.
+
+```mermaid
+sequenceDiagram
+    actor Agent
+    participant Server as server.py
+    participant Reg as dialects/registry
+    participant PG as PostgresDialect
+    participant DB as PostgreSQL
+
+    Agent->>Server: list_databases()
+    Server-->>Agent: [{prod, read}, {dev, write, yolo:false}]
+
+    Agent->>Server: list_tables(db="prod")
+    Server->>Reg: dialect_for("postgresql://…")
+    Reg-->>Server: PostgresDialect
+    Server->>PG: connect(dsn, read_only=true)
+    PG->>DB: SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY
+    PG->>DB: query information_schema
+    DB-->>Agent: [users, orders, …]
+
+    Agent->>Server: get_table_schema(db="prod", table="orders")
+    Server->>PG: get_schema(conn, "orders")
+    PG-->>Agent: columns, types, PK/FK
+
+    Agent->>Server: execute_read_query(db="prod", sql="SELECT …")
+    Server->>PG: connect(read_only=true) → execute(sql)
+    Note over PG,DB: A write here would be rejected by Postgres itself.
+    DB-->>Agent: rows
+```
+
+Read-only is enforced **natively by the database** — even a `read`-mode connection physically cannot mutate data, regardless of what SQL is sent.
+
+---
+
+## 5. Flow C — Agent runs a WRITE query (the safety gate)
+
+This is the heart of the safety model. The decision lives **in the server**, not in the agent's good intentions.
+
+```mermaid
+flowchart TD
+    A[execute_write_query db, sql, user_consent] --> B{db.mode == write?}
+    B -- no --> R1[❌ REJECT: db is read-only]
+    B -- yes --> C{db.yolo == true?}
+    C -- yes --> RUN[✅ run write SQL]
+    C -- no --> D{user_consent == true?}
+    D -- yes --> RUN
+    D -- no --> R2[❌ REJECT:<br/>'Read the table & schema, show the<br/>exact SQL to the user, get a yes,<br/>then call again with user_consent=true']
+```
+
+The intended agent choreography for a non-yolo write:
+
+```mermaid
+sequenceDiagram
+    actor User
+    actor Agent
+    participant Server as server.py
+    participant PG as PostgresDialect
+    participant DB as PostgreSQL
+
+    Note over Agent: 1. Understand before changing
+    Agent->>Server: get_table_schema(db="dev", table="users")
+    Server->>PG: get_schema → columns/types
+    PG-->>Agent: schema
+    Agent->>Server: sample_table_rows(db="dev", table="users")
+    PG-->>Agent: example rows (learn the data shape)
+
+    Note over Agent,User: 2. First call WITHOUT consent — server forces the ask
+    Agent->>Server: execute_write_query(db="dev", sql="UPDATE users SET …", user_consent=false)
+    Server-->>Agent: ❌ REJECT — show SQL to user, get explicit yes
+
+    Agent->>User: "I will run:  UPDATE users SET … (affects ~3 rows). Proceed?"
+    User-->>Agent: "yes"
+
+    Note over Agent,DB: 3. Re-call WITH consent
+    Agent->>Server: execute_write_query(db="dev", sql="UPDATE users SET …", user_consent=true)
+    Server->>PG: connect(read_only=false) → execute(sql)
+    DB-->>Agent: rows affected
+```
+
+`mode` is the **hard boundary** (native, unbypassable). `yolo` and `user_consent` only relax the *prompt* on a DB that is *already* `write` — they can never make a `read` DB writable.
+
+---
+
+## 6. Flow D — Enabling YOLO mode (persisted)
+
+When the user is tired of confirming every write on a trusted DB, they ask the agent to enable yolo. The server writes it back to disk so it survives restarts.
+
+```mermaid
+sequenceDiagram
+    actor User
+    actor Agent
+    participant Server as server.py
+    participant Cfg as config.py
+    participant FS as connections.json
+
+    User->>Agent: "Enable yolo mode for dev — stop asking me."
+    Agent->>Server: set_yolo_mode(database="dev", enabled=true)
+    Server->>Cfg: set_yolo("dev", true)
+    Cfg->>FS: rewrite connections.json (dev.yolo = true)
+    Server-->>Agent: ✅ yolo enabled for "dev" (persisted)
+
+    Note over Agent,FS: Future writes to "dev" skip the consent gate —<br/>across this and all future sessions.
+```
+
+`set_yolo_mode("dev", false)` reverts it. YOLO is **per-database**: enabling it on `dev` never affects `prod`.
+
+---
+
+## 7. Flow E — Self-diagnosing connections (the doctor)
+
+Connections are validated **lazily**: the server boots even if a database is down, and *any* tool that hits an unreachable DB gets a sanitized, actionable diagnostic instead of a raw stack trace. The agent (or user) can also probe proactively with `check_database`.
+
+```mermaid
+sequenceDiagram
+    actor Agent
+    participant Server as server.py
+    participant Diag as diagnostics.py
+    participant PG as PostgresDialect
+    participant DB as PostgreSQL
+
+    Agent->>Server: check_database(name="prod")
+    Server->>PG: connect(dsn, read_only=true)
+    PG->>DB: TCP connect / auth
+    DB--xPG: error (refused / auth / no-db / SSL / timeout)
+    PG-->>Server: raises driver exception
+    Server->>Diag: explain(error)  ⟵ DSN/password NEVER passed in
+    Diag-->>Server: {category, cause, fixes[]}
+    Server-->>Agent: "❌ prod unreachable — AUTH FAILED.<br/>Likely: wrong user/password or role missing.<br/>Fix: verify credentials; confirm the role exists.<br/>(full checklist: prompt 'troubleshoot_connection')"
+    Note over Agent: For the complete gotchas list:
+    Agent->>Server: getPrompt("troubleshoot_connection")
+    Server-->>Agent: full host/port/firewall/sslmode/<br/>container-localhost/db-name/pool checklist
+```
+
+**Error classification** (`diagnostics.py` maps driver exception → sanitized advice — credentials never appear in the output):
+
+| Category | Triggered by (examples) | Sanitized cause + fix shown to agent |
+|---|---|---|
+| `AUTH_FAILED` | invalid password / role does not exist | "Wrong user/password, or the role doesn't exist. Verify credentials and that the role exists." |
+| `HOST_UNREACHABLE` | connection refused / timeout | "DB not accepting connections. Is it running? Check host/port, firewall. In Docker, `localhost` ≠ the DB container." |
+| `DB_NOT_FOUND` | database "x" does not exist | "Database name is wrong or not created yet. Check spelling/case; create it if needed." |
+| `DNS_FAILURE` | could not translate host name | "Hostname can't be resolved — likely a typo in the host or a missing VPN/network." |
+| `SSL_REQUIRED` | server requires SSL | "Server demands SSL. Add `?sslmode=require` (or appropriate mode) to the DSN." |
+| `POOL_EXHAUSTED` | too many connections | "Connection limit hit. Close idle sessions or raise the server's `max_connections`." |
+| `UNKNOWN` | anything unmatched | "Unrecognized connection error. See the `troubleshoot_connection` prompt for the full checklist." |
+
+The **`troubleshoot_connection` MCP prompt** is the standalone, full gotchas checklist — discoverable by the agent at any time, not just on error. Targeted fixes appear inline per error; the prompt is the complete reference.
+
+> **Security:** `diagnostics.explain()` receives only the *driver exception type/message-class* — never the `Connection` object or DSN — so no host, user, or password can leak into a tool response or log.
+
+---
+
+## 8. Extensibility — Adding a Database
+
+Adding MySQL or SQLite later touches **exactly one new file** plus a one-line registration. Nothing above the dialect layer changes.
+
+```mermaid
+flowchart LR
+    subgraph Today [v1 — today]
+        REG[registry] --> PGD[postgres.py]
+    end
+    subgraph Later [adding MySQL]
+        REG2[registry<br/>+1 line] --> PGD2[postgres.py]
+        REG2 -.new file.-> MYD[mysql.py]
+    end
+    Today ==> Later
+```
+
+The contract a new dialect must satisfy:
+
+```python
+class Dialect(ABC):
+    scheme: str                                       # e.g. "mysql"
+    async def connect(self, dsn, *, read_only): ...   # native read-only enforcement lives here
+    async def list_tables(self, conn): ...
+    async def get_schema(self, conn, table): ...
+    async def sample_rows(self, conn, table, n=10): ...
+    async def execute(self, conn, sql): ...
+```
+
+| DB | Read-only mechanism (inside `connect`) | Introspection source |
+|---|---|---|
+| PostgreSQL (v1) | `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` | `information_schema` |
+| MySQL (future) | `START TRANSACTION READ ONLY` | `information_schema` |
+| SQLite (future) | open file with `?mode=ro` | `sqlite_master` / `PRAGMA` |
+
+Because each dialect owns its own read-only enforcement and catalog queries, those per-database differences **never leak** into `safety.py` or `server.py`.
+
+---
+
+## 9. End-to-End at a Glance
+
+```
+Human ──setup──► connections.json ──read──► config.py
+                                              │
+AI Agent ──MCP (stdio/http)──► server.py ─────┼─► safety.py     (write gate)
+                                  │            ├─► diagnostics.py (doctor, sanitized)
+                                  ▼            ▼
+                              dialects/registry ──► PostgresDialect ──► PostgreSQL
+                                (scheme → impl)      (RO guard + SQL)
+```
+
+1. A human registers a DB once via the CLI wizard → `connections.json`.
+2. An agent connects over MCP and **explores** (`list_*`, `get_table_schema`, `sample_table_rows`) — always read-only.
+3. **Reads** run inside a native read-only transaction.
+4. **Writes** pass through the server-side gate: `mode` (hard) → `yolo` (persisted trust) → `user_consent` (per-op ask).
+5. `set_yolo_mode` lets a trusted DB skip the per-op ask, persisted to disk.
+6. Any unreachable DB yields a **sanitized diagnostic** (cause + fix), never a raw error or leaked DSN; `check_database` probes proactively and `troubleshoot_connection` is the full gotchas checklist.

db_conn_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,57 @@
+# AI Agent Rules (CLAUDE.md / .cursorrules)
+
+Welcome, AI Agent (Claude, Agy, Cursor, or otherwise)! 
+When assisting the user with the `db-conn-mcp` project, please strictly adhere to the following rules to maintain the project's core philosophy.
+
+> **Note:** This file is canonical. `CLAUDE.md` and `.cursorrules` are exact copies — when you change a rule, update all three so they stay byte-identical.
+
+## 1. Simplicity First (No Over-engineering)
+- **DO NOT** introduce complex architectures, custom OAuth servers, or JWT minting.
+- **DO NOT** use complex AST parsers to validate read vs. write queries. 
+- **DO** rely on native database features. Read-only enforcement lives inside each dialect (for Postgres v1: set the session read-only with `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;`).
+
+## 2. Code Quality & Standards (Production Grade)
+- **Ruff:** Use `ruff` as the strict standard for all linting and formatting. Ensure all code passes `ruff check` and `ruff format`.
+- **SOLID & KISS:** Code must be highly modular but radically simple. Follow SOLID principles to keep concerns separated (e.g., config parsing vs. database connection vs. MCP transport), but never at the expense of KISS (Keep It Simple, Stupid).
+- **DevX & AgentX:** The codebase must be highly readable and easy to modify for *both* human developers and AI agents. Keep files reasonably small, avoid deep nesting, and use explicit typing (`typing` module) everywhere.
+- **Documentation:** Well-documented from day one. Every class, module, and non-trivial function must have a clear Python docstring.
+
+## 3. Configuration via JSON
+- The single source of truth for database connections is `connections.json`.
+- The schema is a top-level object `{ "connections": [ ... ] }`; each connection has `name`, `dsn`, `mode` (`"read"` or `"write"`), and an optional `yolo` (boolean, default `false`).
+- Feel free to programmatically read, update, or create `connections.json` for the user if they ask you to add a database.
+
+## 4. Technology Stack
+- Keep the project in Python.
+- Use the official `mcp` SDK (`pip install mcp`).
+- Use standard, modern async libraries where applicable (e.g., `asyncpg`).
+- **`pyproject.toml` is the single source of truth for dependencies** — declare all packages there. Do NOT maintain a separate `requirements.txt`.
+- **v1 ships PostgreSQL only**, but all DB-specific code lives behind a `Dialect` abstraction (`dialects/`) so adding MySQL/SQLite later is a single new file. Never leak a specific database's SQL above the dialect layer.
+
+## 5. MCP Transport Modes
+- The application must support both `stdio` and `http` (SSE) transports.
+- Ensure command-line arguments (using `argparse`) dictate which transport is launched.
+
+## 6. Security & Safety
+- **Never log DSNs** or passwords to the console. Connection diagnostics must be **sanitized** — describe the *category* of failure and how to fix it, never echo the DSN, host, user, or password.
+- Treat the `mode` attribute in `connections.json` as an absolute security boundary. If `mode` is `read`, the AI must not be able to bypass it.
+- Writes are gated server-side in this order: `mode` (hard, native) → `yolo` (per-database persisted trust) → `user_consent` (explicit per-operation approval). `yolo` and `user_consent` only relax the *prompt* on a DB that is already `write`; they can NEVER make a `read` DB writable.
+
+## 7. Living Documentation (Always Keep Docs Updated)
+- **ALWAYS, ALWAYS, ALWAYS** keep the docs in sync with decisions. The moment a design, scope, or architecture decision is made or accepted, update the relevant docs in the SAME change — never defer it:
+  - `PRD.md` — product scope, features, tools.
+  - `PLAN.md` — implementation roadmap / phases.
+  - `ARCHITECTURE.md` — components, flows, diagrams.
+  - These rule files (`AGENT_RULES.md` → copied to `CLAUDE.md` and `.cursorrules`) when a rule itself changes.
+- Docs and code must never drift. A change that alters behavior or scope without updating the docs is **incomplete**.
+
+## 8. Commit Hygiene (No Agent Watermarks)
+- **NEVER** add agent/AI watermarks, attributions, or trailers to commits, PRs, or any other output — e.g. no `Co-Authored-By: Claude …`, no "Generated with Claude Code", no 🤖 lines. Commits and messages must read like a normal human developer's work.
+
+## 9. Environment & Sanitation
+- **Always work inside a project-local virtual environment** (`.venv`): `python -m venv .venv`, activate it, and install there. NEVER install dependencies into the global/system Python. `.venv` is git-ignored.
+- **Install from `pyproject.toml`** (the single source of truth — see Rule 4): `pip install -e .`. Do not hand-maintain a `requirements.txt`.
+- **Input sanitation:** validate and safely quote any identifier (database/table/column names) before placing it into catalog/introspection queries — never naive string concatenation. Route user-supplied *values* through driver parameterization. (Raw SQL in `execute_read_query`/`execute_write_query` is intentional and governed by the `mode` → `yolo` → `user_consent` gate.)
+- **Secrets sanitation:** never commit `connections.json` or `.env` (both git-ignored); never print or log DSNs, hosts, or credentials; keep all error/diagnostic output sanitized (see Rule 6).
+
+Follow these rules rigidly to ensure `db-conn-mcp` remains the cleanest, most straightforward open-source database MCP server available.

db_conn_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 db-conn-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.