dbmcp: Instructions file for Claude Code

CLAUDE.md

A single-binary MCP (Model Context Protocol) server for MySQL, MariaDB, PostgreSQL, and SQLite. Built in Rust with zero runtime dependencies.

Build & Test Commands

cargo build                                    # debug build
cargo build --release                          # release build
cargo run -- stdio --db-backend mysql --db-user root # stdio transport
cargo run -- http --db-backend mysql --db-user root --host 127.0.0.1 --port 9001

cargo test                          # all tests
cargo test --workspace --lib --bins # unit tests only
cargo test <name>             # single test
cargo test -- --nocapture     # with stdout

cargo clippy --workspace --tests -- -D warnings   # lint (warnings = errors)
cargo fmt --check             # check formatting
cargo fmt                     # apply formatting

./tests/run.sh                # integration tests (Docker required)
./tests/run.sh --filter mysql # filter by backend

Architecture

Cargo workspace: root binary (dbmcp) + 7 library crates under crates/. Workspace members use "crates/*" glob.

• src/ — Binary crate. cli.rs owns CLI parsing (clap with subcommands), tracing init, and subcommand dispatch. commands/common.rs hosts the shared DatabaseArguments group, the TryFrom<&DatabaseArguments> for DatabaseConfig conversion, and the create_server factory. commands/stdio.rs and commands/http.rs own transport-specific execution; HttpArguments is private to http.rs.
• crates/config/ (dbmcp-config) — Config, DatabaseConfig, HttpConfig structs, DatabaseBackend enum (Mysql, Mariadb, Postgres, Sqlite via clap::ValueEnum). DatabaseConfig::validate() and HttpConfig::validate() accumulate errors into Result<(), Vec<ConfigError>>.
• crates/backend/ (dbmcp-sql) — Shared AppError type, SQL read-only validation (validation module), identifier quoting/validation (identifier module), and request/response types (types module).
• crates/server/ (dbmcp-server) — Shared MCP tool implementations (tools module) and server_info(). Reused by all three database handler crates.
• crates/pii/ (dbmcp-pii) — Regex-based PII detection (46 built-in entity types covering personal, financial, government, contact, network, digital-identity, and crypto categories) tagged by Category (Personal, Financial, Government, Contact, Network, DigitalIdentity, Crypto), four anonymisation operators (replace, mask, redact, hash), and an Analyzer::builder() entry point for category-filtered registries. Wired into query tool output behind PiiConfig. Canonical entity list: crates/pii/src/entity.rs (Entity enum); registration order: crates/pii/src/recognizers/mod.rs (all()).
• crates/mysql/ (dbmcp-mysql) — MySQL/MariaDB backend: connection pooling, query operations, schema introspection, MCP handler via rmcp::tool_router.
• crates/postgres/ (dbmcp-postgres) — PostgreSQL backend: per-database connection pool cache (moka), query operations, schema introspection, MCP handler.
• crates/sqlite/ (dbmcp-sqlite) — SQLite backend: single-file connection, query operations, schema introspection, MCP handler.
• crates/sqlx-json/ (sqlx-json) — RowExt trait for type-safe row-to-JSON conversion. Per-backend implementations for SqliteRow, PgRow, and MySqlRow.
• Transport: stdio (for Claude Desktop/Cursor) and http (Streamable HTTP with CORS via axum + tower-http). A transport subcommand is required — dbmcp with no subcommand prints usage help and exits non-zero.