Bitrefill

Bitrefill MCP सर्वर (नमूना कार्यान्वयन)

यह एक नमूना / संदर्भ कार्यान्वयन है। उत्पादन उपयोग के लिए, इसके बजाय आधिकारिक होस्टेड Bitrefill eCommerce MCP से https://api.bitrefill.com/mcp पर कनेक्ट करें। यह Bitrefill द्वारा अनुरक्षित है, OAuth का समर्थन करता है, और आपको कुछ भी चलाने, तैनात करने या अपडेट करने की आवश्यकता के बिना समान उपकरण प्रदान करता है।

इस रिपॉजिटरी का उपयोग करें यदि आप सीखना चाहते हैं कि Bitrefill MCP कैसे बनाया जा सकता है, इसे फोर्क करें, इसका विस्तार करें, या 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।

इस रिपो के बजाय कब उपयोग करें

इस स्थानीय 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)

उपकरण	API
search-products	GET /products/search (q के साथ) या GET /products (ब्राउज़)
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}

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, सारांश पंक्तियाँ, उद्देश्य पर डमी आईडी):

pnpm run test:inspector:all-tools

Inspector --tool-arg key=value (कई कुंजियों के लिए दोहराएं) का उपयोग करता है, एकल JSON ब्लॉब नहीं। नेस्टेड डेटा के लिए, मान में 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