CatMCP

       /\_/\
      ( o.o )   [ BETA ]
       > ^ <
     _ /   \ _
    ( )     ( )
    ` `     ` `
     \__/\_/

CatMCP is a lightweight, playful, and fully standard-compliant Model Context Protocol (MCP) server that serves a curated collection of hilarious cat jokes to LLM clients (like Claude Desktop, Cursor, and more). Whether you need tech puns, classic question-and-answers, silly scenarios, or workplace meow-ments, CatMCP has you covered!

---

🌟 Features

• Purr-fect Joke Database: Hand-crafted collection of 24 cat jokes categorized by themes.
• Categorized Selections: Easily request jokes filtered by category (tech, classic, puns, silly, work).
• Flexible Searching: Full-text case-insensitive search across the entire joke database.
• Rich Resources:
  • jokes://all: Read the complete dataset in JSON format.
  • jokes://categories: Read a summary of all categories and their joke counts.
  • jokes://random: Fetch a dynamic random joke in raw text format.
• Creative Prompts: Integrate interactive prompt templates like tell_cat_joke to turn LLMs into cat-loving stand-up comedians.
• Robustly Tested: Built using fastmcp with comprehensive unit tests for high reliability.

---

🚀 Quick Start

Prerequisites

• Python: >=3.12
• uv (Recommended package manager): Install uv

Installation

Clone the repository and install dependencies using uv:

# Clone the repository
git clone https://github.com/Perseu/catmcp.git
cd catmcp

# Install dependencies and create a virtual environment
uv sync

Running the Server

You can start the MCP server using standard IO (stdio) transport:

uv run python main.py

---

🛠️ MCP Capabilities

1. Tools

• get_random_joke(category: Optional[str]): Retrieve a random cat joke. You can filter by category: tech, classic, puns, silly, or work.
• list_categories(): Get a sorted list of all available joke categories.
• search_jokes(keyword: str): Case-insensitive text search across joke setups, punchlines, and categories.

2. Resources

• jokes://all: Serves the entire joke database as a static JSON resource.
• jokes://categories: Serves the category distribution and count summary as a JSON resource.
• jokes://random: Serves a dynamic random cat joke in plain text format.

3. Prompts

• tell_cat_joke(category: Optional[str], tone: Optional[str]): Generates a standard instruction set directing the AI client to perform the joke under a specified persona (e.g. CatComedian) and tone (e.g. sarcastic, enthusiastic, dry).

---

⚙️ Host Configuration

To integrate CatMCP with your favorite LLM client, add the server to your configuration file.

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "catmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/catmcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Cursor

1. Go to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Fill in the fields:
   • Name: CatMCP
   • Type: command
   • Command: uv --directory "/absolute/path/to/catmcp" run python main.py

---

🧪 Testing

CatMCP uses pytest for testing. You can run all 11 unit tests to verify server tools, resources, and prompts:

uv run pytest

---

📄 License

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

---

Created with 🐾 by Perseu.