Provides HTTP MCP endpoints through Cloudflare Workers, enabling deployment of the joke server as a serverless function with health check and joke retrieval endpoints
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; typehealth
orgetJoke {"category":"programming"}
on stdin.npm run build && npm start
– compile todist/
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 |
| Primary provider (
or
). |
|
| Fallback category when input omits one. |
|
| Default language (currently
or
). |
|
| Per-request HTTP timeout in ms. |
|
| Retry attempts with exponential backoff. |
|
| Opt-in for live HTTP calls (
to enable). |
|
| Emit provider diagnostics to
. |
|
Usage Examples
Testing
Offline suite:
npm test
Live integration (opt-in):
npm run test:online
withALLOW_NET=true
Tests mock network providers by default; CLI I/O is covered in
tests/integration/cli.test.ts
, HTTP Worker coverage intests/integration/worker.test.ts
, and fallback behaviour intests/e2e/offline.test.ts
.
Cloudflare Worker (HTTP MCP)
Configure
wrangler.toml
(included) and set secrets/env vars withwrangler secret put
if needed.Dev server:
npm run dev:worker
(serves onhttp://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.
This server cannot be installed
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.