dbhub-analytics CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

DBHub Development Guidelines

DBHub is a database MCP server implementing the Model Context Protocol (MCP) server interface. It bridges MCP-compatible clients (Claude Desktop, Claude Code, Cursor) with various database systems (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, Databricks SQL, Google BigQuery).

Commands

Prerequisites: Node.js >= 20, pnpm, Docker (for integration tests).

pnpm install                    # Install dependencies (monorepo: root + frontend/)
pnpm run build                  # Full build: generate API types + tsup backend + vite frontend
pnpm run build:backend          # Backend only (generates API types + tsup)
pnpm run dev                    # Dev mode: backend (HTTP transport) + frontend (Vite) concurrently
pnpm run dev:backend            # Backend dev only with tsx
pnpm run generate:api-types     # Regenerate src/api/openapi.d.ts from src/api/openapi.yaml

# Testing (vitest)
pnpm test                       # All tests (unit + integration)
pnpm test:unit                  # Unit tests only (no Docker)
pnpm test:integration           # Integration tests only (requires Docker)
pnpm test:watch                 # Interactive watch mode
pnpm test src/utils/__tests__/sql-parser.test.ts           # Single test file
pnpm test -- --testNamePattern="PostgreSQL"                 # Tests matching pattern
pnpm test:build                 # Post-build smoke test

Architecture Overview

Monorepo Structure

pnpm workspace with two packages (pnpm-workspace.yaml):

• Root — Backend TypeScript MCP server, bundled with tsup to dist/
• frontend/ — React SPA (Vite + Tailwind + CodeMirror), builds to dist/public/

Backend (src/)

src/
├── index.ts                 # Entry point: dynamic-imports connectors, calls main()
├── server.ts                # MCP server: stdio/HTTP transport, Express routes, tool registration
├── connectors/
│   ├── interface.ts         # Connector/DSNParser interfaces, ConnectorRegistry
│   ├── manager.ts           # ConnectorManager: multi-source connection lifecycle
│   └── {postgres,mysql,mariadb,sqlserver,sqlite,databricks,bigquery}/index.ts
├── tools/
│   ├── index.ts             # registerTools(): wires tools to MCP server
│   ├── registry.ts          # ToolRegistry: manages enabled tools per source
│   ├── execute-sql.ts       # execute_sql tool handler
│   ├── search-objects.ts    # search_objects tool handler (progressive disclosure)
│   └── custom-tool-handler.ts  # User-defined SQL tools from TOML config
├── api/                     # REST API for the Workbench frontend
│   ├── openapi.yaml         # OpenAPI spec (source of truth for API types)
│   ├── openapi.d.ts         # Generated types (run generate:api-types)
│   ├── sources.ts           # /api/sources endpoints
│   └── requests.ts          # /api/requests endpoints
├── config/
│   ├── env.ts               # CLI args + env var resolution
│   ├── toml-loader.ts       # TOML config parsing and validation
│   └── demo-loader.ts       # --demo mode setup
├── requests/store.ts        # In-memory request history (FIFO, 100 per source)
├── types/                   # TypeScript interfaces (config.ts, sql.ts, ssh.ts)
└── utils/                   # ~20 utility modules