# korea-payments-mcp

[![CI](https://github.com/kiseskrap/korea-payments-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kiseskrap/korea-payments-mcp/actions/workflows/ci.yml)

MCP (Model Context Protocol) server for Korean payment gateways.

**v0.2 scope**: PortOne V2 + TossPayments (결제 조회 / 취소, PortOne 웹훅 검증)
**Planned**: KakaoPay, 국세청 사업자번호 조회, 현금영수증

## Why

영어권 MCP 생태계에 한국 결제 도메인 커버리지가 사실상 없다. Claude/Cursor 등에서 결제 이슈를 디버깅할 때 PortOne 대시보드를 열지 않고도 조회·부분환불·웹훅 서명 검증을 툴 콜로 처리하기 위함.

## Tools

각 툴은 관련 환경변수가 설정된 경우에만 노출된다 (컨텍스트 절약 + 실수 방지).

| Tool | 필요 env | Description |
| --- | --- | --- |
| `portone_get_payment` | `PORTONE_API_SECRET` | PortOne V2 결제 단건 조회 (`GET /payments/{id}`) |
| `portone_cancel_payment` | `PORTONE_API_SECRET` | PortOne V2 결제 취소/환불 (전액/부분, 낙관적 락 지원) |
| `portone_verify_webhook` | `PORTONE_WEBHOOK_SECRET` | PortOne V2 웹훅 서명 검증 ([Standard Webhooks](https://www.standardwebhooks.com/) 스펙, HMAC-SHA256) |
| `toss_get_payment` | `TOSS_SECRET_KEY` | TossPayments 결제 조회 (paymentKey 또는 orderId) |
| `toss_cancel_payment` | `TOSS_SECRET_KEY` | TossPayments 결제 취소/환불 (전액/부분) |

> PortOne 공식 문서 확인: V2 웹훅은 Standard Webhooks 스펙을 준수하며, `webhook-id` / `webhook-timestamp` / `webhook-signature` 헤더와 `{id}.{ts}.{body}` 형식의 signed payload를 사용한다. 공식 [@portone/server-sdk](https://www.npmjs.com/package/@portone/server-sdk)를 쓰는 것도 가능하지만, 본 MCP는 Toss/Kakao 등 다른 Standard Webhooks 준수 게이트웨이에도 재사용하기 위해 스펙을 직접 구현했다.

## Setup

```bash
npm install
cp .env.example .env
# .env 에 PORTONE_API_SECRET, PORTONE_WEBHOOK_SECRET 입력
npm run build
```

## Claude Desktop / Claude Code 등록

`~/Library/Application Support/Claude/claude_desktop_config.json` 또는 각 MCP 클라이언트 설정:

```json
{
  "mcpServers": {
    "korea-payments": {
      "command": "node",
      "args": ["/absolute/path/to/korea-payments-mcp/dist/index.js"],
      "env": {
        "PORTONE_API_SECRET": "your-portone-v2-api-secret",
        "PORTONE_WEBHOOK_SECRET": "whsec_...",
        "TOSS_SECRET_KEY": "test_sk_..."
      }
    }
  }
}
```

## Development

```bash
npm run dev        # tsx watch
npm run typecheck
npm test           # node:test + tsx (Standard Webhooks 공식 vector 포함)
npm run inspect    # MCP Inspector GUI (브라우저에서 tools/list, tools/call 검증)
```

### Stdio 스모크 (CI용)

`scripts/smoke.mjs`가 MCP 프로토콜 초기화 + `tools/list` 응답을 검증. 플래그로 어떤 env var를 설정할지 지정하고, 예상되는 툴 이름 집합과 대조:

```bash
npm run build
node scripts/smoke.mjs                              # portone only (2 tools)
node scripts/smoke.mjs --with-webhook               # portone + webhook (3)
node scripts/smoke.mjs --with-webhook --with-toss   # portone + webhook + toss (5)
node scripts/smoke.mjs --no-portone --with-toss     # toss only (2)
```

CI(GitHub Actions)에서 이 4가지 조합을 매 커밋 검증한다.

## Roadmap

- [x] PortOne V2 조회/취소 + 웹훅 검증 (v0.1)
- [x] TossPayments 조회/취소 (v0.2)
- [ ] TossPayments 웹훅 검증
- [ ] TossPayments 빌링키 (정기결제)
- [ ] KakaoPay (일회성/정기결제)
- [ ] 국세청 사업자번호 진위확인 (공공데이터포털)
- [ ] 현금영수증 발급 (PortOne 우선)
- [ ] Read-only `search_payments` (기간/상태 필터)

## License

MIT