@mobilpay/mcp-server

KG파이낸셜 결제서비스 연동을 위한 MCP(Model Context Protocol) 서버입니다.

AI 코딩 도구(Cursor, Claude Code, Kiro, VS Code, Windsurf, Claude Desktop 등)에서 자연어로 질문하면, 결제 연동 문서(27개)를 자동 검색하여 정확한 코드를 생성할 수 있습니다.

지원 서비스

설치 및 설정

• Node.js 18+ 필요 (ES2022 타겟)

• stdio 전송 방식 사용 — 네트워크 불필요, 오프라인 동작 가능

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "mobilpay": {
      "command": "npx",
      "args": ["-y", "@mobilpay/mcp-server@latest"]
    }
  }
}

Claude Code (CLI)

claude mcp add mobilpay -- npx -y @mobilpay/mcp-server@latest

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "mobilpay": {
      "command": "npx",
      "args": ["-y", "@mobilpay/mcp-server@latest"]
    }
  }
}

Windsurf

.windsurf/mcp.json:

{
  "mcpServers": {
    "mobilpay": {
      "command": "npx",
      "args": ["-y", "@mobilpay/mcp-server@latest"]
    }
  }
}

Kiro (AWS)

.kiro/settings/mcp.json:

{
  "mcpServers": {
    "mobilpay": {
      "command": "npx",
      "args": ["-y", "@mobilpay/mcp-server@latest"]
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "mobilpay": {
      "command": "npx",
      "args": ["-y", "@mobilpay/mcp-server@latest"]
    }
  }
}

제공 Tool

공통

MOBILPAY 결제연동

내죠여왕(NEZO)

지원 문서

MOBILPAY REST API

내죠여왕(NEZO)

사용 예시

AI 코딩 도구에서 다음과 같이 질문하면 됩니다:

MOBILPAY

• "MOBILPAY 휴대폰 결제 연동 코드 작성해줘"

• "거래등록 API 전체 명세 보여줘"

• "HMAC 검증 Python 예제 코드 알려줘"

• "결제 취소 API 파라미터가 뭐야?"

내죠여왕

• "내죠여왕 알림톡 결제 요청 코드 작성해줘"

• "내죠여왕 콜백 핸들러 Node.js로 구현해줘"

• "내죠여왕 MAC 생성 Java 예제 보여줘"

• "내죠여왕 결제 조회 후 취소하는 코드 만들어줘"

보안 규칙

MCP 서버가 코드 생성 시 다음 규칙을 자동으로 적용합니다:

MOBILPAY

1. skey(서비스키)는 절대 클라이언트 코드에 포함 금지 — 환경변수에서 로드

2. HMAC 무결성 검증은 반드시 서버 사이드에서 처리 — 엔드포인트별 메시지 구성 상이 (거래등록/승인 / 취소·환불 / 에스크로 배송등록)

3. noti_url 처리 시 중복 거래 방어 로직(tid 기반 멱등성) 필수

4. 결제 승인 API(/MUP/api/approval)는 반드시 백엔드에서 호출

5. 결제 취소/환불은 해시 검증이 있는 /MUP/api/cancellation 사용 (구 /cancel 금지)

6. 테스트: test.mobilians.co.kr / 운영: mup.mobilians.co.kr

내죠여왕

1. svc_id와 MAC_KEY는 절대 클라이언트 코드에 포함 금지 — 환경변수에서 로드

2. HmacSHA256 MAC 생성/검증은 반드시 서버 사이드에서 처리

3. callback_url 핸들러에 중복 거래 방어 로직(trade_no 기반 멱등성) 필수

4. 테스트: test.mpps.co.kr / 운영: www.nezo.co.kr

동작 원리

AI 도구 → MCP 프로토콜 → 6개 Tool 중 선택 → 문서 검색/조회 → 결과 반환
                          ├── get-docs                → 통합 BM25 키워드 검색
                          ├── document-by-id           → 문서 ID 기반 조회
                          ├── get-payment-api-spec     → MOBILPAY API 명세
                          ├── get-payment-code-example → MOBILPAY 코드 예제
                          ├── get-nezo-api-spec        → 내죠여왕 API 명세
                          └── get-nezo-code-example    → 내죠여왕 코드 예제

서버 시작 시 번들된 마크다운 문서(27개)를 청크 분할 후 BM25 인덱스를 구축합니다.