pb-hypernode-mcp

Claude Code 的客户端插件，用于 Hypernode Brancher — 快速创建可丢弃的生产环境克隆预览节点，通过 SSH 驱动 AI 辅助更改，并通过你现有的浏览器 MCP 查看。

为什么需要它

Brancher 会为你提供一个可变、临时的生产环境 Hypernode 副本（包含 ≤24小时前的数据、完整的工具链、真实的基础设施 — 而非 Docker 模拟）。问题在于：它会完整克隆生产环境，这意味着真实的客户 PII（个人身份信息）以及真实的支付/API 凭证也会默认被包含进来，并且该节点会获得一个公开 URL。本插件弥补了这一差距 — 它创建的每一个节点都会自动进行匿名化和沙箱化处理，在报告就绪之前完成，因此“让客户端的 AI 在一个真实的克隆生产环境中操作”并不意味着“将真实的客户数据暴露在互联网上”。

Related MCP server: DDEV MCP

设置

三个步骤：安装插件、告诉它你的 Hypernode Token、重启 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. 添加你的 Hypernode API Token

本插件需要你的 Hypernode API Token 才能代表你与你的 Hypernode 账户通信。它不会被插件存储在任何地方 — 你将其设置为环境变量，就像设置任何密码类值一样。

在你的 Hypernode 控制面板中查找你的 Token，然后在你的终端中（在打开 Claude Code 之前）执行：

export HYPERNODE_API_TOKEN="your-token-here"

（可选但推荐）限制此插件允许操作的 Hypernode 应用，以防止因输入错误而误操作到错误的站点：

export HYPERNODE_APP_ALLOWLIST="myapp"

（如果管理多个应用，请用逗号分隔多个应用名称，例如 "myapp,myapp2"。）

提示：将这两行添加到你的 shell 启动文件（~/.zshrc 或 ~/.bashrc）中，这样你就不必每次都重新输入了。

3. 重启 Claude Code

关闭并重新打开 Claude Code，以便它获取 Token 并与插件建立连接。一切准备就绪。

快速开始

只需用普通英文提问：

“为 myapp 创建一个 Brancher 预览环境，以便我可以向客户展示新的分类页面布局。”

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

要求

• 一个 Falcons 计划中的 Hypernode 账户，并具有来自控制面板的 API Token（Brancher 是 Falcons 独有的功能）。

• 你用于连接 Hypernode 的 SSH 密钥 — 无需额外设置，Brancher 预览节点会自动继承访问权限。

• 在运行 Claude Code 的机器上安装 Python 3.11+ 和 uv（Claude Code 插件本质上是代码 — 这是它们所需的运行时环境）。

MCP 工具

所有 6 个工具都在 pb-hypernode-mcp 服务器（src/pb_hypernode_mcp/server.py）上注册。brancher_exec 和 brancher_put 使用你已经配置好的本地 SSH agent/密钥调用系统 ssh/rsync 二进制文件 — 本插件本身不持有或存储密钥材料。

技能

• brancher-spinup — 从生产环境克隆创建一个可丢弃的 Brancher 预览节点，包含强制自动清理，并报告其访问 URL。当客户希望在变更上线前，在真实的克隆生产环境中预览变更时使用。封装了单一的 brancher_create 工具调用 — 绝不手动重复创建/等待/清理序列。

• brancher-preview — 完整流程：启动一个节点（通过 brancher-spinup 技能），应用代码变更（使用 brancher_put 推送本地差异，或使用 brancher_exec 就地编辑），仅运行变更实际需要的 Magento 构建命令（src/pb_hypernode_mcp/preview_logic.py 中的 decide_build_commands()），通过会话中已有的任何浏览器 MCP 工具查看结果，然后明确提醒用户该节点仍在消耗 Brancher 分钟数。当客户希望在一个可丢弃的环境中端到端查看变更时使用。绝不自行删除节点。

• brancher-cleanup — 使用 brancher_list 列出活动节点，标记任何已达到或超过某个时间阈值（minutes >= threshold_minutes，默认 240 分钟/4 小时，通过 src/pb_hypernode_mcp/cleanup_logic.py 中的 flag_stale_nodes() 实现），仅在获得用户明确确认后删除被标记的节点（单个或批量）。当客户希望检查或移除剩余的 Brancher 节点以停止分钟数累积时使用。Brancher 按自创建以来的运行时间计费，无论是否有人正在使用该节点。

安全护栏

• 强制净化——不可禁用。 每次调用 brancher_create 都会在节点被报告为 "ready" 或返回 access_url 之前，对其执行完整的净化序列（src/pb_hypernode_mcp/sanitization/）。没有标志、配置选项或绕过路径——brancher_create 是该插件注册的唯一节点创建 MCP 工具（没有单独的、未净化的创建工具），并且 src/pb_hypernode_mcp/tools/brancher_spinup_flow.py 中的 spinup_sanitized_brancher_node()（其背后的函数）在结构上无法在每条净化命令都成功退出（退出码为 0）之前返回访问 URL。如果净化命令中途失败，该工具会引发 SanitizationFailedError 并故意不提供访问 URL——异常本身甚至不携带该 URL，因此捕获它的调用方无法意外地将其暴露出来。

  该序列（由配置驱动，默认的 Magento 形状配置位于 sanitization/config.py::DEFAULT_MAGENTO_SANITIZATION_CONFIG）：

  1. PII 匿名化——针对 customer_entity、customer_address_entity、sales_order、sales_order_address 执行 UPDATE 语句（通过 n98-magerun2 db:query）（姓名/电子邮件/电话/街道被替换为匿名占位符），并将存储的卡数据（quote_payment、sales_order_payment：cc_number_enc、cc_cid_enc、cc_owner、additional_data）置空。

  2. 管理员凭据重置——admin_user 用户名/电子邮件重置为占位值，密码被覆盖为对任何真实密码都故意无效的哈希值（锁定基于表单的登录，直到操作员通过 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 在打开任何 SSH 连接或子进程之前，会针对 <appname>-eph<id> 模式（tools/_guards.py::validate_eph_node_name，.fullmatch()——无部分匹配或尾随字符间隙）验证 node_name。在结构上，不可能将任一工具指向生产主机名。

• 确认后再删除——brancher_delete 在首次调用时从不删除。它需要在显示目标节点的详细信息后，进行显式的 confirm=True 重新调用；配置了阈值或节点被标记为过期本身绝不构成确认。

• 强制标签——brancher_create 拒绝没有 labels 的调用，因此每个节点都可追溯到某个原因/工单。

• 令牌处理——HYPERNODE_API_TOKEN 仅从环境变量读取，此插件从不将其写入磁盘或插件配置。

• brancher_put 参数强化——remote_path/local_path 经过 shell 引用，并且 rsync 使用 --protect-args 运行，因此远程主机的 shell 永远不会重新解析路径参数，从而阻止通过精心构造的路径进行元字符注入。

此设计在发布前经过了 3 位专家的安全审查（静态分析、对抗性测试、防御性审计）。它发现了一个早期草案中的真实关键漏洞——净化流程是作为第二个工具构建的，同时还有一个仍然暴露的原始、未净化的创建路径——这就是上面如此坚持地指出“一个创建工具，没有例外”的原因。发现了安全问题？请提交一个包含漏洞详细信息的问题，而不是拉取请求。

局限性（v1）

• 仅限 Magento/Mage-OS。 净化层的默认配置（DEFAULT_MAGENTO_SANITIZATION_CONFIG）和 brancher-preview 技能的构建命令决策逻辑（decide_build_commands()）都是针对 Magento 的。这不是一个通用的多平台工具——WooCommerce、Shopware、Laravel 和其他 Hypernode 托管的平台不在 v1 的范围内。非 Magento 应用至少需要一个手写的 SanitizationConfig，并且预览技能的构建序列将不适用。

• 无 MCP 管理的 SSH 密钥。 brancher_exec/brancher_put 调用系统 ssh/rsync 二进制文件，并完全依赖您自己的本地 SSH 代理/密钥已经有权访问 Brancher 节点（这些节点通过 Brancher 从生产环境进行的完整文件系统克隆自动继承访问权限）。此插件从不配置、存储或传输密钥材料。

• 仅 stdio 传输。 v1 中没有远程/HTTP MCP 传输——这是一个本地 Claude Code 插件，每个开发者针对自己的 HYPERNODE_API_TOKEN 运行。此 MCP 没有托管/管理版本。令牌和 SSH 访问完全由客户端拥有。

• 仅 REST API。 v1 中没有 Hypernode Deploy（deploy.php）集成。

• 挂钟时间（非空闲感知）分钟计算。 brancher-cleanup 的过期检查使用 Hypernode API 报告的 minutes（自创建以来的运行时间）——它无法区分空闲节点和活跃使用的节点。

• 未经验证的 API 响应结构。 brancher_list 的预期响应结构（{"nodes": [{"name", "host", "minutes"}, ...]}）和 brancher_create 的计划/分钟字段名称（plan_type、brancher_minutes_remaining）是文档化的假设，尚未针对实时 Hypernode API 合同进行确认——如果运行时 API 响应不匹配，请参阅 src/pb_hypernode_mcp/tools/brancher_list.py 和 src/pb_hypernode_mcp/tools/brancher_create.py 中的模块文档字符串。在将此工具指向客户端之前，请针对 Falcons 计划账户运行一次真实的创建 -> brancher_exec whoami 冒烟测试。

• 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 的同一 shell 中设置。

许可证

Apache-2.0。有关第三方依赖项/服务归属（Hypernode Brancher API、系统 ssh/rsync、MCP Python SDK），请参阅 LICENSE 和 NOTICE。