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, Dockerfile) sit at the repository root.
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.
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.
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.
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.
Runtime configuration is sourced from environment variables parsed in src/config.ts (PORT, SERVER_NAME, LOG_LEVEL, etc.). Document defaults when introducing new flags and avoid hard-coding secrets. Pino logging is structured; keep contextual metadata small and redact user-provided content where necessary.