아래는 **“Cyphers API 기반 MCP Server (Smithery 배포용)” 문서의 개요(목차/구성안)** 초안이야. (Neople Cyphers API 문서/공통가이드/에러코드 기준으로 잡았어.) ([developers.neople.co.kr][1])
---
## 0. 문서 목적과 범위
* 이 문서는 **Neople Cyphers Open API**를 감싸는 **MCP Server**를 구현하고, 이를 **Smithery에 등록/배포**하기 위한 개발자 문서다. ([developers.neople.co.kr][1])
* 범위:
* Cyphers API 호출 래핑(툴 제공), 인증/레이트리밋/에러 처리, 배포/운영(로그, 시크릿)까지 포함
* “Cyphers API Key”는 필수, “OpenRouter API Key”는 (모델 라우팅/에이전트 기능을 넣을 경우) 선택 모듈로 분리
---
## 1. 배경: MCP / Smithery 한 장 요약
* MCP란: LLM 클라이언트가 외부 도구(tool)를 호출할 수 있도록 서버가 **툴 스키마 + 실행**을 제공하는 표준 프로토콜 ([Model Context Protocol][2])
* Smithery란: MCP 서버를 **목록화/배포/호스팅**(또는 연결)해 유저가 쉽게 설치/사용하게 해주는 배포 플랫폼 ([smithery.ai][3])
---
## 2. API 개요: Neople Cyphers Open API
### 2.1 Base URL / 전송 방식
* API Gateway: `https://api.neople.co.kr` (REST, **GET only**) ([developers.neople.co.kr][4])
* 서비스 구분: Cyphers는 경로에 `/cy/` 사용 ([developers.neople.co.kr][1])
### 2.2 인증(API Key)
* API Key는 **요청 변수 `apikey`** 또는 **Request Header `apikey: <key>`** 로 전달 가능 ([developers.neople.co.kr][4])
* Key는 Neople Developers에서 “애플리케이션 등록” 후 발급 ([developers.neople.co.kr][4])
### 2.3 레이트 리밋(요청 제한)
* 애플리케이션 기준 **초당 1,000건**(분/시간 제한 표 포함) ([developers.neople.co.kr][4])
* MCP 서버에서는 (1) 사용자별 제한, (2) 서버 전역 제한, (3) 429/400 대응 정책을 문서화
### 2.4 URL 인코딩 규칙
* 닉네임/아이템명 등 일부 파라미터는 **URL 인코딩 필수**, `encodeURIComponent` 권장 ([developers.neople.co.kr][4])
### 2.5 에러 처리(HTTP + 에러코드 JSON)
* HTTP 상태코드: 200/400/401/404/500/503 ([developers.neople.co.kr][5])
* 공통/사이퍼즈 에러코드(예: API003 유효하지 않은 키, CY002 유효하지 않은 플레이어 등) ([developers.neople.co.kr][5])
---
## 3. Cyphers API 엔드포인트 카탈로그(= MCP Tool 후보)
> Cyphers API Docs에 현재 노출된 주요 엔드포인트들 ([developers.neople.co.kr][1])
### 3.1 Player
1. **플레이어 검색** `GET /cy/players` (nickname, wordType, limit) ([developers.neople.co.kr][1])
2. **플레이어 정보 조회** `GET /cy/players/:playerId` ([developers.neople.co.kr][1])
3. **플레이어 매칭 기록 조회** `GET /cy/players/:playerId/matches` (gameTypeId, startDate/endDate 최대 90일, next 등) ([developers.neople.co.kr][1])
### 3.2 Match
4. **매칭 상세 조회** `GET /cy/matches/:matchId` ([developers.neople.co.kr][1])
### 3.3 Ranking
5. **통합 랭킹 조회** `GET /cy/ranking/ratingpoint` ([developers.neople.co.kr][1])
6. **캐릭터 랭킹 조회** `GET /cy/ranking/characters/:characterId/:rankingType` ([developers.neople.co.kr][1])
7. **투신전 랭킹 조회** `GET /cy/ranking/tsj/:tsjType` ([developers.neople.co.kr][1])
### 3.4 Items
8. **아이템 검색** `GET /cy/battleitems` (itemName, q[characterId/slotCode/rarityCode/seasonCode] 등) ([developers.neople.co.kr][1])
9. **아이템 상세 조회** `GET /cy/battleitems/:itemId` ([developers.neople.co.kr][1])
10. **다중 아이템 상세 조회** `GET /cy/multi/battleitems` (itemIds 최대 30개) ([developers.neople.co.kr][1])
### 3.5 Characters
11. **캐릭터 정보** `GET /cy/characters` (+ 이미지 zoom 파라미터) ([developers.neople.co.kr][1])
### 3.6 이미지 리소스 규칙(정적 리소스)
* 아이템 이미지: `https://img-api.neople.co.kr/cy/items/<itemId>`
* 캐릭터 이미지: `https://img-api.neople.co.kr/cy/characters/<characterId>` (+ zoom) ([developers.neople.co.kr][1])
---
## 4. MCP Server 설계 개요(문서 섹션)
* **Tool 설계 원칙**
* “엔드포인트 1개 = tool 1개” 기본, 자주 쓰는 조합은 “편의 tool”로 추가(예: nickname→playerId→최근 매치 요약)
* 파라미터는 문서의 타입/기본값/최대값을 그대로 스키마로 반영 ([developers.neople.co.kr][1])
* **인증/시크릿**
* `CYPHERS_API_KEY` (필수)
* `OPENROUTER_API_KEY` (선택: 서버 내에서 모델 호출이 필요할 때만)
* **에러 매핑**
* HTTP status + Neople error code를 MCP tool error로 표준화 ([developers.neople.co.kr][5])
* **레이트리밋/캐싱**
* 서버 전역 토큰버킷 + 엔드포인트별 캐시(랭킹/캐릭터 목록 등) ([developers.neople.co.kr][4])
---
## 5. Smithery 배포/등록(문서 섹션)
* “로컬에서 MCP 서버 구현 → 레포 공개(또는 배포 가능한 형태) → Smithery 등록 페이지에서 연결” 흐름을 안내 ([smithery.ai][3])
* 문서에 포함할 항목
* 실행 방법(로컬), 필요한 환경변수, 배포 시 시크릿 설정, 공개 범위(레포/라이선스), 기본 예제 프롬프트
---
원하면 다음 단계로, 위 개요의 **“3. 엔드포인트 카탈로그”를 그대로 MCP tool 스펙으로 바꾸는 문서(각 tool: name/description/input schema/output 예시/에러코드 표)**까지 한 번에 이어서 써줄게.
[1]: https://developers.neople.co.kr/contents/apiDocs/cyphers "Neople Developers"
[2]: https://modelcontextprotocol.io/?utm_source=chatgpt.com "What is the Model Context Protocol (MCP)? - Model Context ..."
[3]: https://smithery.ai/new?utm_source=chatgpt.com "Publish an MCP Server"
[4]: https://developers.neople.co.kr/contents/guide/pages/all "Neople Developers"
[5]: https://developers.neople.co.kr/contents/guide/pages/code "Neople Developers"
