pb-hypernode-mcp

Plugin de Claude Code del lado del cliente para Hypernode Brancher: crea entornos de vista previa desechables, clones de producción, realiza cambios asistidos por IA a través de SSH y visualiza el resultado a través de tu MCP de navegador existente.

Por qué

Brancher te proporciona una copia mutable y temporal de tu Hypernode de producción (datos de hasta 24 horas de antigüedad, cadena de herramientas completa, infraestructura real, no una aproximación con Docker). El inconveniente: clona la producción al completo, lo que significa que los datos personales de clientes reales y las credenciales de pago/API reales se incluyen por defecto, y el nodo obtiene una URL pública. Este plugin cierra esa brecha: cada nodo que crea se anonimiza y se aísla automáticamente, antes de que se informe como listo, para que «permitir que la IA del cliente manipule un clon de producción real» no signifique también «exponer datos reales de clientes en internet».

Related MCP server: DDEV MCP

Configuración

Tres pasos: instala el plugin, indica tu token de Hypernode, reinicia Claude Code.

1. Instala el plugin

Escribe esto directamente en Claude Code (no necesitas terminal):

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

Claude Code obtiene todo directamente desde GitHub: sin descargas, sin servidores separados que ejecutar, nada que clonar manualmente.

(Si prefieres ejecutarlo desde una terminal, los mismos comandos funcionan como claude plugin marketplace add ... / claude plugin install ...).

2. Añade tu token de API de Hypernode

Este plugin necesita tu token de API de Hypernode para comunicarse con tu cuenta de Hypernode en tu nombre. Nunca se almacena en el plugin: lo estableces como una variable de entorno, de la misma manera que establecerías cualquier valor similar a una contraseña.

Encuentra tu token en el Panel de Control de tu Hypernode, luego en tu terminal (antes de abrir Claude Code):

export HYPERNODE_API_TOKEN="your-token-here"

Opcional pero recomendado: restringe qué aplicaciones de Hypernode puede tocar este plugin, para que un error tipográfico nunca pueda afectar al sitio equivocado:

export HYPERNODE_APP_ALLOWLIST="myapp"

(Separa con comas varios nombres de aplicación, ej. "miapp,miapp2", si gestionas más de una).

Consejo: añade ambas líneas al archivo de inicio de tu shell (~/.zshrc o ~/.bashrc) para no tener que reescribirlas cada vez.

3. Reinicia Claude Code

Cierra y vuelve a abrir Claude Code para que reconozca el token y se conecte al plugin. Ya estás listo.

Inicio rápido

Simplemente pregunta, en lenguaje natural:

«Crea una vista previa de Brancher para miapp para que pueda mostrar al cliente el nuevo diseño de la página de categorías.»

Claude crea el nodo, espera a que esté en línea, lo sanitiza (consulta Certificados de seguridad) e informa:

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

A partir de ahí, pídele que haga un cambio y te muestre el resultado, o simplemente di «limpia los nodos de vista previa sobrantes» cuando hayas terminado. Brancher factura por minuto, tanto si alguien lo está viendo como si no.

Qué incluye el plugin

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

Requisitos

• Una cuenta de Hypernode en un plan Falcons, con un token de API del Panel de Control (Brancher es una función exclusiva de Falcons).

• La clave SSH que ya usas para acceder a tu Hypernode: no hay nada extra que configurar, los nodos de vista previa de Brancher heredan el acceso automáticamente.

• Python 3.11+ y uv instalados en la máquina que ejecuta Claude Code (los plugins de Claude Code son solo código; este es el entorno de ejecución que necesitan).

Herramientas MCP

Las 6 herramientas están registradas en el servidor pb-hypernode-mcp (src/pb_hypernode_mcp/server.py). brancher_exec y brancher_put ejecutan los binarios del sistema ssh/rsync utilizando tu agente/clave SSH local ya configurada; este plugin nunca almacena ni retiene material de clave por sí mismo.

Habilidades

• brancher-spinup — crea un nodo de vista previa Brancher desechable clonado de producción, con sanitización automática obligatoria, e informa de su URL de acceso. Úsalo cuando un cliente quiera previsualizar un cambio en un entorno clonado de producción real antes de implementarlo. Envuelve la única llamada a la herramienta brancher_create: nunca reproduce la secuencia de crear/esperar/sanitizar manualmente.

• brancher-preview — el bucle completo: crea un nodo (mediante la habilidad brancher-spinup), aplica un cambio de código (envía un diff local con brancher_put, o edita en el lugar con brancher_exec), ejecuta solo los comandos de compilación de Magento que el cambio realmente necesita (decide_build_commands() en src/pb_hypernode_mcp/preview_logic.py), visualiza el resultado a través de la herramienta MCP del navegador que ya esté en la sesión, y luego recuerda explícitamente al usuario que el nodo sigue facturando minutos de Brancher. Úsalo cuando un cliente quiera una visión integral de un cambio en un entorno desechable. Nunca elimina el nodo por sí mismo.

• brancher-cleanup — lista los nodos activos con brancher_list, marca cualquier nodo que esté o supere un umbral de edad (minutes >= threshold_minutes, por defecto 240 minutos / 4 horas, mediante flag_stale_nodes() en src/pb_hypernode_mcp/cleanup_logic.py), y elimina los nodos marcados (individualmente o en lote) solo después de la confirmación explícita del usuario. Úsalo cuando un cliente quiera buscar o eliminar nodos Brancher sobrantes para detener la acumulación de minutos. Brancher factura minutos de pared desde la creación, independientemente de si alguien está usando activamente el nodo.

Certificados de seguridad

• Desinfección obligatoria: no se puede desactivar. Cada llamada brancher_create ejecuta la secuencia completa de desinfección (src/pb_hypernode_mcp/sanitization/) en el nodo antes de que se informe como "ready" o devuelva un access_url. No hay bandera, opción de configuración ni ruta de omisión: brancher_create es la ÚNICA herramienta MCP de creación de nodos que registra este plugin (no hay una herramienta de creación independiente sin desinfección), y spinup_sanitized_brancher_node() en src/pb_hypernode_mcp/tools/brancher_spinup_flow.py (la función que hay detrás) no puede devolver estructuralmente una URL de acceso sin que todos los comandos de desinfección hayan salido con 0 primero. Si un comando de desinfección falla a mitad del proceso, la herramienta lanza SanitizationFailedError y retiene deliberadamente la URL de acceso; la excepción ni siquiera la lleva, por lo que una persona que la recopte no tiene forma de exponerla accidentalmente.

  La secuencia (impulsada por configuración, con valores predeterminados con forma de Magento en sanitization/config.py::DEFAULT_MAGENTO_SANITIZATION_CONFIG):

  1. Anonimización de PII — Sentencias UPDATE (a través de n98-magerun2 db:query) contra customer_entity, customer_address_entity, sales_order, sales_order_address (nombres/correos electrónicos/teléfonos/calle reemplazados con marcadores de posición anonimizados) y datos de tarjetas almacenados (quote_payment, sales_order_payment: cc_number_enc, cc_cid_enc, cc_owner, additional_data anulados).

  2. Restablecimiento de credenciales de administrador — nombre de usuario/correo electrónico de admin_user restablecido a valores de marcador de posición y contraseña sobrescrita con un hash que es deliberadamente inválido para cualquier contraseña real (bloquea el inicio de sesión basado en formularios hasta que un operador establezca una contraseña real a través de bin/magento admin:user:create).

  3. Forzar modo de prueba para pasarela de pago — bin/magento config:set fuerza, por ejemplo, payment/braintree/environment=sandbox, paypal/general/sandbox_flag=1.

  4. Sustitución de claves API de terceros — bin/magento config:set reemplaza claves reales (por ejemplo, ShipperHQ, AvaTax) con valores de prueba ficticios para que ningún nodo de vista previa pueda realizar un cobro real o una llamada API real de terceros con credenciales de producción.

  La forma exacta de las tablas y las integraciones instaladas de una aplicación cliente real deben sobrescribir/extender SanitizationConfig, no depender del valor predeterminado incluido en producción; existe como punto de partida seguro por defecto, no como una promesa de que coincida con cada esquema.

• Lista blanca de aplicaciones (HYPERNODE_APP_ALLOWLIST): cuando está configurada, brancher_create, brancher_list y brancher_delete rechazan cualquier appname que no esté en la lista.

• Comprobación de elegibilidad del plan Falcons — brancher_create rechaza aplicaciones que no estén en un plan elegible para Brancher antes de crear nada.

• Protección exclusiva -eph — brancher_exec y brancher_put validan node_name contra el patrón <appname>-eph<id> (tools/_guards.py::validate_eph_node_name, .fullmatch() — sin coincidencias parciales ni espacios de caracteres finales) antes de abrir cualquier conexión SSH o subproceso. Es estructuralmente imposible apuntar cualquiera de las herramientas a un nombre de host de producción.

• Confirmar antes de eliminar — brancher_delete nunca elimina en la primera llamada. Requiere una nueva llamada explícita con confirm=True después de mostrar los detalles del nodo de destino; el hecho de que se haya configurado un umbral o que un nodo se haya marcado como obsoleto nunca es en sí mismo una confirmación.

• Etiqueta obligatoria — brancher_create rechaza llamadas sin labels, por lo que cada nodo se puede rastrear hasta un motivo/ticket.

• Manejo de tokens — HYPERNODE_API_TOKEN se lee solo del entorno y este plugin nunca lo escribe en el disco ni en la configuración del plugin.

• Protección de argumentos de brancher_put — remote_path/local_path se entrecomillan para el shell y rsync se ejecuta con --protect-args, por lo que el shell del host remoto nunca vuelve a analizar un argumento de ruta, bloqueando la inyección de metacaracteres a través de una ruta manipulada.

Este diseño fue verificado por una revisión de seguridad de 3 especialistas antes del lanzamiento (análisis estático, pruebas adversarias, auditoría defensiva). Detectó una brecha crítica real en un borrador anterior: el flujo desinfectado se había creado como una segunda herramienta junto a una ruta de creación sin desinfección aún expuesta, por lo que se insiste tanto en "una herramienta de creación, sin excepciones". ¿Encontraste un problema de seguridad? Abre un issue en lugar de un PR con los detalles del exploit.

Limitaciones (v1)

• Solo Magento/Mage-OS. La configuración predeterminada de la capa de desinfección (DEFAULT_MAGENTO_SANITIZATION_CONFIG) y la lógica de decisión del comando de compilación de la habilidad brancher-preview (decide_build_commands()) tienen ambas forma de Magento. Esta no es una herramienta genérica multiplataforma: WooCommerce, Shopware, Laravel y otras plataformas alojadas en Hypernode están fuera del alcance de la v1. Una aplicación que no sea de Magento necesitaría como mínimo un SanitizationConfig escrito a mano, y la secuencia de compilación de la habilidad de vista previa no se aplicaría.

• Sin claves SSH gestionadas por MCP. brancher_exec/brancher_put invocan los binarios ssh/rsync del sistema y dependen completamente de que tu propio agente SSH local/clave ya tenga acceso a los nodos Brancher (que heredan el acceso automáticamente a través del clon completo del sistema de archivos de Brancher desde producción). Este plugin nunca aprovisiona, almacena ni transmite material de clave.

• Solo transporte stdio. Sin transporte MCP remoto/HTTP en v1: este es un plugin local de Claude Code, ejecutado por cada desarrollador contra su propio HYPERNODE_API_TOKEN. No existe una versión alojada/gestionada de este MCP. El token y el acceso SSH son propiedad total del cliente.

• Solo API REST. Sin integración de Hypernode Deploy (deploy.php) en v1.

• Contabilidad de minutos de tiempo real, no consciente de inactividad. La comprobación de obsolescencia de brancher-cleanup usa minutes según lo informado por la API de Hypernode (tiempo de actividad desde la creación); no puede distinguir un nodo inactivo de uno activo.

• Formas de respuesta de API no verificadas. La forma de respuesta esperada de brancher_list ({"nodes": [{"name", "host", "minutes"}, ...]}) y los nombres de los campos de plan/minutos de brancher_create (plan_type, brancher_minutes_remaining) son suposiciones documentadas, aún no confirmadas con el contrato real de la API de Hypernode en vivo; consulta los docstrings de los módulos en src/pb_hypernode_mcp/tools/brancher_list.py y src/pb_hypernode_mcp/tools/brancher_create.py si las respuestas de la API no coinciden en tiempo de ejecución. Ejecuta una prueba de humo real de create -> brancher_exec whoami contra una cuenta del plan Falcons antes de apuntar esto a un cliente.

• Descarga de pruebas de Playwright aún no implementada. Ejecutar el conjunto de pruebas funcionales contra un nodo Brancher en lugar de local/CI se rastrea por separado; consulta ProxiBlue/pb-hypernode-mcp#1 o el ticket de diseño original.

Desarrollo

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

No se ejecutan pruebas de integración automáticamente contra una cuenta real de Hypernode. Si estás cambiando tools/brancher_exec.py o la lógica de sondeo de capacidad de alcance en tools/brancher_spinup_flow.py, realiza una prueba de humo manual contra un nodo real del plan Falcons antes de fusionar; los simulacros no pueden detectar una suposición incorrecta de usuario SSH o un desajuste de forma en la respuesta real de la API.

Para instalar tu propio clon para desarrollo local en lugar de la versión publicada, apunta Claude Code directamente a la carpeta:

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

Después de editar las habilidades o el código del servidor, ejecuta claude plugin update pb-hypernode-mcp@pb-hypernode-mcp para aplicar el cambio sin volver a agregar el marketplace.

Si el plugin no aparece después de la instalación, verifica: claude plugin list muestra pb-hypernode-mcp como habilitado; una sesión nueva de Claude Code enumera las herramientas brancher_* y las tres habilidades brancher-*; HYPERNODE_API_TOKEN está configurado en el mismo shell desde el que iniciaste Claude Code.

Licencia

Apache-2.0. Consulta LICENSE y NOTICE para conocer la atribución de dependencias/servicios de terceros (API de Hypernode Brancher, ssh/rsync del sistema, SDK MCP de Python).