Joke MCP Server

# Repository Guidelines ## Project Structure & Module Organization - `src/` will contain the MCP agent implementation; group reusable conversation logic under `src/agents/` and isolate adapters (CLI, server, tests) under `src/interfaces/`. - `data/jokes/` is the canonical store for curated joke corpora and prompt snippets; keep original assets immutable and add derived files under `data/generated/`. - `tests/` mirrors the `src/` tree; create `tests/integration/` fixtures for end-to-end protocol sessions. - `docs/` houses protocol notes, session transcripts, and diagrams that explain agent behavior; link new design docs from the pull request description. ## Build, Test, and Development Commands - `npm install` installs dependencies; rerun after updating `package.json` or `package-lock.json`. - `npm run dev` starts the local MCP server with hot reload; point your MCP client to `localhost:4242` for manual QA. - `npm run build` emits the production bundle to `dist/`; confirm this before release tagging. - `npm test` executes all unit and integration suites; add `-- --watch` while iterating locally. ## Coding Style & Naming Conventions - TypeScript is the default language; prefer `.ts` modules and keep public APIs typed explicitly. - Follow ESLint + Prettier defaults (`npm run lint`); never commit files with lint warnings. - Use descriptive, lower-hyphen filenames for agents (`joke-writer.agent.ts`) and camelCase for internal helpers. - Keep functions under 50 lines; extract utilities into `src/shared/` when logic is reused in multiple agents. ## Testing Guidelines - Vitest backs unit tests; co-locate fast tests beside source as `*.spec.ts`. - Integration flows live in `tests/integration/` and should simulate full MCP conversations using recorded transcripts. - Aim for 85% line coverage measured via `npm run test -- --coverage`; raise the threshold before adding new surfaces. - Name test cases after the user intent they protect (`responds with pun when tone=playful`). ## Commit & Pull Request Guidelines - Use Conventional Commits (`feat:`, `fix:`, `docs:`) to keep the changelog actionable. - Branch names follow `type/short-topic` (e.g., `feat/prompt-cache`). - Pull requests must include: summary of behavior change, test evidence (`npm test` output), and linked issue/roadmap item. - Request review from another agent maintainer; add screenshots or transcript snippets when UI or UX behavior shifts. ## Security & Configuration Tips - Store secrets (API keys, webhook URLs) in `.env.local`; never commit them—use `.env.example` for placeholders. - Validate external joke sources before ingesting; sanitize user-provided prompts to prevent prompt-injection attacks. - Rotate authentication tokens quarterly and document updated scopes in `docs/configuration.md`.