# CatMCP

```text
       /\_/\
      ( 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](https://github.com/astral-sh/uv)

### Installation
Clone the repository and install dependencies using `uv`:

```bash
# 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:

```bash
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`:

```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:

```bash
uv run pytest
```

---

## 📄 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---
*Created with 🐾 by Perseu.*