Bitrefill

Bitrefill MCP Server (Implementasi Contoh)

Ini adalah implementasi contoh / referensi. Untuk penggunaan produksi, hubungkan ke Bitrefill eCommerce MCP resmi yang dihosting di https://api.bitrefill.com/mcp. Ini dikelola oleh Bitrefill, mendukung OAuth, dan menyediakan alat yang sama tanpa Anda perlu menjalankan, menerapkan, atau memperbarui apa pun.

Gunakan repositori ini jika Anda ingin mempelajari bagaimana Bitrefill MCP dapat dibangun, memfork-nya, memperluasnya, atau menghosting sendiri varian yang disesuaikan di atas Bitrefill API v2.

Server ini membungkus Bitrefill API v2 (https://api.bitrefill.com/v2) menggunakan Authorization: Bearer ${BITREFILL_API_KEY}. Hanya parameter request yang divalidasi dengan Zod; respons API dikembalikan sebagai teks JSON tanpa perubahan.

Gunakan MCP jarak jauh resmi (disarankan untuk produksi)

Bitrefill eCommerce MCP dihosting oleh Bitrefill dan merupakan cara yang disarankan untuk berintegrasi dengan ChatGPT, Claude Desktop / Code, Cursor, dan klien lain yang kompatibel dengan MCP.

• OAuth (disarankan). Arahkan klien Anda ke:

  https://api.bitrefill.com/mcp
  

  Anda akan dialihkan ke Bitrefill untuk masuk dan mengotorisasi akses. Tidak perlu penanganan kunci API.

• Kunci API. Tambahkan kunci Anda dari bitrefill.com/account/developers:

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

Panduan pengaturan per klien: ChatGPT, Claude Desktop, Claude Code, Cursor.

Kapan menggunakan repo ini sebagai gantinya

Jalankan MCP lokal ini hanya jika Anda perlu:

• Mempelajari implementasi referensi yang berfungsi dari server Bitrefill MCP.
• Memfork-nya untuk menambahkan alat, prompt, validasi, pencatatan, atau perutean kustom.
• Menghosting sendiri di dalam jaringan pribadi atau lingkungan terisolasi.
• Bereksperimen dengan set endpoint v2 yang lebih luas (contoh ini menyediakan 18 alat, sementara MCP jarak jauh resmi sengaja menyediakan set terkurasi sebanyak 7; lihat eCommerce MCP).

Untuk kasus penggunaan sehari-hari "beli kartu hadiah / eSIM dari asisten AI saya", lebih baik gunakan server yang dihosting di atas.

Konfigurasi

1. Buat kunci API: Akun Bitrefill → Developers.
2. Atur di environment (atau .env untuk menjalankan lokal):

BITREFILL_API_KEY=your_api_key_here

Jika BITREFILL_API_KEY tidak ada, tidak ada alat yang terdaftar (v2 memerlukan autentikasi bahkan untuk ping).

Alat (v1.0.0)

Alat	API
search-products	GET /products/search (dengan q) atau GET /products (telusuri)
product-details	GET /products/{id}
buy-products	POST /invoices
get-invoice-by-id	GET /invoices/{id}
get-order-by-id	GET /orders/{id}
list-invoices	GET /invoices
list-orders	GET /orders
pay-invoice	POST /invoices/{id}/pay
get-account-balance	GET /accounts/balance
check-phone-number	GET /check_phone_number
ping	GET /ping
list-esim-products	GET /products/esims
get-esim-product	GET /products/esims/{id}
create-esim-invoice	POST /esims
get-esim-invoice	GET /esims/invoice/{id}
pay-esim-invoice	POST /esims/invoice/{id}/pay
list-esims	GET /esims
get-esim	GET /esims/{id}

Perubahan yang merusak vs 0.x: nama alat snake_case lama (search, create_invoice, unseal_order, ...) telah dihapus. Gunakan nama di atas. Tidak ada unseal_order di v2; GET /orders/{id} mengembalikan redemption_info saat terkirim.

Sumber Daya

• bitrefill://payment-methods: string payment_method yang diizinkan untuk buy-products / create-esim-invoice
• bitrefill://category-slugs: nilai kueri category B2B untuk daftar/pencarian produk
• bitrefill://product-types: kunci family produk
• bitrefill://product-types/{productType}: slug kategori per family

Tata letak proyek

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)

Pengembangan

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Uji asap (hanya MCP repo ini)

Uji asap selalu memulai server paket ini (node build/index.js setelah pnpm run build). Mereka tidak membuka https://api.bitrefill.com/mcp atau URL MCP jarak jauh lainnya.

Disarankan: Klien MCP dalam proses (stdio ke build/index.js):

pnpm run build
pnpm run smoke

Sama seperti pnpm run test-services (alias).

Opsional: MCP Inspector CLI, tetap hanya terhadap server ini:

pnpm run build
pnpm run smoke:inspector

Semua 18 alat (Inspector CLI, baris ringkasan, id dummy sengaja):

pnpm run test:inspector:all-tools

Inspector menggunakan --tool-arg key=value (ulangi untuk beberapa kunci), bukan blob JSON tunggal. Untuk data bersarang, gunakan JSON di nilainya, mis.
--tool-arg 'products=[{"product_id":"x","value":10}]'.

UI Interaktif (hanya server lokal):

pnpm run build
pnpm run inspector

Contoh:

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

Contoh klien (contoh yang dihosting sendiri)

Pengingat: untuk produksi, lebih baik gunakan https://api.bitrefill.com/mcp yang dihosting (OAuth) daripada konfigurasi stdio di bawah.

Konfigurasi MCP gaya Cursor / Claude, berikan kunci di env:

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

Docker, mis. -e BITREFILL_API_KEY=... atau --env-file .env.

MCP jarak jauh yang dihosting (tanpa instalasi, disarankan):

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

Dokumentasi

• Dokumen Bitrefill (indeks llms)
• Bitrefill eCommerce MCP (dihosting): server jarak jauh resmi, disarankan untuk produksi
• Panduan pengaturan: ChatGPT, Claude, Cursor

Lisensi

MIT