🎭 Joke MCP Server

一个简单而强大的模型上下文协议（MCP）服务器，为 AI 交互带来幽默。该 MCP 将随机笑话生成作为工具暴露出来，可以无缝集成到 Claude 和其他兼容 MCP 的客户端中。

✨ 功能特性

• get_random_joke - 获取一个包含铺垫和笑点的随机笑话

• count_jokes - 获取数据库中可用笑话的总数

• 简单轻量 - 依赖最少，执行快速

• 易于集成 - 适用于 Claude Desktop 和其他 MCP 客户端

• 文档完善 - 清晰的模式和用法示例

Related MCP server: Jokes MCP Server

🚀 快速开始

先决条件

• Python 3.11 或更高版本

• pip 包管理器

安装

# 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

运行服务器

python joke-mcp.py

你应该看到：

🚀 Joke MCP Server starting...

📖 使用方法

与 Claude Desktop 一起使用

将此添加到你的 Claude Desktop 配置文件中：

macOS/Linux： ~/.config/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

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

然后重启 Claude Desktop，你就可以让 Claude 讲笑话了！

API 参考

get_random_joke

返回一个包含铺垫和笑点的随机笑话。

输入： 无

输出：

Setup: Why don't scientists trust atoms?

Punchline: Because they make up everything!

count_jokes

返回数据库中可用笑话的总数。

输入： 无

输出：

Total jokes: 5

🏗️ 项目结构

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

🔧 技术细节

构建工具

• Python 3.11+ - 编程语言

• MCP SDK v1.0.0 - 模型上下文协议库

• Asyncio - 异步编程

工作原理

Joke MCP Server：

1. 启动一个监听 stdio 的 MCP 服务器

2. 注册可用工具及其模式

3. 处理来自 MCP 客户端的传入请求

4. 返回包含笑话数据的格式化响应

# 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

📦 依赖

• mcp==1.0.0 - 模型上下文协议 SDK

完整依赖列表请参阅 requirements.txt。

🎯 当前功能

✅ 5 个内置笑话 ✅ 支持 Async/await ✅ 清晰的错误处理 ✅ 基于模式的简单工具定义 ✅ Stdout 日志记录

🔮 未来增强

• 添加笑话分类（爸爸笑话、双关语、黑色幽默）

• 实现难度等级

• 添加笑话评分/反馈

• 连接外部笑话 API

• 持久化用户收藏

• 多语言支持

• 用于笑话管理的 Web UI

🤝 贡献

欢迎：

• 向数据库添加更多笑话

• 改进文档

• 报告错误

• 建议新功能

📝 许可证

本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

🔗 链接

• GitHub： https://github.com/tehrimaly/mcp-guide

• MCP 规范： https://spec.modelcontextprotocol.io/

• Anthropic MCP 文档： https://modelcontextprotocol.io/

💡 示例用例

1. AI 助手集成 - 为 Claude 交互添加幽默

2. Slack 机器人 - 将笑话集成到团队沟通中

3. 学习工具 - 了解 MCP 实现基础

4. 模板 - 作为你自己的 MCP 服务器的起点

🐛 故障排除

问题：模块未找到错误

pip install -r requirements.txt

问题：端口已被占用 服务器使用 stdio，而不是端口。这种情况不应发生。

问题：服务器无法启动

• 检查 Python 版本（3.11+）

• 确认所有依赖已安装

• 检查语法错误

📧 支持

如有问题、疑问或建议，请在 GitHub 上提交 issue。