Cyphers MCP Server (Python)

Neople Cyphers Open API를 위한 MCP (Model Context Protocol) 서버입니다.

📋 소개

이 MCP 서버는 Neople의 Cyphers Open API를 Claude, Cursor, Cline 등의 AI 어시스턴트에서 쉽게 사용할 수 있도록 합니다. 플레이어 검색, 매칭 기록 조회, 랭킹 조회, 아이템 검색 등 다양한 기능을 제공합니다.

✨ 주요 기능

Player Tools

cy_players_search - 닉네임으로 플레이어 검색
cy_players_get - 플레이어 상세 정보 조회
cy_players_matches - 플레이어 매칭 기록 조회

Match Tools

cy_matches_get - 매치 상세 정보 조회

Ranking Tools

cy_ranking_ratingpoint - 통합 랭킹 조회
cy_ranking_characters - 캐릭터별 랭킹 조회
cy_ranking_tsj - 투신전 랭킹 조회

Item Tools

cy_battleitems_search - 아이템 검색
cy_battleitems_get - 아이템 상세 조회
cy_battleitems_multi_get - 여러 아이템 한번에 조회 (최대 30개)

Character Tools

cy_characters_list - 모든 캐릭터 목록 조회

Image Tools

cy_images_character_url - 캐릭터 이미지 URL 생성
cy_images_item_url - 아이템 이미지 URL 생성

🚀 설치

필수 요구사항

Python 3.10 이상
pip 또는 uv

설치 방법

# 저장소 클론
git clone https://github.com/DHKim327/CyphersMCPServer.git
cd CyphersMCPServer

# venv 환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 의존성 설치
pip install -e .

개발 의존성 설치

pip install -e ".[dev]"

⚙️ 설정

1. API 키 발급

Neople Developers에 가입
애플리케이션 등록
Cyphers API 키 발급

2. 환경변수 설정

Linux/macOS:

export CYPHERS_API_KEY="your-api-key-here"

Windows:

set CYPHERS_API_KEY=your-api-key-here

3. 서버 실행

# 직접 실행
python -m cyphers_mcp.server

# 또는 설치 후 명령어로 실행
cyphers-mcp

🔧 MCP 클라이언트 설정

Cursor 설정

Cursor 설정 파일에 추가:

macOS/Linux: ~/.cursor/mcp.json Windows: %APPDATA%\Cursor\mcp.json

{
  "mcpServers": {
    "cyphers": {
      "command": "python",
      "args": ["-m", "cyphers_mcp.server"],
      "cwd": "/path/to/CyphersMCPServer",
      "env": {
        "CYPHERS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop 설정

Claude Desktop 설정 파일에 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cyphers": {
      "command": "python",
      "args": ["-m", "cyphers_mcp.server"],
      "cwd": "/home/kdhadsfasdf/CyphersMCPServer",
      "env": {
        "CYPHERS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline (VS Code Extension) 설정

VS Code에서 Cline 확장 설치
Cline 설정 열기
MCP 서버 추가:
- 명령: python -m cyphers_mcp.server
- 환경변수: CYPHERS_API_KEY=your-api-key-here

📖 사용 예시

플레이어 검색

닉네임 "플레이어이름"으로 사이퍼즈 플레이어를 검색해줘

최근 전적 조회

플레이어 ID "xxx"의 최근 10경기를 조회하고 승률을 분석해줘

랭킹 조회

현재 레이팅 상위 10명의 랭킹을 보여줘

🏗️ 프로젝트 구조

CyphersMCPServer/
├── cyphers_mcp/
│   ├── __init__.py       # 패키지 초기화
│   ├── server.py         # MCP 서버 메인
│   ├── api_client.py     # Cyphers API 클라이언트
│   ├── types.py          # 타입 정의
│   ├── cache.py          # 캐싱 관리
│   └── rate_limiter.py   # 레이트 리밋 관리
├── note/                 # 프로젝트 노트
├── pyproject.toml        # Python 패키지 설정
├── README.md             # 이 문서
├── INSTALLATION.md       # 상세 설치 가이드
├── INTRODUCTION.md       # 프로젝트 소개
├── DETAIL.md             # 상세 기술 문서
└── smithery.json         # Smithery 배포 설정

🔧 고급 기능

캐싱

서버는 자동으로 응답을 캐싱하여 API 호출을 최적화합니다:

캐릭터 목록: 24시간
아이템 상세: 6시간
플레이어 정보: 5분
랭킹: 1분
매치 기록: 30초

레이트 리밋

Neople API의 레이트 리밋을 준수하기 위해 자동으로 요청을 제한합니다:

초당 최대 100건 (보수적 설정)
분당 최대 5,000건
시간당 최대 300,000건

🐛 문제 해결

API 키 오류

Error: CYPHERS_API_KEY environment variable is required

→ 환경변수 CYPHERS_API_KEY가 설정되었는지 확인하세요.

의존성 오류

# 의존성 재설치
pip install -e . --force-reinstall

MCP 연결 오류

Python 버전 확인 (3.10 이상 필요)
패키지가 제대로 설치되었는지 확인
환경변수 경로가 올바른지 확인

📚 참고 자료

📄 라이선스

MIT License

👤 작성자

DHKim327

🔗 링크