Joke MCP Server

A lightweight Model Context Protocol (MCP) companion that serves short jokes to developers while tasks are processed. Designed for Node.js 18+ with airtight offline defaults and fast fallbacks.

Quick Start

npm install – install dependencies (TypeScript, linting, Vitest).
npm test – run offline unit + e2e suites (no network requests).
npm run dev – launch the server with tsx; type health or getJoke {"category":"programming"} on stdin.
npm run build && npm start – compile to dist/ and run the production bundle.
npm run dev:worker – start the Cloudflare Worker MCP locally via Wrangler dev (HTTP interface).

Environment Variables

Variable	Description	Default
`JOKE_API`	Primary provider ( `jokeapi` or `official` ).	`jokeapi`
`JOKE_DEFAULT_CATEGORY`	Fallback category when input omits one.	`programming`
`JOKE_LANG`	Default language (currently `en` or `zh` ).	`en`
`TIMEOUT_MS`	Per-request HTTP timeout in ms.	`2000`
`RETRIES`	Retry attempts with exponential backoff.	`2`
`ALLOW_NET`	Opt-in for live HTTP calls ( `true` to enable).	`false`
`LOG_VERBOSE`	Emit provider diagnostics to `stderr` .	`false`

Usage Examples

# Health check printf 'health\n' | npm run dev --silent # Category + language request printf 'getJoke {"category":"programming","lang":"en"}\n' | npm run dev --silent # Development helper ./scripts/dev.sh 'getJoke {"lang":"zh"}'

Testing

Offline suite: npm test
Live integration (opt-in): npm run test:online with ALLOW_NET=true
Tests mock network providers by default; CLI I/O is covered in tests/integration/cli.test.ts, HTTP Worker coverage in tests/integration/worker.test.ts, and fallback behaviour in tests/e2e/offline.test.ts.

Cloudflare Worker (HTTP MCP)

Configure wrangler.toml (included) and set secrets/env vars with wrangler secret put if needed.
Dev server: npm run dev:worker (serves on http://127.0.0.1:4242 by default).
Deploy: wrangler deploy (requires Cloudflare account credentials).
Endpoints:
- GET /health → { ok: true }
- POST /getJoke with JSON body matching CLI payloads.

Codex MCP Configuration

[mcp_servers.jokes] command = "node" args = ["./dist/interfaces/cli.js"] env = { JOKE_API = "jokeapi", JOKE_DEFAULT_CATEGORY = "programming", JOKE_LANG = "en", TIMEOUT_MS = "2000", RETRIES = "2" } startup_timeout_ms = 20000

Project Layout

src/interfaces/cli.ts – MCP stdin/stdout adapter wrapping the agent.
src/agents/jokes-mcp.agent.ts – provider orchestration, fallback policy, structured logging hooks.
src/providers/ – Joke providers (jokeapi, official, local) plus shared fetch helper.
data/jokes/local-jokes.json – curated bilingual fallback pool (20 jokes, categorized).
src/interfaces/cloudflare/worker.ts – Cloudflare Worker entry that exposes the HTTP MCP endpoints.
tests/ – unit, CLI/HTTP integration, offline e2e, and opt-in live coverage.
docs/integration-guide.md – playbook for wiring jokes into wait-period workflows.