pb-hypernode-mcp

Hypernode Brancher용 클라이언트 측 Claude Code 플러그인 — 일회용 프로덕션 클론 미리보기 환경을 생성하고, SSH를 통해 AI 지원 변경을 수행하고, 기존 브라우저 MCP를 통해 확인합니다.

왜

Brancher는 프로덕션 Hypernode의 변경 가능하고 임시적인 복사본을 제공합니다(≤24시간 전 데이터, 전체 도구 체인, 실제 인프라 — Docker 근사가 아님). 문제는 프로덕션을 통째로 복제한다는 점입니다. 즉, 기본적으로 실제 고객 PII와 실제 결제/API 자격 증명이 함께 제공되고 노드에 공개 URL이 부여됩니다. 이 플러그인은 그 격차를 해소합니다. 생성되는 모든 노드는 준비 완료로 보고되기 전에 자동으로 익명화되고 샌드박스 처리되므로 "클라이언트의 AI가 실제 프로덕션 클론을 건드리게 하는 것"이 "실제 고객 데이터를 인터넷에 노출하는 것"을 의미하지 않습니다.

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. 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으로 로컬 diff를 푸시하거나 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는 누군가 노드를 적극적으로 사용하는지와 관계없이 생성 시점부터 경과된 실제 시간(분)으로 청구합니다.

안전 가드레일

• 필수 정리(sanitization) — 비활성화 불가능. 모든 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을 보류합니다. 예외조차도 이를 전달하지 않으므로, 이를 잡는 호출자가 실수로 표면화할 방법이 없습니다.

시퀀스(구성 기반, 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 키 스텁(stubbing) — 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는 쉘 인용 처리되고 rsync는 --protect-args로 실행되므로 원격 호스트의 셸이 경로 인자를 다시 구문 분석하지 않아 조작된 경로를 통한 메타문자 주입을 차단합니다.

이 설계는 출시 전 3명의 전문가 보안 검토(정적 분석, 적대적 테스트, 방어적 감사)를 거쳤습니다. 초기 초안에서 실제 심각한 결함을 발견했습니다. 정리된 흐름이 여전히 노출된 원시의 정리되지 않은 생성 경로와 함께 두 번째 도구로 구축되었기 때문에 위에서 "하나의 생성 도구, 예외 없음"이 그렇게 강조된 이유입니다. 보안 문제를 발견하셨나요? 익스플로잇 세부 정보가 포함된 PR 대신 이슈를 열어주세요.

한계 (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 바이너리를 호출하며 Brancher 노드에 대한 액세스 권한이 이미 있는 사용자 고유의 로컬 SSH 에이전트/키에 전적으로 의존합니다(Brancher의 프로덕션에서 전체 파일 시스템 복제를 통해 액세스가 자동으로 상속됨). 이 플러그인은 키 자료를 프로비저닝, 저장 또는 전송하지 않습니다.

• stdio 전송만 지원. v1에서는 원격/HTTP MCP 전송이 없습니다. 이는 각 개발자가 자신의 HYPERNODE_API_TOKEN에 대해 실행하는 로컬 Claude Code 플러그인입니다. 이 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-* 스킬이 표시됨, Claude Code를 실행한 동일한 셸에 HYPERNODE_API_TOKEN이 설정되어 있음.

라이선스

Apache-2.0. 타사 종속성/서비스 저작권 표시(Hypernode Brancher API, 시스템 ssh/rsync, MCP Python SDK)는 LICENSE 및 NOTICE를 참조하십시오.