Samsung Checkout MCP Server

Samsung Smart TV 인앱결제(Samsung Checkout / DPI) 개발을 위한 MCP(Model Context Protocol) 서버입니다.

AI 코딩 도구(Claude, Cursor 등)에 연결하면 Samsung Checkout 개발에 필요한 API 레퍼런스, 코드 생성, 트러블슈팅을 실시간으로 지원받을 수 있습니다.

---

설치 및 연결

방법 1: npx (npm 배포 후)

별도 설치 없이 바로 사용:

{
  "mcpServers": {
    "samsung-checkout": {
      "command": "npx",
      "args": ["-y", "samsung-checkout-mcp"]
    }
  }
}

방법 2: 로컬 직접 실행

git clone https://github.com/HoRockx2/samsung-checkout-mcp.git
cd samsung-checkout-mcp
npm install

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "samsung-checkout": {
      "command": "node",
      "args": ["/절대경로/samsung-checkout-mcp/src/index.js"]
    }
  }
}

Claude Code (CLI)

claude mcp add samsung-checkout node "/절대경로/samsung-checkout-mcp/src/index.js"

Cursor

Settings > MCP에서 추가하거나, 프로젝트 루트에 .cursor/mcp.json 생성:

{
  "mcpServers": {
    "samsung-checkout": {
      "command": "node",
      "args": ["/절대경로/samsung-checkout-mcp/src/index.js"]
    }
  }
}

연결 성공 시 Settings > MCP에서 초록색 점이 표시됩니다.

---

제공 도구 (Tools)

도구명	설명
lookup_api	Billing API, DPI API 레퍼런스 조회 (파라미터, 코드 예제)
generate_checkvalue_guide	CheckValue(HMAC SHA256) 생성 가이드 (API별 공식, 다국어 코드)
get_implementation_guide	상품 타입별(Consumable/Subscription 등) 전체 구현 플로우
troubleshoot	에러코드/증상 기반 진단 및 해결 방법 안내
get_setup_checklist	환경 설정 단계별 체크리스트 (Seller Office → DPI → 테스트 → 출시)
get_code_snippet	클라이언트/서버 보일러플레이트 및 코드 스니펫
search_knowledge	전체 지식 베이스 키워드 검색

---

User Scenarios

Scenario 1: 처음 Samsung Checkout 개발을 시작하는 경우

"Samsung TV 앱에 인앱결제를 넣으려는데, 어디서부터 시작해야 해?"

AI가 get_setup_checklist 도구를 호출하여 Seller Office 가입부터 DPI 포털 설정, 상품 등록, config.xml 설정까지 단계별 가이드를 제공합니다.

추가 질문 예시:

• "Seller Office 가입은 어떻게 해?"
• "config.xml에 어떤 privilege를 추가해야 해?"
• "Test Buyer는 어떻게 등록해?"

---

Scenario 2: 특정 API 사용법을 알고 싶을 때

"buyItem API 파라미터 알려줘"

AI가 lookup_api 도구를 호출하여 buyItem()의 전체 파라미터 스펙, 필수/선택 여부, 타입, 설명, 코드 예제를 제공합니다.

추가 질문 예시:

• "getUserPurchaseList는 어떻게 호출해?"
• "DPI 서버 API 중에 구매 검증 API 스펙 보여줘"
• "cont/apply API의 요청/응답 형식이 뭐야?"
• "서버 API 전체 목록 보여줘"

---

Scenario 3: 상품 타입별 구현 방법이 궁금할 때

"Consumable 상품 구현 플로우가 어떻게 돼?"

AI가 get_implementation_guide 도구를 호출하여 Consumable 상품의 구매 → 서버 검증 → Apply 처리까지 전체 플로우를 안내합니다.

추가 질문 예시:

• "구독(Subscription) 상품은 어떻게 구현해?"
• "Non-Consumable과 Limited Period의 차이가 뭐야?"
• "구독 해지 플로우를 알려줘"
• "각 상품 타입별 차이점을 비교해줘"

---

Scenario 4: CheckValue 생성이 필요할 때

"cont/verify API의 CheckValue를 Python으로 어떻게 만들어?"

AI가 generate_checkvalue_guide 도구를 호출하여 해당 API의 파라미터 연결 순서, HMAC SHA256 해싱 방법, Python 코드 예제를 제공합니다.

추가 질문 예시:

• "CheckValue가 뭐야? 왜 필요해?"
• "invoice/list API의 CheckValue 공식 알려줘"
• "Java로 CheckValue 생성하는 코드 보여줘"
• "CheckValue에서 자주 하는 실수가 뭐야?"

---

Scenario 5: 에러가 발생했을 때

"0410424 에러가 뭐야?"

AI가 troubleshoot 도구를 호출하여 해당 에러 코드의 원인과 해결 방법을 안내합니다.

추가 질문 예시:

• "CheckValue Invalid 에러가 나는데 어떻게 해?"
• "Staging에서는 되는데 Production에서 안 돼"
• "buyItem 호출했는데 'Billing not available'이 나와"
• "구매는 됐는데 apply가 안 돼"
• "Samsung Account 로그인 안 됨 에러"

---

Scenario 6: 코드 보일러플레이트가 필요할 때

"서버 전체 코드 보일러플레이트 줘"

AI가 get_code_snippet 도구를 호출하여 Node.js 기반 DPI 서버 전체 코드를 제공합니다.

추가 질문 예시:

• "클라이언트 측 전체 코드 예제 보여줘"
• "config.xml 템플릿 줘"
• "buyItem 호출하는 코드만 보여줘"
• "구매 검증(verify) 코드 스니펫 줘"

---

Scenario 7: 특정 키워드로 정보를 찾고 싶을 때

"OrderCustomID가 뭐야?"

AI가 search_knowledge 도구를 호출하여 전체 문서에서 해당 키워드가 포함된 섹션을 찾아 반환합니다.

추가 질문 예시:

• "Free Trial 관련 내용 찾아줘"
• "CountryCode는 어디에 쓰여?"
• "SecurityKey는 어디서 발급받아?"
• "invoice에 대해 전체적으로 알려줘"

---

Scenario 8: 실제 개발 중 복합 질문

실제 개발 중에는 여러 도구가 조합되어 사용됩니다:

"Subscription 상품을 만들려고 해. 구현 플로우, 서버 API 스펙, CheckValue 생성법, 그리고 서버 보일러플레이트까지 한번에 알려줘"

AI가 get_implementation_guide, lookup_api, generate_checkvalue_guide, get_code_snippet을 순차적으로 호출하여 종합적인 가이드를 제공합니다.

복합 질문 예시:

• "지금 Consumable 상품 개발 중인데, buyItem 호출 후 서버에서 검증하는 전체 과정을 코드와 함께 알려줘"
• "Production 배포 전에 확인해야 할 체크리스트와 Staging/PRD 환경 차이점 알려줘"
• "결제 연동 테스트하다가 에러가 났어. 에러 코드는 0410424이고 CheckValue 관련인 것 같아"

---

테스트

npm test

71개 테스트가 10개 카테고리로 구성되어 있습니다:

1. MD 파일 존재 여부 (9개 문서)
2. Markdown 파서 기본 동작
3. 문서 로드 검증
4. 지식 베이스 내용 품질 (필수 데이터 누락 여부)
5. 검색 기능
6. 섹션 검색
7. 코드 블록 추출
8. 콘텐츠 렌더링
9. 엣지 케이스 & 견고성
10. 데이터 일관성 (문서 간 교차 검증)

docs/의 MD 파일을 수정한 후 npm test로 품질을 검증하세요.

---

데이터 유지보수

지식 베이스는 docs/ 디렉토리의 Markdown 파일로 관리됩니다. 코드 수정 없이 MD 파일만 편집하면 됩니다.

docs/
├── 01-overview.md           # 전체 개요, 아키텍처, 상품 타입
├── 02-client-billing-api.md # buyItem, getUserPurchaseList 상세 스펙
├── 03-dpi-server-api.md     # DPI 서버 API 5종
├── 04-security-checkvalue.md# CheckValue 생성 가이드 (4개 언어)
├── 05-setup-and-testing.md  # 환경 설정 8단계, 테스트, 출시 체크리스트
├── 06-troubleshooting.md    # 에러코드, FAQ, 디버깅 팁
├── 07-implementation-flows.md# 상품 타입별 구현 플로우
├── 08-code-snippets.md      # 클라이언트/서버 보일러플레이트
└── 09-references.md         # 공식 문서, 포털, GitHub 링크

License

MIT