mcp-mysql-client: Instructions file for Claude Code

CLAUDE.md — mcp-mysql-client

MCP server for one MySQL/MariaDB database, TypeScript over stdio. No HTTP API and no OAuth: the transport is a mysql2 connection pool built from MYSQL_* environment variables, and the whole product is what happens between the model's SQL and that pool.

The threat model is the point of this repo. The caller is a language model with a prompt-shaped attack surface, pointed at a database that may be production. So: the server classifies every statement itself (sql.ts) instead of trusting which tool the model picked, reads run inside START TRANSACTION READ ONLY so the server refuses a write that got past the classifier, and write permissions live only in the environment where the model cannot reach them.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + a dist smoke probe, no database
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live READ-ONLY check (needs MYSQL_* in the environment)

Architecture

• src/config.ts — env → config. Missing MYSQL_USER / MYSQL_DB (empty string = absent) is NOT an error: the fields stay undefined, the server starts degraded and the client raises CredentialsError at call time. ConfigError (with a reason code) is reserved for malformed values — invalid_port, unreadable_ssl_ca, unreadable_pass_file — and is caught by loadConfigOrDegraded in index.ts. boolean() never opens a write permission on an unparseable value. describeTarget is the only printable form of the target (stderr is captured to disk by MCP hosts, so the password must never reach it).
• src/types.ts — config, QueryResult ({rows, rowCount, truncated, columns, durationMs}), WriteResult, Permissions, and the error vocabulary: CredentialsError, ValidationError, PermissionError (with kind), TimeoutError, MysqlError (keeps code/errno/sqlState).
• src/sql.ts — the statement gate. scan() is a lexical scanner tracking strings, backtick identifiers and comments, splitting on top-level ;. analyze() classifies into read / insert / update / delete / replace / ddl / forbidden. assertReadable and assertWritable are the two gates the tools call. Deliberately conservative, not a grammar.
• src/client.ts — the pool and the two paths. read() streams rows and stops at the cap (a cut-short stream leaves the connection unusable, so it is destroyed, not released), write() runs in autocommit. Plus the information_schema queries behind the schema tools, all scoped to the bound database.
• src/tools/*.ts — server (server_info), schema (list_tables, describe_table), query (query, explain), write (execute); each exports one register*Tools. tools/util.ts — ok/fail, the MySQL error→fix map, the annotation presets and the shared zod schema factories. tools/harness.ts — the fake server/client pair the tool tests share.
• src/index.ts — wires every register* into the McpServer, builds the session instructions from the live config (bound database, current permissions, row cap, timeout), and closes the pool on SIGINT/SIGTERM.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only; never SQL, table names, row data, the host or the database name). Opt-out ASKADS_TELEMETRY=0.