📘 KICC EasyPay AI Developer Kit (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

{
  "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 공식 홈페이지에서 최신 버전을 설치해 주세요.

Q. 실제 결제 승인이 되나요? A. 아니요. 이 도구는 개발 편의를 위한 코드 생성 및 검증 도구입니다. 생성된 JSON을 복사하여 귀사의 백엔드 서버에서 KICC API로 전송해야 실제 결제가 이루어집니다.

Developed by KICC EasyPay Dev Relations