pb-hypernode-mcp

Client-seitiges Claude Code Plugin für Hypernode Brancher — Erstellen von wegwerfbaren, produktionsidentischen Vorschauumgebungen, Durchführen KI-gestützter Änderungen per SSH, Anzeigen über Ihr vorhandenes Browser-MCP.

Warum

Brancher gibt Ihnen eine veränderbare, temporäre Kopie Ihres Produktions-Hypernode (≤24h alte Daten, vollständige Toolchain, echte Infrastruktur — keine Docker-Annäherung). Der Haken: Es klont die Produktion vollständig, was bedeutet, dass live Kundendaten (PII) und echte Zahlungs-/API-Zugangsdaten standardmäßig mitkommen, und der Knoten erhält eine öffentliche URL. Dieses Plugin schließt diese Lücke — jeder Knoten, den es erstellt, wird automatisch anonymisiert und in einer Sandbox ausgeführt, bevor er als bereit gemeldet wird, sodass „lass die KI des Kunden an einem echten Produktionsklon herumstochern“ nicht auch bedeutet, „echte Kundendaten im Internet preiszugeben“.

Related MCP server: DDEV MCP

Einrichtung

Drei Schritte: Plugin installieren, Hypernode-Token mitteilen, Claude Code neu starten.

1. Plugin installieren

Geben Sie dies direkt in Claude Code ein (kein Terminal erforderlich):

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

Claude Code lädt alles direkt von GitHub herunter – kein Herunterladen, kein separater Server zum Ausführen, nichts, was von Hand geklont werden muss.

(Wenn Sie es stattdessen lieber über ein Terminal ausführen möchten, funktionieren die gleichen Befehle als claude plugin marketplace add ... / claude plugin install ....)

2. Hypernode-API-Token hinzufügen

Dieses Plugin benötigt Ihr Hypernode-API-Token, um in Ihrem Namen mit Ihrem Hypernode-Konto zu kommunizieren. Es wird nirgendwo vom Plugin gespeichert – Sie setzen es als Umgebungsvariable, genau wie Sie einen passwortähnlichen Wert setzen würden.

Finden Sie Ihren Token im Hypernode-Control-Panel und geben Sie ihn dann in Ihrem Terminal ein (bevor Sie Claude Code öffnen):

export HYPERNODE_API_TOKEN="your-token-here"

Optional, aber empfohlen – schränken Sie ein, auf welche Hypernode-Apps dieses Plugin zugreifen darf, damit ein Tippfehler niemals die falsche Website trifft:

export HYPERNODE_APP_ALLOWLIST="myapp"

(Komma-getrennte mehrere App-Namen, z.B. "myapp,myapp2", wenn Sie mehr als eine verwalten.)

Tipp: Fügen Sie beide Zeilen zu Ihrer Shell-Startdatei (~/.zshrc oder ~/.bashrc) hinzu, damit Sie sie nicht jedes Mal neu eingeben müssen.

3. Claude Code neu starten

Schließen und öffnen Sie Claude Code erneut, damit es den Token erkennt und eine Verbindung zum Plugin herstellt. Sie sind startbereit.

Schnellstart

Fragen Sie einfach, in einfachem Englisch:

"Spin up a Brancher preview for myapp so I can show the client the new category page layout."

Claude erstellt den Knoten, wartet darauf, dass er online kommt, bereinigt ihn (siehe Sicherheitsvorkehrungen) und meldet sich zurück:

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

Von dort aus können Sie bitten, eine Änderung vorzunehmen und das Ergebnis anzuzeigen, oder einfach „Bereinige alle übrig gebliebenen Vorschauknoten“ sagen, wenn Sie fertig sind – Brancher berechnet pro Minute, unabhängig davon, ob jemand darauf schaut.

Was das Plugin enthält

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

Voraussetzungen

• Ein Hypernode-Konto mit einem Falcons-Plan, mit einem API-Token aus dem Control Panel (Brancher ist eine reine Falcons-Funktion).

• Der SSH-Schlüssel, den Sie bereits verwenden, um auf Ihren Hypernode zuzugreifen – nichts zusätzlich einzurichten, Brancher-Vorschauknoten erben den Zugriff automatisch.

• Python 3.11+ und uv auf dem Rechner installiert, auf dem Claude Code läuft (Claude Code-Plugins sind nur Code – das ist die Laufzeitumgebung, die sie benötigen).

MCP-Tools

Alle 6 Tools sind auf dem pb-hypernode-mcp-Server (src/pb_hypernode_mcp/server.py) registriert. brancher_exec und brancher_put greifen auf die systemeigenen ssh/rsync-Binärdateien zu, wobei sie Ihren bereits konfigurierten lokalen SSH-Agent/Schlüssel verwenden – dieses Plugin speichert selbst kein Schlüsselmaterial.

Fähigkeiten

• brancher-spinup — Erstellt einen wegwerfbaren Brancher-Vorschauknoten, der aus der Produktion geklont wurde, mit obligatorischer automatischer Bereinigung und meldet seine Zugriffs-URL. Verwenden Sie dies, wenn ein Kunde darum bittet, eine Änderung in einer echten Produktionsklon-Umgebung vor dem Ausliefern zu prüfen. Kapselt den einzelnen brancher_create-Toolaufruf – reproduziert niemals die Erstellungs-/Warte-/Bereinigungssequenz von Hand.

• brancher-preview — Der vollständige Kreislauf: Erstellen eines Knotens (über die brancher-spinup-Fähigkeit), Anwenden einer Codeänderung (einen lokalen Diff mit brancher_put übertragen oder direkt mit brancher_exec bearbeiten), Ausführen nur der Magento-Build-Befehle, die die Änderung tatsächlich benötigt (decide_build_commands() in src/pb_hypernode_mcp/preview_logic.py), Anzeigen des Ergebnisses über das im Browser bereits vorhandene MCP-Tool, dann explizites Erinnern des Benutzers, dass der Knoten immer noch Brancher-Minuten verbraucht. Verwenden Sie dies, wenn ein Kunde eine durchgängige Ansicht einer Änderung in einer wegwerfbaren Umgebung wünscht. Löscht den Knoten selbst nie.

• brancher-cleanup — Listet aktive Knoten mit brancher_list auf, markiert alle, die einen Altersschwellenwert erreicht oder überschritten haben (minutes >= threshold_minutes, Standard 240 Minuten / 4 Stunden, über flag_stale_nodes() in src/pb_hypernode_mcp/cleanup_logic.py), und löscht markierte Knoten (einzeln oder in großen Mengen) nur nach expliziter Benutzerbestätigung. Verwenden Sie dies, wenn ein Kunde übrig gebliebene Brancher-Knoten überprüfen oder entfernen möchte, um die Minutenakkumulation zu stoppen. Brancher berechnet Echtzeit-Minuten ab der Erstellung, unabhängig davon, ob jemand den Knoten aktiv nutzt.

Sicherheitsvorkehrungen

• Erzwungene Bereinigung – kann nicht deaktiviert werden. Jeder brancher_create-Aufruf führt die vollständige Bereinigungssequenz (src/pb_hypernode_mcp/sanitization/) gegen den Node aus, bevor er jemals als "ready" gemeldet wird oder eine access_url zurückgibt. Es gibt kein Flag, keine Konfigurationsoption und keinen Umgehungspfad – brancher_create ist das EINZIGE Node-Erstellungs-MCP-Tool, das dieses Plugin registriert (es gibt kein separates, ungereinigtes Erstellungstool), und spinup_sanitized_brancher_node() in src/pb_hypernode_mcp/tools/brancher_spinup_flow.py (die dahinterstehende Funktion) kann strukturell keine Zugriffs-URL zurückgeben, ohne dass zuvor jeder Bereinigungsbefehl mit Exit-Code 0 beendet wurde. Wenn ein Bereinigungsbefehl zwischendurch fehlschlägt, löst das Tool SanitizationFailedError aus und enthält die Zugriffs-URL bewusst zurück – die Ausnahme trägt sie nicht einmal, sodass ein abfangender Aufrufer sie nicht versehentlich preisgeben kann.

  Die Sequenz (konfigurationsgesteuert, Magento-förmiger Standard in sanitization/config.py::DEFAULT_MAGENTO_SANITIZATION_CONFIG):

  1. PII-Anonymisierung – UPDATE-Anweisungen (via n98-magerun2 db:query) gegen customer_entity, customer_address_entity, sales_order, sales_order_address (Namen/E-Mails/Telefone/Straße durch anonymisierte Platzhalter ersetzt) und gespeicherte Kartendaten (quote_payment, sales_order_payment: cc_number_enc, cc_cid_enc, cc_owner, additional_data auf null gesetzt).

  2. Admin-Anmeldedaten zurücksetzen – admin_user Benutzername/E-Mail auf Platzhalterwerte zurückgesetzt und Passwort mit einem Hash überschrieben, der absichtlich für jedes echte Passwort ungültig ist (sperrt formularbasiertes Login, bis ein Betreiber ein echtes via bin/magento admin:user:create setzt).

  3. Payment-Gateway-Sandbox-Erzwingung – bin/magento config:set erzwingt z. B. payment/braintree/environment=sandbox, paypal/general/sandbox_flag=1.

  4. Third-Party-API-Key-Stubbing – bin/magento config:set ersetzt Live-Keys (z. B. ShipperHQ, AvaTax) durch Dummy-Sandbox-Werte, sodass kein Vorschau-Node eine echte Belastung oder einen echten Third-Party-API-Aufruf mit Produktionsanmeldedaten durchführen kann.

  Die genaue Tabellenstruktur und die installierten Integrationen einer echten Client-App sollten SanitizationConfig überschreiben/erweitern, nicht auf den ausgelieferten Standard in der Produktion vertrauen – er existiert als sicherer Standard-Ausgangspunkt, nicht als Versprechen, dass er jedes Schema abdeckt.

• App-Allowlist (HYPERNODE_APP_ALLOWLIST) – wenn gesetzt, lehnen brancher_create, brancher_list und brancher_delete jeden appname ab, der nicht auf der Liste steht.

• Falcons-Plan-Berechtigungsprüfung – brancher_create lehnt Apps ab, die sich nicht in einem Brancher-berechtigten Plan befinden, bevor etwas erstellt wird.

• -eph-nur-Schutz – brancher_exec und brancher_put validieren node_name gegen das <appname>-eph<id>-Muster (tools/_guards.py::validate_eph_node_name, .fullmatch() – keine Teilübereinstimmungen oder nachgestellte Zeichenlücken), bevor eine SSH-Verbindung oder ein Unterprozess geöffnet wird. Es ist strukturell unmöglich, eines der Tools auf einen Produktions-Hostnamen zu richten.

• Bestätigung-vor-Löschung – brancher_delete löscht nie beim ersten Aufruf. Es erfordert einen expliziten erneuten Aufruf mit confirm=True, nachdem die Details des Ziel-Nodes angezeigt wurden; eine konfigurierte Schwelle oder ein als veraltet markierter Node ist niemals selbst eine Bestätigung.

• Erforderliches Label – brancher_create lehnt Aufrufe ohne labels ab, sodass jeder Node auf einen Grund/Ticket zurückverfolgbar ist.

• Token-Handhabung – HYPERNODE_API_TOKEN wird nur aus der Umgebung gelesen und von diesem Plugin niemals auf die Festplatte oder in die Plugin-Konfiguration geschrieben.

• brancher_put-Argumenthärtung – remote_path/local_path werden shell-quoted und rsync läuft mit --protect-args, sodass die Shell des entfernten Hosts ein Pfadargument nie neu parst, wodurch Metazeichen-Injektion über einen manipulierten Pfad unterbunden wird.

Dieses Design wurde vor der Veröffentlichung von einer 3-Spezialisten-Sicherheitsüberprüfung geprüft (statische Analyse, adversariales Testen, defensives Audit). Es deckte eine echte kritische Lücke in einem früheren Entwurf auf – der bereinigte Ablauf war als zweites Tool neben einem noch exponierten rohen, ungereinigten Erstellungspfad gebaut worden – weshalb „ein Erstellungstool, keine Ausnahmen“ oben so nachdrücklich betont wird. Ein Sicherheitsproblem gefunden? Eröffnen Sie ein Issue anstelle eines PRs mit den Exploit-Details.

Einschränkungen (v1)

• Nur Magento/Mage-OS. Die Standardkonfiguration der Bereinigungsschicht (DEFAULT_MAGENTO_SANITIZATION_CONFIG) und die Build-Befehl-Entscheidungslogik des brancher-preview-Skills (decide_build_commands()) sind beide Magento-förmig. Dies ist kein generisches Multiplattform-Tool – WooCommerce, Shopware, Laravel und andere von Hypernode gehostete Plattformen sind für v1 nicht vorgesehen. Eine Nicht-Magento-App würde mindestens ein handgeschriebenes SanitizationConfig benötigen, und die Build-Sequenz des Preview-Skills würde nicht zutreffen.

• Keine MCP-verwalteten SSH-Schlüssel. brancher_exec/brancher_put greifen auf die systemeigenen ssh/rsync-Binärdateien zurück und verlassen sich vollständig darauf, dass Ihr eigener lokaler SSH-Agent/Schlüssel bereits Zugriff auf Brancher-Nodes hat (die den Zugriff automatisch über Branchers vollständiges Dateisystem-Klon aus der Produktion erben). Dieses Plugin stellt niemals Schlüsselmaterial bereit, speichert es oder überträgt es.

• Nur stdio-Transport. Kein Remote/HTTP-MCP-Transport in v1 – dies ist ein lokales Claude Code-Plugin, das pro Entwickler gegen seinen eigenen HYPERNODE_API_TOKEN ausgeführt wird. Es gibt keine gehostete/verwaltete Version dieses MCP. Token- und SSH-Zugriff liegen vollständig in der Hand des Clients.

• Nur REST-API. Keine Hypernode Deploy (deploy.php)-Integration in v1.

• Wanduhr-basierte, nicht leerlauferkennende Minutenabrechnung. Die Veralterungsprüfung von brancher-cleanup verwendet minutes, wie von der Hypernode-API gemeldet (Betriebszeit seit Erstellung) – sie kann einen inaktiven Node nicht von einem aktiv genutzten unterscheiden.

• Nicht verifizierte API-Antwortstrukturen. Die erwartete Antwortstruktur von brancher_list ({"nodes": [{"name", "host", "minutes"}, ...]}) und die Feldnamen für Plan/Minuten von brancher_create (plan_type, brancher_minutes_remaining) sind dokumentierte Annahmen, die noch nicht gegen den Live-Hypernode-API-Vertrag bestätigt wurden – siehe die Modul-Docstrings in src/pb_hypernode_mcp/tools/brancher_list.py und src/pb_hypernode_mcp/tools/brancher_create.py, wenn API-Antworten zur Laufzeit nicht übereinstimmen. Führen Sie einen echten create -> brancher_exec whoami-Smoke-Test gegen ein Falcons-Plan-Konto durch, bevor Sie dies auf einen Client ausrichten.

• Playwright-Test-Auslagerung noch nicht implementiert. Das Ausführen der funktionalen Testsuite gegen einen Brancher-Node anstatt lokal/CI wird separat verfolgt – siehe ProxiBlue/pb-hypernode-mcp#1 oder das ursprüngliche Design-Ticket.

Entwicklung

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

Es werden keine Integrationstests automatisch gegen ein echtes Hypernode-Konto ausgeführt. Wenn Sie tools/brancher_exec.py oder die Erreichbarkeits-Polling-Logik in tools/brancher_spinup_flow.py ändern, führen Sie vor dem Mergen einen manuellen Smoke-Test gegen einen echten Falcons-Plan-Node durch – Mocks können eine falsche SSH-Benutzerannahme oder eine Strukturinkonsistenz in der echten API-Antwort nicht abfangen.

Um Ihren eigenen Klon für die lokale Entwicklung anstelle der veröffentlichten Version zu installieren, richten Sie Claude Code direkt auf den Ordner:

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

Nachdem Sie Skills oder Servercode bearbeitet haben, führen Sie claude plugin update pb-hypernode-mcp@pb-hypernode-mcp aus, um die Änderung zu übernehmen, ohne den Marktplatz erneut hinzuzufügen.

Wenn das Plugin nach der Installation nicht angezeigt wird, überprüfen Sie: claude plugin list zeigt pb-hypernode-mcp als aktiviert; eine neue Claude Code-Sitzung listet die brancher_*-Tools und die drei brancher-*-Skills auf; HYPERNODE_API_TOKEN ist in derselben Shell gesetzt, von der aus Sie Claude Code gestartet haben.

Lizenz

Apache-2.0. Siehe LICENSE und NOTICE für die Zuschreibung von Drittanbieter-Abhängigkeiten/Diensten (Hypernode Brancher API, system ssh/rsync, MCP Python SDK).