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.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables developers to retrieve short jokes in multiple categories and languages during task processing. Provides fast offline fallbacks and configurable joke providers for entertainment during development workflows.

Joke MCP Server

Joke MCP Server

Quick Start

Environment Variables

Usage Examples

Testing

Codex MCP Configuration

Project Layout

New MCP Servers

MCP directory API