sensor-humor Handbook

sensor-humor is an MCP tool that gives your LLM a persistent comedic sidekick. It provides mood-based personality, session-aware callbacks, running gags, roasts, heckles, and catchphrases — with optional voice integration via Piper TTS.

What it does

Instead of making the host LLM funnier directly, sensor-humor acts as a comedy sidekick — a distinct voice that chimes in when called. The host LLM decides when to request humor, gets structured JSON back, and weaves it into its response (or doesn’t).

This separation means:

• The host LLM stays precise and serious by default
• Comedy is deterministic and observable (JSON schema enforced, logged, validated)
• Session state (gags, callbacks, catchphrases) is managed independently
• You can toggle it off instantly — just stop calling the tools

How it works

1. You set a mood (dry, roast, chaotic, cheeky, cynic, zoomer)
2. You call a tool (comic_timing, roast, heckle, catchphrase)
3. sensor-humor builds a prompt from the mood’s skeleton prompt + session state summary + your input
4. A local Ollama model (qwen2.5:7b by default) generates the comedy under strict JSON schema
5. sensor-humor validates the output, updates session state, and returns clean structured data
6. Optionally, the output is spoken via Piper TTS with mood-specific prosody

What makes it different

Most humor tools are joke databases or prompt wrappers. sensor-humor is a comedy director that manages:

• Continuity — callbacks to earlier bits, running gags that evolve, catchphrases that recur
• Voice — each mood has a distinct personality anchor and fill-in-the-blank skeleton
• Prosody — when paired with Piper TTS, dry sounds flat, roast sounds sarcastic, chaotic sounds erratic
• Determinism — every output is schema-validated, length-capped, and checked for banned patterns