# 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.
- **CLI interface (`src/interfaces/cli.ts`):** readline loop over stdin; validates JSON payloads, delegates to the agent, measures latency, and responds with stable JSON. Provider logs remain gated by `LOG_VERBOSE` (default `false`).
- **Cloudflare Worker (`src/interfaces/cloudflare/worker.ts`):** HTTP MCP adapter exposing `GET /health` and `POST /getJoke`, sharing the same agent with lightweight caching for env-driven config.
- **Agent core (`src/agents/jokes-mcp.agent.ts`):** constructs provider chain, enforces fallback policy, captures attempt telemetry, and exposes a typed resolution API used by tests and both interfaces.
- **Configuration (`src/config.ts`, `src/validation.ts`):** 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.ts` – wraps JokeAPI with timeout/retry support, blacklist flags, language negotiation, and internal category mapping.
- `src/providers/official.ts` – Official Joke API adapter (English only) with punchline/setup formatting and category normalisation.
- `src/providers/local.ts` – deterministic fallback using statically imported `data/jokes/local-jokes.json` (20 curated en/zh jokes across categories), compatible with Workers.
- `src/providers/sharedFetch.ts` – reusable Fetch + AbortController wrapper with exponential backoff and retry delays.
- **Utilities:** `src/logger.ts` writes structured JSON logs to stderr when verbose, aiding observability without polluting stdout results.
- **Data:** `data/jokes/local-jokes.json` bilingual joke pool, ensures offline coverage.
- **Tooling:** `scripts/dev.sh` pipes a single command through `npm run dev` for manual testing; `npm run build` emits the production bundle to `dist/` and copies static data; `npm run dev:worker` delegates to Wrangler for HTTP testing.
## Testing & Quality
- **Test Runner:** Vitest. Commands:
- `npm test` – offline unit + integration 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, CLI protocol handling (`tests/integration/cli.test.ts`), Worker HTTP surface (`tests/integration/worker.test.ts`), and fallback logic (`tests/e2e/offline.test.ts`).
- 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:** layer in coverage tooling (`c8`) and wire lint/format/typecheck scripts into CI to keep the expanded TypeScript surface healthy.
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/hosting for both CLI and Worker targets (pm2/systemd vs Cloudflare deploy workflows) 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`, `npm run lint`, `npm run typecheck`, and a `wrangler deploy --dry-run` or preview publish step.
## Quick Start Reminder
```bash
npm install
LOG_VERBOSE=false ALLOW_NET=false npm run dev --silent
printf 'getJoke {"category":"programming","lang":"en"}\n' | npm run dev --silent
wrangler dev
```
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.
## Handoff Notes (2025-09-27)
- **Repository status:** pending commit with TypeScript migration, Cloudflare Worker adapter, updated tooling (`npm run lint`, `npm test`, `npm run build` all passing as of 2025-09-27 14:30 UTC-7). Run `git status` before committing to confirm no unexpected files.
- **Environment preparation:** requires Node.js 18+, npm 9+, and Wrangler ≥4.40.2. Install deps with `npm install` after cloning; rerun if package-lock differs.
- **Testing matrix:**
- Offline: `npm test`
- Live JokeAPI: `ALLOW_NET=true npm run test:online`
- Lint: `npm run lint`
- Type check: `npm run typecheck`
- Build artifacts (CLI + Worker bundle): `npm run build`
- **Cloudflare Worker development:** Wrangler’s local runtime needs macOS ≥13.5, Windows 11, or Linux glibc ≥2.35. On unsupported systems like macOS 12.6 the Worker fails to start; workaround is to develop in a supported VM/DevContainer or execute `npm run dev:worker -- --remote` from a supported environment to push a temporary preview.
- **Key scripts:**
- `npm run dev` – CLI MCP hot reload
- `npm run dev:worker` – Worker dev via Wrangler (requires supported OS)
- `npm run build && npm start` – production CLI bundle
- **Outstanding actions:** resolve two moderate npm audit alerts (`npm audit`), decide on CI workflow, and plan containerized environment for consistent Wrangler support.
