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:

descobrir cupons elegíveis sem reservar ou consumir;
calcular o desconto e reservar uma quote temporária;
confirmar o resgate com o mesmo contexto;
registrar pagamento somente após confirmação externa;
consultar e reconciliar a operação;
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

cd mcp
bun install
bun run build

Instalação publicada

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

{
  "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.

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

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

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.

cupom-center

Documentation