jokegen

An MCP server that generates tailored, learnable jokes for developers. Unlike generic LLM humor, jokegen learns your specific sense of humor through ratings and adapts over time.

Features

• Learns Your Humor: Rate jokes and watch the system adapt to your preferences
• 10 Comedy Styles: From observational to dark humor, absurdist to wholesome
• 10 Joke Patterns: Classical structures like misdirection, rule of three, escalation
• Topic Awareness: Tech, AI, relationships, work, existential dread, and more
• MCP Integration: Works directly with Claude Desktop and Claude CLI
• Preference Persistence: Your humor profile is saved and grows over time
• Avoid Topics: Block topics you don't want jokes about

Installation

pip install -e .

Quick Start

CLI Usage

# Generate a joke
jokegen generate

# Generate with specific style and topic
jokegen generate --style absurdist --topic tech --topic ai

# Rate a joke (use the joke_id shown after generation)
jokegen rate abc123 --rating love --note "perfect timing"

# View your learned preferences
jokegen profile

# List available styles
jokegen styles

# List joke patterns
jokegen patterns

MCP Server (for Claude)

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "jokegen": {
      "command": "python",
      "args": ["-m", "jokegen.mcp.server"]
    }
  }
}

Or start manually:

jokegen serve

MCP Tools

When used with Claude, these tools become available:

Tool	Description
generate_joke	Generate jokes with style, topic, pattern preferences
rate_joke	Rate a joke (1=love, 0=meh, -1=not funny) to train preferences
get_humor_profile	See your learned humor preferences
avoid_topic	Block a topic from appearing in jokes
unblock_topic	Remove a topic from your avoid list
reset_preferences	Start fresh with default preferences
list_styles	See all 10 comedy styles
list_patterns	See all 10 joke structure patterns

Comedy Styles

Style	Description	Think...
observational	Noticing the weird in everyday life	Seinfeld, Mulaney
absurdist	Reality is optional, logic is a suggestion	Tim Robinson, Mitch Hedberg
self_deprecating	I'm a mess and we're all in on it	Ali Siddiq, Gary Gulman
curmudgeon	Everything is ridiculous and I'm tired	Bill Burr, Sebastian Maniscalco
dark	Finding humor in places we shouldn't	Anthony Jeselnik, Daniel Sloss
storytelling	Taking you on a journey with a twist ending	Bert Kreischer, Tom Segura
wordplay	Language is a playground	Demetri Martin, Bo Burnham
social_commentary	Pointing out systemic absurdity	George Carlin, Hasan Minhaj
character	Becoming someone else entirely	Kate McKinnon, Fred Armisen
wholesome	Finding joy in simple things	Nate Bargatze, Jim Gaffigan
dad_joke	Weaponized puns that demand a groan	Phil Dunphy, r/dadjokes

Joke Patterns

Pattern	Description
setup_punchline	Classic two-part: establish expectation, then subvert
misdirection	Lead one direction, reveal something unexpected
escalation	Start normal, keep adding absurdity
callback	Reference something from earlier in new context
deconstruction	Acknowledge the joke format, then flip it
juxtaposition	Place contrasting things together
self_aware	The joke acknowledges it's a joke
rule_of_three	Two normal things, third breaks the pattern
subverted_expectation	Set up clear expectation, deliver opposite
absurd_premise	Start ridiculous, play completely straight
pun_bomb	Setup question → groan-worthy pun answer

How Learning Works

┌─────────────────────────────────────┐
│ 1. Generate joke (style + topic)    │
├─────────────────────────────────────┤
│ 2. You rate: love / meh / not funny │
├─────────────────────────────────────┤
│ 3. System updates weights:          │
│    - Style preference increases     │
│    - Topic affinity adjusts         │
│    - Pattern success tracked        │
├─────────────────────────────────────┤
│ 4. Next generation adapts to you    │
└─────────────────────────────────────┘

Your preferences are stored locally in:

• Windows: %APPDATA%\jokegen\
• macOS: ~/Library/Application Support/jokegen/
• Linux: ~/.local/share/jokegen/

Example Session with Claude

You: Tell me a joke about AI

Claude: [uses generate_joke with topic=["ai"]]

Here's one:

"My AI assistant said it would 'handle my schedule.'
Now I have 47 meetings with myself and a reminder to
'contemplate the void' at 3 PM daily."

(Joke ID: f7a2c1b)

Did that land? You can say "rate f7a2c1b love" if it did!

You: rate f7a2c1b love

Claude: [uses rate_joke]

Got it! I've noted you enjoyed that absurdist + AI combo.
I'll lean into that style more.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check your config paths
jokegen config

License

MIT