mcpField
S
setup-polar

setup-polar

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

关于 setup-polar

setup-polar 是用于在项目中配置 Polar 收款的引导技能，涵盖 MCP 设置、创建产品以及测试 Webhook 和结账流程。它会收集框架和产品需求，并将集成代码生成交给 `polar-integration`。

主要功能

  1. 01检查并安装 Polar MCP
  2. 02收集框架与支付需求
  3. 03创建组织和测试产品
  4. 04配置 Webhook 转发与密钥
  5. 05测试结账和 Webhook 处理

适用场景

  1. 01搭建 Polar 沙盒支付流程
  2. 02为项目准备生产环境收款

MCP 相关

使用 Polar MCP 检查组织、创建产品，并可配置部署用的 Webhook 端点；还提供安装服务和身份验证的说明。

安装

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

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

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

详细介绍

Polar 设置向导

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

设置流程

请按顺序执行以下步骤：

步骤 1：检查 MCP 是否可用

首先，检查 Polar MCP 服务是否可用。尝试使用 MCP 工具列出产品或组织。

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

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

步骤 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 是否正常工作。

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

询问用户：

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

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

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

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

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

    • 订阅（定期付款）
    • 一次性购买
    • 两者皆有
步骤 4：创建组织（如有需要）

使用 MCP 检查用户是否已有组织。如果没有，引导他们前往以下地址创建：

步骤 5：创建首个产品

使用 MCP 创建一个测试产品。订阅产品示例：

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

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

步骤 6：生成集成代码

交由 polar-integration 技能为步骤 3 中选择的框架生成结账、客户门户和 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

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

步骤 7：设置 Webhooks

使用 Polar CLI 将 Webhooks 转发到本地开发服务器。无需隧道，也无需在控制面板中设置端点。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. 在后台启动 polar listen <port>/<webhook-path>，其中路径使用步骤 6 生成的路由路径，并保持运行。
  4. 运行 polar trigger order.paid。该命令会打印处理程序的响应；处理程序失败时，退出状态为 1。修复处理程序并重复操作，直到退出状态为 0。

部署时，使用 MCP 或在控制面板中（Settings → Webhooks）为公网 URL 创建 Webhook 端点，选择 order.paid、subscription.created 和 subscription.canceled，并在部署环境中将该端点的密钥用作 POLAR_WEBHOOK_SECRET。

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

基本设置正常运行后，建议：

  1. 添加客户门户——让用户管理订阅（polar-integration 中的方案 2）。
  2. 关联你的身份验证系统——在结账时传入 externalCustomerId。
  3. 添加权益——许可证密钥、文件下载、Discord 角色。
  4. 切换到生产环境——将 POLAR_SERVER 从 sandbox 改为 production。

评论

支持 Markdown