db-connect-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents working in this repository.

Project Overview

This is a read-only Multi-Database MCP (Model Context Protocol) server that provides safe database exploration and analysis capabilities for PostgreSQL, MySQL, and ClickHouse databases. The server enforces read-only access at multiple levels and is designed for exploratory data analysis without risk of data modification.

Pre-Commit Requirements

IMPORTANT: Before every commit and push, ALL of the following checks must pass:

# 1. Format code
uv run ruff format .

# 2. Lint code
uv run ruff check .

# 3. Type checking
npx pyright

# 4. Run all tests
uv run pytest -n 6

Do NOT commit or push if any of these checks fail. Fix all issues first.

Development Commands

Setup & Installation

# Install dependencies using uv (preferred)
uv sync

# Or using pip
pip install -e .

# Install dev dependencies for testing
uv sync --dev

Running the Server

# As a module (recommended - works without PATH configuration)
python -m db_connect_mcp

# Using uv (for development with dependencies)
uv run python -m db_connect_mcp

# For Windows: __main__.py sets WindowsProactorEventLoopPolicy automatically

See docs/guides/DEVELOPMENT.md for detailed development setup.

Testing

IMPORTANT: Always run tests with 6 parallel workers (-n 6) for optimal performance.

# Start local test database (PostgreSQL 17 with sample data)
cd tests/docker && docker-compose up -d && cd ../..

# Run all tests in parallel (preferred - 6 workers)
uv run pytest -n 6

# Run specific test modules in parallel
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# Stop test database
cd tests/docker && docker-compose down && cd ../..

# Reset database (clean slate with fresh data)
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..