@payretailers/mcp

PayRetailers Payments API용 공식 Model Context Protocol (MCP) 서버입니다.

MCP 호환 AI 어시스턴트를 PayRetailers 통합 전문가로 바꿔줍니다. 이 서버는 공식 가이드, 전술적 스킬, 엔드포인트 레퍼런스, 통합 도구(검색, 국가별 검증, 웹훅 플레이북)를 일급 MCP 리소스, 도구, 프롬프트로 노출합니다.

Cursor, Claude Desktop, Claude Code, Windsurf, Antigravity, Zed, VS Code + Copilot, JetBrains IDEs, Continue.dev, Cline 및 stdio를 통해 MCP를 지원하는 모든 클라이언트에서 작동합니다.

왜 사용해야 하나요

이 서버를 설치하면 AI 어시스턴트가 PayRetailers에 대해 추측하는 것을 멈추고 모든 단계에서 진실의 원천을 참고하기 시작합니다.

• 첫 시도에 올바른 코드. 어시스턴트가 각 엔드포인트의 실제 OpenAPI 형태를 읽으므로(get_endpoint_spec), 생성된 코드는 다른 PSP에서 가져온 것이 아닌 실제 필드 이름, 타입, 필수 조합을 사용합니다.

• 처음부터 국가 인지. PIX payin을 요청하면 어시스턴트는 PIX가 브라질 전용이고, BRL을 기대하며, 유효한 11자리 CPF가 필요하고, QR 만료가 빠르다는 것을 압니다. SPEI를 요청하면 멕시코가 CURP 또는 RFC, MXN을 원하고 CLABE가 비동기적으로 프로비저닝된다는 것을 압니다. 모두 get_country_rules로 지원됩니다.

• 샌드박스에 도달하기 전에 페이로드 검증. validate_payload는 CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE에 대한 실제 체크섬 검증과 교차 규칙(정수 소수 단위, HTTPS 알림 URL, 통화/국가 일치, 결제수단/국가 호환성, 멱등성 키, 고객 필수 필드 매트릭스, 구독 AmountModel 형태, PIX Automático 재시도 계약)을 실행합니다. 에디터에서 버그를 잡을 수 있으며, 400 INVALID_MODEL_SCHEMA 응답에서 잡을 필요가 없습니다.

• 올바르게 설계된 웹훅 수신기. get_webhook_playbook은 표준 이벤트 어휘, 재시도 정책, 서명/재생 계약을 반환합니다. validate_webhook_handler는 수신기 코드를 한 줄도 작성하기 전에 가장 해로운 6가지 안티패턴(처리 후 ack, eventId 중복 제거 누락, 비즈니스 오류를 500으로 처리, 프로덕션에서 서명 비활성화, 벽시계 순서 가정, HTTPS 누락)을 잡아냅니다.

• 어려운 흐름을 위한 슬래시 명령 프롬프트. /integrate-pix-payin, /integrate-subscriptions, /implement-webhook-handler, /integrate-payout-fx, /build-checkout, /debug-401-auth, /reconcile-with-graphql을 입력하면 선택한 스택에서 프로덕션 수준의 구현을 얻을 수 있습니다.

• 제로 구성, 제로 네트워크, 오프라인 친화적. 모든 것이 릴리스 zip에 번들로 포함되어 있습니다. 계정, API 키, 문서에 대한 질문에 답하기 위한 아웃바운드 호출이 필요 없습니다. 자격 증명은 (계획된) simulate_transaction 도구에만 필요합니다.

내부적으로 7개의 도구, 7개의 프롬프트, 158개의 문서 리소스(가이드 + 스킬 + 레퍼런스 + 레시피 + 개념 문서)가 있으며, 모두 payretailers-ai-docs 저장소에서 그대로 미러링되었습니다.

Related MCP server: Payman AI Documentation MCP Server

노출되는 것

리소스

구조화된 LLM 친화적인 PayRetailers 문서 접근 방식입니다.

전체 목록은 연결 시 동적으로 공지되며, 클라이언트는 리소스 선택기를 통해 탐색할 수 있습니다.

도구

LLM이 추측하는 대신 호출할 수 있는 작업입니다.

프롬프트

개발자가 Cursor / Claude Desktop 등에서 /로 선택할 수 있는 바로 사용 가능한 템플릿입니다.

설치

두 가지 지원 경로가 있습니다. 하나를 선택하세요:

• 옵션 A — GitHub Releases에서 사전 빌드된 zip 다운로드 (현재 권장): npm 계정 불필요, 컴파일 불필요, 다운로드 후 완전히 오프라인으로 작동합니다. @payretailers/mcp가 아직 npm에 없는 동안 공식적으로 지원되는 배포 방식입니다.

• 옵션 B — 소스에서 빌드: 코드를 실행하기 전에 감사(audit)하려는 기여자와 보안에 민감한 배포 환경을 위한 방식입니다.

옵션 C — npm에서 @payretailers/mcp로 설치하는 방식은 계획되어 있지만 아직 사용할 수 없습니다. 패키지가 게시되면 클라이언트별 구성 섹션의 npx -y @payretailers/mcp 스니펫이 즉시 작동합니다.

옵션 A — GitHub Releases에서 설치

사전 요구 사항: Node.js 20 이상 (node --version). 그 외에는 없습니다 — 릴리스 zip은 자체 포함(self-contained)입니다.

1. Releases 페이지를 열고 최상위 릴리스의 "Assets" 섹션에서 최신 payretailers-mcp-vX.Y.Z.zip을 다운로드합니다.

2. 아무 곳에나 압축을 풉니다. 일반적인 위치:

   • Windows: C:\Tools\payretailers-mcp

   • macOS / Linux: ~/tools/payretailers-mcp

3. MCP 클라이언트에 서버를 추가합니다 (아래 클라이언트별 구성 또는 해당 섹션에 링크된 단계별 가이드 참조). 압축을 푼 폴더 안의 dist/index.js 절대 경로를 지정합니다.

4. MCP 클라이언트를 다시 로드/재시작합니다. 서버가 다른 도구들과 함께 표시됩니다.

스크린샷과 검증 프롬프트가 포함된 단계별 설정 가이드:

• Cursor

• Claude Code CLI

• Claude Desktop

• VS Code + GitHub Copilot

연결 전후에 선택적으로 스모크 테스트를 실행할 수 있습니다 — 번들이 끝까지 정상 작동하는지 확인합니다:

cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs

예상 결과: 마지막에 PASS ✅가 표시되고, 도구 7개, 리소스 158개, 프롬프트 7개, 리소스 템플릿 5개가 공지됩니다.

옵션 B — 소스에서 빌드

기여자이거나 보안 정책상 실행 전에 코드를 감사해야 하는 경우를 위한 방식입니다. 사전 요구 사항: Node.js 20 이상, git.

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)

data/ (Guides, Skills, Reference, Recipes, 개념 문서, 선별된 JSON)는 저장소에 포함되어 있습니다 — 동일한 머신에서 업데이트된 payretailers-ai-docs 체크아웃을 미러링하는 경우가 아니라면 npm run sync:docs를 실행할 필요가 없습니다.

그런 다음 옵션 A와 동일한 방식으로 dist/index.js를 MCP 클라이언트에 연결합니다.

클라이언트별 구성

검증 프롬프트와 문제 해결이 포함된 전체 안내를 선호하시나요? Cursor, Claude Code, Claude Desktop, VS Code + Copilot용 단계별 가이드는 docs/setup/를 참조하세요. 아래 스니펫은 클라이언트 사용법을 이미 알고 있는 경우 필요한 최소한의 JSON입니다.

모든 클라이언트는 동일한 세 가지 정보를 필요로 합니다: command(node), dist/index.js의 절대 경로를 가리키는 args 배열, 그리고 향후 simulate_transaction 도구를 위한 선택적 env 블록.

아래의 C:/Tools/payretailers-mcp/dist/index.js를 릴리스를 압축 해제한 절대 경로로 바꾸세요. Windows에서는 JSON에 슬래시(/)를 사용하세요 — 백슬래시는 이스케이프가 필요하며 혼란스러운 오류를 유발합니다.

Cursor

~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트별)에 추가:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}

env 블록은 선택 사항입니다 — Resources, search_docs, 모든 검증 도구는 자격 증명 없이 작동합니다.

Claude Desktop

claude_desktop_config.json에 추가:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

VS Code + Copilot

.vscode/mcp.json(워크스페이스)에 추가하거나 명령 팔레트 → MCP: Open User Configuration으로 사용자 범위 파일을 엽니다:

{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}

참고: VS Code는 예외입니다 — 루트 키가 "servers"입니다 ("mcpServers"가 아님). MCP 도구는 Copilot Chat의 Agent 모드에서만 실행됩니다.

Zed

~/.config/zed/settings.json에 추가:

{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}

Continue.dev

~/.continue/config.json에 추가:

{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}

JetBrains AI Assistant

Settings → AI Assistant → MCP Servers → Add를 열고 다음을 입력합니다:

• Name: payretailers

• Command: node

• Arguments: C:/Tools/payretailers-mcp/dist/index.js (절대 경로)

기타 클라이언트

stdio를 통해 MCP를 지원하는 모든 클라이언트는 이 서버를 사용할 수 있습니다. node <절대-경로>/dist/index.js로 지정하면 끝입니다.

npm 사용 가능 시점

@payretailers/mcp가 npm에 게시되면 동일한 구성이 더 짧은 형식으로 작동합니다:

{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }

env 변경 없음, 압축 해제된 폴더를 유지할 필요도 없습니다.

작동 확인

MCP 클라이언트를 다시 로드한 후 서버의 상태 항목에 다음과 같은 내용이 표시되어야 합니다:

도구 7개 · 리소스 158개 · 프롬프트 7개 · 리소스 템플릿 5개

• Cursor: Ctrl+Shift+P → Customize → MCPs 탭. payretailers가 초록색 점과 함께 표시되는지 확인하고 확장합니다.

• Claude Desktop: 새 채팅에서 도구 서랍을 확인합니다. PayRetailers 도구가 다른 MCP 도구와 함께 표시되어야 합니다.

• VS Code / Zed / Continue.dev / Windsurf: 각 클라이언트 문서에서 MCP 상태 패널을 확인합니다.

어시스턴트가 도구를 호출하지 않는 것 같으면 프롬프트 앞에 *"PayRetailers MCP를 사용하여..."*를 붙여 한 번 강제로 호출해 보세요. 대화에서 도구를 한 번 호출하면 이후에도 계속 호출하는 경향이 있습니다.

문제 해결

서버가 시작되지 않습니다. 터미널에서 번들을 수동으로 실행합니다:

node /path/to/payretailers-mcp/dist/index.js

입력을 기다리며 조용히 대기하면 번들은 정상입니다 — 문제는 클라이언트 측에 있습니다 (구성의 경로 오타, Windows의 슬래시/백슬래시, 잘못된 프로세스 재시작). 오류가 출력되면 가장 흔한 원인은 Node < 20 (Node 업그레이드) 또는 불완전한 다운로드 (zip 재다운로드)입니다.

클라이언트에 이전 개수가 표시됩니다 (예: 도구 5개, 리소스 89개). 일부 클라이언트는 MCP 도구/리소스 목록을 캐시합니다. 클라이언트의 MCP 패널에서 서버를 OFF → ON으로 전환하거나, 구성에 사용하지 않는 env 항목(예: "MCP_VERSION": "0.4.1")을 추가하여 재시작을 강제합니다.

모델이 MCP 도구를 전혀 호출하지 않는 것 같습니다. 채팅이 Agent 모드(Ask/읽기 전용 모드가 아닌)인지 확인하세요. 일부 경량 모델은 도구 호출에 덜 적극적입니다 — 처음 호출할 때는 최상위 모델로 전환하면 어시스턴트가 나머지 대화 동안 도구를 사용할 수 있음을 기억합니다.

로그는 어디에 있나요? 모든 MCP 클라이언트에는 JSON-RPC 핸드셰이크, 파싱 오류, 서버 stderr를 캡처하는 MCP 로그 패널이 있습니다. Cursor: Ctrl+Shift+U → 드롭다운 → MCP Logs.

환경 변수

선택 사항 — 향후 simulate_transaction 도구(4단계)에만 필요합니다. 그 외 모든 것(Resources, search_docs, Prompts)은 자격 증명 없이 작동합니다.

보안: 서버는 자격 증명을 로그에 기록하거나 영구 저장하지 않습니다. 세션 동안 메모리에만 존재하며 simulate_transaction을 호출할 때 api-sandbox.payretailers.com 또는 api.payretailers.com으로만 전송됩니다.

사용 예시

구성이 완료되면 AI 어시스턴트에게 자연어로 요청합니다:

"브라질에서 R$50에 대한 첫 PIX payin을 샌드박스에서 생성해 줘. Node.js를 사용해."

내부적으로 어시스턴트는 다음을 수행합니다:

1. search_docs({ query: "pix payin brazil" }) 호출 → brazil-pix-payin 스킬 찾기.

2. 정확한 단계를 위해 payretailers://skill/brazil-pix-payin 읽기.

3. 올바른 엔드포인트, 헤더, 소수 단위(minor units), CPF 형식으로 실행 가능한 코드 생성.

또는 /integrate-pix-payin 프롬프트를 직접 사용하여 완전한 스캐폴딩 답변을 받을 수 있습니다.

제출 전 페이로드 검증

어시스턴트가 페이로드를 작성한 후 API를 호출하기 전에 검증할 수 있습니다:

// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}

응답에는 code, severity, path, message가 포함된 모든 문제가 나열되며, 종종 hint와 suggestion도 포함됩니다 — LLM은 네트워크 왕복을 낭비하기 전에 페이로드를 수정할 수 있습니다.

개발

git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio

data/ (Guides, Skills, Reference, Recipes, 개념 문서, 선별된 JSON)는 저장소에 포함되어 있습니다. ../payretailers-ai-docs를 체크아웃했고 미러를 새로 고치려는 경우에만 npm run sync:docs를 실행하세요.

공식 MCP Inspector로 서버를 검사할 수 있습니다:

npx @modelcontextprotocol/inspector node dist/index.js

릴리스 (관리자용)

릴리스는 태그 푸시(v*.*.*) 시 GitHub Actions를 통해 자동화됩니다. 워크플로우:

1. lint, typecheck, 단위 테스트, 빌드, 스모크 테스트를 실행합니다.

2. npm run pack:release를 실행하여 release/payretailers-mcp-vX.Y.Z.zip(번들된 dist/index.js + data/ 미러 + README + LICENSE + CHANGELOG + 스모크 테스트)을 생성합니다.

3. GitHub Release를 만들고 zip을 첨부합니다.

4. NPM_TOKEN 저장소 시크릿이 구성된 경우에만 npm에 @payretailers/mcp로 게시합니다 — 그렇지 않으면 릴리스는 GitHub 전용입니다.

로컬에서 릴리스를 만들고 태그를 푸시하려면:

# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml

Semver는 엄격하게 적용됩니다: 패치 릴리스는 버그 수정, 마이너 릴리스는 기존 기능을 깨지 않고 도구/프롬프트/리소스 추가, 메이저 릴리스는 이름 변경/제거에만 사용됩니다.

로드맵

• 0.1 ✅ Resources (Guides, Skills), search_docs, integrate-pix-payin 프롬프트.

• 0.2 ✅ Resources (Reference, Recipes), get_country_rules, get_test_data, get_endpoint_spec, 프롬프트 integrate-payout-fx, build-checkout, debug-401-auth, reconcile-with-graphql.

• 0.3 ✅ CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE에 대한 실제 체크섬 검증 + 교차 규칙(소수 단위, 통화/국가, HTTPS 웹훅, 결제수단/국가, 멱등성)이 포함된 validate_payload.

• 0.4 ✅ 개념 문서 리소스 카테고리, get_webhook_playbook, validate_webhook_handler, 구독 작업을 위한 확장된 validate_payload, 프롬프트 implement-webhook-handler, integrate-subscriptions.

• 0.4.1 ✅ 구독 스키마 정렬 (AmountModel, frequency enum, authorizationType) — CHANGELOG.md.

• 0.5 — simulate_transaction (샌드박스 대상 드라이런), get_error_code, 확장된 국가 커버리지.

• 1.0 — 안정적인 공개 릴리스 + 공식 MCP 레지스트리 등재 + npm 게시.

자세한 내용은 CHANGELOG.md를 참조하세요.

관련 자료

• Cursor, Claude Code, Claude Desktop, VS Code + Copilot용 단계별 설정 가이드: docs/setup/.

• 동반 문서 저장소: payretailers-dev/payretailers-ai-docs — Guides, Skills 및 문서 미러의 원본.

• 공식 문서: www.payretailers.dev.

• LLM 개발 가이드: www.payretailers.dev/docs/develop-with-llms.

• Model Context Protocol: modelcontextprotocol.io.

라이선스

소스 코드: MIT. LICENSE 참조.

data/에 포함된 문서 콘텐츠(Guides, Skills, Reference, Recipes)는 payretailers-ai-docs 저장소에서 상속된 CC BY-ND 4.0에 따라 라이선스가 부여됩니다. 선별된 데이터 파일(data/country-rules.json, data/test-data.json)도 CC BY-ND 4.0으로 공개됩니다.

기여

버그 리포트와 기능 요청은 GitHub Issues를 통해 환영합니다. 커뮤니티의 풀 리퀘스트는 검토되지만 병합 여부는 PayRetailers 팀의 재량에 따릅니다 — CONTRIBUTING.md가 제공되면 참조하세요.