duckdb-mcp: Instructions file for Codex

DuckDB MCP - Development Guidelines

Build & Test Commands

Core Commands

yarn install          # Install dependencies
yarn build            # Build project (TypeScript compilation)
yarn build:bundle     # Bundle with Rspack for npx distribution (optional)
yarn dev              # Watch mode for development
yarn start            # Run compiled JavaScript

Testing

yarn test             # Run all tests
yarn test:unit        # Run unit tests only
yarn test:e2e         # Run E2E tests only
yarn test:watch       # Watch mode for tests
yarn test:db          # Create test database fixture
yarn coverage         # Generate coverage report

Run a single test:

yarn test tests/unit/database.test.ts
yarn test -- --testNamePattern="should execute a simple query"

Code Quality

yarn lint             # Check linting
yarn lint:fix         # Auto-fix linting issues
yarn format           # Format code with Prettier
yarn format:check     # Check formatting without writing
yarn typecheck        # Run TypeScript type checking

---

Code Style Guidelines

TypeScript Configuration

• Target: ES2022
• Module: NodeNext (ESM)
• Strict mode: Enabled
• Universal rules: noImplicitAny, noImplicitReturns, noUnusedLocals, noUnusedParameters

Naming Conventions

• Classes: PascalCase (e.g., DatabaseClient, FastMCP)
• interfaces/types: PascalCase with Result suffix for return types
• functions/variables: camelCase (e.g., executeQuery, maxRows)
• Constants: UPPER_SNAKE_CASE (e.g., SERVER_VERSION)
• Files: camelCase for implementation, .test.ts for tests

Import Order

1. External dependencies (e.g., duckdb, commander)
2. Internal modules (e.g., ./database.js, ./types.js)
3. Relative imports using .js extension

Formatting (Prettier)

• Semi-colons: true
• Single quotes: true
• Tab width: 2
• Trailing commas: es5
• Print width: 100
• Arrow parentheses: avoid
• Line endings: LF