# 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
### 설치 방법
```bash
# 저장소 클론
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 .
```
### 개발 의존성 설치
```bash
pip install -e ".[dev]"
```
## ⚙️ 설정
### 1. API 키 발급
1. [Neople Developers](https://developers.neople.co.kr)에 가입
2. 애플리케이션 등록
3. Cyphers API 키 발급
### 2. 환경변수 설정
**Linux/macOS:**
```bash
export CYPHERS_API_KEY="your-api-key-here"
```
**Windows:**
```cmd
set CYPHERS_API_KEY=your-api-key-here
```
### 3. 서버 실행
```bash
# 직접 실행
python -m cyphers_mcp.server
# 또는 설치 후 명령어로 실행
cyphers-mcp
```
## 🔧 MCP 클라이언트 설정
### Cursor 설정
Cursor 설정 파일에 추가:
**macOS/Linux:** `~/.cursor/mcp.json`
**Windows:** `%APPDATA%\Cursor\mcp.json`
```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`
```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) 설정
1. VS Code에서 Cline 확장 설치
2. Cline 설정 열기
3. 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`가 설정되었는지 확인하세요.
### 의존성 오류
```bash
# 의존성 재설치
pip install -e . --force-reinstall
```
### MCP 연결 오류
1. Python 버전 확인 (3.10 이상 필요)
2. 패키지가 제대로 설치되었는지 확인
3. 환경변수 경로가 올바른지 확인
## 📚 참고 자료
- [Neople Developers - Cyphers API](https://developers.neople.co.kr/contents/apiDocs/cyphers)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Smithery Documentation](https://smithery.ai/docs)
## 📄 라이선스
MIT License
## 👤 작성자
DHKim327
## 🔗 링크
- [Neople Developers](https://developers.neople.co.kr)
- [Cyphers 공식 사이트](https://cyphers.nexon.com)
