Cupom Center

io.github.experiensPublished by GitHub account experiensv0.1.0Updated Nov 5, 2026

Conecta agentes de IA à API REST do Cupom Center com fluxos seguros de cupons.

VerifiedSTDIODesktop onlyDeveloper ToolsBusiness & Commerce

Overview

AI-generated overview

Local MCP server that connects an AI assistant to the Cupom Center REST API to discover, quote, redeem, inspect and reverse coupons.

What you can do
  • Discover eligible coupons and pick coupons for multi-unit carts
  • Quote one or several coupon codes with authoritative totals and a temporary reservation
  • Issue, read and revoke individual codes from ISSUED offers
  • Redeem single or multiple coupons atomically and record externally confirmed payments
  • Inspect operations and receipts, reverse operations, and recommend the right integration flow
When to use it
Useful when building or operating a client integration against Cupom Center and you want the assistant to follow the correct discover, quote, redeem, pay and reverse cycle instead of computing discounts itself. Also handy for reconciling or reversing existing coupon operations.
Requirements
Runs locally over stdio via the npm package, needing Node.js 20 or higher. Requires a Cupom Center API key in CUPOM_API_KEY, created for the right project and environment, with permissions matching the tools used (COUPON_READ, COUPON_ISSUE, COUPON_REDEEM, PAYMENT_WRITE). Network access to the Cupom Center API; CUPOM_API_URL and CUPOM_API_TIMEOUT_MS are optional.
Before you install
The API key grants access to the organization derived from it, so protect the host configuration file or load the key from an OS credential store. Redeem, issuance, payment recording and reversal change commercial state and consume the organization's API allowance; there is no automatic retry, and after a timeout you should not resend altered input. Cupom Center records payments but never charges or refunds money, and reversals do not move funds at the payment provider.

Installation

In SourceWeft

  1. Open Cupom Center in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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çãoPermissão
Descoberta, consulta de operaçãoCOUPON_READ
Emissão, consulta e revogação de código individualCOUPON_ISSUE e COUPON_READ
Quote, resgate e reversãoCOUPON_REDEEM
Pagamento no resgate ou posteriorPAYMENT_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 mcpbun installbun 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/[email protected]"],      "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:

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 typecheckbun 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.

Source: README.md at commit 8367e7d

Tools

13

recommend_integration_flow

Recommend Cupom Center integration flow

Choose the correct Cupom Center workflow before making API calls. This tool is local, has no commercial effect, and consumes no Cupom Center API allowance. Use it whenever it is unclear whether to discover, quote, issue, redeem, record payment, inspect, or reverse.

Parametersbusiness_goalrequiredpayment_confirmedoperation_id_known

find_eligible_coupons

Find eligible coupons

Discover coupons whose configured rules match the known customer/cart context. This does not calculate final totals, reserve budget, or consume a coupon. Missing context intentionally excludes coupons that require that fact. public defaults to true.

Parameterscontextpagination

quote_single_coupon

Calculate and reserve one coupon

Validate a known coupon code against the current cart, calculate authoritative totals, and create a temporary quote reservation. Use before redeeming or displaying a final discount. Do not use for catalog discovery.

Parameterscart_idcontextrequiredcoupon_coderequired

quote_multiple_coupons

Calculate and reserve multiple coupons

Validate and calculate 2–10 known coupon codes. code_order stacks sequentially in supplied order; highest_discount_per_product applies only the best coupon to each product. Every supplied code must be eligible and applied.

Parameterscart_idcontextrequiredselectionrequiredcoupon_codesrequired

select_coupons_for_units

Select coupons per unit

Automatically select public coupons for 1–20 marketplace/store units. Use only when a cart is partitioned into units and the integration wants Cupom Center to choose by coverage or total discount. This is not for validating a known code.

Parametersmoderequiredunitsrequiredcontextprioritymax_coupons_per_unit

create_coupon_issuance

Issue an individual coupon code

Create an individual code from an existing coupon configured with ISSUED distribution, typically for cart recovery, CRM, or individualized delivery. This never creates discount rules. Requires COUPON_ISSUE and a stable idempotency key.

Parameterscartrequiredsubjectrequiredmetadatashippingcoupon_idrequiredvalid_untilidempotency_keyrequiredexternal_referencerequired

get_coupon_issuance

Get coupon issuance

Read the current state and immutable commercial details of an individual issued code.

Parametersissuance_idrequired

revoke_coupon_issuance

Revoke coupon issuance

Revoke one active individual issuance. This is idempotent but cannot reactivate a consumed or expired code. Use only when the individual code must no longer be accepted.

Parametersissuance_idrequired

redeem_single_coupon

Redeem one coupon

Confirm one coupon as a commercial operation. Normally call after quote_single_coupon and send the same cart/context. Provide cart_id, context.user.id, or quote_id for correlation. Include payment only after external confirmation; Cupom Center does not charge money.

Parameterscart_idcontextrequiredpaymentorder_idquote_idcoupon_coderequired

redeem_multiple_coupons

Redeem multiple coupons

Atomically confirm 2–10 coupons previously calculated together. Preserve code order and selection strategy from the quote. Either all applicable uses/budgets confirm or none do.

Parameterscart_idcontextrequiredpaymentorder_idquote_idselectionrequiredcoupon_codesrequired

get_coupon_operation

Get coupon operation

Inspect a redemption operation, immutable receipts, current payment, and reversals. Use for reconciliation and as the first recovery step after a timeout when operation_id is known.

Parametersoperation_idrequired

record_operation_payment

Record confirmed operation payment

Record an integral payment that an external payment provider has already confirmed. This does not charge or capture money and does not consume coupons again. Requires PAYMENT_WRITE.

Parameterspaymentrequiredoperation_idrequired

reverse_operation

Cancel or refund a coupon operation

Fully reverse one coupon operation and release its usage counters and budgets. The backend classifies it as cancellation without payment or refund with confirmed payment. This does not move money at the payment provider and accepts no reason or partial amount.

Parametersoperation_idrequired

Version history

1
  1. v0.1.0LatestNov 4, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts