🎭 Joke MCP Server

AI 상호작용에 유머를 더하는, 간단하면서도 강력한 Model Context Protocol (MCP) 서버입니다. 이 MCP는 무작위 농담 생성 기능을 도구(tool)로 노출하며, Claude 및 기타 MCP 호환 클라이언트와 원활하게 통합할 수 있습니다.

✨ 기능

• get_random_joke - 셋업(setup)과 펀치라인(punchline)이 포함된 무작위 농담 가져오기

• 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 - Model Context Protocol 라이브러리

• 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 - Model Context Protocol SDK

전체 의존성 목록은 requirements.txt를 참조하세요.

🎯 현재 기능

✅ 내장 농담 5개 ✅ Async/await 지원 ✅ 깔끔한 오류 처리 ✅ 간단한 스키마 기반 도구 정의 ✅ Stdout 로깅

🔮 향후 개선 사항

• 농담 카테고리 추가 (아재 개그, 말장난, 다크 유머)

• 난이도 레벨 구현

• 농담 평점/피드백 추가

• 외부 농담 API 연동

• 사용자 즐겨찾기 저장

• 다국어 지원

• 농담 관리를 위한 웹 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 이슈를 열어주세요.