Bitrefill

Servidor MCP de Bitrefill (Implementación de muestra)

Esta es una implementación de muestra / referencia. Para uso en producción, conéctese al MCP oficial alojado de Bitrefill eCommerce en https://api.bitrefill.com/mcp en su lugar. Es mantenido por Bitrefill, soporta OAuth y expone las mismas herramientas sin que usted tenga que ejecutar, desplegar o actualizar nada.

Use este repositorio si desea aprender cómo se puede construir un MCP de Bitrefill, bifurcarlo, extenderlo o autoalojar una variante personalizada sobre la API v2 de Bitrefill.

Este servidor envuelve la API v2 de Bitrefill (https://api.bitrefill.com/v2) usando Authorization: Bearer ${BITREFILL_API_KEY}. Solo los parámetros de solicitud se validan con Zod; las respuestas de la API se devuelven como texto JSON sin cambios.

Use el MCP remoto oficial (recomendado para producción)

El MCP de Bitrefill eCommerce está alojado por Bitrefill y es la forma recomendada de integrarse con ChatGPT, Claude Desktop / Code, Cursor y cualquier otro cliente compatible con MCP.

• OAuth (recomendado). Apunte su cliente a:

  https://api.bitrefill.com/mcp
  

  Será redirigido a Bitrefill para iniciar sesión y autorizar el acceso. No se requiere manejo de clave API.

• Clave API. Agregue su clave desde bitrefill.com/account/developers:

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

Guías de configuración por cliente: ChatGPT, Claude Desktop, Claude Code, Cursor.

Cuándo usar este repositorio en su lugar

Ejecute este MCP local solo si necesita:

• Estudiar una implementación de referencia funcional de un servidor MCP de Bitrefill.
• Bifurcarlo para agregar herramientas personalizadas, prompts, validación, registro o enrutamiento.
• Autoalojarlo dentro de una red privada o entorno aislado.
• Experimentar con un conjunto más amplio de endpoints v2 (esta muestra expone 18 herramientas, mientras que el MCP remoto oficial expone intencionalmente un conjunto curado de 7; consulte eCommerce MCP).

Para casos de uso cotidianos de "comprar tarjetas de regalo / eSIMs desde mi asistente de IA", prefiera el servidor alojado arriba.

Configuración

1. Cree una clave API: Cuenta de Bitrefill → Developers.
2. Establezca en el entorno (o .env para ejecuciones locales):

BITREFILL_API_KEY=your_api_key_here

Si BITREFILL_API_KEY falta, no se registran herramientas (v2 requiere autenticación incluso para ping).

Herramientas (v1.0.0)

Herramienta	API
search-products	GET /products/search (con q) o GET /products (explorar)
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}

Cambio disruptivo vs 0.x: los nombres antiguos en snake_case (search, create_invoice, unseal_order, ...) fueron eliminados. Use los nombres de arriba. No hay unseal_order en v2; GET /orders/{id} devuelve redemption_info cuando se entrega.

Recursos

• bitrefill://payment-methods: cadenas payment_method permitidas para buy-products / create-esim-invoice
• bitrefill://category-slugs: valores de consulta category B2B para lista/búsqueda de productos
• bitrefill://product-types: claves de familia de productos
• bitrefill://product-types/{productType}: slugs de categoría por familia

Estructura del proyecto

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)

Desarrollo

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Pruebas de humo (solo MCP de este repositorio)

Las pruebas de humo siempre inician el servidor de este paquete (node build/index.js después de pnpm run build). No abren https://api.bitrefill.com/mcp ni ninguna otra URL de MCP remoto.

Recomendado: Cliente MCP en proceso (stdio a build/index.js):

pnpm run build
pnpm run smoke

Igual que pnpm run test-services (alias).

Opcional: MCP Inspector CLI, aún solo contra este servidor:

pnpm run build
pnpm run smoke:inspector

Las 18 herramientas (Inspector CLI, líneas de resumen, IDs ficticios a propósito):

pnpm run test:inspector:all-tools

El Inspector usa --tool-arg key=value (repita para múltiples claves), no un solo blob JSON. Para datos anidados, use JSON en el valor, p. ej.
--tool-arg 'products=[{"product_id":"x","value":10}]'.

IU interactiva (solo servidor local):

pnpm run build
pnpm run inspector

Ejemplos:

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

Ejemplos de cliente (muestra autoalojada)

Recordatorio: para producción, prefiera el https://api.bitrefill.com/mcp alojado (OAuth) sobre la configuración stdio a continuación.

Configuración MCP estilo Cursor / Claude, pase la clave en env:

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

Docker, p. ej. -e BITREFILL_API_KEY=... o --env-file .env.

MCP remoto alojado (sin instalación, recomendado):

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

Documentación

• Documentos de Bitrefill (índice llms)
• MCP de Bitrefill eCommerce (alojado): servidor remoto oficial, recomendado para producción
• Guías de configuración: ChatGPT, Claude, Cursor

Licencia

MIT