GrowSurf MCP Server

Официальный интерфейс командной строки (CLI) GrowSurf и сервер Model Context Protocol (MCP) с открытым исходным кодом для внедрения реферальных и партнёрских программ GrowSurf с пошаговыми инструкциями и безопасными обёртками REST API.

Подключите его к ИИ-агенту, и на простом языке агент сможет создать реферальную или партнёрскую программу, настроить вознаграждения, установить отслеживание, добавлять и управлять участниками, а также читать аналитику — всё на основе REST API GrowSurf.

• Узнайте больше о GrowSurf на https://growsurf.com

• Узнайте больше об этом MCP-сервере на https://docs.growsurf.com/build-with-ai

Для кого это

Этот MCP-сервер предназначен для:

• Разработчиков, использующих инструменты, совместимые с MCP (Claude Code, Codex, Cursor, Copilot и другие MCP-клиенты)

• Команд, которым нужны управляемые интеграции GrowSurf с помощью ИИ

Этот MCP-сервер НЕ предназначен для:

• Пользователей, работающих только в браузере и желающих локальную установку stdio. ChatGPT web, Claude.ai и Claude Desktop не запускают локальный MCP-сервер, но все три подключаются к GrowSurf через размещённый удалённый коннектор по адресу https://mcp.growsurf.com. Полный список клиентов и настройку см. на https://docs.growsurf.com/build-with-ai#mcp.

Related MCP server: SurfRank MCP Server

Что вы получаете

• Управляемая интеграция:

  • Установка универсального кода

  • Рекомендации по внедрению нативных iOS/Android SDK

  • Рекомендации по нативному окну GrowSurf

  • Поток регистрации

  • Поток квалифицирующего действия

  • Отслеживание продаж / транзакций партнёров

  • Вебхуки

• Рецепты для агентов:

  • MCP-промпты для создания реферальных программ, создания партнёрских программ, встраивания виджета, перечисления и получения программ и участников, настройки вознаграждений, подключения вебхуков и чтения аналитики

  • Устанавливаемый набор навыков агента в skills/growsurf-agent-toolkit

  • Направление на проверку стартового дизайна, писем, параметров, установки, вознаграждений и содержимого окна GrowSurf перед внесением изменений

  • Промпты для одноразового создания программы и проверки приёмки для стартового содержимого и проверки конфигурации

• Обёртки REST API для счастливого пути:

  • Создание аккаунта и получение API-ключа без существующих учётных данных

  • Чтение и переименование привязанной команды, запрос верификации команды и повторная отправка письма с подтверждением владельцу команды

  • Перечисление и получение кампаний

  • Получение аналитики кампании (итоги, необязательные временные ряды по периодам, метрики электронной почты, итоги за предыдущий период, счётчики статусов и коэффициенты)

  • Создание, обновление и клонирование программ (кампаний)

  • Перечисление, создание, обновление и удаление вознаграждений кампании

  • Получение/обновление конфигурации дизайна, писем, параметров и установки

  • Создание временных предварительных снимков экрана GrowSurf, когда пользователь явно запрашивает визуальное подтверждение

  • Перечисление, создание, обновление, удаление и тестирование вебхуков программы

  • Перечисление, получение и добавление участников

  • Обновление участника, отправка письма участнику и получение аналитики и журналов активности участника

  • Начисление реферального кредита (для реферальных программ) с возможностью отложенного начисления (1–90 дней)

  • Отмена ожидающего отложенного реферального триггера (для реферальных программ)

  • Запись продажи/транзакции партнёра (для партнёрских программ)

  • Создание мобильных токенов участников для вошедших в систему пользователей нативных приложений

• Официальные фрагменты библиотеки API:

  • TypeScript

  • Python

  • PHP

  • Ruby

  • Java

• Помощники:

  • Вычисление HMAC-хэша для автоматической аутентификации участника

  • Нормализация полезных нагрузок вебхуков

  • Генерация ключей идемпотентности с максимальным усилием для дедупликации вебхуков

Требования

• Node.js 22+

• Аккаунт GrowSurf для размещённого OAuth

• API-ключ GrowSurf для локальной настройки stdio или ручной удалённой настройки с API-ключом. Ключ с ограниченными правами подойдёт, если он имеет доступ к инструментам и программам, которые агент должен использовать.

• Идентификатор кампании (программы) для инструментов, ограниченных кампанией. Установите GROWSURF_CAMPAIGN_ID по умолчанию, передайте аргумент campaignId для конкретной программы или вызовите growsurf_list_campaigns, чтобы найти доступные программы. Для новой программы передайте id, возвращённый growsurf_create_campaign, в другие инструменты.

• Статические инструменты с руководствами и фрагментами могут работать без учётных данных

• Исключение: growsurf_create_account не требует API-ключа. Он создаёт новый аккаунт и возвращает API-ключ. Инструментам уровня команды не нужен идентификатор кампании.

• Каждый перечисленный инструмент публикует стандартные подсказки безопасности MCP: только чтение, деструктивные, идемпотентные и открытые. Ограниченные бизнес-действия остаются доступными; ротация API-ключей намеренно не является инструментом MCP. Вращайте ключи в настройках GrowSurf или через прямой REST/SDK-клиент.

Официальный CLI

Пакет npm устанавливает команду growsurf-mcp. Запустите её без глобальной установки:

npx -y @growsurfteam/growsurf-mcp

CLI запускает локальный stdio-сервер MCP GrowSurf. Установите GROWSURF_API_KEY для действий, использующих API, и GROWSURF_CAMPAIGN_ID для программы по умолчанию. Публичные ресурсы для разработчиков и статические руководства по интеграции работают без учётных данных.

Проверьте установленную команду, не запуская stdio-сервер:

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

Поддерживаемые MCP-хосты

Рекомендуемый путь — размещённая конечная точка OAuth GrowSurf по адресу https://mcp.growsurf.com, если ваш хост поддерживает удалённый Streamable HTTP с OAuth. Используйте локальный сервер npx, если вашему хосту нужен процесс stdio или ручная настройка API-ключа. Ещё нет аккаунта GrowSurf? Агент может подключиться к размещённой конечной точке онбординга https://mcp.growsurf.com/onboard без учётных данных и вызвать growsurf_create_account для регистрации.

Сервер MCP GrowSurf работает с любым хостом, совместимым с MCP. Примеры ниже охватывают несколько хостов на основе конфигурации и CLI. Полный актуальный список поддерживаемых клиентов (включая ChatGPT web, Claude.ai, Claude Desktop, GitHub Copilot, Gemini CLI, Devin Desktop и Cline) с пошаговой настройкой см. на https://docs.growsurf.com/build-with-ai#mcp.

• Cursor

• Claude Code (на основе CLI)

• Antigravity

• Codex (на основе CLI)

Cursor

1. Откройте или создайте глобальную MCP-конфигурацию Cursor в ~/.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 и выберите Authenticate для GrowSurf.

Для локального 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"

Или настройте локальный stdio из CLI:

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. Полезно для локальных или размещённых MCP-шлюзов, которые должны вызывать другой источник API GrowSurf)

• GROWSURF_PARTICIPANT_AUTH_SECRET (необязательно; используется помощником хэширования)

• GROWSURF_WEBHOOK_TOKEN (необязательно; используется для вашей собственной схемы токенов URL вебхуков)

Запуск с npx

После публикации этого пакета клиенты могут запустить:

npx @growsurfteam/growsurf-mcp

Для локальной разработки в этом репозитории:

npm install
npm run build
node dist/cli.js

Инструменты MCP

Каждый инструмент объявляет схему вывода MCP и возвращает structuredContent, поэтому хосты знают форму результата каждого инструмента. Инструменты REST возвращают ответ API (плюс текстовый блок JSON для старых клиентов); инструменты с руководствами и фрагментами возвращают свой документ Markdown в поле markdown.

Управляемая интеграция

• growsurf_integration_guide Пошаговые рекомендации по внедрению реферальной или партнёрской программы GrowSurf.

• growsurf_mobile_sdk_guide Рекомендации по нативным iOS/Android SDK для атрибуции, shareUrl, trackShare и нативного окна GrowSurf.

• growsurf_api_library_snippets Официальные фрагменты библиотеки REST API для TypeScript, Python, PHP, Ruby и Java.

• growsurf_get_integration_connect_link Получите ссылку на панель управления, которая открывает панель подключения конкретной интеграции (Stripe, PayPal, Tango Card, Mailchimp и многие другие). Передайте её пользователю, когда он захочет подключить интеграцию. Подключение происходит в панели управления, а не через API.

Фрагменты для клиента и интерфейса

• growsurf_client_snippets Примеры JavaScript SDK, окна GrowSurf и встраиваемых элементов. Включает напоминание об использовании рабочего процесса дизайна интерфейса при размещении или стилизации встраиваемого интерфейса.

• growsurf_embeddable_element_snippet HTML-фрагмент для конкретного встраиваемого элемента GrowSurf.

• growsurf_grsf_config_snippet Фрагмент <head> для настройки window.grsfConfig и автоматической аутентификации участника.

Онбординг аккаунта

• 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.

• growsurf_create_campaign Создать новую программу (кампанию) со стартовым контентом, соответствующим типу, и опциональными встроенными вознаграждениями (требуется только GROWSURF_API_KEY, не GROWSURF_CAMPAIGN_ID). Проверьте сгенерированный контент во вкладках Design, Emails, Options, Installation, вознаграждения и GrowSurf Window перед внесением изменений.

• growsurf_agent_program_creation_eval Сгенерировать одноразовые 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_get_campaign_design / growsurf_update_campaign_design Прочитать или изменить конфигурацию дизайна, включая вкладку Design в редакторе программы и текст страницы подтверждения способа выплаты.

• growsurf_get_campaign_emails / growsurf_update_campaign_emails Прочитать или изменить конфигурацию вкладки Emails в редакторе программы.

• growsurf_get_campaign_options / growsurf_update_campaign_options Прочитать или изменить конфигурацию вкладки Options в редакторе программы.

• growsurf_get_campaign_installation / growsurf_update_campaign_installation Прочитать или изменить конфигурацию вкладки Installation в редакторе программы.

• growsurf_capture_referral_flow_screenshots Сделать временные скриншоты предпросмотра GrowSurf для текущей программы после того, как пользователь явно запросит визуальное подтверждение. Этот инструмент возвращает контролируемый опыт реферера и приглашенного друга; для подтверждения установки на сайте пользователя используйте автоматизацию браузера.

• growsurf_list_campaign_webhooks Вывести список вебхуков программы (секреты никогда не возвращаются).

• growsurf_create_campaign_webhook Добавить вебхук в программу (с событиями и секретом подписи только для записи).

• growsurf_update_campaign_webhook Обновить вебхук по id (primary для основного вебхука программы).

• growsurf_delete_campaign_webhook Удалить вебхук по id.

• growsurf_test_campaign_webhook Отправить живое тестовое событие на вебхук, используя его сохраненные URL и секрет.

• growsurf_add_participant Добавить участника (или приглашенного участника) при регистрации.

• growsurf_list_participants Вывести список участников текущей программы с пагинацией по nextId. Используйте этот инструмент, чтобы найти ID участника перед вызовом инструментов, ограниченных участником.

• growsurf_get_participant Получить одного участника по GrowSurf ID участника или адресу электронной почты.

• growsurf_update_participant Обновить участника по ID или email (включая внутренние notes).

• growsurf_bulk_delete_participants Навсегда удалить до 200 участников (по ID и/или email, смешанные списки допускаются) одним запросом, с результатами DELETED/NOT_FOUND/DUPLICATE/ERROR по каждой строке. Необратимо — удаляет реферальные ссылки участников, вознаграждения, комиссии и записи о выплатах.

• growsurf_email_participant Отправить письмо участнику, используя настроенный шаблон или свободную тему/текст.

• growsurf_get_participant_analytics Получить данные одного участника: вовлеченность, рейтинг, шеринг, доход от партнерской программы, комиссию, выплаты и опциональные email-метрики. Используйте include=series, include=email или оба значения через запятую.

• 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): статус по провайдеру, подтвержденный email для выплат, юридический тип получателя и причину исправления.

• 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 Нормализовать полезные нагрузки вебхуков и сгенерировать ключи идемпотентности (для дедупликации доставок вебхуков).

Вебхуки

Вебхуки GrowSurf уведомляют ваш сервер о важных событиях реферальной или партнерской программы, например, когда создаются новые объекты, такие как участники, реферальные ссылки, вознаграждения или транзакции. Вот распространенные сценарии использования:

• Автоматическое выполнение вознаграждений

• Поддержание внутренних систем баллов или кредитов

• Синхронизация данных об участниках и реферальных ссылках в вашу базу данных

Обработка дублирующихся доставок

Обработчики вебхуков должны быть идемпотентными, потому что одно и то же событие может прийти более одного раза. Сохраняйте ключ идемпотентности перед любыми изменениями в вашей системе.

Безопасность вебхуков и идемпотентность

GrowSurf подписывает доставки вебхуков, когда у вебхука настроен secret: каждая доставка включает HMAC-заголовок GrowSurf-Signature, вычисленный с этим секретом (секрет доступен только для записи и никогда не возвращается). Для безопасного использования вебхуков мы рекомендуем следующее:

• Установите secret на вебхуке и проверяйте заголовок GrowSurf-Signature при получении

• Проверяйте форму полезной нагрузки и ожидаемый тип события

• Дедуплицируйте события вебхуков с помощью ключа идемпотентности, потому что одно и то же событие может прийти более одного раза

MCP-сервер GrowSurf предоставляет вспомогательный инструмент (growsurf_webhook_normalize), который нормализует полезные нагрузки вебхуков и генерирует ключ идемпотентности по мере возможности, чтобы упростить безопасную обработку вебхуков.

Разработка и тестирование

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-native-mobile

• iOS SDK: https://docs.growsurf.com/developer-tools/ios-sdk

• Android SDK: https://docs.growsurf.com/developer-tools/android-sdk

• Начало работы с GrowSurf: https://docs.growsurf.com/getting-started

MCP-сервер GrowSurf помогает клиентам GrowSurf быстро внедрять реферальные и партнерские программы.