Bitrefill

Servidor MCP Bitrefill (Implementação de Exemplo)

Esta é uma implementação de exemplo / referência. Para uso em produção, conecte-se ao MCP oficial hospedado de eCommerce da Bitrefill em https://api.bitrefill.com/mcp. Ele é mantido pela Bitrefill, suporta OAuth e expõe as mesmas ferramentas sem que você precise executar, implantar ou atualizar nada.

Use este repositório se quiser aprender como um MCP da Bitrefill pode ser construído, bifurcá-lo, estendê-lo ou auto-hospedar uma variante personalizada sobre a API v2 da Bitrefill.

Este servidor encapsula a API v2 da Bitrefill (https://api.bitrefill.com/v2) usando Authorization: Bearer ${BITREFILL_API_KEY}. Apenas os parâmetros de requisição são validados com Zod; as respostas da API são retornadas como texto JSON inalterado.

Use o MCP remoto oficial (recomendado para produção)

O MCP de eCommerce da Bitrefill é hospedado pela Bitrefill e é a forma recomendada de integrar com ChatGPT, Claude Desktop / Code, Cursor e qualquer outro cliente compatível com MCP.

• OAuth (recomendado). Aponte seu cliente para:

  https://api.bitrefill.com/mcp
  

  Você será redirecionado para a Bitrefill para fazer login e autorizar o acesso. Não é necessário gerenciar chave de API.

• Chave de API. Anexe sua chave de bitrefill.com/account/developers:

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

Guias de configuração por cliente: ChatGPT, Claude Desktop, Claude Code, Cursor.

Quando usar este repositório

Execute este MCP local apenas se precisar:

• Estudar uma implementação de referência funcional de um servidor MCP da Bitrefill.
• Bifurcá-lo para adicionar ferramentas, prompts, validação, registro ou roteamento personalizados.
• Auto-hospedar dentro de uma rede privada ou ambiente isolado.
• Experimentar um conjunto mais amplo de endpoints v2 (este exemplo expõe 18 ferramentas, enquanto o MCP remoto oficial expõe intencionalmente um conjunto curado de 7; veja MCP de eCommerce).

Para casos de uso cotidianos de "comprar vale-presentes / eSIMs do meu assistente de IA", prefira o servidor hospedado acima.

Configuração

1. Crie uma chave de API: Conta Bitrefill → Desenvolvedores.
2. Defina no ambiente (ou .env para execuções locais):

BITREFILL_API_KEY=your_api_key_here

Se BITREFILL_API_KEY estiver ausente, nenhuma ferramenta será registrada (v2 requer autenticação até mesmo para ping).

Ferramentas (v1.0.0)

Ferramenta	API
search-products	GET /products/search (com q) ou GET /products (navegar)
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}

Mudança incompatível vs 0.x: nomes de ferramentas antigos em snake_case (search, create_invoice, unseal_order, ...) foram removidos. Use os nomes acima. Não há unseal_order na v2; GET /orders/{id} retorna redemption_info quando entregue.

Recursos

• bitrefill://payment-methods: strings payment_method permitidas para buy-products / create-esim-invoice
• bitrefill://category-slugs: valores de consulta B2B category para lista/pesquisa de produtos
• bitrefill://product-types: chaves de família de produtos
• bitrefill://product-types/{productType}: slugs de categoria por família

Estrutura do projeto

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)

Desenvolvimento

pnpm install
pnpm run build
pnpm run typecheck
pnpm run lint

Testes de fumaça (apenas MCP deste repositório)

Os testes de fumaça sempre iniciam o servidor deste pacote (node build/index.js após pnpm run build). Eles não abrem https://api.bitrefill.com/mcp ou qualquer outra URL de MCP remoto.

Recomendado: Cliente MCP em processo (stdio para build/index.js):

pnpm run build
pnpm run smoke

O mesmo que pnpm run test-services (alias).

Opcional: CLI do MCP Inspector, ainda apenas contra este servidor:

pnpm run build
pnpm run smoke:inspector

Todas as 18 ferramentas (CLI do Inspector, linhas de resumo, ids fictícios de propósito):

pnpm run test:inspector:all-tools

O Inspector usa --tool-arg key=value (repita para múltiplas chaves), não um único blob JSON. Para dados aninhados, use JSON no valor, ex.:
--tool-arg 'products=[{"product_id":"x","value":10}]'.

IU interativa (apenas servidor local):

pnpm run build
pnpm run inspector

Exemplos:

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

Exemplos de cliente (amostra auto-hospedada)

Lembrete: para produção, prefira o https://api.bitrefill.com/mcp hospedado (OAuth) em vez da configuração stdio abaixo.

Configuração MCP estilo Cursor / Claude, passe a chave em env:

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

Docker, ex.: -e BITREFILL_API_KEY=... ou --env-file .env.

MCP remoto hospedado (sem instalação, recomendado):

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

Documentação

• Documentação da Bitrefill (índice llms)
• MCP de eCommerce da Bitrefill (hospedado): servidor remoto oficial, recomendado para produção
• Guias de configuração: ChatGPT, Claude, Cursor

Licença

MIT