jokebox

jokebox

jokebox は icanhazdadjoke.com の親父ギャグを提供します。 ランダムにギャグを聞いたり、単語や フレーズを含むギャグを探したり、ID が分かっている特定のギャグを もう一度表示したりできます。 1 つのバイナリで、小規模なコマンドラインインターフェースと stdio MCP サーバーの両方を提供するため、ターミナルでも MCP クライアント内でも同じインストールを利用できます。

設定は不要です。上流サービスは公開されており、 API キーは不要で、クライアントには自身を識別し、 JSON の応答を受け入れることだけを求めます。jokebox は各リクエストでこの両方を行います。

インストール

npx @reneturcios/jokebox random

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/jokebox

コンテナーはデフォルトで MCP サーバーを起動します（下記参照）。CLI として使うには、 CLI の引数を渡します。

CLI

jokebox random
jokebox search pizza
jokebox search pizza --limit 3
jokebox joke R7UfaahVfFd

jokebox --version

各コマンドは JSON を出力します。random は 1 件のギャグを { "id": ..., "joke": ... } として出力します。search は { "term": ..., "total_jokes": ..., "jokes": [...] } を出力します。ここで total_jokes は上流サービスがその検索語に対して保持するすべての一致件数を示し、 jokes には指定されたページのギャグが含まれます。joke は指定された ID に保存されている 1 件のギャグを出力します。

検索の制限：--limit は 1～30 の整数で、デフォルトは 5 です。範囲外の件数、検索語の不足、または ギャグ ID の不足は使用法エラーとなり、リクエストは送信されません。

終了コード：成功時は 0、上流リクエストの失敗時は 1 （エラーには HTTP ステータスまたは不正な応答が示されます）、使用法エラー時は 2 です。

MCP サーバー

1 つのバイナリで両方の機能を提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/jokebox mcp

MCP クライアントの設定：

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

ツール

ツール	入力	返される内容
get_random_joke_tool	（なし）	ランダムな親父ギャグ 1 件：id とギャグのテキスト。
search_jokes_tool	term（文字列、必須）、limit（整数、任意、デフォルト 5、最大 30）	検索語を含むギャグ：検索語、一致件数、および一致したギャグ。
get_joke_by_id_tool	joke_id（文字列、必須）	その ID に保存されているギャグ 1 件。

開発

npm install
npm 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

ライセンス

MIT — LICENSE を参照してください。