pb-hypernode-mcp

クライアント側のClaude Codeプラグイン for Hypernode Brancher — 使い捨てのプロダクションクローンプレビュー環境を起動し、SSH経由でAI支援による変更を加え、既存のブラウザMCPを介して表示します。

なぜ必要か

Brancherは、本番Hypernodeの可変的な一時コピーを提供します（最大24時間前のデータ、完全なツールチェーン、実際のインフラ — Dockerの近似ではありません）。ただし欠点として、本番環境を丸ごとクローンするため、デフォルトでは実際の顧客の個人情報や本物の決済・API認証情報もそのまま含まれ、ノードには公開URLが割り当てられます。このプラグインはそのギャップを埋めるものです — 作成されるすべてのノードは、準備完了と報告される前に自動的に匿名化およびサンドボックス化されるため、「クライアントのAIに本番クローンを触らせる」という行為が「実際の顧客データをインターネット上にさらす」ことを意味しなくなります。

Related MCP server: DDEV MCP

セットアップ

3つの手順：プラグインのインストール、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. Hypernode APIトークンの追加

このプラグインは、あなたのHypernodeアカウントとやり取りするためにHypernode APIトークンを必要とします。プラグインによってトークンが保存されることは一切ありません — 環境変数として設定する方法で、パスワードのような値を設定するのと同じ方法です。

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を閉じて再度開き、トークンを読み込んでプラグインに接続させます。準備完了です。

クイックスタート

あとは、普通の英語で質問するだけです：

"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トークン（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エージェント/キーを使用してシステムの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 呼び出しは、ノードが "準備完了" と報告されるか access_url を返す前に、完全なサニタイゼーションシーケンス (src/pb_hypernode_mcp/sanitization/) を実行します。フラグ、設定オプション、バイパスパスはありません — brancher_create はこのプラグインが登録する唯一のノード作成MCPツールです（別のサニタイズされていない作成ツールはありません）。また、その背後にある関数 spinup_sanitized_brancher_node() (src/pb_hypernode_mcp/tools/brancher_spinup_flow.py) は、すべてのサニタイゼーションコマンドが終了コード0で終了するまで、構造的に access_url を返すことができません。サニタイゼーションコマンドが途中で失敗した場合、ツールは SanitizationFailedError を発生させ、意図的に access_url を隠蔽します — 例外はそれを保持していないため、キャッチする呼び出し元が誤ってそれを表面化する方法はありません。

  シーケンス（設定駆動、sanitization/config.py::DEFAULT_MAGENTO_SANITIZATION_CONFIG にMagento向けデフォルト）：

  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 をNULL化）。

  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接続やサブプロセスを開く前に、node_name を <appname>-eph<id> パターンに対して検証します（tools/_guards.py::validate_eph_node_name、.fullmatch() — 部分一致や末尾文字のギャップはありません）。どちらのツールも本番ホスト名を指すことは構造的に不可能です。

• 削除前確認 — brancher_delete は最初の呼び出しでは決して削除しません。ターゲットノードの詳細を表示した後、明示的な confirm=True の再呼び出しが必要です。しきい値が設定されていることやノードが古いとフラグが立っていることは、それ自体が確認にはなりません。

• 必須ラベル — brancher_create は labels がない呼び出しを拒否するため、すべてのノードは理由/チケットにトレース可能です。

• トークン処理 — HYPERNODE_API_TOKEN は環境からのみ読み取られ、このプラグインによってディスクやプラグイン設定に書き込まれることはありません。

• brancher_put 引数の強化 — remote_path/local_path はシェルクォートされ、rsync は --protect-args で実行されるため、リモートホストのシェルがパス引数を再解析することはなく、細工されたパスによるメタキャラクタインジェクションを遮断します。

この設計はリリース前に3人の専門家によるセキュリティレビュー（静的解析、敵対的テスト、防御的監査）でチェックされました。初期のドラフトで実際の重大なギャップを発見しました — サニタイズされたフローが、まだ露出している生のサニタイズされていない作成パスと並んで2番目のツールとして構築されていたため、上記で「作成ツールは1つ、例外なし」としつこく強調されています。セキュリティ問題を発見しましたか？ エクスプロイトの詳細を含むPRではなく、Issueを開いてください。

制限事項 (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_* ツールと3つの brancher-* スキルがリストされること；HYPERNODE_API_TOKEN がClaude Codeを起動したシェルで設定されていること。

ライセンス

Apache-2.0。サードパーティの依存関係/サービスの帰属（Hypernode Brancher API、システム ssh/rsync、MCP Python SDK）については LICENSE および NOTICE を参照してください。