pb-hypernode-mcp

Клиентский плагин Claude Code для Hypernode Brancher — создавайте одноразовые превью-окружения, клонированные с продакшена, вносите изменения с помощью ИИ через SSH и просматривайте результат через ваш браузерный MCP.

Зачем это нужно

Brancher предоставляет изменяемую временную копию вашего продакшен-узла Hypernode (данные не старше 24 часов, полный набор инструментов, реальная инфраструктура — не эмуляция Docker). Проблема в том, что он клонирует продакшен целиком, включая реальные персональные данные клиентов и настоящие платежные/API-учетные данные, а узел получает публичный URL. Этот плагин устраняет этот разрыв — каждый созданный им узел автоматически анонимизируется и изолируется до того, как будет объявлен готовым, так что «позволить ИИ клиента поработать с реальной копией продакшена» не означает «выставить реальные данные клиентов в интернет».

Related MCP server: DDEV MCP

Установка

Три шага: установите плагин, укажите ваш токен Hypernode, перезапустите Claude Code.

1. Установите плагин

Введите эту команду прямо в Claude Code (терминал не нужен):

/plugin marketplace add ProxiBlue/pb-hypernode-mcp
/plugin install pb-hypernode-mcp@pb-hypernode-mcp

Claude Code загружает всё напрямую с GitHub — не нужно ничего скачивать, запускать отдельный сервер или клонировать вручную.

(Если вы предпочитаете запускать из терминала, те же команды работают как claude plugin marketplace add ... / claude plugin install ....)

2. Добавьте ваш API-токен Hypernode

Этот плагин использует ваш API-токен Hypernode для взаимодействия с вашей учетной записью Hypernode от вашего имени. Плагин никогда не сохраняет его — вы задаете его как переменную окружения, так же, как любой пароль.

Найдите ваш токен в панели управления Hypernode, затем в терминале (перед запуском Claude Code):

export HYPERNODE_API_TOKEN="your-token-here"

Опционально, но рекомендуется — ограничьте, к каким приложениям Hypernode плагин может обращаться, чтобы опечатка не затронула не тот сайт:

export HYPERNODE_APP_ALLOWLIST="myapp"

(Укажите несколько имен приложений через запятую, например "myapp,myapp2", если управляете более чем одним.)

Совет: добавьте обе строки в файл запуска вашей оболочки (~/.zshrc или ~/.bashrc), чтобы не вводить их каждый раз заново.

3. Перезапустите Claude Code

Закройте и снова откройте Claude Code, чтобы он подхватил токен и подключился к плагину. Всё готово к работе.

Быстрый старт

Просто спросите на естественном языке:

«Создай превью Brancher для myapp, чтобы я мог показать клиенту новую верстку страницы категорий.»

Claude создает узел, ожидает его готовности, выполняет санитарную обработку (см. Защитные ограничения) и сообщает результат:

node_name:     myapp-eph482913
access_url:    https://myapp-eph482913.hypernode.io/
minutes_remaining: 387

После этого попросите внести изменения и показать результат или просто скажите «удали все оставшиеся превью-узлы», когда закончите — Brancher тарифицирует поминутно, независимо от того, смотрит ли кто-то на узел.

Что входит в плагин

skills/
├── brancher-spinup/      create a sanitized preview node, report access details
├── brancher-preview/     full loop: spin up -> change -> build -> screenshot
└── brancher-cleanup/     list/flag/delete leftover nodes
src/pb_hypernode_mcp/     the MCP server (6 tools) — see MCP tools below
tests/                    automated test suite

Требования

• Учетная запись Hypernode на тарифе Falcons с API-токеном из панели управления (Brancher доступен только на тарифе Falcons).

• SSH-ключ, который вы уже используете для доступа к вашему Hypernode — ничего дополнительно настраивать не нужно, превью-узлы Brancher наследуют доступ автоматически.

• Python 3.11+ и uv, установленные на машине, где запущен Claude Code (плагины Claude Code — это просто код, и это среда выполнения, которая им нужна).

MCP-инструменты

Все 6 инструментов зарегистрированы на сервере pb-hypernode-mcp (src/pb_hypernode_mcp/server.py). brancher_exec и brancher_put вызывают системные ssh/rsync через ваш уже настроенный локальный SSH-агент/ключ — этот плагин никогда не хранит ключевой материал самостоятельно.

Навыки

• brancher-spinup — создает одноразовый превью-узел Brancher, клонированный с продакшена, с обязательной автоматической санитарной обработкой, и сообщает его URL доступа. Используйте, когда клиент просит предварительно просмотреть изменения на реальной копии продакшена перед развертыванием. Оборачивает единственный вызов инструмента brancher_create — никогда не воспроизводит последовательность create/wait/sanitize вручную.

• brancher-preview — полный цикл: создание узла (через навык brancher-spinup), применение изменений кода (отправка локального diff через brancher_put или редактирование на месте через brancher_exec), запуск только тех команд сборки Magento, которые действительно нужны для изменений (decide_build_commands() в src/pb_hypernode_mcp/preview_logic.py), просмотр результата через любой браузерный MCP-инструмент, уже доступный в сессии, и затем явное напоминание пользователю, что узел продолжает тарифицировать минуты Brancher. Используйте, когда клиент хочет полностью оценить изменения в одноразовом окружении. Никогда не удаляет сам узел.

• brancher-cleanup — выводит список активных узлов с помощью brancher_list, помечает узлы, достигшие или превысившие порог времени (minutes >= threshold_minutes, по умолчанию 240 минут / 4 часа, через flag_stale_nodes() в src/pb_hypernode_mcp/cleanup_logic.py), и удаляет помеченные узлы (по одному или все сразу) только после явного подтверждения пользователя. Используйте, когда клиент хочет проверить или удалить оставшиеся узлы Brancher, чтобы остановить начисление минут. Brancher тарифицирует минуты с момента создания, независимо от того, использует ли кто-то узел.

Защитные ограничения

• Обязательная санитизация — не может быть отключена. Каждый вызов brancher_create запускает полную последовательность санитизации (src/pb_hypernode_mcp/sanitization/) на узле, прежде чем он будет сообщен как "ready" или вернет access_url. Нет ни флага, ни опции конфигурации, ни пути обхода — brancher_create является ЕДИНСТВЕННЫМ инструментом MCP для создания узлов, зарегистрированным этим плагином (нет отдельного, несанитизированного инструмента создания), и spinup_sanitized_brancher_node() в src/pb_hypernode_mcp/tools/brancher_spinup_flow.py (функция за ним) структурно не может вернуть access URL, пока все команды санитизации не завершатся с кодом 0. Если команда санитизации завершается ошибкой на полпути, инструмент вызывает SanitizationFailedError и умышленно скрывает access URL — исключение даже не содержит его, поэтому перехватывающий вызывающий код не может случайно его раскрыть.

  Последовательность (управляемая конфигурацией, с настройками по умолчанию для Magento в sanitization/config.py::DEFAULT_MAGENTO_SANITIZATION_CONFIG):

  1. Анонимизация PII — операторы UPDATE (через n98-magerun2 db:query) против customer_entity, customer_address_entity, sales_order, sales_order_address (имена/email/телефоны/улицы заменяются анонимизированными заглушками) и сохраненные данные карт (quote_payment, sales_order_payment: cc_number_enc, cc_cid_enc, cc_owner, additional_data обнуляются).

  2. Сброс учетных данных администратора — admin_user имя пользователя/email сбрасываются на значения-заглушки, а пароль перезаписывается хешем, который заведомо недействителен для любого реального пароля (блокирует вход через форму, пока оператор не установит реальный пароль через bin/magento admin:user:create).

  3. Принудительный перевод платежного шлюза в песочницу — bin/magento config:set принудительно устанавливает, например, payment/braintree/environment=sandbox, paypal/general/sandbox_flag=1.

  4. Замена ключей API третьих сторон — bin/magento config:set заменяет живые ключи (например, ShipperHQ, AvaTax) на фиктивные значения песочницы, чтобы ни один узел предпросмотра не мог совершить реальный платеж или реальный вызов API третьей стороны под производственными учетными данными.

  Точная структура таблиц и установленные интеграции реального клиентского приложения должны переопределять/расширять SanitizationConfig, а не полагаться на поставляемый по умолчанию вариант в продакшене — он существует как безопасная отправная точка, а не как обещание соответствия каждой схеме.

• Белый список приложений (HYPERNODE_APP_ALLOWLIST) — когда установлен, brancher_create, brancher_list и brancher_delete отказывают любому appname, не входящему в список.

• Проверка соответствия плану Falcons — brancher_create отклоняет приложения, не соответствующие плану, поддерживающему Brancher, до создания чего-либо.

• Защита только для -eph — brancher_exec и brancher_put проверяют node_name на соответствие шаблону <appname>-eph<id> (tools/_guards.py::validate_eph_node_name, .fullmatch() — без частичного совпадения или пропуска символов в конце) перед открытием любого SSH-соединения или подпроцесса. Структурно невозможно направить любой из этих инструментов на производственное имя хоста.

• Подтверждение перед удалением — brancher_delete никогда не удаляет при первом вызове. Он требует явного повторного вызова с confirm=True после отображения деталей целевого узла; настроенный порог или пометка узла как устаревшего сами по себе не являются подтверждением.

• Обязательная метка — brancher_create отклоняет вызовы без labels, поэтому каждый узел можно отследить до причины/заявки.

• Обработка токенов — HYPERNODE_API_TOKEN считывается только из окружения и никогда не записывается на диск или в конфигурацию плагина этим плагином.

• Усиление аргументов brancher_put — remote_path/local_path заключаются в кавычки для оболочки, а rsync запускается с --protect-args, поэтому оболочка удаленного хоста никогда не перепарсит аргумент пути, закрывая внедрение метасимволов через подделанный путь.

Эта конструкция была проверена в ходе аудита безопасности тремя специалистами перед выпуском (статический анализ, тестирование на проникновение, защитная проверка). Он выявил реальный критический пробел в более раннем черновике — санитизированный поток был построен как второй инструмент наряду с все еще открытым необработанным, несанитизированным путем создания — поэтому "один инструмент создания, никаких исключений" так настойчиво выделяется выше. Нашли проблему безопасности? Откройте issue, а не PR с деталями эксплуатации.

Ограничения (v1)

• Только Magento/Mage-OS. Конфигурация по умолчанию для слоя санитизации (DEFAULT_MAGENTO_SANITIZATION_CONFIG) и логика принятия решений о командах сборки навыка brancher-preview (decide_build_commands()) ориентированы на Magento. Это не универсальный многоплатформенный инструмент — WooCommerce, Shopware, Laravel и другие платформы, размещаемые на Hypernode, выходят за рамки v1. Для приложения, не основанного на Magento, потребуется как минимум собственноручно написанный SanitizationConfig, а последовательность сборки навыка предпросмотра не будет применяться.

• Нет SSH-ключей, управляемых MCP. brancher_exec/brancher_put обращаются к системным программам ssh/rsync и полностью полагаются на то, что ваш локальный SSH-агент/ключ уже имеет доступ к узлам Brancher (которые наследуют доступ автоматически через полное клонирование файловой системы Brancher с продакшена). Этот плагин никогда не предоставляет, не хранит и не передает ключевой материал.

• Только транспорт stdio. Нет удаленного/HTTP-транспорта MCP в v1 — это локальный плагин Claude Code, запускаемый каждым разработчиком с собственным HYPERNODE_API_TOKEN. Нет хостируемой/управляемой версии этого MCP. Токен и SSH-доступ полностью принадлежат клиенту.

• Только REST API. Нет интеграции с Hypernode Deploy (deploy.php) в v1.

• Учет минут по астрономическому времени, а не по бездействию. Проверка устаревания brancher-cleanup использует minutes, сообщаемые API Hypernode (время работы с момента создания) — он не может отличить бездействующий узел от активно используемого.

• Непроверенные формы ответов API. Ожидаемая форма ответа brancher_list ({"nodes": [{"name", "host", "minutes"}, ...]}) и имена полей плана/минут brancher_create (plan_type, brancher_minutes_remaining) являются задокументированными предположениями, еще не подтвержденными по контракту живого API Hypernode — см. строки документации модулей в src/pb_hypernode_mcp/tools/brancher_list.py и src/pb_hypernode_mcp/tools/brancher_create.py, если ответы API не совпадают во время выполнения. Выполните реальный дымовой тест create -> brancher_exec whoami на аккаунте с планом Falcons, прежде чем направлять это на клиента.

• Выгрузка тестов Playwright еще не реализована. Запуск функционального тестового набора на узле Brancher вместо локального/CI отслеживается отдельно — см. ProxiBlue/pb-hypernode-mcp#1 или исходный проектный тикет.

Разработка

git clone https://github.com/ProxiBlue/pb-hypernode-mcp
cd pb-hypernode-mcp
uv sync --extra dev

uv run pytest -v                     # 84 tests, mocked HTTP/SSH — no real Hypernode account touched
uv run ruff check src tests          # lint
uv run ruff format --check src tests # format check
uv run pyright src tests             # type check

Интеграционные тесты не запускаются автоматически на реальном аккаунте Hypernode. Если вы изменяете tools/brancher_exec.py или логику опроса достижимости в tools/brancher_spinup_flow.py, выполните ручной дымовой тест на реальном узле с планом Falcons перед слиянием — имитации не могут поймать неверное предположение о пользователе SSH или несоответствие формы в реальном ответе API.

Чтобы установить собственную копию для локальной разработки вместо опубликованной версии, укажите Claude Code прямо на папку:

claude plugin marketplace add pb-hypernode-mcp /path/to/your/clone
claude plugin install pb-hypernode-mcp@pb-hypernode-mcp

После редактирования навыков или серверного кода выполните claude plugin update pb-hypernode-mcp@pb-hypernode-mcp, чтобы применить изменения без повторного добавления на маркетплейс.

Если плагин не отображается после установки, проверьте: claude plugin list показывает pb-hypernode-mcp как включенный; новый сеанс Claude Code перечисляет инструменты brancher_* и три навыка brancher-*; HYPERNODE_API_TOKEN установлен в той же оболочке, из которой вы запустили Claude Code.

Лицензия

Apache-2.0. См. LICENSE и NOTICE для указания атрибуции сторонних зависимостей/служб (API Hypernode Brancher, системные ssh/rsync, MCP Python SDK).