Jokebox

jokebox

jokebox serves dad jokes from icanhazdadjoke.com. Ask for a joke at random, hunt for jokes that mention a word or phrase, or pull up one specific joke again when you know its ID. One binary offers both a small command-line interface and a stdio MCP server, so the same install works in a terminal and inside an MCP client.

There is nothing to configure: the upstream service is public, needs no API key, and asks only that clients identify themselves and accept JSON answers — jokebox does both on every request.

Install

npx @reneturcios/jokebox random

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/jokebox

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

jokebox randomjokebox search pizzajokebox search pizza --limit 3jokebox joke R7UfaahVfFd
jokebox --version

Every command prints JSON. random prints one joke as { "id": ..., "joke": ... }. search prints { "term": ..., "total_jokes": ..., "jokes": [...] }, where total_jokes counts every match the upstream holds for the term and jokes holds the requested page of them. joke prints the single joke stored under the given ID.

Search limits: --limit is an integer from 1 to 30 and defaults to 5. An out-of-range limit, a missing search term, or a missing joke ID is a usage error and no request is sent.

Exit codes: 0 on success, 1 when the upstream request fails (the error names the HTTP status or the malformed answer), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/jokebox mcp

MCP client configuration:

{  "mcpServers": {    "jokebox": {      "command": "npx",      "args": ["-y", "@reneturcios/jokebox", "mcp"]    }  }}

Tools

Development

npm installnpm run build   # tsc -> dist/npm test        # node test runner over test/*.test.ts, no network (fake fetch only)npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.