DB-Explorer-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

uv run python tests/seed_test_db.py    # (re)create sample.db
uv run pytest                          # live tests skip unless TEST_*_URL is set
uv run server.py                       # start server, stdio transport
uv run python evals/run.py             # agent evals through claude -p (uses the Claude Code login's usage)

uv run ruff check . lints (bug-catching rules only, see [tool.ruff.lint] in pyproject.toml).

To run over HTTP locally, set MCP_TRANSPORT=streamable-http (plus MCP_HOST/MCP_PORT and MCP_AUTH_TOKEN or MCP_AUTH_TOKENS) before uv run server.py — see README "Serve over HTTP".

If uv isn't on PATH, prefix commands with py -m.

Architecture

This is an MCP server (server.py, FastMCP) exposing 7 read-only database tools (explore_schema, execute_query, explain_query, validate_schema, suggest_index, migration_context, validate_migration) over one SQLAlchemy engine per token group (server.current_engine; stdio and ungrouped tokens use DATABASE_URL). It makes no LLM calls itself — the MCP client's model writes the SQL; this server's only job is to make mutation structurally impossible before it reaches the driver.

Trust boundary is safety.py. Every query-executing tool routes through it first. It parses SQL with sqlparse (never string-matches) through parse_sql, which caps input at MAX_SQL_CHARS and turns sqlparse's token/nesting limits into query_too_complex, and rejects anything that isn't exactly one SELECT statement, contains SQL comments, contains a blocked keyword, or contains a locking clause (FOR UPDATE/SHARE etc., matched as a multi-word clause sequence, not a keyword set — plain columns named share must still pass). A query that passes is unconditionally wrapped as SELECT * FROM (\n<query>\n) AS limited_query LIMIT <row_limit + 1> (the line breaks keep a comment the validator missed from swallowing the LIMIT), so a LIMIT inside the original query narrows the inner result but never removes the outer cap. The extra probe row is dropped and sets truncated: true in the result, so a capped result is never mistaken for a complete one. Rows are also cut once the result passes MAX_RESULT_BYTES, and serialization.py cuts any text value over MAX_INLINE_TEXT_CHARS. Queries run through db.execute_raw (exec_driver_sql with no_parameters), never text(), which reads :word inside a string literal as a bind parameter. row_limit is clamped to 1000. See the README's "Safety model" section for the full denylist rationale (which entries are load-bearing vs. defense-in-depth) before touching the keyword list.