Joke MCP Server

# Project Progress Report ## Context & Intent - **Goal:** deliver a Model Context Protocol (MCP) server that surfaces quick jokes to developers during short wait periods after submitting tasks, reducing perceived latency and frustration. - **MVP Scope:** single-node executable (Node.js 18+) handling `health` and `getJoke` commands; prioritised provider chain (JokeAPI → Official Joke API → local fallback); environment-driven configuration; offline-friendly tests; minimal dependencies. - **Non-Goals:** persistence, database, web UI, auth—server remains a stateless CLI process. ## Current Implementation Snapshot (2025-09-21) - **Entry point (`src/jokes-mcp.js`):** readline loop over stdin; validates JSON payloads, selects providers, measures latency, responds with stable JSON. Provider logs are gated by `LOG_VERBOSE` (default `false`), ensuring quiet stdout unless diagnostics are needed. Exports orchestrator helper for tests. - **Configuration (`src/config.js`, `src/validation.js`):** centralised env parsing with defaults (`JOKE_API`, `JOKE_DEFAULT_CATEGORY`, `JOKE_LANG`, `TIMEOUT_MS`, `RETRIES`, `ALLOW_NET`, `LOG_VERBOSE`). Validation enforces supported categories (`programming`, `general`, `pun`, `spooky`, `christmas`), languages (`en`, `zh`), and blacklist flags. - **Providers:** - `src/providers/jokeapi.js` – wraps JokeAPI with timeout/retry support, blacklist flags, language negotiation, and internal category mapping. - `src/providers/official.js` – Official Joke API adapter (English only) with punchline/setup formatting and category normalisation. - `src/providers/local.js` – deterministic fallback pulling from `local-jokes.json` (20 curated en/zh jokes across categories). - `src/providers/sharedFetch.js` – reusable Fetch + AbortController wrapper with exponential backoff. - **Utilities:** `src/logger.js` writes structured JSON logs to stderr when verbose, aiding observability without polluting stdout results. - **Data:** `local-jokes.json` bilingual joke pool, ensures offline coverage. - **Tooling:** `scripts/dev.sh` sends one `getJoke` command for manual testing. ## Testing & Quality - **Test Runner:** Vitest (only dev dependency). Commands: - `npm test` – offline unit + e2e suite (no network calls thanks to mocks and local fallback). - `npm run test:online` – opt-in integration requiring `ALLOW_NET=true` (hits JokeAPI once). - **Coverage Focus:** validation rules, provider URL construction, fallback logic (`tests/e2e/offline.test.js` ensures local fallback when remote providers fail). - All tests currently pass (last run: 2025-09-21 11:53 local), verifying quiet logs when `LOG_VERBOSE=false`. ## Documentation Assets - `README.md` – quick start, env reference, testing instructions, Codex MCP TOML snippet, and project layout. - `AGENTS.md` – contributor guidelines (structure, commands, conventions, testing expectations, security tips). - `docs/integration-guide.md` – playbook for wiring the server into waiting workflows (shell examples, Codex CLI usage, Node/Python snippets). ## Outstanding Considerations & Next Steps 1. **Quality Gates:** introduce coverage tooling (`c8`) or linting (ESLint/Prettier) to enforce style and detect regressions before scaling contributors. 2. **Provider Enhancements:** expand local joke pool for non-English or niche categories; consider caching to reduce repeated API calls when `ALLOW_NET=true`. 3. **Operationalisation:** decide on process supervision (pm2/systemd) for long-running deployments and log aggregation strategy if verbose mode is used in production. 4. **Telemetry Options:** optionally expose metrics (counts, failures) via stdout or dedicated command to integrate with monitoring tools. 5. **CI/CD Setup:** add workflow definitions (GitHub Actions or similar) running `npm install` + `npm test` and optionally integration tests when `ALLOW_NET=true` is toggled. ## Quick Start Reminder ```bash npm install LOG_VERBOSE=false ALLOW_NET=false node ./src/jokes-mcp.js printf 'getJoke {"category":"programming","lang":"en"}\n' | node ./src/jokes-mcp.js ``` This document should be updated whenever major functionality, configuration defaults, or testing practices change so the next development agent can resume quickly with full context.