Which integrations are available for this server?

Provides HTTP MCP endpoints through Cloudflare Workers, enabling deployment of the joke server as a serverless function with health check and joke retrieval endpoints

How do I use Joke MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Joke MCP Server tell me a programming joke" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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' | npm run dev --silent

# Category + language request
printf 'getJoke {"category":"programming","lang":"en"}\n' | npm run dev --silent

# 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; 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

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

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.