Cyphers Server

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

설치 방법

# 저장소 클론
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 키 발급

1. Neople Developers에 가입
2. 애플리케이션 등록
3. 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) 설정

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가 설정되었는지 확인하세요.

의존성 오류

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

MCP 연결 오류

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

📚 참고 자료

• Neople Developers - Cyphers API
• Model Context Protocol
• MCP Python SDK
• Smithery Documentation

📄 라이선스

MIT License

👤 작성자

DHKim327

🔗 링크

• Neople Developers
• Cyphers 공식 사이트