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 (Mitigated footprint: vitest only).
• npm test – run offline unit + e2e suites (no network requests).
• node src/jokes-mcp.js – launch the server; type health or getJoke {"category":"programming"} on stdin.

Environment Variables

Usage Examples

# Health check
printf 'health\n' | node src/jokes-mcp.js

# Category + language request
printf 'getJoke {"category":"programming","lang":"en"}\n' | node src/jokes-mcp.js

# 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; local fallback is validated in tests/e2e/offline.test.js.

Codex MCP Configuration

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

Project Layout

• src/jokes-mcp.js – MCP stdin loop, provider orchestration, structured logging.
• src/providers/ – Joke providers (jokeapi, official, local) plus shared fetch helper.
• local-jokes.json – curated bilingual fallback pool (20 jokes, categorized).
• tests/ – unit, offline e2e, and opt-in integration coverage.
• docs/integration-guide.md – playbook for wiring jokes into wait-period workflows.