# Cyphers MCP Server 설치 및 사용 가이드
## 📦 빠른 시작
### 1. API 키 준비
APIKey.json 파일에 이미 키가 저장되어 있습니다:
```json
{
"CyphersAPIKey": "t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
}
```
### 2. 환경변수 설정
**Linux/macOS:**
```bash
export CYPHERS_API_KEY="t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
```
**Windows (PowerShell):**
```powershell
$env:CYPHERS_API_KEY = "t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
```
**Windows (CMD):**
```cmd
set CYPHERS_API_KEY=t1krdM3IID25rYwIowrvZvlQv3X1AHzF
```
### 3. 빌드 확인
빌드는 이미 완료되었습니다! `dist/` 폴더에 컴파일된 파일들이 있습니다.
## 🔧 Cursor에서 사용하기
### Cursor 설정 파일 위치:
- **macOS/Linux**: `~/.cursor/mcp_config.json` 또는 `~/.config/cursor/mcp_config.json`
- **Windows**: `%APPDATA%\Cursor\mcp_config.json`
### 설정 추가:
```json
{
"mcpServers": {
"cyphers": {
"command": "node",
"args": ["/home/kdhadsfasdf/CyphersMCPServer/dist/index.js"],
"env": {
"CYPHERS_API_KEY": "t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
}
}
}
}
```
## 🤖 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": "node",
"args": ["/home/kdhadsfasdf/CyphersMCPServer/dist/index.js"],
"env": {
"CYPHERS_API_KEY": "t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
}
}
}
}
```
## 🎯 Cline (VS Code)에서 사용하기
1. VS Code에서 Cline 확장 설치
2. Cline 설정 열기 (Command Palette: `Cline: Settings`)
3. MCP 서버 섹션에서 "Add Server" 클릭
4. 다음 정보 입력:
- **Name**: `cyphers`
- **Command**: `node`
- **Args**: `/home/kdhadsfasdf/CyphersMCPServer/dist/index.js`
- **Environment Variables**:
- Key: `CYPHERS_API_KEY`
- Value: `t1krdM3IID25rYwIowrvZvlQv3X1AHzF`
또는 Cline의 설정 파일에 직접 추가:
```json
{
"cline.mcpServers": {
"cyphers": {
"command": "node",
"args": ["/home/kdhadsfasdf/CyphersMCPServer/dist/index.js"],
"env": {
"CYPHERS_API_KEY": "t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
}
}
}
}
```
## ✅ 테스트하기
설정 후 MCP 클라이언트를 재시작하고 다음과 같이 테스트해보세요:
### 테스트 프롬프트 예시:
1. **플레이어 검색**
```
사이퍼즈에서 닉네임 "테스트"로 플레이어를 검색해줘
```
2. **캐릭터 목록 조회**
```
사이퍼즈의 모든 캐릭터 목록을 보여줘
```
3. **랭킹 조회**
```
사이퍼즈 통합 랭킹 상위 10명을 보여줘
```
## 🔍 문제 해결
### 서버가 시작되지 않는 경우
1. Node.js 버전 확인 (18.0.0 이상 필요):
```bash
node --version
```
2. 빌드 파일 확인:
```bash
ls -la /home/kdhadsfasdf/CyphersMCPServer/dist/
```
3. 수동으로 서버 실행 테스트:
```bash
cd /home/kdhadsfasdf/CyphersMCPServer
export CYPHERS_API_KEY="t1krdM3IID25rYwIowrvZvlQv3X1AHzF"
node dist/index.js
```
### API 키 오류가 발생하는 경우
환경변수가 제대로 설정되었는지 확인:
```bash
echo $CYPHERS_API_KEY
```
### 재빌드가 필요한 경우
```bash
cd /home/kdhadsfasdf/CyphersMCPServer
npm run build
```
## 📚 사용 가능한 Tools
서버가 제공하는 13개의 도구:
### 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` - 여러 아이템 조회
### Character Tools
- `cy_characters_list` - 캐릭터 목록
### Image Tools
- `cy_images_character_url` - 캐릭터 이미지 URL
- `cy_images_item_url` - 아이템 이미지 URL
## 🚀 Smithery 배포 (선택사항)
나중에 다른 사람들과 공유하려면:
1. GitHub 저장소 생성 및 푸시
2. Smithery에 등록: https://smithery.ai
3. 설정 파일이 이미 준비되어 있습니다 (`smithery.json`)
## 💡 팁
1. **캐싱**: 서버는 자동으로 응답을 캐싱하여 API 호출을 최소화합니다
2. **레이트 리밋**: 자동으로 요청을 제한하여 API 제한을 준수합니다
3. **에러 처리**: 모든 에러는 구조화되어 반환됩니다
## 🔗 참고 링크
- [Neople Developers](https://developers.neople.co.kr)
- [Cyphers API 문서](https://developers.neople.co.kr/contents/apiDocs/cyphers)
- [MCP 공식 문서](https://modelcontextprotocol.io)
