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

Usage Examples

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

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.