GrowSurf

GrowSurf MCP 服务

这是 官方 GrowSurf 命令行界面（CLI）和开源 Model Context Protocol（MCP）服务，通过引导步骤和安全的 REST API 封装，实现 GrowSurf 推荐和联盟计划。

将其连接到 AI Agent 后，Agent 便能通过自然语言创建推荐或联盟计划、配置奖励、安装跟踪功能、添加和管理参与者，以及读取分析数据，所有操作均由 GrowSurf REST API 提供支持。

MCP 是可选的。任何能够发送 HTTPS 请求并执行操作的 Agent，都可以先使用 GrowSurf 与客户端无关的 REST 工作流：https://growsurf.com/agent-start.md。

• 了解更多关于 GrowSurf 的信息：https://growsurf.com
• 从直接使用 REST 开始：https://growsurf.com/agent-start.md
• 阅读 OpenAPI 契约：https://growsurf.com/openapi.json
• 阅读 Arazzo 工作流：https://growsurf.com/arazzo.yaml
• 了解可选的 MCP 设置：https://docs.growsurf.com/build-with-ai#optional-connect-mcp

适用对象

此 MCP 服务适用于：

• 使用兼容 MCP 的工具的开发者（Claude Code、Codex、Cursor、Copilot 及其他 MCP 客户端）
• 希望通过引导式 AI 辅助集成 GrowSurf 的团队

此 MCP 服务不适用于：

• 希望在浏览器中使用本地 stdio 安装的用户。ChatGPT 网页版和 Claude.ai 使用托管的远程连接器 https://mcp.growsurf.com。Claude Desktop 可以使用本地 stdio 服务，也可以使用托管连接器。完整的客户端列表和设置说明请参阅 https://docs.growsurf.com/build-with-ai#optional-connect-mcp。

你将获得

• 引导式集成：
  • Universal Code 安装
  • 原生 iOS/Android 和 React Native SDK 实现指南
  • 原生 GrowSurf Window 指南
  • 注册流程
  • 符合条件的操作流程
  • 联盟销售 / 交易跟踪
  • Webhook
• Agent 配方：
  • MCP 提示词，用于创建推荐计划、创建联盟计划、提供计划设计建议、排查推荐跟踪问题、嵌入小组件、列出和获取计划及参与者、配置奖励、接入 Webhook 和读取分析数据
  • 提示词会使用对话中的详细信息，并且只询问下一步所需的缺失信息。无需填写表单。现有提示词名称和直接参数仍受支持。
  • 可安装的 Agent Skill 软件包，位于 skills/growsurf-agent-toolkit
  • 指引 Agent 在修改前检查入门版 Design、Emails、Options、Installation、奖励和 GrowSurf Window 内容
  • 一次性计划创建评估提示词，以及用于检查入门内容和配置的验收标准
• Happy‑Path REST API 封装：
  • 无需现有凭据即可创建账户并获取 API 密钥
  • 读取和重命名已绑定的团队、申请团队验证，以及重新发送团队所有者的验证邮件
  • 列出和获取营销活动
  • 获取营销活动分析数据（总计、时间序列、电子邮件指标、参与者互动活动和激活群组）
  • 创建、更新和克隆计划（营销活动）
  • 列出、创建、更新和删除营销活动奖励
  • 列出、创建、更新和删除计划资源，包括安全的一次性 FILE 准备流程
  • 获取 / 更新 Design、Emails、Options 和 Installation 配置
  • 捕获临时 GrowSurf 预览截图，让用户查看计划草稿
  • 列出、创建、更新、删除和测试计划 Webhook
  • 列出、获取和添加参与者
  • 更新参与者信息、向参与者发送电子邮件，以及获取参与者的分析数据和活动日志
  • 触发推荐积分（适用于推荐计划），可选择延迟发放（1–90 天）
  • 取消待处理的延迟推荐触发（适用于推荐计划）
  • 记录联盟销售 / 交易（适用于联盟计划）
  • 为已登录的原生应用用户创建移动参与者令牌
• 官方 API 库代码片段：
  • TypeScript
  • Python
  • PHP
  • Ruby
  • Java
• 辅助工具：
  • 计算参与者自动身份验证 HMAC 哈希
  • 规范化 Webhook 负载
  • 生成尽力而为的幂等键，用于 Webhook 去重

选择工具

使用 program 和 participant 工具读取或更改记录。指导工具会提供建议或代码，供你应用：

任务	工具
选择 program 设计和奖励结构	growsurf_program_design_advisor
规划 Web 集成	growsurf_integration_guide
获取浏览器 JavaScript 示例	growsurf_client_snippets
获取一个可嵌入元素的 HTML	growsurf_embeddable_element_snippet
生成页面级 participant 自动身份验证代码	growsurf_grsf_config_snippet
获取后端 REST API 库示例	growsurf_api_library_snippets
集成原生 iOS、Android 或 React Native 应用	growsurf_mobile_sdk_guide
诊断 program 问题	growsurf_troubleshoot_referral_tracking
为 Agent 的 program 创建工作流生成检查项	growsurf_agent_program_creation_eval

已发布的工具名称和字段使用 campaign 表示 program，包括 campaignId。这些标识符仍受支持。显示标题使用 program 术语；Campaign Reward 仍是奖励配置的名称。

要删除一位 participant，请在 growsurf_bulk_delete_participants 的 participants 中传入一个 ID 或电子邮件地址。同样适用永久删除警告。不需要单独的单 participant 工具。program 删除和显式奖励发放不属于这套 MCP 工具；完成 program 不等于删除，配置奖励也不能证明奖励已发放。

可选的精简连接

默认连接会列出全部 63 个工具。添加 --compact，即可选择 32 个用于 program 设置、安装、participant 管理、推荐跟踪、奖励和分析的工具。凭证权限可能会进一步缩减可见工具集。

npx -y @growsurfteam/growsurf-mcp --compact

在 stdio 客户端配置中，将 "--compact" 添加到软件包的 args 数组中。服务集成可以调用 createGrowSurfMcpServer({ toolSurface: "compact" })。省略此选项即可保留完整目录。

精简模式会合并相关的指导和设置工具：

工具	选择项	参数
growsurf_get_guidance	topic：integration、browser、api_libraries、mobile_sdk、embeddable_element、participant_auto_auth 或 program_creation_checks	将所选指南的现有参数放在 input 下。使用 {} 表示默认值。
growsurf_get_program_settings	section：design、emails、options 或 installation	将 campaignId 放在 input 下，或使用已配置的默认值。
growsurf_update_program_settings	相同的 section 值	将 campaignId 和 fields 补丁放在 input 下。请先读取该部分。

例如，读取 program 的安装设置：

{
  "name": "growsurf_get_program_settings",
  "arguments": { "section": "installation", "input": { "campaignId": "YOUR_PROGRAM_ID" } }
}

program 建议和故障排查仍使用各自的工具。participant 读取、更新和删除，以及推荐操作、销售或退款操作仍保持独立。精简模式下的提示词、资源、指导和建议配置调用使用精简工具名称和参数。

以下操作请使用完整连接：创建账户、团队管理、克隆 program、participant 资源、创建／更新／删除／测试 webhook、participant 电子邮件、付款目的地，以及 webhook 规范化。移除 --compact 并重新连接。这些操作在完整连接中仍可使用原有契约；精简模式会拒绝调用目录之外的工具。上方的工具选择表描述的是完整连接。

要求

• Node.js 22+
• 用于托管 OAuth 的 GrowSurf 账户
• 用于本地 stdio 设置或手动 API 密钥远程设置的 GrowSurf API 密钥。只要作用域密钥有权访问你希望 Agent 使用的工具和计划，就可以使用。
• 用于需要指定计划的工具的活动（计划）ID。将 GROWSURF_CAMPAIGN_ID 设为默认值，传入 campaignId 参数以指定某个计划，或调用 growsurf_list_campaigns 查找可用计划。对于新创建的计划，将 growsurf_create_campaign 返回的 id 传给其他工具。
• 静态指导/代码片段工具无需凭据即可运行
• 例外：growsurf_create_account 不需要 API 密钥。仅当获授权的所有者批准创建账户并接受 GrowSurf 的服务条款和隐私政策后，才能调用此工具。账户会自动开始为期 14 天的 Business 试用，无需信用卡，并且只返回一次 API 密钥。密钥丢失后无法通过 API 找回，因此只有在你能将密钥存储到当前对话结束之后时才使用此工具；否则，请让所有者连接 https://mcp.growsurf.com 并登录。在进行受保护的调用前，请先等待所有者完成电子邮件验证。未经验证的账户会在 7 天后删除。团队级工具无需计划 ID。
• 所有列出的工具都会发布标准 MCP 安全提示，包括只读、破坏性、幂等和开放世界提示。作用域内的业务操作仍可使用；API 密钥轮换有意不作为 MCP 工具提供。请在 GrowSurf Settings 中轮换密钥，或通过直接 REST/SDK 客户端轮换。

官方 CLI

npm 包会安装 growsurf-mcp 命令。无需全局安装即可运行：

npx -y @growsurfteam/growsurf-mcp

CLI 会启动 GrowSurf 本地 stdio MCP 服务。为基于 API 的操作设置 GROWSURF_API_KEY，并为默认计划设置 GROWSURF_CAMPAIGN_ID。公共开发者资源和静态集成指南无需凭据即可使用。

查看已安装的命令，但不启动 stdio 服务：

npx -y @growsurfteam/growsurf-mcp --help
npx -y @growsurfteam/growsurf-mcp --version

支持的 MCP 主机

对于兼容 MCP 的主机，如果其支持带 OAuth 的远程 Streamable HTTP，请使用 GrowSurf 托管的 OAuth 端点 https://mcp.growsurf.com。如果主机需要 stdio 进程或手动设置 API 密钥，请使用本地 npx 服务。还没有 GrowSurf 账户？经所有者批准后，Agent 可以在无需凭据的情况下连接到 https://mcp.growsurf.com/onboard 并调用 growsurf_create_account。

GrowSurf MCP 服务适用于任何兼容 MCP 的主机。以下示例涵盖了几种基于配置和 CLI 的主机。如需查看受支持客户端的完整最新列表（包括 ChatGPT 网页版、Claude.ai、Claude Desktop、GitHub Copilot、Gemini CLI、Devin Desktop 和 Cline）以及分步设置说明，请参阅 https://docs.growsurf.com/build-with-ai#optional-connect-mcp。

• Cursor
• Claude Code（基于 CLI）
• Antigravity
• Codex（基于 CLI）

Cursor

1. 打开或创建 Cursor 的全局 MCP 配置文件 ~/.cursor/mcp.json。
2. 添加一个名为 growsurf 的服务，并使用托管 OAuth 端点：

{
  "mcpServers": {
    "growsurf": {
      "type": "http",
      "url": "https://mcp.growsurf.com"
    }
  }
}

若要改用本地 stdio，请使用：

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Claude Code（基于 CLI）

打开终端，将 Claude Code 连接到托管 OAuth 端点：

claude mcp add --transport http --scope user growsurf https://mcp.growsurf.com
claude mcp login growsurf

若要改用本地 stdio，请将服务直接安装到 Claude Code 中：

claude mcp add growsurf \
  -e GROWSURF_API_KEY=your_api_key \
  -e GROWSURF_CAMPAIGN_ID=your_campaign_id \
  -- npx -y @growsurfteam/growsurf-mcp

Antigravity

1. 打开 Antigravity。
2. 点击右侧面板中的 … 菜单，然后选择 MCP Servers。
3. 点击 Manage MCP Servers > View raw config。
4. 建议：在 mcp_config.json 文件中添加托管 OAuth 端点：

{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com"
    }
  }
}

5. 保存配置，打开 Settings > Customizations，然后为 GrowSurf 选择 Authenticate。

若要改用本地 stdio，请使用：

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Codex

建议：将 Codex 连接到托管 OAuth 端点：

codex mcp add growsurf --url https://mcp.growsurf.com
codex mcp login growsurf

或者创建或编辑 ~/.codex/config.toml：

[mcp_servers.growsurf]
url = "https://mcp.growsurf.com"

若要改用本地 stdio，请添加以下内容：

[mcp_servers.growsurf]
command = "npx"
args = ["-y", "@growsurfteam/growsurf-mcp"]

[mcp_servers.growsurf.env]
GROWSURF_API_KEY = "YOUR_API_KEY"
GROWSURF_CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"

或者通过 CLI 配置本地 stdio：

codex mcp add growsurf \
  --env GROWSURF_API_KEY=YOUR_API_KEY \
  --env GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID \
  -- npx -y @growsurfteam/growsurf-mcp

配置

运行 MCP 服务时，请设置以下环境变量：

• GROWSURF_API_KEY（启动时可选；调用 API 的工具必须设置。请使用具备这些工具所需权限范围和程序访问权限的密钥）
• GROWSURF_CAMPAIGN_ID（可选；作为适用于特定活动的工具的默认程序。工具的 campaignId 参数会覆盖此值，因此单个服务可以操作你的任意程序）
• GROWSURF_API_BASE_URL（可选；默认为 https://api.growsurf.com/v2。适用于需要调用其他 GrowSurf API 源站的本地或托管 MCP 网关）
• GROWSURF_UPLOAD_ALLOWED_ORIGINS（仅 FILE Resource 上传时必需；用逗号分隔的私有允许列表，其中列出 GrowSurf 上传凭证中接受的 HTTPS 源站。拒绝通配符和 URL 路径）

哈希辅助工具需要显式传入 participantAuthSecret 参数，且绝不会使用 GROWSURF_PARTICIPANT_AUTH_SECRET。MCP 示例中请使用测试密钥；在后端对用户进行身份验证，并使用生产密钥进行签名。

对于 Webhook，请配置签名 secret，并在后端验证 GrowSurf-Signature。不再使用 GROWSURF_WEBHOOK_TOKEN；请勿将密钥放在 Webhook URL 中。

使用 npx 运行

发布此软件包后，用户可以运行：

npx @growsurfteam/growsurf-mcp

在此仓库中进行本地开发：

npm install
npm run build
node dist/cli.js

MCP 工具

每个工具都会声明 MCP 输出架构并返回 structuredContent，以便宿主了解各工具的结果结构。REST 工具会返回 API 响应（并为较旧的客户端附带一个 JSON 文本块）；指导和代码片段工具会在 markdown 下返回其 Markdown 文档。

程序、奖励配置、选项和参与者读取结果也会在 structuredContent 中包含 rewardEvidence 对象。该对象记录此响应能够证明的审批政策和自动履约标记信息。若没有相关履约记录，交付状态仍属未知。此评估仅适用于当前响应；请结合其他证据。API 字段和原始 JSON 文本保持不变。

集成指南

• growsurf_integration_guide 提供分步指导，帮助实现 GrowSurf 推荐或联盟计划。

• growsurf_mobile_sdk_guide 提供原生 iOS/Android 或 React Native SDK 的指导，涵盖归因、shareUrl、trackShare 和原生 GrowSurf Window。使用 React Native SDK 时，将 platform 设为 react_native。

• growsurf_api_library_snippets 提供 TypeScript、Python、PHP、Ruby 和 Java 的官方 REST API 库代码片段。

• growsurf_list_integrations 列出该程序可以连接的所有集成，并提供每项集成的 connected、enabled、autoDisabled 和仪表板 connectUrl。操作某项集成前，请先检查此列表。

• growsurf_get_integration_connect_link 获取打开特定集成连接面板的仪表板链接（包括 Stripe、PayPal、Tango Card、Mailchimp 等）。用户想连接某项集成时，将链接提供给他们。系统会先检查程序，结果还会报告该集成是否已连接。连接操作在仪表板中进行，而非通过 API。

方案设计与问题排查

• growsurf_program_design_advisor 默认返回简短的初稿。设置 detail: "full" 可获取完整报告，其中包含奖励、分享和集成数据。benchmarkFacts 包含完整的说明，列出每项比率的单位、中位数、四分位数、样本和来源。引用这些说明时请一并引用，避免将推荐比率误认为推荐人数的百分比。

  推荐符合条件的操作、奖励结构、发放路径、安全措施、分享渠道和集成方案。结果包含 markdown、含精确工具参数的 configurationPlan，以及包含符合条件的操作和待客户决定事项的 decisions。请在提出奖励方案前调用此工具。保留返回的调用格式；顾问工具和计划创建工具使用不同的 goal 枚举值。将每个 <new-program-id> 替换为计划创建返回的 id。在客户做出选择之前，草案不会确定奖励金额和佣金条款；预算是上限，而非激励。对于演示或协商签约，将 salesMotion 设为 sales_led；对于直接购买，则设为 self_service。当主机提供数据洞察时，建议会包含汇总数据；没有数据洞察时，则会依据文档。非 USD 的建议和预算对比会省略美元奖励区间，因为数据混用了不同货币。

• growsurf_troubleshoot_referral_tracking 按症状优先进行诊断：推荐未计入、参与者邮件未发送、奖励未发放、参与者未添加、未检测到 Universal Code、集成未同步、Zapier 错误、欺诈标记、仪表板数字异常等。按顺序返回要执行的检查（以及每项检查对应的读取工具和字段）、最常见的可能原因、修复方法和文档链接。传入 symptom 键，或传入包含症状名称的 description。

客户端与 UI 代码片段

• growsurf_client_snippets JavaScript SDK、GrowSurf Window 和可嵌入示例。还会提醒你在放置或设置可嵌入 UI 样式时使用前端设计工作流。

• growsurf_embeddable_element_snippet 特定 GrowSurf 可嵌入元素的 HTML 代码片段。

• growsurf_grsf_config_snippet 用于配置 window.grsfConfig 和参与者自动身份验证的 <head> 代码片段。

账户入门

• growsurf_create_account 创建 GrowSurf 账户并获取 API 密钥。这是唯一不需要 GROWSURF_API_KEY 的工具。返回的密钥只显示一次；在所有者验证邮箱之前，密钥会被锁定（403 EMAIL_NOT_VERIFIED_ERROR）；完成验证后，同一密钥即可解锁，因此请妥善保存并重试。只有在所有者首次登录仪表板时，密钥才会被替换。创建账户即代表账户持有人同意 GrowSurf 的服务条款和隐私政策。

团队

• growsurf_get_team 获取与 API 密钥或 OAuth 连接绑定的团队，包括其 GrowSurf 验证状态。

• growsurf_update_team 更新绑定团队的显示名称。

• growsurf_request_team_verification 请求 GrowSurf 验证绑定的团队。计划向参与者发送邮件前必须完成此验证。

• growsurf_resend_team_owner_verification_email 向绑定团队的所有者重新发送验证邮件，但不会透露其邮箱地址。

API 与跟踪

• growsurf_get_campaign 获取计划配置。

• growsurf_list_campaigns 列出凭据可用的计划。调用计划范围内的工具之前，可使用此工具查找 campaignId。

• growsurf_get_campaign_analytics 获取计划分析数据，可选包含每个周期的 series、对比、状态、比率、通过 include=email 获取的邮件指标，以及通过 include=engagement 获取的参与者活动周期互动数据。

• growsurf_get_campaign_activation_analytics 获取符合条件的参与者激活群组，并使用固定的 7 天或 30 天观察窗口。推荐计划按 enrolledAsAdvocateAt 分组，联盟计划按 approvedAsAffiliateAt 分组。解读零值或 null 值之前，请先查看 coverageStartAt、state 和 reason。

• growsurf_create_campaign 创建新计划（campaign），并提供适合其类型的入门内容和可选的内联奖励（只需要 GROWSURF_API_KEY，不需要 GROWSURF_CAMPAIGN_ID）。修改前，请检查已预置的 Design、Emails、Options、Installation、奖励和 GrowSurf Window 内容。

• growsurf_agent_program_creation_eval 生成一次性计划创建评估提示词和验收检查，涵盖入门内容、谨慎设置的奖励、配置审核、前端安装证明以及清晰的公开文案。

• growsurf_update_campaign 更新计划的身份信息和生命周期：名称、公司品牌和状态（只更改你发送的字段）。

• growsurf_clone_campaign 将计划克隆为一个新的 DRAFT 计划（不会复制集成和凭据）。

• growsurf_list_campaign_rewards 列出计划中配置的奖励。

• growsurf_create_campaign_reward 创建计划奖励。

• growsurf_update_campaign_reward 根据奖励键更新计划奖励。

• growsurf_delete_campaign_reward 根据奖励键删除计划奖励。

• growsurf_list_program_resources / growsurf_create_program_resource / growsurf_update_program_resource / growsurf_delete_program_resource 管理按顺序排列的参与者资源。LINK 使用 HTTPS，TEXT 使用纯文本。

• growsurf_prepare_program_resource_file 申请一次性票据，并将不超过 10 MB 的允许文件上传到 GrowSurf 选定且精确列入主机允许列表的目标地址。将返回的票据和签名结果原样传递给创建或更新操作。此工具不接受上传 URL 或凭据，且绝不会重试上传。

• growsurf_get_campaign_design / growsurf_update_campaign_design 读取或修改设计配置，包括 Program Editor 的 Design 选项卡和付款目标确认页文案。

• growsurf_get_campaign_emails / growsurf_update_campaign_emails 读取或修改 Program Editor 的 Emails 选项卡配置。

• growsurf_get_campaign_options / growsurf_update_campaign_options 读取或修改 Program Editor 的 Options 选项卡配置，包括计划的 languages。

• growsurf_get_campaign_installation / growsurf_update_campaign_installation 读取或修改 Program Editor 的 Installation 选项卡配置。

• growsurf_capture_referral_flow_screenshots 为当前计划截取临时 GrowSurf 预览截图，可在保存草稿后或用户要求查看时使用。此工具会返回受控的推荐人 Window 和被推荐好友体验；若要证明用户网站上的安装情况，请改用浏览器自动化。

• growsurf_list_campaign_webhooks 列出计划的 Webhook（绝不会返回密钥）。

• growsurf_create_campaign_webhook 向计划添加 Webhook（包含事件和只能写入的签名密钥）。

• growsurf_update_campaign_webhook 根据 ID 更新 Webhook（计划的主要 Webhook 使用 primary）。

• growsurf_delete_campaign_webhook 根据 ID 移除 Webhook。

• growsurf_test_campaign_webhook 使用 Webhook 已存储的 URL 和密钥发送实时测试事件。

• growsurf_add_participant 在注册期间添加参与者（或被推荐的参与者）。

• growsurf_list_participants 列出当前计划中的参与者，并通过 nextId 分页。传入 metadata（最多 3 个键）可仅返回元数据完全匹配的参与者，例如根据你自己的客户 ID 查找用户。调用参与者范围的工具之前，请使用此工具查找参与者 ID。

• growsurf_get_participant 根据 GrowSurf 参与者 ID 或电子邮件地址获取一位参与者。

• growsurf_update_participant 按 ID 或邮箱更新参与者（包括内部 notes 和参与者的 language）。

• growsurf_bulk_delete_participants — 检查每一行的处理结果。analyticsErasure.status: "pending" 表示分析数据擦除仍在处理中；不要重复处理已成功的行。 在一次请求中永久删除最多 200 位参与者（可按 ID 和／或邮箱指定，允许混合列表），并返回每行的 DELETED／NOT_FOUND／DUPLICATE／ERROR 结果。此操作不可撤销。成功处理的行会立即失去参与者访问权限；相关记录会自动清理，但须遵守财务记录的保留要求。

• growsurf_email_participant 使用已配置的模板或自定义主题／正文向参与者发送邮件。

• growsurf_get_participant_analytics 获取单个参与者的互动、排名、分享、联盟收入、佣金、付款、可选的邮件指标，以及已涵盖的首个里程碑。使用 include=activation 获取 firstPortalViewedAt 和 firstShareChannel 等里程碑；添加 series 可获取已涵盖的 portalViews 和 shareActions。无法获取的 null 表示未知，不能证明该操作从未发生。

• growsurf_get_participant_activity_logs 列出参与者的活动日志（按 offset／limit 分页）。

• growsurf_trigger_referral 触发推荐（仅适用于推荐计划）。可选传入 delayInDays（1-90），在授予奖励前延迟 N 天（例如，覆盖退款期）。

• growsurf_cancel_delayed_referral 在延迟期结束前取消待处理的延迟推荐触发（例如，发生退款／取消时）。

• growsurf_get_participant_payout_destination 获取参与者在计划启用的每个服务商（PayPal 和／或 Wise）的收款目的地状态：各服务商状态、已确认的收款邮箱、法定收款人类型和修复原因。

• growsurf_request_participant_payout_destination_confirmation 请求参与者确认某个服务商的收款目的地——向其发送一次性确认链接（只有参与者本人可以确认）。

• growsurf_record_sale 记录联盟销售或交易（仅适用于联盟计划）。

• growsurf_refund_transaction 针对已记录的交易记录调整（退款、部分退款或拒付）；撤销或调整推荐人的佣金（仅适用于联盟计划）。此工具与 growsurf_record_sale 的作用相反。

• growsurf_create_mobile_participant_token 创建或获取参与者，然后为已登录的移动用户创建参与者专属的移动 SDK 令牌。

辅助工具

• growsurf_participant_auth_hash 生成参与者自动身份验证 HMAC 哈希（用于自动验证参与者）。

• growsurf_webhook_normalize 规范化 Webhook 负载并生成幂等键（用于对 Webhook 投递进行去重）。

Webhook

GrowSurf Webhook 会在发生重要的推荐或联盟事件时通知你的服务端，例如创建参与者、推荐、奖励或交易等新对象。常见用例如下：

• 自动发放奖励
• 维护内部积分或信用系统
• 将参与者和推荐数据同步到数据库

处理重复投递

Webhook 处理程序应具备幂等性，因为同一事件可能会多次到达。在对系统进行任何更改之前，先存储幂等键。

Webhook 安全性与幂等性

当 webhook 配置了 secret 时，GrowSurf 会对 webhook 投递进行签名：每次投递都会包含一个 GrowSurf-Signature HMAC 标头，该标头使用该密钥计算得出（该密钥仅可写入，绝不会返回）。为安全地使用 webhook，我们建议：

• 在 webhook 上设置 secret，并在收到投递时验证 GrowSurf-Signature 标头
• 验证载荷结构和预期的事件类型
• 使用幂等键对 webhook 事件去重，因为同一事件可能会多次到达

GrowSurf MCP 服务提供了一个辅助工具（growsurf_webhook_normalize），用于规范化 webhook 载荷并尽可能生成幂等键，从而简化安全的 webhook 处理。

开发与测试

npm run dev
npm test

其他资源

请参阅以下开发者文档：

• JavaScript SDK 参考：https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference
• REST API 参考：https://docs.growsurf.com/developer-tools/rest-api/api-reference
• REST API 库：https://docs.growsurf.com/developer-tools/rest-api/api-libraries
• 原生移动应用指南：https://docs.growsurf.com/getting-started-for-mobile
• iOS SDK：https://docs.growsurf.com/developer-tools/ios-sdk
• Android SDK：https://docs.growsurf.com/developer-tools/android-sdk
• React Native SDK：https://docs.growsurf.com/developer-tools/react-native-sdk
• GrowSurf 入门指南：https://docs.growsurf.com/getting-started

GrowSurf MCP 服务可帮助 GrowSurf 客户快速实施推荐计划和联盟营销计划。