# Cyphers MCP Server (Python)

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

## 📋 소개

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

## ✨ 주요 기능

### 📚 Resources (게임 컨텍스트)
MCP Server가 LLM에게 사이퍼즈 게임에 대한 컨텍스트를 제공합니다:

| Resource URI | 설명 |
|--------------|------|
| `cyphers://game-context` | 게임 규칙, 시스템, 용어, 메타 분석 등 |
| `cyphers://characters` | 캐릭터 목록, 역할 분류, 평가 지표 등 |

LLM이 API 데이터를 받았을 때 올바르게 해석하고 분석할 수 있도록 도와줍니다.

### 🔧 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   # 레이트 리밋 관리
├── docs/                 # 게임 컨텍스트 문서 (MCP Resources)
│   ├── cyphers_game_context.md  # 게임 규칙, 용어, 메타
│   └── characters_reference.md  # 캐릭터 목록, 역할 분류
├── note/                 # 프로젝트 노트
├── pyproject.toml        # Python 패키지 설정
├── README.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)