Dad Jokes MCP Server

A professional Model Context Protocol (MCP) server that brings the joy of dad jokes to your development workflow. Perfect for lightening the mood during code reviews, team meetings, or when you need a quick laugh break.

🎯 Features

• Multiple Joke Styles: Classic, punny, wholesome, and groan-worthy variants
• Topic-Based Generation: Generate jokes about specific subjects
• Random Joke Generation: Get random jokes when you need inspiration
• Joke Rating System: Rate and get feedback on dad jokes
• Category Browser: Explore available joke categories
• Fun Statistics: Get interesting dad joke statistics
• Type-Safe: Built with TypeScript for robust development
• Professional Architecture: Clean, maintainable code structure

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• TypeScript knowledge (optional but helpful)

Installation

# Clone the repository
git clone https://github.com/OrenGrinker/dad-jokes-mcp-server.git
cd dad-jokes-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Development Setup

# Run in development mode with auto-rebuild
npm run dev

# Run linting
npm run lint

# Run tests (when implemented)
npm test

# Clean build directory
npm run clean

📋 Available Prompts

generate-dad-joke

Generate a dad joke on a specific topic with optional style.

Parameters:

• topic (string): The subject for the joke
• style (optional string): "classic", "punny", "wholesome", or "groan-worthy"

Example:

{
  "topic": "programming",
  "style": "punny"
}

Sample Output:

"Why do programmers prefer dark mode? Because light attracts bugs!"

random-dad-joke

Generate random dad jokes.

Parameters:

• count (optional string): Number of jokes to generate ("1" to "5")

Example:

{
  "count": "3"
}

rate-dad-joke

Get a professional rating and feedback for a dad joke.

Parameters:

• joke (string): The joke to evaluate

Example:

{
  "joke": "Why don't scientists trust atoms? Because they make up everything!"
}

🛠️ Available Tools

get-joke-categories

Retrieve all available joke categories.

Parameters: None

Returns: List of 15 joke categories including Animals, Food, Technology, Sports, etc.

joke-stats

Get fun statistics about dad jokes.

Parameters: None

Returns: Entertaining statistics like success rates, average groan time, and more!

🔧 Integration with MCP Clients

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dad-jokes": {
      "command": "node",
      "args": ["/path/to/dad-jokes-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, use the stdio transport:

node /path/to/dad-jokes-mcp-server/dist/index.js

🏗️ Architecture

The server is built with a clean, object-oriented architecture:

src/
├── index.ts          # Main server class and startup logic
├── types/            # TypeScript type definitions (future expansion)
├── prompts/          # Prompt configurations (future expansion)
└── tools/            # Tool implementations (future expansion)

Key Components

• DadJokesMcpServer: Main server class handling MCP protocol
• Prompt Management: Organized prompt definitions with proper validation
• Tool Integration: Extensible tool system for additional functionality
• Error Handling: Comprehensive error handling and logging
• Type Safety: Full TypeScript coverage with strict configuration

📖 Usage Examples

Example Workflow

1. Start your day with humor:

   Prompt: random-dad-joke
   Count: 1
   

2. Generate topic-specific jokes:

   Prompt: generate-dad-joke
   Topic: "TypeScript"
   Style: "punny"
   

3. Rate team jokes:

   Prompt: rate-dad-joke
   Joke: "Why do developers wear glasses? Because they can't C#!"
   

4. Browse categories for inspiration:

   Tool: get-joke-categories
   

Integration Ideas

• Code Review Comments: Add dad jokes to lighten PR reviews
• Team Standup: Start meetings with a daily dad joke
• Error Messages: Soften build failures with humor
• Documentation: Add personality to technical docs
• Slack Bots: Integrate with team communication tools

🧪 Testing

The project includes a basic test structure:

# Run tests (implement tests in tests/ directory)
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

Manual Testing

Test the server manually:

# Build and start
npm run build && npm start

# In another terminal, test with sample MCP client
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | node dist/index.js

🔧 Configuration

Environment Variables

# Optional: Enable debug logging
DEBUG=true

# Optional: Set custom logging level
LOG_LEVEL=info

Customization

Modify the joke categories, styles, or statistics by editing the arrays in src/index.ts:

// Add new categories
const categories = [
  "Animals", "Food", "Technology", // ... existing
  "Your Custom Category"
];

// Add new joke styles
const styles = ["classic", "punny", "wholesome", "groan-worthy", "your-style"];

📦 Publishing

To publish to npm:

# Ensure you're logged into npm
npm login

# Build and prepare for publishing
npm run prepublishOnly

# Publish (update version in package.json first)
npm version patch  # or minor/major
npm publish

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Start for Contributors

1. Fork the repository on GitHub
2. Clone your fork:

   git clone https://github.com/YOUR-USERNAME/dad-jokes-mcp-server.git
   cd dad-jokes-mcp-server
   

3. Create a feature branch:

   git checkout -b feature/amazing-feature
   

4. Make your changes and test them
5. Commit your changes:

   git commit -m "Add amazing feature"
   

6. Push to your branch:

   git push origin feature/amazing-feature
   

7. Open a Pull Request on GitHub

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation for API changes
• Run npm run lint before committing
• Keep jokes family-friendly and inclusive

Ideas for Contributions

• 🎭 New joke categories (Science, Gaming, etc.)
• 🛠️ Additional tools (joke history, favorites)
• 🎨 Joke formatting (ASCII art, emojis)
• 🧪 Test coverage improvements
• 📚 Documentation enhancements
• 🚀 Performance optimizations

🐛 Troubleshooting

Common Issues

1. Build Errors:

   # Clear cache and rebuild
   npm run clean && npm install && npm run build
   

2. MCP Connection Issues:

   • Verify Node.js version >= 18.0.0
   • Check file paths in MCP client configuration
   • Ensure the built files exist in dist/

3. TypeScript Errors:

   • Run npm run lint to check for issues
   • Verify all dependencies are installed

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Check the README and code comments

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎭 Why Dad Jokes?

Dad jokes are more than just humor—they're:

• Ice breakers for team meetings
• Stress relievers during intense coding sessions
• Conversation starters in code reviews
• Morale boosters for development teams
• Universal language that transcends technical barriers
• Confidence builders (if you can survive a dad joke, you can handle any code review)

🚀 Roadmap

Future enhancements we're considering:

• 🎯 Joke persistence (save favorites)
• 🌐 Multi-language support
• 🤖 AI-powered joke generation improvements
• 📊 Analytics (most popular jokes, usage stats)
• 🎨 Rich formatting (markdown, emojis)
• 🔌 More integrations (Slack, Discord, etc.)

🙏 Acknowledgments

• Model Context Protocol team for the excellent framework
• The dad joke community for endless inspiration
• All contributors who help make this project better
• Every developer who appreciates a good (bad) pun

📊 Project Stats

• Language: TypeScript
• Runtime: Node.js
• Protocol: Model Context Protocol (MCP)
• License: MIT
• Maintainer: OrenGrinker

---

Remember: A day without laughter is a day wasted, but a day with dad jokes is a day where everyone groans together. 😄

Fun Fact: This README contains exactly 42 dad joke references. That's not a coincidence – it's the answer to life, the universe, and everything... including why developers love terrible puns! 🤓