Cupom Center

Cupom Center MCP

本地 MCP 服务，可帮助 AI Agent 将客户端系统集成到 Cupom Center REST API。

该服务通过 stdio 在客户端计算机上运行。它不托管 AI 模型，也不开放网络端口：服务接收本地宿主的 MCP 调用，并使用项目的 API key 访问 https://api.cupom.center。

它的功能

除了将 REST 端点表示为 MCP 工具外，该服务还会引导 Agent 遵循正确的流程：

1. 查找符合条件的优惠券，不预留也不核销；
2. 计算折扣并预留临时 quote；
3. 使用相同的上下文确认兑换；
4. 仅在外部确认后登记付款；
5. 查询并核对操作；
6. 撤销使用次数和预算，不假装已发生资金流转。

recommend_integration_flow 无需调用 API 即可决定流程，也不会消耗 Cupom Center 的配额。其余工具会访问 REST API，并受速率限制和组织用量计量约束。

要求

• Node.js 20 或更高版本；
• 在 Cupom Center 中为正确的项目和环境创建的 API key；
• 与所用工具相匹配的权限。

操作	权限
查找、查询操作	COUPON_READ
创建、查询和撤销单个优惠券代码	COUPON_ISSUE 和 COUPON_READ
Quote、兑换和撤销	COUPON_REDEEM
兑换时或之后付款	PAYMENT_WRITE

组织、环境和项目始终由 API key 决定。MCP 不允许通过参数选择其他租户。

本地开发

cd mcp
bun install
bun run build

已发布版本的安装

发布到 npm 后，请在 MCP 宿主中固定一个版本：

{
  "mcpServers": {
    "cupom-center": {
      "command": "npx",
      "args": ["-y", "@cupom_center/[email protected]"],
      "env": {
        "CUPOM_API_KEY": "cpm_..."
      }
    }
  }
}

发布、npm Trusted Publishing 和 MCP Registry 说明见 PUBLISHING.md。

配置 MCP 宿主，通过绝对路径运行编译后的文件：

{
  "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 为可选项，默认使用 https://api.cupom.center。仅接受用于 localhost 的 HTTP，以方便开发，同时避免在不安全的远程连接中传递凭据。

CUPOM_API_TIMEOUT_MS 为可选项，默认值为 20 秒，接受 1.000 至 120.000 ms 之间的值。

即使未设置 API key，服务也可以启动，以便查询指南和运行 recommend_integration_flow。在设置 CUPOM_API_KEY 之前，访问 REST API 的工具会返回配置错误。

在生产环境中，建议安装程序从操作系统的凭据库中获取 API key。直接在宿主的 JSON 文件中配置虽然简单，但必须防止该文件被未经授权地读取、备份或共享。

工具

• 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

MCP 资源 cupom://integration-guide 包含该服务共用的决策规则。

安全与重试

• 服务绝不会在日志或响应中写入 API key。
• stdout 专用于 MCP 协议；诊断信息使用 stderr。
• 对具有商业影响的请求不会自动重试。
• 超时后，不要更改数据并盲目重试。
• 创建优惠券时使用 Idempotency-Key；重复使用同一密钥必须提交相同的命令。
• 兑换时必须保留购物车、上下文、代码、顺序、策略、quote 和付款信息。
• Cupom Center 会记录客户端确认的付款，但不会扣款或退款。
• 撤销操作会全部撤销并释放使用次数和预算；财务退款仍由客户端的支付提供商负责。

MCP 不负责管理优惠券、活动、组织、成员或 API key。这些操作属于面板中经过身份验证的 GraphQL 接口。

验证

bun run typecheck
bun run build

该项目避免进行孤立的单元测试。协议验证应通过将编译后的二进制文件连接到 MCP 客户端或 MCP Inspector 来完成，REST 验证则应使用验收环境／项目。