querybridge-mcp: Instructions file for Claude Code

CLAUDE.md

Operational notes for agents working in this repo. Read CONVENTIONS.md for the full set of rules; this file is the 60-second briefing.

Quick orientation

• What it is. An MCP server connecting Claude (and other MCP clients) to MySQL. Ships two transports: stdio (default) and Streamable HTTP (with bearer auth). 40 tools across 9 families (see README.md → Tools).
• Stack. TypeScript, Node ≥ 20, pnpm (not npm — packageManager field in package.json), Vitest, mysql2/promise, ssh2, @modelcontextprotocol/sdk.
• Architecture. Transport → Tools → Infrastructure. Enforced by .dependency-cruiser.cjs; CONVENTIONS.md §1 has the prose. Don't import upward.
• Entry points. src/server/index.ts dispatches stdio vs HTTP. src/tools/index.ts is the tool-registry barrel.

Commands

pnpm install            # also installs the husky pre-commit hook via `prepare`
pnpm build              # tsc
pnpm lint               # eslint + dep-cruiser (architecture enforcement)
pnpm test               # unit tests (Vitest)
pnpm test:integration   # MySQL Testcontainers — needs Docker running
pnpm format             # prettier --write across the repo
pnpm format:check       # prettier --check (no writes) — what CI would run

pnpm lint && pnpm test covers everything CI does. The pre-commit hook handles the formatting + ESLint pass on staged files automatically — no need to remember pnpm format before each commit.

Release flow

Changesets-driven. Never bump versions manually.

• Any user-visible change → add .changeset/<short-name>.md with the appropriate bump (patch / minor / major) and a clear changelog entry.
• Merging to main triggers the Changesets bot to open or update a "Version Packages" PR.
• Merging the Version Packages PR pushes a vX.Y.Z tag → release.yml publishes to npm (with Sigstore provenance) and GHCR (multi-arch + SBOM).

Hard rules

• Never commit config.json. It contains DB credentials. config.example.json is the sanitized template.
• Never skip pre-commit hooks (--no-verify). The hook (.husky/pre-commit) runs lint-staged, which calls eslint --fix --max-warnings=0 and prettier --write on staged files only. Fast (~1s typical) and fixable — if it fails, fix the root cause instead of bypassing.
• Never reach for mysql2 outside src/connection.ts, src/db/cancel.ts, or src/tools/query-tools.ts. Pool hardening (LOCAL_FILES block, SSL setup, SET SESSION transaction_read_only) only happens in buildPoolOptions. Bypassing it loses defenses. dep-cruiser enforces.
• Every new tool ships with an integration test. MockRunner unit tests are not enough — real MySQL catches behavior the mock doesn't (CONVENTIONS.md §8).
• Read-only by default. Two layers, both required: getConnectionConfig().readonly flag check AND isReadOnlyQuery() SQL whitelist. Don't skip either.
• config.json is gitignored but .changeset/config.json is not — the gitignore has a !.changeset/config.json negation. Don't break it.