# Cyphers MCP Server 완벽 가이드
> Neople Cyphers Open API를 위한 MCP (Model Context Protocol) 서버 - Python 버전
---
## 📖 목차
1. [프로젝트 소개](#1-프로젝트-소개)
2. [MCP와 Smithery 이해하기](#2-mcp와-smithery-이해하기)
3. [Cyphers Open API 개요](#3-cyphers-open-api-개요)
4. [설치 및 환경 설정](#4-설치-및-환경-설정)
5. [MCP 클라이언트 설정](#5-mcp-클라이언트-설정)
6. [사용 가능한 Tools](#6-사용-가능한-tools)
7. [사용 예시](#7-사용-예시)
8. [고급 기능](#8-고급-기능)
9. [문제 해결](#9-문제-해결)
10. [Smithery 배포](#10-smithery-배포)
---
## 1. 프로젝트 소개
### 1.1 목적
이 프로젝트는 **Neople Cyphers Open API**를 **MCP Server**로 감싸서, Claude, Cursor, Cline 등의 AI 어시스턴트에서 쉽게 사용할 수 있도록 합니다.
### 1.2 주요 특징
- 🎮 **13개의 MCP Tools**: 플레이어, 매치, 랭킹, 아이템, 캐릭터, 이미지 URL
- 🚀 **Python 기반**: Python 3.10+ 지원, 비동기(async/await) 처리
- ⚡ **자동 캐싱**: API 호출 최소화 및 응답 속도 향상
- 🛡️ **레이트 리밋**: Neople API 제한 준수
- 🔧 **에러 처리**: 구조화된 에러 응답
### 1.3 프로젝트 구조
```
CyphersMCPServer/
├── cyphers_mcp/ # Python 패키지
│ ├── __init__.py # 패키지 초기화
│ ├── server.py # MCP 서버 메인 진입점
│ ├── api_client.py # Cyphers API 클라이언트 (httpx)
│ ├── types.py # 타입 정의 (dataclass)
│ ├── cache.py # 메모리 캐시 관리
│ └── rate_limiter.py # Token Bucket 레이트 리밋
├── pyproject.toml # Python 패키지 설정
├── smithery.json # Smithery 배포 설정
├── README.md # 간단한 사용 가이드
└── GUIDE.md # 이 문서 (상세 가이드)
```
---
## 2. MCP와 Smithery 이해하기
### 2.1 MCP (Model Context Protocol)란?
MCP는 **LLM 클라이언트가 외부 도구(tool)에 연결하는 표준 프로토콜**입니다.
- **서버**: Tools(도구), Resources(리소스), Prompts(프롬프트)를 제공
- **클라이언트**: Claude Desktop, Cursor, Cline 등 AI 어시스턴트
- **프로토콜**: JSON-RPC 기반 통신
- **공식 문서**: https://modelcontextprotocol.io
```
[AI 어시스턴트] <--MCP--> [MCP 서버] <--HTTP--> [Cyphers API]
```
### 2.2 Smithery란?
Smithery는 **MCP 서버를 배포하고 공유하는 플랫폼**입니다.
- MCP 서버 레지스트리 (검색/설치)
- 원클릭 설치 지원
- 시크릿(API 키) 관리
- **공식 사이트**: https://smithery.ai
---
## 3. Cyphers Open API 개요
### 3.1 기본 정보
| 항목 | 값 |
|------|-----|
| API Gateway | `https://api.neople.co.kr` |
| 서비스 경로 | `/cy/` |
| HTTP 메서드 | GET only |
| 인증 방식 | Query Parameter `apikey` |
| 응답 형식 | JSON (UTF-8) |
### 3.2 API 키 발급
1. [Neople Developers](https://developers.neople.co.kr) 가입
2. 애플리케이션 등록
3. Cyphers API 키 발급
### 3.3 레이트 리밋 (요청 제한)
| 단위 | 제한 |
|------|------|
| 초당 | 1,000건 |
| 분당 | 60,000건 |
| 시간당 | 3,600,000건 |
> 이 서버는 보수적으로 초당 100건, 분당 5,000건으로 제한합니다.
### 3.4 에러 코드
| HTTP Status | 에러 코드 | 설명 |
|-------------|-----------|------|
| 401 | API003 | 유효하지 않은 API 키 |
| 404 | CY002 | 유효하지 않은 플레이어 ID |
| 429 | - | 요청 제한 초과 |
| 500+ | - | 서버 오류 |
### 3.5 API 엔드포인트 목록
| 분류 | 엔드포인트 | 설명 |
|------|-----------|------|
| **Player** | `GET /cy/players` | 닉네임으로 플레이어 검색 |
| | `GET /cy/players/:playerId` | 플레이어 상세 정보 |
| | `GET /cy/players/:playerId/matches` | 매칭 기록 조회 |
| **Match** | `GET /cy/matches/:matchId` | 매치 상세 정보 |
| **Ranking** | `GET /cy/ranking/ratingpoint` | 통합 랭킹 |
| | `GET /cy/ranking/characters/:characterId/:rankingType` | 캐릭터 랭킹 |
| | `GET /cy/ranking/tsj/:tsjType` | 투신전 랭킹 |
| **Item** | `GET /cy/battleitems` | 아이템 검색 |
| | `GET /cy/battleitems/:itemId` | 아이템 상세 |
| | `GET /cy/multi/battleitems` | 다중 아이템 조회 |
| **Character** | `GET /cy/characters` | 캐릭터 목록 |
### 3.6 이미지 URL 규칙
| 타입 | URL 패턴 |
|------|---------|
| 캐릭터 이미지 | `https://img-api.neople.co.kr/cy/characters/{characterId}?zoom={1-3}` |
| 아이템 이미지 | `https://img-api.neople.co.kr/cy/items/{itemId}` |
---
## 4. 설치 및 환경 설정
### 4.1 요구사항
- **Python**: 3.10 이상
- **pip**: 최신 버전 권장
- **Cyphers API Key**: Neople Developers에서 발급
### 4.2 설치
```bash
# 저장소 클론 (또는 다운로드)
cd /home/kdhadsfasdf/CyphersMCPServer
# 의존성 설치
pip install -e .
# 또는 uv 사용 (더 빠름)
uv pip install -e .
```
### 4.3 환경변수 설정
**Linux/macOS:**
```bash
export CYPHERS_API_KEY="your-api-key-here"
```
**Windows (PowerShell):**
```powershell
$env:CYPHERS_API_KEY = "your-api-key-here"
```
**Windows (CMD):**
```cmd
set CYPHERS_API_KEY=your-api-key-here
```
### 4.4 서버 실행 테스트
```bash
# 환경변수 설정 후
python -m cyphers_mcp.server
# 또는 설치 후 명령어로 실행
cyphers-mcp
```
정상 실행 시 출력:
```
Cyphers MCP Server running on stdio
API Key configured: b1HeWxU0...
```
---
## 5. MCP 클라이언트 설정
### 5.1 Cursor 설정
**설정 파일 위치:**
- **macOS/Linux**: `~/.cursor/mcp.json`
- **Windows**: `%APPDATA%\Cursor\mcp.json`
**설정 내용:**
```json
{
"mcpServers": {
"cyphers": {
"command": "python",
"args": ["-m", "cyphers_mcp.server"],
"cwd": "/home/kdhadsfasdf/CyphersMCPServer",
"env": {
"CYPHERS_API_KEY": "your-api-key-here"
}
}
}
}
```
### 5.2 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"
}
}
}
}
```
### 5.3 Cline (VS Code) 설정
**방법 1: GUI 설정**
1. VS Code에서 Cline 확장 설치
2. Command Palette → `Cline: Settings`
3. MCP 서버 섹션 → "Add Server"
4. 정보 입력:
- **Name**: `cyphers`
- **Command**: `python`
- **Args**: `-m cyphers_mcp.server`
- **CWD**: `/home/kdhadsfasdf/CyphersMCPServer`
- **Environment**: `CYPHERS_API_KEY=your-api-key-here`
**방법 2: 설정 파일**
```json
{
"cline.mcpServers": {
"cyphers": {
"command": "python",
"args": ["-m", "cyphers_mcp.server"],
"cwd": "/home/kdhadsfasdf/CyphersMCPServer",
"env": {
"CYPHERS_API_KEY": "your-api-key-here"
}
}
}
}
```
### 5.4 설정 후 재시작
설정 파일 저장 후 **클라이언트를 반드시 재시작**하세요.
---
## 6. 사용 가능한 Tools
### 6.1 Player Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_players_search` | 닉네임으로 플레이어 검색 | `nickname` |
| `cy_players_get` | 플레이어 상세 정보 조회 | `playerId` |
| `cy_players_matches` | 플레이어 매칭 기록 조회 | `playerId` |
### 6.2 Match Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_matches_get` | 매치 상세 정보 조회 | `matchId` |
### 6.3 Ranking Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_ranking_ratingpoint` | 통합 랭킹 조회 | 없음 |
| `cy_ranking_characters` | 캐릭터별 랭킹 조회 | `characterId`, `rankingType` |
| `cy_ranking_tsj` | 투신전 랭킹 조회 | `tsjType` |
### 6.4 Item Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_battleitems_search` | 아이템 검색 | 없음 |
| `cy_battleitems_get` | 아이템 상세 조회 | `itemId` |
| `cy_battleitems_multi_get` | 여러 아이템 조회 (최대 30개) | `itemIds` |
### 6.5 Character Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_characters_list` | 모든 캐릭터 목록 조회 | 없음 |
### 6.6 Image Tools
| Tool | 설명 | 필수 파라미터 |
|------|------|--------------|
| `cy_images_character_url` | 캐릭터 이미지 URL 생성 | `characterId` |
| `cy_images_item_url` | 아이템 이미지 URL 생성 | `itemId` |
---
## 7. 사용 예시
### 7.1 플레이어 검색
```
사이퍼즈에서 닉네임 "홍길동"으로 플레이어를 검색해줘
```
### 7.2 최근 전적 조회
```
플레이어 ID "abc123"의 최근 10경기를 조회하고 승률을 분석해줘
```
### 7.3 랭킹 조회
```
사이퍼즈 통합 랭킹 상위 10명을 보여줘
```
### 7.4 캐릭터 목록
```
사이퍼즈의 모든 캐릭터 목록을 보여줘
```
### 7.5 아이템 검색
```
사이퍼즈에서 "레어" 등급 아이템을 검색해줘
```
### 7.6 복합 분석
```
닉네임 "프로게이머"의 플레이어를 찾고, 최근 20경기의 승률과
가장 많이 사용한 캐릭터를 분석해줘
```
---
## 8. 고급 기능
### 8.1 캐싱 시스템
서버는 자동으로 API 응답을 캐싱하여 호출을 최소화합니다.
| 데이터 | TTL (캐시 유지 시간) |
|--------|---------------------|
| 캐릭터 목록 | 24시간 |
| 아이템 상세 | 6시간 |
| 플레이어 정보 | 5분 |
| 랭킹 | 1분 |
| 매치 기록 | 30초 |
### 8.2 레이트 리밋
Token Bucket 알고리즘으로 요청을 제한합니다.
| 단위 | 제한 |
|------|------|
| 초당 | 100건 (보수적 설정) |
| 분당 | 5,000건 |
| 시간당 | 300,000건 |
### 8.3 에러 응답 구조
모든 에러는 구조화된 JSON으로 반환됩니다:
```json
{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"request_id": "uuid-..."
}
}
```
### 8.4 메타 정보
모든 성공 응답에는 메타 정보가 포함됩니다:
```json
{
"rows": [...],
"meta": {
"request_id": "uuid-...",
"cached": false,
"rate_limit": {
"remaining": 99,
"reset_at": 1706083200.0
}
}
}
```
---
## 9. 문제 해결
### 9.1 서버가 시작되지 않는 경우
**Python 버전 확인:**
```bash
python --version # 3.10 이상 필요
```
**패키지 설치 확인:**
```bash
pip list | grep mcp
pip list | grep httpx
```
**재설치:**
```bash
pip install -e . --force-reinstall
```
### 9.2 API 키 오류
```
Error: CYPHERS_API_KEY environment variable is required
```
**해결:**
```bash
# 환경변수 확인
echo $CYPHERS_API_KEY
# 설정 안 되어 있으면 설정
export CYPHERS_API_KEY="your-api-key-here"
```
### 9.3 MCP 연결 오류
1. **경로 확인**: `cwd`가 올바른지 확인
2. **Python 경로**: `which python` 또는 절대경로 사용
3. **클라이언트 재시작**: 설정 변경 후 반드시 재시작
### 9.4 API 호출 실패
**레이트 리밋 초과:**
```json
{"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded"}}
```
→ 잠시 후 다시 시도
**잘못된 파라미터:**
```json
{"error": {"code": "NOT_FOUND", "message": "Resource not found"}}
```
→ playerId, matchId 등 확인
---
## 10. Smithery 배포
### 10.1 배포 준비
1. **GitHub 저장소 생성**
2. **코드 푸시**
3. **smithery.json 확인** (이미 설정됨)
### 10.2 Smithery 등록
1. https://smithery.ai 접속
2. GitHub로 로그인
3. "New Server" → 저장소 선택
4. 환경변수(시크릿) 설정: `CYPHERS_API_KEY`
5. 배포
### 10.3 설치 명령
배포 후 다른 사용자들이 설치할 수 있습니다:
```bash
npx @smithery/cli install @yourname/cyphers-mcp-server --client cursor
```
---
## 📚 참고 자료
- **Neople Developers**: https://developers.neople.co.kr
- **Cyphers API 문서**: https://developers.neople.co.kr/contents/apiDocs/cyphers
- **MCP 공식 문서**: https://modelcontextprotocol.io
- **MCP Python SDK**: https://github.com/modelcontextprotocol/python-sdk
- **Smithery**: https://smithery.ai
---
## 📄 라이선스
MIT License
---
## 👤 작성자
kdhadsfasdf
---
*Last updated: 2026-01-24 (Python 버전)*
