database-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.

Project Overview

Database MCP Server — a Model Context Protocol server that gives AI assistants read-only access to SQL Server and PostgreSQL databases. Built with TypeScript, Node.js 18+, ESM modules, and the @modelcontextprotocol/sdk.

Commands

npm run build            # Compile TypeScript → build/
npm run dev              # Watch mode compilation
npm start                # Run server (node build/index.js)
npm test                 # Run all tests (Vitest)
npm run test:unit        # Unit tests only
npm run test:integration # Integration tests only
npm run test:watch       # Tests in watch mode
npm run test:coverage    # Coverage report (V8 provider)

Architecture

Layers

index.ts (entry)
  → ConfigLoader (env/file/CLI config)
  → SqlServerMcpServer (server.ts)
      → ConnectionManager (pool-per-profile, lazy init, multi-database)
      → IDatabaseDriver (driver abstraction per profile)
          → SqlServerDriver (mssql package)
          → PostgresDriver (postgres/porsager package)
      → ToolRegistry → 11 tools (BaseTool subclasses)
      → ResourceRegistry → 3 resources (BaseResource subclasses)
  → StdioServerTransport (MCP stdio transport)

Driver Abstraction

The IDatabaseDriver interface (src/database/interfaces/database-driver.ts) abstracts all database-specific operations. Each database type implements this interface:

• SqlServerDriver (src/database/drivers/sqlserver.driver.ts) — uses mssql ConnectionPool, sys.* views for metadata, TOP for row limiting
• PostgresDriver (src/database/drivers/postgres.driver.ts) — uses postgres (porsager) tagged template queries, pg_catalog/information_schema for metadata, LIMIT for row limiting

Tools and resources interact only with IDatabaseDriver, never with database-specific APIs.

Key Directories

• src/config/ — Config loading (ConfigLoader) and types (ConnectionProfile, DatabaseType, connection string parsing)
• src/core/ — Abstract base classes (BaseTool, BaseResource) and registries
• src/database/ — ConnectionManager (pool management, driver creation)
• src/database/interfaces/ — IDatabaseDriver interface and result type interfaces
• src/database/drivers/ — Database-specific driver implementations and factory
• src/tools/ — MCP tool implementations:
  • Universal: list-schemas, list-tables, describe-table, get-relationships, get-indexes, run-select-query, explain-query, estimate-cost
  • PostgreSQL-only: list-materialized-views, list-extensions, list-enums
• src/resources/ — MCP resource implementations (table-schema, database-info, connection-profiles) using db:/// URI scheme
• src/utils/ — Dialect-aware query validation (validation.ts) and error sanitization (error-handler.ts)
• tests/unit/ — Vitest unit tests