内容
# CatMCP
```text
/\_/\
( o.o ) [ 测试版 ]
> ^ <
_ / \ _
( ) ( )
` ` ` `
\__/\_/
```
**CatMCP** 是一个轻量级、趣味盎然且完全符合标准的 **模型上下文协议（MCP）** 服务器，为 LLM 客户端（如 Claude Desktop、Cursor 等）提供精选的搞笑猫笑话。无论您需要科技段子、经典问答、搞笑场景还是职场猫咪时刻，CatMCP 都能满足您的需求！
---
## 🌟 功能特点
- **完美笑话数据库**：精心整理的 24 个猫笑话，按照主题分类。
- **分类选择**：轻松请求按类别过滤的笑话（`科技`、`经典`、`双关语`、`搞笑`、`职场`）。
- **灵活搜索**：在整个笑话数据库中进行全文不区分大小写的搜索。
- **丰富资源**：
- `jokes://all`：以 JSON 格式读取完整数据集。
- `jokes://categories`：读取所有类别及其笑话数量的摘要。
- `jokes://random`：获取原始文本格式的动态随机笑话。
- **创意提示**：集成交互式提示模板，如 `tell_cat_joke`，将 LLM 变成爱猫的单口相声演员。
- **稳健测试**：使用 `fastmcp` 构建，包含全面的单元测试，以确保高可靠性。
---
## 🚀 快速开始
### 前置条件
- **Python**：`>=3.12`
- **uv**（推荐的包管理器）：[安装 uv](https://github.com/astral-sh/uv)
### 安装
克隆仓库并使用 `uv` 安装依赖项：
```bash
# 克隆仓库
git clone https://github.com/Perseu/catmcp.git
cd catmcp
# 安装依赖项并创建虚拟环境
uv sync
```
### 运行服务器
您可以使用标准 IO（stdio）传输启动 MCP 服务器：
```bash
uv run python main.py
```
---
## 🛠️ MCP 功能
### 1. 工具
- **`get_random_joke(category: 可选[str])`**: 获取一个随机猫笑话。您可以按类别过滤：`科技`、`经典`、`双关语`、`搞笑`或`职场`。
- **`list_categories()`**: 获取所有可用笑话类别的排序列表。
- **`search_jokes(keyword: str)`**: 在笑话设置、结尾和类别中进行不区分大小写的文本搜索。
### 2. 资源
- **`jokes://all`**: 将整个笑话数据库作为静态 JSON 资源提供。
- **`jokes://categories`**: 将类别分布和计数摘要作为 JSON 资源提供。
- **`jokes://random`**: 以纯文本格式提供动态随机猫笑话。
### 3. 提示
- **`tell_cat_joke(category: 可选[str], tone: 可选[str])`**: 生成标准指令集，指导 AI 客户端在指定角色（例如 `CatComedian`）和语气（例如 `sarcastic`、`enthusiastic`、`dry`）下执行笑话。
---
## ⚙️ 主机配置
要将 CatMCP 与您喜欢的 LLM 客户端集成，请将服务器添加到您的配置文件中。
### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"catmcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/catmcp",
"run",
"python",
"main.py"
]
}
}
}
```
### Cursor
1. 进入 **设置** > **功能** > **MCP**。
2. 点击 **+ 新增 MCP 服务器**。
3. 填写字段：
- **名称**：`CatMCP`
- **类型**：`command`
- **命令**：`uv --directory "/absolute/path/to/catmcp" run python main.py`
---
## 🧪 测试
CatMCP 使用 `pytest` 进行测试。您可以运行所有 11 个单元测试来验证服务器工具、资源和提示：
```bash
uv run pytest
```
---
## 📄 许可证
该项目在 **MIT License** 下获得许可。有关详细信息，请参见 [LICENSE](LICENSE) 文件。
---
*由 Perseu 使用 🐾 创建。*
