Cupom Center

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.

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.