# 🎭 Joke MCP Server

A simple yet powerful Model Context Protocol (MCP) server that brings humor to AI interactions. This MCP exposes random joke generation as tools that can be seamlessly integrated with Claude and other MCP-compatible clients.

## ✨ Features

- **`get_random_joke`** - Get a random joke with setup and punchline
- **`count_jokes`** - Get the total number of available jokes in the database
- **Simple & Lightweight** - Minimal dependencies, fast execution
- **Easy Integration** - Works with Claude Desktop and other MCP clients
- **Well-Documented** - Clear schemas and usage examples

## 🚀 Quick Start

### Prerequisites
- Python 3.11 or higher
- pip package manager

### Installation

```bash
# Clone the repository
git clone https://github.com/tehrimaly/mcp-joke.git
cd mcp-joke

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\Activate.ps1
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### Running the Server

```bash
python joke-mcp.py
```

You should see:
```
🚀 Joke MCP Server starting...
```

## 📖 Usage

### With Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS/Linux:** `~/.config/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "joke-mcp": {
      "command": "python",
      "args": ["/path/to/joke-mcp.py"]
    }
  }
}
```

Then restart Claude Desktop and you can ask Claude to tell jokes!

### API Reference

#### `get_random_joke`
Returns a random joke with setup and punchline.

**Input:** None

**Output:**
```
Setup: Why don't scientists trust atoms?

Punchline: Because they make up everything!
```

#### `count_jokes`
Returns the total number of jokes available in the database.

**Input:** None

**Output:**
```
Total jokes: 5
```

## 🏗️ Project Structure

```
mcp-joke/
├── joke-mcp.py          # Main MCP server implementation
├── requirements.txt      # Python dependencies
├── README.md            # This file
├── .gitignore           # Git configuration
└── LICENSE              # MIT License
```

## 🔧 Technical Details

### Built With
- **Python 3.11+** - Programming language
- **MCP SDK v1.0.0** - Model Context Protocol library
- **Asyncio** - Asynchronous programming

### How It Works

The Joke MCP Server:
1. Starts an MCP server listening on stdio
2. Registers available tools with their schemas
3. Handles incoming requests from MCP clients
4. Returns formatted responses with joke data

```python
# Tool registration example
@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_random_joke",
            description="Get a random joke",
            inputSchema={...}
        )
    ]

# Tool execution
@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_random_joke":
        # Return random joke
```

## 📦 Dependencies

- `mcp==1.0.0` - Model Context Protocol SDK

See `requirements.txt` for complete dependency list.

## 🎯 Current Features

✅ 5 built-in jokes
✅ Async/await support
✅ Clean error handling
✅ Simple schema-based tool definition
✅ Stdout logging

## 🔮 Future Enhancements

- [ ] Add joke categories (dad jokes, puns, dark humor)
- [ ] Implement difficulty levels
- [ ] Add joke ratings/feedback
- [ ] Connect to external joke APIs
- [ ] Persist user favorites
- [ ] Multi-language support
- [ ] Web UI for joke management

## 🤝 Contributing

Feel free to:
- Add more jokes to the database
- Improve documentation
- Report bugs
- Suggest new features

## 📝 License

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

## 🔗 Links

- **GitHub:** https://github.com/tehrimaly/mcp-joke
- **MCP Specification:** https://spec.modelcontextprotocol.io/
- **Anthropic MCP Docs:** https://modelcontextprotocol.io/

## 💡 Example Use Cases

1. **AI Assistant Integration** - Add humor to Claude interactions
2. **Slack Bot** - Integrate jokes into team communication
3. **Learning Tool** - Understand MCP implementation basics
4. **Template** - Use as a starting point for your own MCP servers

## 🐛 Troubleshooting

**Issue: Module not found error**
```bash
pip install -r requirements.txt
```

**Issue: Port already in use**
The server uses stdio, not a port. This shouldn't occur.

**Issue: Server won't start**
- Check Python version (3.11+)
- Verify all dependencies installed
- Check for syntax errors

## 📧 Support

For issues, questions, or suggestions, please open a GitHub issue.

---

**Made with ❤️ as part of the MCP learning journey**