MCP-DB: 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

Requires Node.js >=20.10.

npm install          # Install dependencies
npm run build        # Compile TypeScript → dist/ (uses tsconfig.build.json)
npm run dev          # Run CLI directly via tsx (no compile step)
npm run typecheck    # Type-check without emitting (uses tsconfig.json)
npm run lint         # ESLint on src/**/*.ts
npm run format       # Prettier on all TS/MD/JSON/YAML files
npm test             # Run Vitest test suite
vitest run --reporter=verbose  # Run tests with full output

To run a single test file:

npx vitest run src/core/security.test.ts

For local development testing of CLI commands (no global install needed):

node dist/cli.js start
node dist/cli.js validate-config
node dist/cli.js test-connections

Or using tsx without a build step:

npm run dev -- start
npm run dev -- validate-config

Architecture

This is an ESM-only TypeScript package ("type": "module"). Imports must use .js extensions even for .ts source files (NodeNext module resolution).

Request flow

CLI (src/cli.ts)
  → loadConfig (src/config/load-config.ts) parses YAML + Zod validation
  → startStdioServer / startHttpServer (src/server.ts)
      → ConnectorRegistry (src/core/registry.ts) creates connector instances
      → registerDbTools (src/tools/register-tools.ts) wires MCP tools to registry
           → security.ts: validateSqlQuery / validateMongoPipeline / assertAllowedObject
           → audit.ts: writes JSONL audit log if configured
           → format.ts: formats QueryResult as markdown table

Key layers

• src/config/ — YAML loading (load-config.ts) and Zod schema (schema.ts). Config defaults are defined in schema.ts (e.g., defaultMaxRows: 100, queryTimeoutMs: 10000).
• src/types.ts — All shared interfaces: DbConnector, AppConfig, SecurityConfig, connection configs per DB type.
• src/core/ — Cross-cutting concerns: registry.ts (connector lifecycle), security.ts (SQL/MongoDB validation, masking, allowlists), audit.ts (JSONL append), format.ts (markdown table output), errors.ts (UserInputError/PermissionError).
• src/connectors/ — One file per DB type (oracle.ts, mssql.ts, mongodb.ts). Each implements the DbConnector interface from types.ts; mongodb.ts additionally implements MongoDbConnector.
• src/tools/register-tools.ts — Registers all 14 MCP tools on the McpServer (8 shared/SQL tools for Oracle+MSSQL, 6 MongoDB-specific tools). Each tool follows the runAudited wrapper: run action → audit → return ok() or error.
• src/setup/wizard.ts — Interactive setup wizard; generates .mcp.json, .codex/config.toml, .gemini/settings.json, .kimi/mcp.json, mcp-db.local.yml, .env, .gitignore.