Cupom Center

Cupom Center MCP

AI エージェントがクライアントシステムを Cupom Center の REST API に統合するのを支援するローカル MCP サーバーです。

サーバーは stdio 経由でクライアントのコンピューター上で実行されます。AI モデルをホストせず、ネットワークポートも開きません。ローカルホストから MCP 呼び出しを受け取り、プロジェクトの API key を使って https://api.cupom.center にアクセスします。

できること

REST エンドポイントを MCP ツールとして提供するだけでなく、サーバーはエージェントが適切な一連の処理に従えるようにします。

1. クーポンの予約や消費を行わず、利用可能なクーポンを見つける；
2. 割引額を計算し、一時的な quote を予約する；
3. 同じコンテキストで利用を確定する；
4. 外部での確定後にのみ支払いを記録する；
5. 操作を確認して照合する；
6. 金銭を動かしたかのように装うことなく、利用と budgets を元に戻す。

recommend_integration_flow は API を呼び出さず、Cupom Center の利用枠も消費せずにフローを決定します。その他のツールは REST にアクセスするため、レート制限と組織の利用量計測の対象となります。

要件

• 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 を使用します。HTTP は localhost に限り受け付けるため、安全でないリモート接続で認証情報を送信することなく開発できます。

CUPOM_API_TIMEOUT_MS は省略可能で、デフォルトでは 20 秒を使用し、1,000～120,000 ms の値を指定できます。

API key がなくてもサーバーを起動して、ガイドの照会や recommend_integration_flow の実行ができます。REST にアクセスするツールは、CUPOM_API_KEY が設定されるまで設定エラーを返します。

本番環境では、インストーラーがオペレーティングシステムの認証情報保管庫から 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 はクライアントが確定した支払いを記録しますが、金銭の請求や返金は行いません。
• 取り消しは全額を対象とし、利用回数と budgets を解放します。金銭の返金は、引き続きクライアントの決済プロバイダーが担当します。

MCP はクーポン、キャンペーン、組織、メンバー、API key を管理しません。これらの操作は、認証済みのパネルの GraphQL サーフェスで行います。

検証

bun run typecheck
bun run build

このプロジェクトでは、単独のユニットテストは行いません。プロトコルの検証は、コンパイル済みバイナリをMCPクライアントまたはMCP Inspectorに接続して行い、RESTの検証には検証用の環境／プロジェクトを使用してください。