# Cupom Center MCP

Servidor MCP local que ajuda agentes de IA a integrar sistemas clientes à API REST do Cupom Center.

O servidor roda no computador do cliente por `stdio`. Ele não hospeda modelo de IA e não abre uma porta de rede: recebe chamadas MCP do host local e acessa `https://api.cupom.center` com a API key do projeto.

## O que ele faz

Além de representar os endpoints REST como ferramentas MCP, o servidor ensina o agente a seguir o ciclo correto:

1. descobrir cupons elegíveis sem reservar ou consumir;
2. calcular o desconto e reservar uma quote temporária;
3. confirmar o resgate com o mesmo contexto;
4. registrar pagamento somente após confirmação externa;
5. consultar e reconciliar a operação;
6. reverter usos e budgets sem fingir que movimentou dinheiro.

`recommend_integration_flow` decide o fluxo sem chamar a API e sem consumir a franquia do Cupom Center. As demais ferramentas acessam a REST e estão sujeitas ao rate limit e à medição de consumo da organização.

## Requisitos

- Node.js 20 ou superior;
- uma API key criada para o projeto e ambiente corretos no Cupom Center;
- permissões compatíveis com as ferramentas usadas.

| Operação | Permissão |
|---|---|
| Descoberta, consulta de operação | `COUPON_READ` |
| Emissão, consulta e revogação de código individual | `COUPON_ISSUE` e `COUPON_READ` |
| Quote, resgate e reversão | `COUPON_REDEEM` |
| Pagamento no resgate ou posterior | `PAYMENT_WRITE` |

Organização, ambiente e projeto são sempre derivados da API key. O MCP não permite selecionar outro tenant por argumento.

## Desenvolvimento local

```bash
cd mcp
bun install
bun run build
```

## Instalação publicada

Depois da publicação no npm, fixe uma versão no host MCP:

```json
{
  "mcpServers": {
    "cupom-center": {
      "command": "npx",
      "args": ["-y", "@cupom_center/mcp@0.1.0"],
      "env": {
        "CUPOM_API_KEY": "cpm_..."
      }
    }
  }
}
```

As instruções de release, npm Trusted Publishing e MCP Registry estão em [`PUBLISHING.md`](./PUBLISHING.md).

Configure o host MCP para executar o arquivo compilado usando um caminho absoluto:

```json
{
  "mcpServers": {
    "cupom-center": {
      "command": "node",
      "args": ["/caminho/absoluto/para/Cupom/mcp/dist/index.js"],
      "env": {
        "CUPOM_API_KEY": "cpm_...",
        "CUPOM_API_URL": "https://api.cupom.center"
      }
    }
  }
}
```

`CUPOM_API_URL` é opcional e usa `https://api.cupom.center` por padrão. HTTP só é aceito para `localhost`, facilitando desenvolvimento sem permitir credenciais em conexões remotas inseguras.

`CUPOM_API_TIMEOUT_MS` é opcional, usa 20 segundos por padrão e aceita valores entre 1.000 e 120.000 ms.

O servidor pode iniciar sem uma API key para consultar o guia e executar `recommend_integration_flow`. As ferramentas que acessam a REST retornarão um erro de configuração até `CUPOM_API_KEY` ser definida.

Para produção, prefira que o instalador recupere a API key do cofre de credenciais do sistema operacional. Configurá-la diretamente no JSON do host é simples, mas exige proteger esse arquivo contra leitura, backup ou compartilhamento indevido.

## Ferramentas

- `recommend_integration_flow`
- `find_eligible_coupons`
- `quote_single_coupon`
- `quote_multiple_coupons`
- `select_coupons_for_units`
- `create_coupon_issuance`
- `get_coupon_issuance`
- `revoke_coupon_issuance`
- `redeem_single_coupon`
- `redeem_multiple_coupons`
- `get_coupon_operation`
- `record_operation_payment`
- `reverse_operation`

O recurso MCP `cupom://integration-guide` contém as regras de decisão compartilhadas pelo servidor.

## Segurança e retries

- O servidor nunca escreve a API key em logs ou respostas.
- `stdout` é reservado exclusivamente ao protocolo MCP; diagnósticos usam `stderr`.
- Requisições com efeito comercial não recebem retry automático.
- Depois de timeout, não altere os dados e tente novamente às cegas.
- Emissão usa `Idempotency-Key`; repetir a mesma chave exige o mesmo comando.
- Resgates devem preservar carrinho, contexto, códigos, ordem, estratégia, quote e pagamento.
- Cupom Center registra pagamentos confirmados pelo cliente, mas não cobra nem estorna dinheiro.
- Reversões são integrais e liberam usos e budgets; o estorno financeiro continua sendo responsabilidade do provedor de pagamento do cliente.

O MCP não administra cupons, campanhas, organizações, membros ou API keys. Essas operações pertencem à superfície GraphQL autenticada do painel.

## Validação

```bash
bun run typecheck
bun run build
```

O projeto evita testes unitários isolados. A validação de protocolo deve ser feita conectando o binário compilado a um cliente MCP ou ao MCP Inspector, e a validação da REST deve usar um ambiente/projeto de homologação.