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

Start your day with humor:
```
Prompt: random-dad-joke
Count: 1
```

Generate topic-specific jokes:

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

Rate team jokes:

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

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

Fork the repository on GitHub

Clone your fork:

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

Create a feature branch:

git checkout -b feature/amazing-feature

Make your changes and test them
Commit your changes:
```
git commit -m "Add amazing feature"
```

Push to your branch:

git push origin feature/amazing-feature

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

Build Errors:

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

MCP Connection Issues:
- Verify Node.js version >= 18.0.0
- Check file paths in MCP client configuration
- Ensure the built files exist in dist/
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! 🤓

Dad Jokes MCP Server

🎯 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

Start your day with humor:
```
Prompt: random-dad-joke
Count: 1
```

Generate topic-specific jokes:

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

Rate team jokes:

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

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

Fork the repository on GitHub

Clone your fork:

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

Create a feature branch:

git checkout -b feature/amazing-feature

Make your changes and test them
Commit your changes:
```
git commit -m "Add amazing feature"
```

Push to your branch:

git push origin feature/amazing-feature

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

Build Errors:

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

MCP Connection Issues:
- Verify Node.js version >= 18.0.0
- Check file paths in MCP client configuration
- Ensure the built files exist in dist/
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. 😄