@nhnpayco-dev/mcp-devcenter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NHN PAYCO Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# @nhnpayco-dev/mcp-devcenter
+
+> PAYCO 개발자센터 가이드(온라인결제·자동결제·오프라인결제·오더클라우드·멤버십클라우드·결제정산대사)를
+> AI 에디터(Claude·Cursor·VS Code 등)에서 바로 조회·검색할 수 있게 해주는
+> MCP(Model Context Protocol) 서버.
+
+외부 가맹점/제휴사 개발자가 PAYCO 결제 연동을 진행할 때, 가이드 페이지를 일일이 뒤지지 않고
+AI 에디터에 자연어로 물어 즉시 정확한 답을 받을 수 있게 해줍니다.
+
+```
+"PAYCO 자동결제 빌링키 발급부터 결제까지 흐름 알려줘"
+"결제 승인 API 에 필수로 보내야 하는 파라미터가 뭐야?"
+"에러코드 4802 무슨 뜻이야?"
+"BC카드 코드값은 PAYCO 에서 어떻게 표기해?"
+```
+
+---
+
+## 요구사항
+
+- **Node.js 20 LTS 이상** (`node --version` 으로 확인)
+- 지원 클라이언트: Claude Desktop · Cursor · VS Code(Continue 등) · Windsurf 등 **MCP 표준 호환 AI 에디터**
+
+설치는 자동입니다(`npx` 가 알아서 받습니다). 별도 빌드·환경 설정 불필요.
+
+---
+
+## 빠른 시작
+
+### Claude Desktop
+
+`claude_desktop_config.json` 파일을 열어 `mcpServers` 항목에 아래를 추가하세요.
+
+설정 파일 위치:
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+  (MS Store 버전: `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`)
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "payco-devcenter": {
+      "command": "npx",
+      "args": ["-y", "@nhnpayco-dev/mcp-devcenter@latest"]
+    }
+  }
+}
+```
+
+저장 후 Claude Desktop 을 **완전히 종료(시스템 트레이까지)** 한 다음 다시 실행하세요.
+입력창의 도구 메뉴에서 11개 도구(`search_devcenter`, `get_guide`, `list_apis`, `get_api_spec`,
+`get_sample_code`, `get_error_code`, `get_checklist`, `list_validatable_apis`,
+`validate_payload`, `export_validation_excel`, `clear_validation_buffer`)가 보이면 정상입니다.
+
+### Cursor
+
+`.cursor/mcp.json` (프로젝트별) 또는 사용자 전역 설정에 추가:
+
+```json
+{
+  "mcpServers": {
+    "payco-devcenter": {
+      "command": "npx",
+      "args": ["-y", "@nhnpayco-dev/mcp-devcenter@latest"]
+    }
+  }
+}
+```
+
+### VS Code (Continue · Cline 등 MCP 지원 확장)
+
+각 확장의 MCP 설정에 동일 명령으로 등록하세요. 예시는 확장 문서를 따릅니다.
+
+---
+
+## 제공 도구 (11개)
+
+### 가이드 조회 (6개)
+
+| 도구 이름 | 설명 |
+|---|---|
+| `search_devcenter(query)` | 가이드 본문·제목·섹션에서 키워드 검색 (예: "결제 승인", "orderProducts") |
+| `get_guide(slug)` | 특정 카테고리 가이드 전체를 Markdown 으로 반환 |
+| `list_apis()` | 28개 카테고리 + 단계 목록 일람 |
+| `get_api_spec(category)` | 특정 카테고리(easypay, autopay …)의 API 명세·파라미터 표가 담긴 가이드 반환 |
+| `get_sample_code(slug, language?)` | 가이드 본문에서 코드 블록만 추출 (선택적으로 언어 필터링) |
+| `get_error_code(code)` | API 응답코드·결제수단·은행·카드사 등 모든 코드 카테고리에서 일치 항목 조회 |
+
+### 자동 검수 (5개)
+
+| 도구 이름 | 설명 |
+|---|---|
+| `list_validatable_apis()` | 자동 검증 가능한 API 슬러그 35개 목록 (URL·메서드·파라미터 수 포함) |
+| `get_checklist(service)` | 서비스별 사전 검수 체크리스트(자동 + 수동 항목). service: `online`/`offline`/`order`/`membership` |
+| `validate_payload(api, payload)` | API 요청 페이로드 JSON을 검증 — (1) 필수 누락 / 명세 외 파라미터 / 타입 불일치 + (2) 자동 체크리스트(개인정보·URL 인코딩·공백·금액 합산·enum·날짜 형식·returnUrl) + (3) 수동 확인 항목 |
+| `export_validation_excel(path?, clearAfter?)` | 누적된 검수 결과를 xlsx로 추출. **3개 시트**: 검수요약 / 항목별 상세 / 공통검수체크리스트 |
+| `clear_validation_buffer()` | 누적된 검수 결과를 모두 초기화 (새 세션 시작 시) |
+
+**검증 도구 사용 예시 (외부 제휴사 시점):**
+
+```
+사용자> 이 페이로드 검수해줘. API는 online-easypay-01.
+        {"sellerKey":"S0FSJE", "sellerOrderReferenceKey":"ORD-001",
+         "totalPaymentAmt": "15000", "orderMethod":"EASYPAY", ...}
+
+→ # ✗ FAIL — online-easypay-01
+   [POST] /outseller/order/reserve  |  주문 예약 API로 결제창 호출하기
+   서비스: 온라인결제  |  자동실패 1개
+
+   ## 검수 체크리스트 — 온라인결제 (22개)
+   ✓ 개인정보 파라미터 미포함 / ✓ orderMethod 유효값 / ⬜ PAYCO 방화벽 등록 / ...
+
+   ## API 명세 문제 (1개)
+   ✗ totalPaymentAmt: 명세 'number' / 실제 'string'
+
+사용자> 엑셀로 추출해줘.
+→ ✅ ~/Downloads/payco-validation-20260522-180000.xlsx 생성 완료
+   - 시트: 검수요약 / 항목별 상세 / 공통검수체크리스트
+```
+
+⚠️ **운영 로그(실제 카드번호·주민번호·고객 연락처 포함)는 그대로 붙여넣지 말 것.**
+테스트 환경 로그 또는 마스킹된 로그를 사용하세요. 본 MCP 서버는 입력을 검증만 하고 저장하지 않지만,
+검증 단계에서 Claude/Cursor 등 AI 측으로 텍스트가 전달됩니다.
+
+사용 가능한 카테고리 슬러그 (28개):
+
+| Root | 카테고리 |
+|---|---|
+| **online** (온라인 결제) | `online-start`, `online-easypay`, `online-autopay`, `online-etc`, `online-extra`, `online-extradata` 🆕, `online-code`, `online-check`, `online-sample` |
+| **offline** (오프라인 결제) | `offline-start`, `offline-vcat`, `offline-api`, `offline-authapi` 🆕, `offline-code`, `offline-check`, `offline-sample` |
+| **order** (오더 클라우드) | `order-start`, `order-vorder`, `order-code`, `order-check`, `order-sample` |
+| **membership** (멤버십 클라우드) | `membership-start`, `membership-vmem`, `membership-api`, `membership-code`, `membership-check`, `membership-sample` |
+| **calculate** | `calculate` (결제/정산 대사) |
+
+🆕 표시는 PAYCO 개발자센터에는 없는 사내 docx 기반 가이드입니다.
+
+### 자동 검증 가능한 API 슬러그 (35개)
+
+| 카테고리 | 슬러그 |
+|---|---|
+| 온라인 reserve/승인/취소 | `online-easypay-01`~`04`, `online-autopay-01`~`06`, `online-etc-01`/`03`/`04`, `online-extra-02`/`03` |
+| 온라인 reserve 변형 (합성) | `online-easypay-nonmember`(비회원결제), `online-easypay-checkout`(바로구매), `online-easypay-ordersheet`(주문서결제) |
+| 부가정보 스키마 | `online-extradata` (reserve API의 extraData JSON 내부 26개 필드) |
+| 오프라인 심플형 | `offline-api-02`~`05` |
+| 오프라인 인증승인형 🆕 | `offline-authapi-posauth`, `-auth`, `-approval`, `-cancel`, `-netcancel` |
+| 오프라인 VCAT (DLL) | `offline-vcat-setpaycodata`, `-getpaycodata` |
+| 오더 VORDER (DLL) | `order-vorder-setdata`, `-senddata` |
+| 멤버십 API | `membership-api-05` |
+| 멤버십 VMEM (DLL) | `membership-vmem-execasyncapproval`, `-execcomplete`, `-execcancel` |
+
+---
+
+## 데이터 범위
+
+본 패키지에 포함된 가이드 정보:
+- [PAYCO 개발자센터](https://devcenter.payco.com)의 **연동하기 > 온라인/오프라인/오더/멤버십** 전 섹션 + **결제/정산 대사**
+- 사내 docx 기반 가이드 2종: 오프라인 POS **인증승인형 연동 가이드**, **부가정보(extraData) 명세**
+
+- 가이드 본문 카테고리: **28개** (devcenter 크롤 26개 + 사내 docx 2개)
+- 에러코드/코드값 표 항목: **500+ 개** (4개 root 의 API 응답코드, 결제수단, 카드사, 은행, VAN사, 결제수단 코드 등 통합)
+- 자동 검증 가능한 API 명세: **35개**
+  - REST API 27개 (easypay/autopay/etc/extra/offline-api/authapi 등)
+  - DLL 함수 7개 (offline-vcat, order-vorder, membership-vmem)
+  - 합성 변형 슬러그 3개 (`online-easypay-nonmember`/`-checkout`/`-ordersheet`)
+
+**검증 가이드 사항 (자동 검증 한계):**
+- 조건부 필수 파라미터 (예: `extraData.appUrl` — iOS App 호출 시에만 필수)는 단순 "필수"로 표시될 수 있음
+- `returnUrl` 등 URL 검사는 prefix(`http://`/`https://`)만 확인. URL 내부 공백·인코딩 오류는 감지 불가
+- 배열 안 객체별 누락은 첫 객체 기준으로 검출
+
+**제외 범위:**
+- 보안사항 확인하기 (USERTrust 루트 인증서 설치 가이드)
+- PAYCO 로그인 가이드 (별도 사이트 `developers.payco.com`)
+
+---
+
+## 최신 가이드 반영
+
+PAYCO 개발자센터가 갱신될 경우 본 패키지도 주기적으로 재배포됩니다.
+항상 최신을 받으려면 설정에서 `@latest` 태그를 유지하세요.
+
+특정 시점에 고정하고 싶다면 `@0.0.1` 같이 버전을 명시할 수 있습니다.
+
+---
+
+## 문의 / 이슈
+
+- PAYCO 가이드 자체 문의: <dl_payco_ts@nhn.com>
+- 본 MCP 서버 동작 문의: (TBD — 사내 협의 후 공식 채널 안내 예정)
+
+---
+
+## 라이선스 / 출처
+
+- 가이드 본문 원본 저작권: NHN PAYCO Corp.
+- 패키지 형태로 가공·배포: PAYCO 개발팀
+- 라이선스: TBD (사내 협의 진행 중)