mcp-database CLAUDE.md

CLAUDE.md

Multi-database MCP server (PostgreSQL, MySQL, MariaDB, SQLite, MongoDB, Redis) over stdio. Python 3.12, managed with uv.

• References: docs/architecture.md (decisions, component map, request flow, failure modes, runbook), docs/tools.md (39 tools, per-engine support), docs/configuration.md, docs/connections.md (per-engine local/external examples), docs/examples/.
• temp/ is gitignored scratch space
• scripts/ holds standalone dev/build scripts (see scripts/README.md); never import from it in src/ or tests/.

Commands

make install            # uv sync
make lint               # ruff check + format check (must pass clean)
make fmt                # autofix + reformat
make test-unit          # fast: tests/unit + tests/e2e, no Docker
make test-integration   # real databases via testcontainers (requires Docker)
make test-cluster       # multi-node topologies incl. failure scenarios (crash/failover/quorum); own CI job, never in the coverage gate
make test               # full suite; 95% coverage gate; HTML report in temp/reports/coverage/
make up && make mongo-rs && make seed  # playground + seed data (pgvector pg; host ports: mysql 3306, mariadb 3307, mongo 27019, redis 6380; sqlite → temp/playground.db)
make atlas-local && make atlas-seed    # optional: mongodb-atlas-local (mongot) on port 27018
make evals              # one-shot agent evals via the logged-in claude CLI; reports in temp/reports/
make run                # run the server against the playground PostgreSQL
uv run pytest tests/unit/test_guard_sql.py -k name  # single test

Architecture

Full picture in docs/architecture.md. Map:

• entry.py — env-only config, no CLI: one connection per instance (URI required); more databases = more MCP entries.
• server.py — build_server only: assembles FastMCP, applies TOOLS/DISABLE_TOOLS, lifespan closes pools (the only close hook).
• tools/ — one module per risk class (schema.py, read.py, perf.py, write_admin.py) + params.py + context.py (ToolContext orchestrates validation, timeout, audit); perf.py's pure section-to-findings summarizers live in perf_summary.py. Prefix encodes risk: db_schema_/db_read_/db_perf_ never write; db_write_/db_admin_ are destructive and audited.
• guard.py — all authorization and query validation, fail-closed. SQL via sqlglot (_DIALECTS); MongoDB and Redis via envelope allowlists (helpers/mongo_query.py, helpers/redis_query.py).
• adapters/ — Adapter ABC + shared SQLAdapter in base.py; engine features declared in CAPABILITIES. Every engine is a package: the full engines (postgres/, mysql/, mongodb/, sqlite/, redis/) are split by area into mixins mirroring tools/ (schema.py/read.py/perf.py/write.py + optional _common.py, composed in __init__.py); mariadb/ holds only its MySQLAdapter overrides in __init__.py (no mixins — it inherits everything). Import path is unchanged (from .postgres import PostgresAdapter).
• formatter.py — truncation, masking, compact, sanitize_error; audit.py — hash-chained JSONL shapes; helpers/ — sql_ast.py, mongo_query.py, connection_fields.py.