# ribbo-mcp

Servidor **MCP** ([Model Context Protocol](https://modelcontextprotocol.io)) 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:

```bash
# 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**):

```json
{
  "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

```bash
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](./LICENSE) © Ribbo