# Repository Guidelines

## Project Structure & Module Organization

Core server code lives in `src/`. `src/index.ts` hosts the MCP Express server, `src/config.ts` normalizes environment variables, `src/logger.ts` wires Pino logging, and `src/lib/` contains reusable helpers alongside colocated tests such as `utils.test.ts`. Build artifacts land in `dist/`; configuration files (`vite.config.ts`, `tsconfig.json`, `eslint.config.js`) sit at the repository root.

## Build, Test, and Development Commands

Use `npm run dev` for a live TypeScript dev loop with native type stripping (enabled by default in Node.js 22.18+). `npm run build` compiles to ES modules via Vite, while `npm start` serves the compiled output from `dist/`. Run `npm run test` for the interactive Vitest runner or `npm run test:ci` to emit JSON results into `test-results.json`. Quality gates include `npm run lint`, `npm run lint:fix`, `npm run format`, and `npm run format:check`.

## Coding Style & Naming Conventions

TypeScript files use ES module syntax (`import/export`) and live under `src/`. Follow the default Prettier style (two-space indent, double quotes, trailing commas) enforced by the formatting scripts. ESLint runs with `@typescript-eslint`; unused variables must be prefixed with `_` if intentional, and `any` is discouraged. Prefer `camelCase` for functions and variables, `PascalCase` for types, and descriptive filenames like `logger.ts` or `utils.ts`.

## Testing Guidelines

Vitest powers unit tests. Name specs `*.test.ts` and keep them beside the code under test to mirror the existing `src/lib/utils.test.ts` pattern. Cover new tools, transports, and configuration logic with focused tests that exercise observable behaviour. Failing tests should reproduce regressions before fixes; wrap asynchronous tests with `async/await` to keep stack traces actionable.

## Commit & Pull Request Guidelines

Adopt Conventional Commits (`feat:`, `chore:`, `docs:`) as seen in the history to keep change logs readable. Each PR should summarize the user-facing impact, reference related issues, and list follow-up tasks if scope is deferred. Include testing evidence (`npm run test`, `npm run lint`) and call out new environment variables or configuration knobs so reviewers can verify runtime changes.

## Configuration & Operational Notes

Runtime configuration is handled in `src/config.ts`, which validates environment variables for:
- **Embedding providers**: `OPENAI_API_KEY` for OpenAI, or AWS credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE`, `AWS_REGION`) for Bedrock
- **Logging**: `LOG_LEVEL` (`error`, `warn`, `info`, `debug`) and `NODE_ENV`
- **Credential verification**: At startup, the server verifies embedding provider credentials using `verifyEmbeddingProvider()` which resolves AWS credentials through the full provider chain

The database layer (`src/db/migrate.ts`) automatically detects embedding dimension mismatches and rebuilds the database when switching between models with different vector sizes.

Document new environment variables when you add them, and avoid hard-coding secrets. Pino logging is structured; keep contextual metadata small and redact user-provided content where necessary.

## Tests

To run tests, run `npm run test:ci` from the project root.