# CyphersMCPServer 프로젝트 현황 요약ll
**작성일:** 2026-01-24 (Python 버전으로 리팩토링 완료)
---
## 📌 프로젝트 개요
**Neople Cyphers Open API**를 **MCP(Model Context Protocol) Server**로 감싸서 Claude, Cursor, Cline 등 AI 어시스턴트에서 쉽게 사용할 수 있도록 하는 프로젝트입니다.
**🆕 Python으로 완전히 리팩토링되었습니다!** (기존 TypeScript → Python)
---
## ✅ 구현 완료 항목
### 1. 핵심 인프라 (100% 완료)
- [x] MCP Server 기본 구조 (`cyphers_mcp/server.py`)
- [x] Stdio Transport 기반 서버 연결
- [x] 환경변수 API 키 로딩 (`CYPHERS_API_KEY`)
- [x] Graceful Shutdown 처리
### 2. API 클라이언트 (100% 완료)
- [x] httpx 기반 비동기 HTTP 클라이언트 (`cyphers_mcp/api_client.py`)
- [x] 재시도 로직 (exponential backoff)
- [x] 에러 처리 및 표준화 (`CyphersAPIError`)
- [x] Neople 에러코드 → MCP 에러코드 매핑
### 3. 캐싱 시스템 (`cyphers_mcp/cache.py`)
- [x] 메모리 기반 캐시 구현
- [x] TTL(Time-To-Live) 적용
- 캐릭터 목록: 24시간
- 아이템 상세: 6시간
- 플레이어 정보: 5분
- 랭킹: 1분
- 매치 기록: 30초
### 4. 레이트 리밋 (`cyphers_mcp/rate_limiter.py`)
- [x] Token Bucket 알고리즘 구현
- [x] 초당/분당/시간당 제한 설정
- 초당: 100건 (보수적 설정)
- 분당: 5,000건
- 시간당: 300,000건
### 5. MCP Tools (13개 완료)
| 카테고리 | Tool 이름 | 설명 |
|----------|-----------|------|
| **Player** | `cy_players_search` | 닉네임으로 플레이어 검색 |
| | `cy_players_get` | 플레이어 상세 정보 조회 |
| | `cy_players_matches` | 매칭 기록 조회 |
| **Match** | `cy_matches_get` | 매치 상세 조회 |
| **Ranking** | `cy_ranking_ratingpoint` | 통합 랭킹 조회 |
| | `cy_ranking_characters` | 캐릭터별 랭킹 조회 |
| | `cy_ranking_tsj` | 투신전 랭킹 조회 |
| **Item** | `cy_battleitems_search` | 아이템 검색 |
| | `cy_battleitems_get` | 아이템 상세 조회 |
| | `cy_battleitems_multi_get` | 다중 아이템 조회 (최대 30개) |
| **Character** | `cy_characters_list` | 캐릭터 목록 조회 |
| **Image** | `cy_images_character_url` | 캐릭터 이미지 URL 생성 |
| | `cy_images_item_url` | 아이템 이미지 URL 생성 |
---
## 📁 프로젝트 구조 (Python 버전)
```
CyphersMCPServer/
├── cyphers_mcp/ # Python 패키지
│ ├── __init__.py # 패키지 초기화
│ ├── server.py # MCP 서버 메인 진입점
│ ├── api_client.py # Cyphers API 클라이언트
│ ├── types.py # 타입 정의 (dataclass)
│ ├── cache.py # 캐싱 관리
│ └── rate_limiter.py # 레이트 리밋 관리
├── note/ # 프로젝트 노트
├── pyproject.toml # Python 패키지 설정
├── README.md # 기본 사용 가이드
├── INSTALLATION.md # 상세 설치 가이드
├── INTRODUCTION.md # 프로젝트 소개/배경
├── DETAIL.md # 상세 기술 문서
├── smithery.json # Smithery 배포 설정
└── APIKey.json # API 키 저장 (gitignore 대상)
```
---
## 🔧 기술 스택 (Python 버전)
| 영역 | 기술 |
|------|------|
| 언어 | **Python 3.10+** |
| MCP SDK | mcp (Python SDK) |
| HTTP | httpx (비동기) |
| 타입 | dataclass, typing |
| 패키지 관리 | pyproject.toml (PEP 621) |
| 빌드 | hatchling |
---
## 📦 설치 및 실행
### 설치
```bash
cd CyphersMCPServer
pip install -e .
```
### 실행
```bash
export CYPHERS_API_KEY="your-api-key"
python -m cyphers_mcp.server
# 또는
cyphers-mcp
```
### Cursor/Claude Desktop 설정
```json
{
"mcpServers": {
"cyphers": {
"command": "python",
"args": ["-m", "cyphers_mcp.server"],
"cwd": "/home/kdhadsfasdf/CyphersMCPServer",
"env": {
"CYPHERS_API_KEY": "your-api-key"
}
}
}
}
```
---
## ⏳ 남은 작업 (TODO)
### 즉시 필요
- [ ] 의존성 설치 테스트 (`pip install -e .`)
- [ ] 실제 API 호출 테스트 (모든 13개 Tool)
- [ ] 에러 케이스 테스트
### 배포 관련
- [ ] GitHub 저장소 생성 및 푸시
- [ ] Smithery 등록 및 배포 (smithery.json 업데이트 필요)
- [ ] PyPI 패키지 배포 (선택)
### 개선 사항
- [ ] 단위 테스트 추가 (pytest)
- [ ] Composite Tool 추가 (예: 닉네임→최근매치요약)
- [ ] 로깅 시스템 개선
---
## 📋 API 키 정보
| 키 종류 | 상태 | 실제 사용 여부 | 용도 |
|---------|------|---------------|------|
| CyphersAPIKey | ✅ 저장됨 | ✅ **사용 중** | Neople Cyphers API 호출 |
| OpenRouterAPIKey | ✅ 저장됨 | ❌ **미사용** | LLM 라우팅 (향후 기능용) |
### OpenRouterAPIKey 미사용 상세
- `APIKey.json`에 저장되어 있으나, **현재 코드에서 읽지 않음**
- `cyphers_mcp/server.py`: `CYPHERS_API_KEY` 환경변수만 로드
- **권장**: MCP 서버는 도구 제공에 집중, LLM 요약은 클라이언트(Claude Agent)가 수행
> ⚠️ 주의: API 키는 `.gitignore`에 포함되어 있어 Git에 커밋되지 않음
---
## 🔄 TypeScript → Python 리팩토링 기록
| 기존 (TypeScript) | 신규 (Python) |
|-------------------|---------------|
| `src/index.ts` | `cyphers_mcp/server.py` |
| `src/api-client.ts` | `cyphers_mcp/api_client.py` |
| `src/tools.ts` | `cyphers_mcp/server.py` (Tool 정의 통합) |
| `src/types.ts` | `cyphers_mcp/types.py` |
| `src/cache.ts` | `cyphers_mcp/cache.py` |
| `src/rate-limiter.ts` | `cyphers_mcp/rate_limiter.py` |
| `package.json` | `pyproject.toml` |
| `node_modules/` | 삭제됨 (pip 의존성 사용) |
| `dist/` | 삭제됨 (Python은 빌드 불필요) |
---
## 📚 관련 문서
- [Neople Developers](https://developers.neople.co.kr) - API 키 발급
- [Cyphers API 문서](https://developers.neople.co.kr/contents/apiDocs/cyphers) - 엔드포인트 명세
- [MCP 공식 문서](https://modelcontextprotocol.io) - MCP 프로토콜
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Python SDK
- [Smithery](https://smithery.ai) - MCP 서버 배포 플랫폼
