npm package: @kicc/easypay-mcp
Description: KICC Easypay Payment MCP Server
Latest version: 1.0.2

# 📘 KICC EasyPay AI Developer Kit (MCP)

[![npm version](https://img.shields.io/npm/v/@kicc/easypay-mcp.svg)](https://www.npmjs.com/package/@kicc/easypay-mcp)
![License](https://img.shields.io/npm/l/@kicc/easypay-mcp)

**"더 이상 200페이지짜리 연동 매뉴얼(PDF)을 찾아 헤매지 마세요."**

이 프로젝트는 KICC EasyPay 결제 연동을 진행하는 개발자를 위한 **AI 코딩 어시스턴트(MCP Server)**입니다.
Claude, Cursor, Windsurf 같은 AI 에디터에 연결하면, **결제 규격에 딱 맞는 JSON 생성**부터 **데이터 유효성 검증**까지 대화로 해결할 수 있습니다.

> **🔒 보안 안심 (Security Note)**
> 이 도구는 **100% 오프라인 모드**로 작동합니다.
> 실제 결제 서버와 통신하지 않으며, 귀사의 상점 키(Secret Key)나 민감 정보를 요구하거나 외부로 전송하지 않습니다. 오직 **데이터 구조 설계와 문법 검증**만을 수행합니다.

---

## ✨ 주요 기능 (Features)

1.  **📋 JSON 템플릿 자동 생성 (`generate_payload`)**
    * "부분 취소 JSON 만들어줘", "에스크로 배송 등록 데이터 줘"라고 말하면, KICC 표준 규격에 맞는 JSON을 즉시 코딩해 줍니다.
2.  **✅ 데이터 무결성 검증 (`validate_payload`)**
    * 작성한 코드를 AI에게 보여주면, 필수 값 누락, 길이 초과, 날짜 포맷 오류 등을 **KICC 서버 전송 전에 미리 발견**하여 알려줍니다.
3.  **📚 API 스펙 즉시 조회 (`get_api_spec`)**
    * 복잡한 파라미터 구조를 PDF 없이 채팅창에서 바로 조회할 수 있습니다.

---

## 🚀 설치 및 실행 (Quick Start)

이 도구는 별도의 설치 없이 `npx`를 통해 즉시 실행됩니다. 사용 중인 AI 도구에 맞춰 설정하세요.

### Option A. Cursor (추천)
1.  **Settings** (`Cmd/Ctrl + ,`) > **Features** > **MCP** 이동
2.  **+ Add New MCP Server** 클릭
3.  아래 정보 입력 후 저장:
    * **Name:** `easypay`
    * **Type:** `command`
    * **Command:** `npx`
    * **Args:**
        * `-y`
        * `@kicc/easypay-mcp`

### Option B. Claude Desktop App
설정 파일(`claude_desktop_config.json`)을 열고 아래 내용을 추가하세요.
* **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Win:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "easypay": {
      "command": "npx",
      "args": [
        "-y",
        "@kicc/easypay-mcp"
      ]
    }
  }
}
```

### Option C. Windsurf
설정 파일(`mcp_config.json`)에 위와 동일한 내용을 추가하세요.
* **Path:** `~/.codeium/windsurf/mcp_config.json`

---

## 💬 사용 예시 (Prompt Scenarios)

설정이 완료되면 채팅창에 다음과 같이 입력해 보세요.

### 상황 1: 결제창 연동이 처음일 때
> **개발자:** "일반 결제창을 띄우려고 해. **주문 등록(Register)에 필요한 JSON 템플릿**을 예시 데이터 채워서 만들어줘."
>
> **AI:** "네, KICC 표준 Webpay 요청 규격입니다. `payMethodTypeCode`는 11(카드)로 설정했습니다..." (JSON 코드 생성)

### 상황 2: 부분 취소 기능을 구현할 때
> **개발자:** "고객 요청으로 **부분 취소** 기능을 구현해야 해. 필요한 JSON 구조랑 주의사항 알려줘."
>
> **AI:** "부분 취소 시에는 `reviseTypeCode`를 '32'로 설정하고, `clientKey`가 필수입니다. 다음은 생성된 템플릿입니다..."

### 상황 3: 배포 전 데이터 검증 (가장 중요!)
> **개발자:** "내가 만든 이 JSON 데이터, KICC 서버로 보내도 안전할까? **검증해줘.**"
> (JSON 코드 붙여넣기)
>
> **AI:** "⚠️ **잠시만요! 규격 오류가 발견되었습니다.**
> 1. `shopOrderNo`: 특수문자 `&`는 사용할 수 없습니다.
> 2. `amount`: 0보다 커야 합니다.
> 수정해서 다시 보여드릴까요?"

---

## 🛠️ 지원하는 API 목록

| 기능 | API Key | 설명 |
| :--- | :--- | :--- |
| **일반 결제** | `general_register`, `general_approve` | 결제창 호출 및 승인 |
| **단독 결제** | `standalone_register`, `standalone_approve` | 카드사 직접 호출 (Non-UI) |
| **정기 결제** | `billing_register`, `billing_issue`, `billing_payment` | 빌키 발급 및 승인 |
| **취소/환불** | `cancel_payment`, `refund_payment` | 전체/부분 취소, 계좌 환불 |
| **에스크로** | `escrow_modify` | 배송 등록, 구매 확정 |
| **기타** | `sms_register`, `cash_receipt_issue` | SMS 결제, 현금영수증 |

---

## 🆘 문제 해결 (FAQ)

**Q. `npx` 명령어를 찾을 수 없다고 나와요.**
A. 컴퓨터에 **Node.js**가 설치되어 있어야 합니다. [Node.js 공식 홈페이지](https://nodejs.org/)에서 최신 버전을 설치해 주세요.

**Q. 실제 결제 승인이 되나요?**
A. 아니요. 이 도구는 개발 편의를 위한 **코드 생성 및 검증 도구**입니다. 생성된 JSON을 복사하여 귀사의 백엔드 서버에서 KICC API로 전송해야 실제 결제가 이루어집니다.

---

**Developed by KICC EasyPay Dev Relations**