mcpField
S
setup-polar

setup-polar

github.com/polarsource开发6177 次安装3 天前更新
代码仓库

关于 setup-polar

这是一份为开发者提供的交互式指南，用于在应用中配置 Polar 支付。它依次介绍 MCP 检查、组织与产品选择、凭据和集成代码配置、Webhook 测试，以及从 sandbox 迁移到生产环境。

主要功能

  1. 01检查并配置 Polar MCP
  2. 02收集框架与支付需求
  3. 03选择组织并创建产品
  4. 04准备令牌和集成代码
  5. 05配置并测试 Webhook
  6. 06将配置从 sandbox 转至生产环境

适用场景

  1. 01在新项目中配置 Polar 支付
  2. 02创建 sandbox 产品和结账流程
  3. 03设置本地 Webhook 测试
  4. 04为生产环境准备经过测试的集成

MCP 相关

指南会检查 Polar MCP 服务，并说明如何安装和认证生产或 sandbox 服务。它通过 MCP 列出组织、创建产品，也可配置部署环境的 Webhook 端点。

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/setup-polar确认已加载。

详细介绍

Polar 设置向导

交互式设置指南，帮助你在项目中启用 Polar 付款功能。

设置流程

按顺序完成以下步骤：

步骤 1：检查 MCP 是否可用

首先，通过列出组织来检查 Polar MCP 服务是否可用：调用 execute 执行 GET /v1/organizations/，或者在服务为每项操作单独提供一个工具时，调用 organizations_list。

如果 MCP 工具可用： 跳到步骤 3。

如果 MCP 不可用： 继续步骤 2。

步骤 2：安装 Polar MCP

已安装 Polar 插件： 该插件已配置 Polar 服务（polar，以及可用时的 polar-sandbox）。请让用户登录该服务，优先选择 polar-sandbox：在 Claude Code 中使用 /mcp，在 Codex 中使用 codex mcp login <server>，在 Cursor 或 Antigravity 中通过 MCP 设置登录，在 Gemini CLI 中使用 /mcp auth <server>，在 ChatGPT 中则在提示连接时登录。然后继续执行以下验证。

否则，请根据用户的环境，引导其安装 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"
    }
  }
}

对于其他客户端，请参阅 Polar MCP 指南。安装后，用户需重启编辑器或命令行，并在出现提示时登录（在 Claude Code 中，运行 /mcp 并完成身份验证）。沙盒服务的登录地址为 sandbox.polar.sh，生产服务的登录地址为 polar.sh。

完成身份验证后，通过列出组织来验证 MCP 是否可用。

步骤 3：收集项目背景信息

询问用户：

  1. 框架：你使用的是什么框架？

    • Next.js（App Router）、Express、Hono、Astro、SvelteKit、Remix、TanStack Start、Nuxt、Fastify、Cloudflare Workers，或其他 TypeScript/JavaScript 框架
    • Python：目前没有集成技能；请参阅 Python SDK 文档

  2. 环境：从沙盒还是生产环境开始？

    • 沙盒（新设置推荐）
    • 生产环境

  3. 产品类型：你要销售什么？

    • 订阅（定期付款）
    • 一次性购买
    • 两者都有

从此处开始，沙盒环境使用 polar-sandbox 服务的工具，生产环境使用 polar 服务的工具。如果只有 polar 可用（例如在 ChatGPT 中），则通过沙盒控制面板或 Polar CLI 创建沙盒产品。

步骤 4：选择组织

通过 MCP 列出组织。如果有多个组织，询问用户要使用哪一个。记下其 id、slug 和 default_presentment_currency。登录 MCP 服务时，如果用户尚未加入组织，系统已会要求其创建组织；如果没有 MCP，用户可以在以下地址创建组织：

步骤 5：创建首个产品

通过 MCP 创建产品（POST /v1/products/）。价格必须使用组织的 default_presentment_currency，且每个产品的计费周期固定。以下是月度订阅示例：

{
  "organization_id": "<organization id from Step 4>",
  "name": "Pro Plan",
  "recurring_interval": "month",
  "prices": [{ "amount_type": "fixed", "price_amount": 2900, "price_currency": "<default_presentment_currency>" }]
}

一次性购买时省略 recurring_interval。“两者都有”或同时提供月度和年度计费，意味着需要创建不同的产品。向用户展示服务、组织、名称、价格、货币和周期，并在用户确认后创建产品。

保存返回的产品 ID，以便集成结账功能。

步骤 6：生成集成代码

交由 polar-integration 技能为步骤 3 中选择的框架生成 Checkout、Customer Portal 和 Webhooks 端点。该技能包含规范的、与框架无关的方案，以及各框架对应的变体。

调用该技能前，请确保用户已准备好以下环境变量（使用其框架提供的任意加载器）：

POLAR_ACCESS_TOKEN=          # organization access token, created below
POLAR_WEBHOOK_SECRET=        # created in Step 7
POLAR_ENVIRONMENT=sandbox    # omit or set to "production" when going live

创建访问令牌最快的方法是使用 Polar CLI。使用 npm install -g @polar-sh/cli 安装，然后让用户运行：

polar auth login --sandbox
token=$(polar auth token --scope checkouts:write --scope customer_sessions:write) && echo "POLAR_ACCESS_TOKEN=$token" >> .env

polar auth token 会在浏览器中打开令牌页面，并预先选中相应的权限范围；随后等待用户创建令牌并将其打印出来，因此它会将令牌保存到 .env，而不会显示出来。令牌属于当前激活的组织及其环境：polar auth whoami --json 会显示当前组织和环境，polar auth org 可以更改它们。

如果不使用 CLI，请在沙盒或生产环境的控制面板中创建令牌：Settings → Access Tokens → Create token。

传递步骤 5 中的产品 ID，以便在步骤 8 中测试结账链接。

步骤 7：设置 Webhooks

启动开发服务器，然后按照 polar-testing 中的“本地 Webhook 测试”说明，使用 Polar CLI 将 Webhooks 转发到该服务器。无需隧道或控制面板端点：

  1. 如果步骤 6 中跳过了此步骤，请安装 CLI 并让用户运行 polar auth login --sandbox，这会打开浏览器。
  2. 使用 polar webhook listen --print-secret 将本地签名密钥保存到 .env，然后重启开发服务器。
  3. 在后台运行 polar webhook listen <port>/<webhook-path>，使用步骤 6 中生成的路由路径。如果账号有多个组织，请传入 --org <id from Step 4>。
  4. 运行 polar webhook trigger order.paid。成功时，退出代码为 0，并显示一行 Response 2xx。如果失败，它会打印处理程序的响应，并以状态码 1 退出；修复处理程序后重试。如果它只提示事件已由 polar webhook listen 终端转发，请检查 listen 输出。

部署时，请在控制面板中为公开 URL 创建 Webhook 端点（Settings → Webhooks），或通过 MCP 创建（设置 url、format: "raw"，以及 events：order.paid、subscription.created 和 subscription.canceled）。在已部署环境中，将该端点的密钥设为 POLAR_WEBHOOK_SECRET。MCP 响应中包含该密钥，因此请告知用户在哪里复制它，不要重复提供密钥。

步骤 8：测试集成
  1. 使用步骤 5 中的产品 ID 访问结账 URL（路径和查询参数格式取决于步骤 6 中生成的路由）。
  2. 使用测试卡完成结账：4242 4242 4242 4242。
  3. 确认 polar webhook listen 显示 order.paid，且处理程序返回 2xx 状态码。
  4. 检查成功页面是否正确显示。
步骤 9：后续步骤

基本设置完成后，建议：

  1. 关联身份验证 - 创建结账时，传入已登录用户的 external_customer_id。
  2. 添加权益 - 许可证密钥、文件下载、Discord 角色。
  3. 转入生产环境 - 生产环境与沙盒相互独立：在 polar.sh 设置组织，重新创建产品（它会获得新的 ID），创建生产访问令牌和 Webhook 端点，并设置 POLAR_ENVIRONMENT=production。然后在控制面板中提交组织以供审核；在组织可以接受付款之前，结账会被阻止。

评论

支持 Markdown