mcpField
S
setup-polar

setup-polar

github.com/polarsource開発6169 回インストール3 日前に更新
リポジトリ

setup-polar について

setup-polarは、プロジェクトでPolar決済を設定するためのガイドスキルです。MCPの設定や商品作成からWebhookとチェックアウトのテストまで案内し、連携コードの生成は`polar-integration`に引き継ぎます。

主な機能

  1. 01Polar MCPの確認とインストール
  2. 02フレームワークと決済要件の収集
  3. 03組織とテスト商品の作成
  4. 04Webhook転送とシークレットの設定
  5. 05チェックアウトとWebhook処理のテスト

活用シーン

  1. 01Polarのサンドボックス決済フローの構築
  2. 02本番決済に向けたプロジェクトの準備

MCP 対応

Polar MCPで組織の確認や商品の作成を行い、デプロイ用Webhookエンドポイントの設定にも利用できます。サーバーのインストールと認証方法も案内します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/polarsource/skills --skill setup-polar

インストール後、Claude Code で/setup-polarを入力して読み込まれたか確認します。

詳細

Polar セットアップウィザード

プロジェクトで Polar の決済を利用するための対話型セットアップガイドです。

セットアップの流れ

次の手順を順番に進めてください。

Step 1: MCP の利用可否を確認する

まず、Polar MCP サーバーが利用可能かどうかを確認します。MCP ツールを使って、商品または組織の一覧を取得してみてください。

MCP ツールが使える場合： Step 3 に進みます。

MCP が利用できない場合： Step 2 に進みます。

Step 2: Polar MCP をインストールする

ユーザーの環境に応じて、Polar MCP サーバーのインストールを案内します。

Claude Code：

# Production
claude mcp add --transport http "Polar" "https://mcp.polar.sh/mcp/polar-mcp"

# Sandbox (recommended for setup)
claude mcp add --transport http "Polar Sandbox" "https://mcp.polar.sh/mcp/polar-sandbox"

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "Polar Sandbox": {
      "url": "https://mcp.polar.sh/mcp/polar-sandbox"
    }
  }
}

インストール後、ユーザーに次の操作を依頼します。

  1. エディターまたは CLI を再起動する
  2. 認証を求められたら認証する（polar.sh にリダイレクトされます）

認証後、組織の一覧を取得して MCP が動作することを確認します。

Step 3: プロジェクトのコンテキストを確認する

ユーザーに次のことを尋ねます。

  1. フレームワーク：どのフレームワークを使用していますか？

    • Next.js（App Router）
    • Next.js（Pages Router）
    • Express.js
    • FastAPI（Python）
    • その他

  2. 環境：サンドボックスと本番環境のどちらから始めますか？

    • サンドボックス（新規セットアップにおすすめ）
    • 本番環境

  3. 商品タイプ：何を販売しますか？

    • サブスクリプション（定期購入）
    • 買い切り商品
    • 両方
Step 4: 組織を作成する（必要な場合）

MCP を使って、ユーザーが組織を持っているか確認します。組織がない場合は、次のページで作成するよう案内します。

Step 5: 最初の商品を作成する

MCP を使ってテスト商品を作成します。サブスクリプションの場合の例：

Create a product with:
- Name: "Pro Plan"
- Monthly price: $29
- Organization: [user's org]

返された商品 ID を保存し、チェックアウトの連携に使用します。

Step 6: 連携コードを生成する

polar-integration スキルに引き継ぎ、Step 3 で選択したフレームワーク用の Checkout、Customer Portal、Webhooks エンドポイントを生成します。このスキルには、フレームワークに依存しない標準的なレシピと、フレームワークごとのバリエーションが用意されています。

実行する前に、ユーザーが次の環境変数を用意していることを確認してください（フレームワークが提供する任意のローダーを使用します）。

POLAR_ACCESS_TOKEN=    # from polar.sh/settings (or sandbox)
POLAR_WEBHOOK_SECRET=  # created in Step 7
POLAR_SERVER=sandbox   # omit or set to "production" when going live

Step 5 の商品 ID を渡し、Step 8 でチェックアウトリンクをテストできるようにします。

Step 7: Webhook をセットアップする

Polar CLI を使って、ローカルの開発サーバーに Webhook を転送します。トンネルやダッシュボードのエンドポイントは必要ありません。詳細は polar-testing スキルの「ローカルでの Webhook テスト」を参照してください。

  1. CLI をインストールし（curl -fsSL https://polar.sh/install.sh | bash）、ブラウザーを開く polar auth login --sandbox を実行するようユーザーに依頼します。
  2. ローカルの署名シークレットを出力せずに保存し、開発サーバーを再起動します。 
    secret=$(polar listen --print-secret) && echo "POLAR_WEBHOOK_SECRET=$secret" >> .env
  3. Step 6 で生成したルートのパスを使い、polar listen <port>/<webhook-path> をバックグラウンドで起動して、実行したままにします。
  4. polar trigger order.paid を実行します。ハンドラーの応答が出力され、ハンドラーが失敗した場合は終了ステータス 1 で終了します。ハンドラーを修正し、終了ステータス 0 で終了するまで繰り返します。

デプロイ時は、MCP またはダッシュボード（Settings → Webhooks）で公開 URL 用の Webhook エンドポイントを作成し、order.paid、subscription.created、subscription.canceled を選択します。デプロイ環境では、そのエンドポイントのシークレットを POLAR_WEBHOOK_SECRET として設定します。

Step 8: 連携をテストする
  1. 開発サーバーを起動します。
  2. Step 5 の商品 ID を含むチェックアウト URL にアクセスします（パスとクエリの形式は Step 6 で生成したルートに従います）。
  3. テストカード 4242 4242 4242 4242 を使ってチェックアウトを完了します。
  4. polar listen に order.paid が表示され、ハンドラーから 2xx ステータスが返されることを確認します。
  5. 成功ページが正しく表示されることを確認します。
Step 9: 次のステップ

基本的なセットアップが動作したら、次の項目を提案します。

  1. カスタマーポータルを追加する - ユーザーがサブスクリプションを管理できるようにします（polar-integration の Recipe 2）。
  2. 認証と連携する - チェックアウトで externalCustomerId を渡します。
  3. 特典を追加する - ライセンスキー、ファイルのダウンロード、Discord のロールなど。
  4. 本番環境に移行する - POLAR_SERVER を sandbox から production に切り替えます。

コメント

Markdown 対応