mcp-multi-db: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. Also useful to humans.

See CONTRIBUTING.md for the contributor workflow.

Commands

npm install           # install dependencies
npm run build         # tsc -> build/, then chmod 755 build/index.js
npm test              # runs build, then node:test suite in test/
node --test "test/**/*.test.ts"          # run tests without rebuilding
node --test test/validateReadOnly.test.ts # run a single test file

Tests use Node's built-in runner (node:test, no extra deps) and require Node ≥ 22.18 / 24 (native TypeScript execution). They import the compiled build/*.js — not src — because the source uses constructor parameter properties that Node's type-stripping can't run, so npm test builds first. There is no linter; TypeScript strict mode is the type/correctness gate. Always npm run build after changes — build/index.js is what the MCP client executes.

To run the server manually for debugging (it speaks MCP over stdio, so it waits for JSON-RPC on stdin):

MCP_DB_CONFIG=./databases.json node build/index.js

Architecture

Deeper reference docs (with diagrams) live in docs/ — docs/architecture.md for the component map + run_query lifecycle, docs/extending.md for adding an engine. Keep them in sync when the architecture changes.

A read-only MCP server (stdio transport) that exposes SQL queries over PostgreSQL, MySQL, and SQLite to MCP clients (e.g. Cursor). Layers, from entry point outward:

• src/index.ts — wires everything: load config → build DatabaseRegistry → wrap in DatabaseService → registerTools → connect StdioServerTransport.
• src/config.ts — loads/validates config via Zod. Reads MCP_DB_CONFIG (path to JSON file) first, else MCP_DATABASES (inline JSON). Accepts either { databases: [...] } or a bare array. Enforces unique ids.
• src/tools/registerTools.ts — the 4 MCP tools (list_databases, list_tables, describe_table, run_query). Each is a thin wrapper that calls DatabaseService and returns the result JSON-stringified into a text content block. Tool input schemas are defined here with Zod.
• src/services/databaseService.ts — orchestration layer. The only place the read-only SQL guard runs: runQuery calls clampQueryLimit + validateReadOnlySql before dispatching to an adapter. Resolves adapters via getSqlAdapter, which narrows on kind and rejects a non-SQL database_id with a clear error (the routing seam for future non-SQL families).
• src/adapters/registry.ts — maps database_id → adapter instance (typed AnyDatabasePort), lazily constructing and caching adapters (and their connection pools) on first use.
• src/adapters/{postgres,mysql,sqlite}.ts — per-engine implementations of SqlDatabasePort.
• src/core/databasePort.ts — the thin DatabasePort base (id, type, kind, close) shared by every family, the DatabaseKind discriminant (currently just "sql"), and AnyDatabasePort (the union of all port families). Port-family model: relational engines share one SqlDatabasePort (kind: "sql") because they share a model; non-relational engines are intentionally not grouped under a "nosql" port — each would get its own port/family (e.g. a future MongoDbPort with kind: "mongodb"), its own read-only guard, and its own service, since they share no common vocabulary.
• src/core/sqlDatabasePort.ts + src/core/types.ts — the SqlDatabasePort interface (extends DatabasePort) every SQL adapter implements, plus shared types. This is the seam: code above the adapters is engine-agnostic.