GrowSurf

GrowSurf MCP サーバー

GrowSurf の公式コマンドラインインターフェイス（CLI）およびオープンソースの Model Context Protocol（MCP）サーバーです。ガイド付きの手順と安全な REST API ラッパーを使って、GrowSurf の紹介プログラムやアフィリエイトプログラムを実装できます。

AI エージェントに接続すると、自然言語で指示するだけで、GrowSurf REST API を通じて紹介プログラムやアフィリエイトプログラムの作成、報酬の設定、トラッキングの導入、参加者の追加と管理、分析データの確認を実行できます。

MCP は任意です。HTTPS リクエストを送信できるアクション対応エージェントなら、https://growsurf.com/agent-start.md にあるクライアントに依存しない GrowSurf REST ワークフローから始められます。

• https://growsurf.com で GrowSurf の詳細をご覧ください
• https://growsurf.com/agent-start.md から直接 REST を始められます
• 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 web と 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
• エージェントレシピ：
  • 紹介プログラムやアフィリエイトプログラムの作成、プログラム設計のアドバイス、紹介トラッキングのトラブルシューティング、ウィジェットの埋め込み、プログラムと参加者の一覧表示および取得、報酬の設定、Webhook の接続、分析データの読み取りに使用する MCP プロンプト
  • プロンプトは会話の詳細情報を活用し、次のステップに必要な不足情報のみを質問します。フォームへの入力は不要です。既存のプロンプト名と直接引数も引き続きサポートされます。
  • skills/growsurf-agent-toolkit にインストール可能なエージェントスキルバンドル
  • パッチを適用する前に、スターターの Design、Emails、Options、Installation、報酬、GrowSurf Window の内容を確認するためのガイダンス
  • スターターコンテンツと設定のレビューに使用する、ワンショットのプログラム作成用評価プロンプトと受け入れチェック
• ハッピーパス用 REST API ラッパー：
  • 既存の認証情報なしでアカウントを作成し、API キーを取得
  • バインドされたチームの読み取りと名前変更、チームの認証確認のリクエスト、チーム所有者への確認メールの再送信
  • キャンペーンの一覧表示と取得
  • キャンペーン分析データの取得（合計、時系列、メール指標、参加者のエンゲージメントアクティビティ、アクティベーションコホート）
  • プログラム（キャンペーン）の作成、更新、複製
  • キャンペーン報酬の一覧表示、作成、更新、削除
  • 安全な単発の FILE 準備フローを含む、Program Resources の一覧表示、作成、更新、削除
  • Design、Emails、Options、Installation の設定の取得／更新
  • ユーザーがドラフトプログラムを確認できるよう、一時的な GrowSurf プレビューのスクリーンショットを取得
  • プログラムの Webhook の一覧表示、作成、更新、削除、テスト
  • 参加者の一覧表示、取得、追加
  • 参加者の更新、参加者へのメール送信、参加者の分析データとアクティビティログの取得
  • 紹介クレジットの付与（紹介プログラムの場合。1～90 日の任意の遅延付与に対応）
  • 保留中の遅延紹介トリガーのキャンセル（紹介プログラムの場合）
  • アフィリエイトの販売／取引の記録（アフィリエイトプログラムの場合）
  • サインイン済みのネイティブアプリユーザー向けにモバイル参加者トークンを作成
• 公式 API ライブラリのスニペット：
  • TypeScript
  • Python
  • PHP
  • Ruby
  • Java
• ヘルパー：
  • 参加者の自動認証用 HMAC ハッシュの計算
  • Webhook ペイロードの正規化
  • Webhook の重複排除に使用する、ベストエフォート方式の冪等性キーの生成

ツールの選択

プログラムや参加者の記録を読み取ったり変更したりするには、プログラムツールや参加者ツールを使用します。ガイダンスツールは、適用するためのアドバイスやコードを返します。

タスク	ツール
プログラムの設計と報酬体系を選択する	growsurf_program_design_advisor
ウェブ連携を計画する	growsurf_integration_guide
ブラウザー JavaScript の例を取得する	growsurf_client_snippets
埋め込み可能な要素の HTML を取得する	growsurf_embeddable_element_snippet
ページレベルの参加者自動認証コードを生成する	growsurf_grsf_config_snippet
バックエンド REST API ライブラリーの例を取得する	growsurf_api_library_snippets
ネイティブ iOS、Android、または React Native アプリを連携する	growsurf_mobile_sdk_guide
プログラムの問題を診断する	growsurf_troubleshoot_referral_tracking
エージェントのプログラム作成ワークフロー用のチェック項目を生成する	growsurf_agent_program_creation_eval

公開されているツール名とフィールドでは、campaign（campaignId を含む）をプログラムとして使用します。これらの識別子は引き続きサポートされます。表示タイトルではプログラムの用語を使用しますが、報酬設定の名称は Campaign Reward のままです。

参加者を1人削除するには、growsurf_bulk_delete_participants の participants に1つの ID またはメールアドレスを渡します。同じ完全削除に関する警告が適用されます。参加者1人専用のツールは不要です。プログラムの削除と報酬の明示的な履行は、この MCP ツールセットの対象外です。プログラムの完了は削除ではなく、報酬の設定は報酬が届けられた証明にはなりません。

任意のコンパクト接続

既定の接続では、63個すべてのツールが一覧表示されます。--compact を追加すると、プログラムの設定、インストール、参加者管理、紹介の追跡、報酬、分析に対応する32個のツールを選択できます。認証情報の権限によって、表示されるツールがさらに制限される場合があります。

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

stdio クライアント設定では、パッケージの args 配列に "--compact" を追加します。サーバー連携では、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 の下に指定します。先にセクションを読み取ってください。

たとえば、プログラムのインストール設定を読み取るには、次のようにします。

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

プログラムの推奨事項とトラブルシューティングには、それぞれ専用のツールが引き続き使用されます。参加者の読み取り、更新、削除、紹介アクション、販売または返金アクションは、引き続き個別のツールを使用します。コンパクト接続のプロンプト、リソース、ガイダンス、設定案の呼び出しでは、コンパクト用のツール名と引数を使用します。

アカウント作成、チーム管理、プログラムの複製、参加者リソース、Webhook の作成／更新／削除／テスト、参加者メール、支払い先、Webhook の正規化には、完全な接続を使用します。--compact を削除して再接続してください。これらの操作は完全な接続では、既存の契約のまま引き続き利用できます。コンパクト接続では、カタログに含まれないツールの呼び出しは拒否されます。上記のツール選択表は、完全な接続について説明しています。

要件

• Node.js 22+
• ホスト型 OAuth 用の GrowSurf アカウント
• ローカル stdio の設定または手動での API キーによるリモート設定に使用する GrowSurf API キー。使用するツールやプログラムにアクセスできるスコープ付きキーも利用できます。
• キャンペーンスコープのツールに使用する キャンペーン（プログラム）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 アカウントをまだお持ちでない場合は、所有者の承認後、エージェントが https://mcp.growsurf.com/onboard に認証情報なしで接続し、growsurf_create_account を呼び出せます。

GrowSurf MCP サーバーは、MCP 対応のあらゆるホストで動作します。以下の例では、設定ベースおよび CLI ベースのホストをいくつか紹介します。対応クライアントの最新の完全な一覧（ChatGPT web、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. ホスト型 OAuth エンドポイントを使用して、growsurf という名前のサーバーを追加します：

{
  "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引数で上書きできるため、1 つのサーバーで任意のプログラムを操作できます）
• GROWSURF_API_BASE_URL（任意です。デフォルトはhttps://api.growsurf.com/v2です。別の GrowSurf API オリジンを呼び出すローカルまたはホスト型の MCP ゲートウェイで役立ちます）
• GROWSURF_UPLOAD_ALLOWED_ORIGINS（FILE リソースのアップロード時のみ必須です。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 アトリビューション、shareUrl、trackShare、ネイティブ GrowSurf Window に関する、ネイティブ iOS／Android または React Native SDK のガイダンスです。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 プログラム（キャンペーン）を新規作成します。プログラムの種類に適したスターターコンテンツと、任意のインライン報酬を設定できます（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 1回限りのチケットをリクエストし、GrowSurf が選択した、ホストが許可リストに登録された宛先に、許可されている最大10 MBのファイルをアップロードします。返されたチケットと署名済みの結果は変更せずに、作成または更新に渡してください。このツールはアップロード 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 プログラムの languages を含む、Program Editor の Options タブの設定を読み取るかパッチを適用します。

• 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 保存済みの URL とシークレットを使用して、Webhook にライブテストイベントを送信します。

• growsurf_add_participant 登録時に参加者（または紹介された参加者）を追加します。

• growsurf_list_participants 現在のプログラムの参加者一覧を nextId でページネーションして取得します。metadata（最大3つのキー）を渡すと、独自の顧客 ID で参加者を検索する場合など、メタデータが完全一致する参加者のみが返されます。参加者を対象とするツールを呼び出す前に、参加者 ID を見つけるために使用してください。

• growsurf_get_participant GrowSurf の参加者 ID またはメールアドレスを指定して、参加者を1人取得します。

• growsurf_update_participant ID またはメールアドレスで参加者を更新します（内部の notes および参加者の language を含みます）。

• growsurf_bulk_delete_participants — 各行の結果を確認してください。analyticsErasure.status: "pending" は、分析データの消去がまだ保留中であることを意味します。成功した行を再度処理しないでください。 1 回のリクエストで、最大 200 人の参加者を完全に削除します（ID、メールアドレス、または両方で指定でき、混在するリストも使用できます）。各行の結果として DELETED／NOT_FOUND／DUPLICATE／ERROR が返されます。元に戻すことはできません。成功した行の参加者はすぐにアクセスできなくなり、関連レコードのクリーンアップは、必須の財務記録保持要件に従って自動的に完了します。

• growsurf_email_participant 設定済みのテンプレート、または自由形式の件名と本文を使って、参加者にメールを送信します。

• growsurf_get_participant_analytics 1 人の参加者のエンゲージメント、ランク、シェア、アフィリエイト収益、コミッション、支払い、任意のメール指標、および対象となる初回マイルストーンを取得します。firstPortalViewedAt や firstShareChannel などのマイルストーンには include=activation を使用し、対象となる portalViews と shareActions には series を追加します。利用できない場合の 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 の配信に署名します。各配信には、そのシークレットを使って計算された HMAC ヘッダー GrowSurf-Signature が含まれます（シークレットは書き込み専用で、返されることはありません）。Webhook を安全に利用するには、次のことをおすすめします。

• Webhook に secret を設定し、受信時に GrowSurf-Signature ヘッダーを検証する
• ペイロードの形式と想定されるイベントタイプを検証する
• 同じイベントが複数回届く可能性があるため、冪等性キーを使って Webhook イベントを重複排除する

GrowSurf MCP サーバーには、Webhook ペイロードを正規化し、ベストエフォートで冪等性キーを生成するヘルパーツール（growsurf_webhook_normalize）が用意されており、安全な 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 のお客様は紹介プログラムやアフィリエイトプログラムをすばやく実装できます。