ribbo-mcp

Servidor MCP (Model Context Protocol) da Ribbo. Conecta o seu assistente de IA (Claude Desktop, Cursor, etc.) à API de cobrança recorrente da Ribbo e o transforma em um operador: a IA passa a executar ações reais — criar e gerenciar assinaturas, consultar entitlements, estornar pagamentos, cobrar na hora e gerar links de pagamento/renovação.

Autenticação pela sua API key de tenant (prefixo bk_), gerada no painel em Desenvolvedores → API keys. O servidor é um cliente fino da API pública: nenhum segredo fica no código — você fornece a sua chave por variável de ambiente.

---

Requisitos

• Node.js 18+
• Uma API key da Ribbo (bk_…). Use uma chave de escopo read para só consultar, ou write para deixar a IA agir (estornar, cobrar, cancelar, etc.).

Instalação

A forma mais rápida — sem clonar nada — é apontar o seu cliente de IA para o pacote via npx. Para testar no terminal:

# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp

# ou, depois de publicado no npm:
npx -y ribbo-mcp

Ele fica aguardando no stdio — é assim que um servidor MCP roda. Quem "conversa" com ele é o seu cliente de IA (abaixo), não o terminal. Para sair: Ctrl+C.

Configuração

Duas variáveis de ambiente:

Variável	Descrição
RIBBO_API_KEY	Sua API key (bk_…), do painel em Desenvolvedores → API keys. write habilita as ações; read só as consultas.
RIBBO_API_BASE	Base da API, sem barra no fim. Ex.: https://api.ribbo.app

Claude Desktop

Em claude_desktop_config.json (menu → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ribbo": {
      "command": "npx",
      "args": ["-y", "github:andrespadeto/ribbo-mcp"],
      "env": {
        "RIBBO_API_KEY": "bk_sua_chave_aqui",
        "RIBBO_API_BASE": "https://api.ribbo.app"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas da Ribbo aparecem no ícone de ferramentas do chat.

Cursor

Em .cursor/mcp.json (no projeto) ou nas configurações globais de MCP, use o mesmo bloco mcpServers acima.

Depois de publicado no npm, troque "github:andrespadeto/ribbo-mcp" por "ribbo-mcp".

Ferramentas

Leitura (a chave read basta):

Ferramenta	O que faz
check_entitlements	Consulta os entitlements de um cliente.
list_subscriptions	Lista as assinaturas do tenant (filtros/paginação).
get_subscription	Detalha uma assinatura.
get_gateway_events	Timeline do que o gateway respondeu nas cobranças.
get_payment	Detalha um pagamento.
get_customer_subscriptions	Assinaturas de um cliente (por external_id).
get_customer_payments	Histórico de pagamentos de um cliente.
get_referral_link	Link de indicação.
get_renewal_campaign_link	Link de uma campanha de renovação para um assinante.
list_renewal_campaign_links	Todos os links de uma campanha.
get_payment_link	Link de pagamento da fatura em aberto de uma assinatura.
get_order_payment_link	2ª via / re-acesso ao Pix de um pedido (compra avulsa ou adiantamento de renovação).

Escrita (exigem chave write — movem dinheiro/estado):

Ferramenta	O que faz
create_subscription	Cria assinatura (inclusive sem cartão: Pix-manual/migração).
change_plan	Troca de plano (upgrade/downgrade/troca de ciclo).
cancel_plan_change	Cancela uma troca de plano agendada.
cancel_subscription	Cancela a assinatura.
charge_now	Dispara a cobrança da fatura agora.
reschedule_subscription	Reagenda a próxima cobrança.
remove_coupon	Remove o cupom da assinatura.
create_renewal_link	Gera link de adiantamento de renovação.
create_payment_method_link	Gera link de troca de forma de pagamento.
refund_payment	Estorna um pagamento.
update_customer	Atualiza nome/telefone do cliente.
update_customer_email	Atualiza o e-mail do cliente (local + gateway).

Segurança

• A chave identifica e isola o seu tenant — dados de outros tenants nunca são acessíveis.
• As ferramentas de escrita movem dinheiro/estado (estorno, cobrança, cancelamento). Use uma chave read quando a IA só precisa consultar, e uma write apenas onde for agir.
• A chave vive no env do cliente MCP (na sua máquina) — trate como segredo; nunca a comite.
• O código é aberto e não contém segredos: toda credencial vem do ambiente.

Convenções da API

Dinheiro em centavos (inteiro); IDs com prefixo (sub_, cus_, pay_, ord_…); datas em ISO-8601 UTC. Erros chegam como Erro <status>: {…}. O contrato completo (OpenAPI 3.1) fica em GET {RIBBO_API_BASE}/v1/public/schema/.

Desenvolvimento

git clone https://github.com/andrespadeto/ribbo-mcp.git
cd ribbo-mcp
npm install          # o "prepare" compila o TypeScript para dist/
cp .env.example .env # preencha RIBBO_API_KEY e RIBBO_API_BASE
npm run dev          # build + start

• Código-fonte em src/ (TypeScript ESM). src/index.ts registra as ferramentas; src/api.ts é o cliente HTTP (Bearer).
• O build (dist/) é gerado por npm run build e não é versionado.

Licença

MIT © Ribbo