Skip to main content
Glama

Joke MCP Server

by ericqian77

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.

-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. Quick Start
    1. Environment Variables
      1. Usage Examples
        1. Testing
          1. Cloudflare Worker (HTTP MCP)
            1. Codex MCP Configuration
              1. Project Layout

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/ericqian77/joke-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server