Bitrefill MCP 서버 (샘플 구현)

이것은 샘플/참조 구현입니다. 프로덕션 환경에서 사용하려면 대신 https://api.bitrefill.com/mcp에 있는 공식 호스팅 Bitrefill eCommerce MCP에 연결하세요. 이 서버는 Bitrefill에서 유지 관리하며 OAuth를 지원하고, 직접 실행, 배포 또는 업데이트할 필요 없이 동일한 도구를 제공합니다.

Bitrefill MCP를 구축하는 방법을 배우거나, **포크(fork)**하거나, 확장하거나, Bitrefill API v2 위에 사용자 지정 변형을 직접 호스팅하려는 경우 이 저장소를 사용하세요.

이 서버는 **Authorization: Bearer ${BITREFILL_API_KEY}**를 사용하여 Bitrefill API v2 (https://api.bitrefill.com/v2)를 래핑합니다. 요청 매개변수만 Zod로 검증되며, API 응답은 변경되지 않은 JSON 텍스트로 반환됩니다.

공식 원격 MCP 사용 (프로덕션 권장)

Bitrefill eCommerce MCP는 Bitrefill에서 호스팅하며 ChatGPT, Claude Desktop / Code, Cursor 및 기타 MCP 호환 클라이언트와 통합하는 권장 방법입니다.

• OAuth (권장). 클라이언트를 다음 주소로 지정하세요:

  https://api.bitrefill.com/mcp

  Bitrefill로 리디렉션되어 로그인하고 액세스를 승인하게 됩니다. API 키를 처리할 필요가 없습니다.

• API 키. bitrefill.com/account/developers에서 키를 추가하세요:

  https://api.bitrefill.com/mcp/YOUR_API_KEY

클라이언트별 설정 가이드: ChatGPT, Claude Desktop, Claude Code, Cursor.

Related MCP server: agentstorefront-mcp

이 저장소를 대신 사용해야 하는 경우

다음과 같은 경우에만 이 로컬 MCP를 실행하세요:

• Bitrefill MCP 서버의 작동 참조 구현을 연구해야 할 때.

• 사용자 지정 도구, 프롬프트, 검증, 로깅 또는 라우팅을 추가하기 위해 포크해야 할 때.

• 사설 네트워크 또는 에어갭 환경 내에서 직접 호스팅해야 할 때.

• 더 넓은 범위의 v2 엔드포인트를 실험할 때 (이 샘플은 18개의 도구를 노출하는 반면, 공식 원격 MCP는 의도적으로 7개의 선별된 도구만 노출합니다. eCommerce MCP 참조).

일상적인 "AI 비서로부터 기프트 카드/eSIM 구매" 사용 사례의 경우 위의 호스팅된 서버를 사용하는 것이 좋습니다.

구성

1. API 키 생성: Bitrefill 계정 → 개발자.

2. 환경 변수(또는 로컬 실행을 위한 .env)에 설정:

BITREFILL_API_KEY=your_api_key_here

BITREFILL_API_KEY가 누락되면 도구가 등록되지 않습니다 (v2는 ping조차도 인증이 필요합니다).

도구 (v1.0.0)

0.x 대비 주요 변경 사항: 이전 snake_case 도구 이름(search, create_invoice, unseal_order 등)이 제거되었습니다. 위의 이름을 사용하세요. v2에는 unseal_order가 없으며, GET /orders/{id}는 배송 시 redemption_info를 반환합니다.

리소스

• bitrefill://payment-methods: buy-products / create-esim-invoice에 허용되는 payment_method 문자열

• bitrefill://category-slugs: 상품 목록/검색을 위한 B2B category 쿼리 값

• bitrefill://product-types: 상품군 키

• bitrefill://product-types/{productType}: 제품군별 카테고리 슬러그

프로젝트 레이아웃

src/
  index.ts
  types/api.ts          # Optional TS shapes for API JSON (not validated at runtime)
  constants/            # payment_method list, category slugs
  handlers/             # resources.ts, tools.ts
  schemas/              # Zod: inputs only
  services/             # API calls (search, products, invoices, orders, esims, misc)
  utils/api/            # base (BitrefillApiError), authenticated (Bearer v2)

개발

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

스모크 테스트 (이 저장소의 MCP 전용)

스모크 테스트는 항상 이 패키지의 서버(pnpm run build 후 node build/index.js)를 시작합니다. https://api.bitrefill.com/mcp나 다른 원격 MCP URL을 열지 않습니다.

권장: MCP 클라이언트 인프로세스 (stdio를 build/index.js로 연결):

pnpm run build
pnpm run smoke

pnpm run test-services (별칭)와 동일합니다.

선택 사항: MCP Inspector CLI, 여전히 이 서버에 대해서만 실행:

pnpm run build
pnpm run smoke:inspector

18개 도구 전체 (Inspector CLI, 요약 라인, 의도적인 더미 ID):

pnpm run test:inspector:all-tools

Inspector는 단일 JSON 블록이 아닌 --tool-arg key=value (여러 키에 대해 반복)를 사용합니다. 중첩된 데이터의 경우 값에 JSON을 사용하세요. 예: --tool-arg 'products=[{"product_id":"x","value":10}]'.

대화형 UI (로컬 서버 전용):

pnpm run build
pnpm run inspector

예시:

pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name ping
pnpm dlx @modelcontextprotocol/inspector node build/index.js --cli --method tools/call --tool-name product-details --tool-arg id=test-gift-card-code

클라이언트 예시 (자체 호스팅 샘플)

알림: 프로덕션 환경에서는 아래의 stdio 구성보다 호스팅된 https://api.bitrefill.com/mcp (OAuth)를 사용하는 것이 좋습니다.

Cursor / Claude 스타일 MCP 구성, env에 키 전달:

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "env": {
        "BITREFILL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker, 예: -e BITREFILL_API_KEY=... 또는 --env-file .env.

호스팅된 원격 MCP (설치 불필요, 권장):

{
  "mcpServers": {
    "bitrefill": {
      "url": "https://api.bitrefill.com/mcp"
    }
  }
}

문서

• Bitrefill 문서 (llms 인덱스)

• Bitrefill eCommerce MCP (호스팅됨): 공식 원격 서버, 프로덕션 권장

• 설정 가이드: ChatGPT, Claude, Cursor

라이선스

MIT