# Repository Guidelines
## Project Structure & Module Organization
- `src/`: TypeScript source (ESM).
- `src/index.ts`: MCP server entrypoint (stdio).
- `src/mcp/`: Tool registration and result shaping.
- `src/doc2x/`: Doc2x v2 API client logic (PDF/image/convert/download/materialize).
- `src/config.ts`: Environment-variable config parsing and defaults.
- `src/errors.ts`, `src/utils.ts`: shared helpers.
- `dist/`: Build output (generated by `tsc`). Do not edit by hand.
- `.env.example`: Sample env vars; `.env` is gitignored.
## Build, Test, and Development Commands
- `npm install` (or `npm ci`): Install dependencies.
- `npm run build`: Compile TypeScript to `dist/` via `tsc -p tsconfig.json`.
- `npm start`: Run the MCP server (`node dist/index.js`).
Example local run:
```bash
DOC2X_API_KEY=sk-xxx npm run build && npm start
```
## Coding Style & Naming Conventions
- TypeScript (Node.js ESM, `type: module`); target Node `>=18`.
- Prefer explicit errors and small modules; avoid over-abstraction.
- Naming: `camelCase` for variables/functions, `PascalCase` for types/classes.
- Formatting: keep diffs minimal; follow existing file style (no repo-wide formatter configured).
## Testing Guidelines
- No automated test runner is currently configured.
- If you add tests, keep them deterministic (no real network calls) and document how to run them in `package.json` scripts.
## Commit & Pull Request Guidelines
- Use Conventional Commits style (e.g., `feat: ...`, `fix: ...`, `docs: ...`).
- PRs should include:
- What/why summary, and any behavior changes.
- Repro/verification steps (commands and expected output).
- Security notes when touching auth/config (never commit real `DOC2X_API_KEY`).
## Security & Configuration Tips
- Required: `DOC2X_API_KEY`. Optional defaults are documented in `README.md`.
- Keep `.env` local; use `.env.example` for new variables and update `README.md` accordingly.
