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

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' | 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.