hydra-ops-mcp

Hydra 헤드를 말로 작동하세요. 실행 중인 헤드(생명주기, 원장, L1 지갑, 노드 로그, 온체인 오류 코드)를 LLM 클라이언트가 호출할 수 있는 도구로 노출하는 MCP 서버입니다. TUI, curl, cardano-cli, docker logs 사이를 전환하는 대신 일반 언어로 헤드를 구동하고 디버깅할 수 있습니다.

전체 운영 표면을 다룹니다: init, 예치, 헤드 내 트랜잭션, decommit, close, fanout, 부분 fanout, 예치 복구, 그리고 헤드 상태 및 L1의 읽기 전용 보기. 상태를 변경하는 모든 작업은 수행할 작업을 설명하고 실행 전에 명시적 확인을 기다립니다.

목차

• 이유 · 빠른 시작 · 아키텍처

• 확인 모델

• 도구 참조 — 관찰 가능성, 생명주기, 트랜잭션, 진단

• hydra-tui와 비교

• 구성 · 테스트

• 운영 참고 사항 · 제한 사항

• 확장

이유

헤드를 운영한다는 것은 여러 도구를 동시에 다루는 것을 의미합니다. TUI는 헤드 상태를 보여주지만 트랜잭션이 거부된 이유는 보여주지 않습니다. WebSocket API는 이벤트를 제공하지만 JSON을 수동으로 파싱해야 합니다. 문제가 발생하면 답은 보통 docker compose logs에 있으며, 헤드 상태와 연관시키고 Plutus 소스에 있는 오류 코드로 디코딩해야 합니다.

이 서버는 이 모든 것을 하나의 대화형 인터페이스 뒤에 넣습니다:

"헤드가 fanout되지 않습니다. 무엇이 문제인가요?"

Claude는 헤드 상태를 확인하고, 노드 로그에서 실패한 트랜잭션을 가져오고, H39 중단 코드를 FanoutUTxOHashMismatch로 디코딩하고, 실제로 원인이 되는 두 가지를 한 번에 알려줄 수 있습니다. 헤드 API, 컨테이너 로그, 오류 테이블을 모두 사용할 수 있기 때문입니다.

또한 일상적인 부분(헤드 열기 및 자금 조달, 자금 이동, 정산)에 유용하며, 각 단계가 실행되기 전에 설명되고 확인됩니다. 그리고 단일 노드에 바인딩된 TUI 세션과 달리 모든 도구는 node 인수를 사용하므로 alice, bob, carol이 동일한 헤드에 대해 각각 무엇을 믿고 있는지 비교할 수 있습니다.

현재 hydra demo devnet(3개 노드, 3개 당사자)을 대상으로 합니다. API 계층은 devnet에 특화되지 않았지만 L1 헬퍼와 키 처리는 그렇습니다(제한 사항 참조).

빠른 시작

전제 조건 — Docker, Python 3.10+, 그리고 cardano-scaling/hydra의 체크아웃 (데모 devnet 및 Plutus 오류 테이블용).

git clone https://github.com/skoniog/hydra-ops-mcp && cd hydra-ops-mcp
python3 -m venv .venv                      # or: uv venv .venv
.venv/bin/pip install -r requirements.txt

./reset_devnet.sh                          # cardano-node + 3 hydra-nodes, seeded

MCP 클라이언트에 서버를 등록하세요. Claude Code:

claude mcp add hydra-ops -- /absolute/path/to/hydra-ops-mcp/.venv/bin/python \
    /absolute/path/to/hydra-ops-mcp/server.py

Claude Desktop — claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "hydra-ops": {
      "command": "/absolute/path/to/hydra-ops-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/hydra-ops-mcp/server.py"]
    }
  }
}

MCP 런처는 서버를 축소된 환경에서 실행하므로, 셸에서 내보내는 대신 "env" 블록에 재정의(HYDRA_DEMO_DIR, HYDRA_REPO)를 전달하세요.

그런 다음 물어보세요:

"헤드 상태는 무엇이며, alice는 L1에서 무엇을 보유하고 있나요?" "헤드를 열고 alice의 자금을 커밋하세요." "alice에서 bob으로 5 ADA를 보내고, 헤드 UTXO 세트를 보여주세요."

이 방식으로 헤드를 운영하는 것이 처음이신가요? **RUNBOOK.md**는 전체 생명주기(열기, 자금 조달, 트랜잭션, decommit, 닫기, 정산, 의도적으로 깨기)를 일련의 안내 세션으로 안내합니다.

아키텍처

  MCP client (Claude Code / Claude Desktop / anything speaking MCP)
        │  stdio
        ▼
  server.py                 FastMCP registration; thin wrappers only
        │
  tools/                    one module per domain, plain functions
   ├── observe.py           head state, UTXOs, L1 funds, params, events
   ├── lifecycle.py         init, commit, decommit, close, fanout, recover
   ├── transact.py          in-head transfers
   ├── diagnose.py          node logs, error-code decoding
   └── types.py             ok() / err() / needs_confirmation()
        │
        ├──▶ hydra_client.py    WebSocket + HTTP to hydra-node
        │                       async core, sync facade, event buffer
        ├──▶ tx_builder.py      PyCardano: build + sign in-head txs
        ├──▶ cardano.py         cardano-cli in the node container (L1)
        └──▶ errors.py          parses hydra-plutus for abort codes

**hydra_client.py**는 노드당 WebSocket 연결을 유지하며, 동기식 퍼사드 뒤에서 데몬 스레드에서 비동기 이벤트 루프를 실행합니다. 따라서 도구 함수는 프로토콜 이벤트를 기다리면서도 단순하게 유지됩니다. 모든 서버 출력을 recent_events용으로 버퍼링하고, 헤드 상태를 추적하며, 확인된 트랜잭션을 연관시킵니다. 명령은 낙관적으로 반환하는 대신 특정 결과 이벤트(Decommit → DecommitFinalized, Fanout → HeadIsFinalized)를 기다리므로, 성공한 도구 호출은 프로토콜 단계가 실제로 완료되었음을 의미합니다.

**tx_builder.py**는 PyCardano으로 트랜잭션을 빌드하고 서명합니다. 트랜잭션당 cardano-cli 왕복이 없습니다. **cardano.py**는 실행 중인 cardano-node 컨테이너 내에서 cardano-cli를 실행하여 L1 측(주소 파생, UTXO 쿼리, 예치 트랜잭션 서명 및 제출)을 처리합니다. 키도 그곳에 있습니다.

**errors.py**는 호출 시점에 로컬 hydra 체크아웃에서 HeadError.hs, DepositError.hs, HeadTokensError.hs 등을 파싱하므로, 디코딩된 코드는 표류하는 테이블이 아닌 실행 중인 버전과 항상 일치합니다.

확인 모델

상태를 변경하는 모든 도구는 confirm: bool = False를 받습니다. 이 인수 없이 호출되면 도구는 가능한 모든 것을 검증하고, 실제로 수행할 작업을 결정하며, 아무것도 변경하지 않고 설명을 반환합니다:

{
  "status": "requires_confirmation",
  "action": "deposit alice's UTXO 4a3f…#0 (100,000,000,000 lovelace) into the head via node 1",
  "message": "This would deposit… Nothing has been done. Retry with confirm=True to execute.",
  "party": "alice", "utxo_ref": "4a3f…#0", "lovelace": 100000000000
}

실제로 이는 Claude가 제안하고, 사용자가 승인한 후에야 온체인에서 어떤 일이 발생함을 의미합니다. 이는 일방적이고 되돌릴 수 없는 작업에 가장 중요합니다: close_head는 헤드의 모든 참가자에게 영향을 미치고, fanout은 헤드의 최종 상태를 정산합니다.

미리보기는 가상이 아닌 실제로 결정됩니다. commit_funds는 선택한 정확한 UTXO를 명명하고, decommit은 헤드의 UTXO 세트에서 파생된 소유자와 금액을 명명하며, send_tx는 빌드한 트랜잭션 ID를 보고합니다. 검증은 게이트 전에 실행되므로, 실패할 것을 확인하라는 요청을 받지 않습니다. 읽기 전용 도구에는 게이트가 없으며 즉시 실행됩니다.

도구 참조

모든 도구는 {status, error, ...}를 반환합니다. 실패는 예외 대신 {"status": "error", "error": "<message>", ...}입니다. l1_funds와 explain_error를 제외한 모든 도구는 node: int = 1 (1 = alice, 2 = bob, 3 = carol)을 받습니다.

관찰 가능성 (읽기 전용)

recent_events는 서버가 연결된 이후의 이벤트를 다룹니다. WS 연결은 기록을 요청하지 않으므로 전체 로그가 아닌 실시간 테일입니다. 더 오래된 것은 node_logs를 사용하세요.

생명주기 (확인 게이트)

commit_funds는 호출당 하나의 UTXO를 의도적으로 예치합니다. 다중 UTXO 예치는 2.3.0에서 H39로 fanout을 막습니다 (운영 참고 사항 참조).

트랜잭션 (확인 게이트)

1 ADA 미만의 금액은 거부됩니다. 헤드는 최소 UTXO를 0으로 설정하므로 이러한 출력은 L2에서는 유효하지만 L1에서는 재생성할 수 없어 fanout을 영구적으로 막습니다. 트랜잭션은 확인 시점에 현재 UTxO 세트를 기준으로 재구축되므로, 오래된 미리보기가 오래된 입력을 사용하지 않습니다. 호출은 트랜잭션이 수락된 시점이 아니라 확인된 스냅샷에 나타날 때 반환됩니다.

진단 (읽기 전용)

hydra-tui와 비교

도구 표면은 의도적으로 hydra-tui가 노출하는 것과 일치하므로, TUI에서 할 수 있는 모든 것을 여기서도 할 수 있습니다:

TUI와 마찬가지로, 이 도구는 Contest, SafeClose 또는 SideLoadSnapshot을 노출하지 않습니다. 이들은 특정 온체인 조건에 대한 프로토콜 응답으로, 하나의 동작이 올바르고 타이밍이 중요합니다. 이들은 프롬프트 뒤가 아니라 알림이 있는 결정론적 도구에 속합니다.

더 나아간 점:

• 진단. node_logs와 explain_error는 TUI에 해당하는 기능이 없습니다. 이것이 가장 실용적인 이점입니다. 고착된 헤드가 "TUI가 실패했다고 말한다"에서 디코딩된 중단 코드와 일치하는 로그 라인으로 전환됩니다.

• 교차 노드. TUI 세션은 하나의 노드에 연결됩니다. 여기서 모든 도구는 node를 사용하므로 alice, bob, carol이 동일한 헤드에 대해 각각 무엇을 믿는지 물어볼 수 있습니다. 이는 뒤처진 노드를 찾는 가장 빠른 방법입니다.

• L1과 L2 함께. l1_funds는 체인을 직접 쿼리하므로 "해당 decommit이 실제로 도착했는가?"라는 질문이 cardano-cli로의 컨텍스트 전환 없이 하나의 질문으로 해결됩니다.

• 가드레일. 최소 UTXO 미만의 출력과 다중 UTXO 예치금은 구조적으로 거부됩니다. 둘 다 나중에 fanout을 조용히 고정시키기 때문입니다.

• 구성. 다단계 작업이 하나의 요청으로 이루어집니다: *"헤드를 닫고, 경쟁 기간을 기다린 후, fanout하고, 모든 사람의 최종 L1 잔액을 보여줘"*는 하나의 요청입니다.

TUI가 여전히 우세한 점: 라이브 대시보드입니다. MCP는 요청/응답 방식이므로 지속적으로 업데이트되는 보기가 아닌 스냅샷을 제공합니다. 시간에 따라 헤드를 모니터링하려면 TUI를 열어 두세요. 반복 작업에서는 키 입력이 모델 왕복보다 빠르며, TUI의 UTxO 선택기는 시각적이지만 여기서는 목록을 보고 선택합니다.

설정

서명 키는 데모의 {alice,bob,carol}-funds 쌍입니다. 컨테이너 측 경로는 cardano-cli(L1에서 서명 및 제출)에 사용되며, 동일한 키의 호스트 측 복사본은 PyCardano에서 헤드 내 트랜잭션을 위해 읽습니다. 동일한 레이아웃의 다른 배포를 가리키는 것은 구성 변경이지만, 다른 토폴로지를 가리키는 것은 그렇지 않습니다(제한 사항 참조).

테스트

.venv/bin/python test_ops.py           # offline — no devnet needed
.venv/bin/python test_ops_devnet.py    # live — needs a devnet with the head Idle

**test_ops.py**는 모든 상태 변경 도구가 requires_confirmation을 반환하고 confirm=True 없이는 클라이언트에 도달하지 않으며(스텁 클라이언트는 명령이 게이트를 벗어나면 예외를 발생시킴), 요청 페이로드가 API와 일치하며, 최소 UTXO 거부 및 UTxO 검증이 작동하고, 오류 테이블이 구문 분석 및 디코딩되며, 모든 16개 도구가 서버에 등록되는지 확인합니다.

**test_ops_devnet.py**는 실제 헤드를 전체 수명 주기 동안 구동하고 각 단계에서 관찰 가능성을 확인합니다: 게이트 확인 → init → commit → 6개의 읽기 도구 → 2개의 헤드 내 결제 → 헤드가 열려 있는 동안 L1에 자금이 나타나는 것으로 확인되는 decommit → close → fanout → Idle로 복귀 → 로그 및 오류 디코딩. 데브넷이 실행 중이 아니거나 헤드가 Idle이 아닌 경우 명확한 메시지와 함께 건너뜁니다.

운영 참고 사항

H39 / FanoutUTxOHashMismatch는 헤드를 영구적으로 고정시킵니다. Fanout이 닫힌 헤드가 커밋한 내용을 재현할 수 없으므로 헤드가 정산되지 않고 자금이 고정됩니다. 두 가지 원인이 있으며, 모두 예방 가능하고 여기서 방지됩니다: 2.3.0의 다중 UTXO 예치, 그리고 L1 최소 UTXO 미만의 헤드 출력. 자세한 내용은 explain_error("H39")를 요청하세요.

헤드는 최소 UTXO를 0으로 만듭니다. L1은 그렇지 않습니다. 0.5 ADA 출력은 L2에서 문제없이 거래되지만 L1에서 재생성할 수 없습니다. send_tx는 이 이유로 1 ADA 미만을 거부합니다.

예치금은 예치 기간 후에 흡수되며, 즉시 흡수되지 않습니다. commit_funds는 흡수가 발생하지 않으면 대기하고 보고합니다. 결코 도착하지 않은 예치금은 pending_deposits에 나타나며 recover_deposit으로 회수됩니다.

닫기는 일방적이며 모든 사람에게 영향을 미칩니다. 모든 참가자가 닫을 수 있으며, 전체 헤드가 정산되어야 합니다. 게이트는 주로 이를 위해 존재합니다.

헤드는 모든 참가자가 온라인 상태여야 합니다. 결제가 중단되면 도구를 의심하기 전에 docker compose ps를 확인하세요.

데모 데브넷의 블록 프로듀서는 장기간 유휴 상태 후에 중단될 수 있습니다. cardano-cli query tip이 동일한 슬롯을 두 번 반환하고 모든 것이 중단됩니다. ./reset_devnet.sh로 해결됩니다. 데브넷은 설계상 일회용입니다.

구문 분석할 수 없는 WebSocket 입력은 tag를 반환하지 않습니다. 노드가 인식하지 못하는 명령은 태그된 이벤트가 아닌 {"input", "reason"} 객체로 반환됩니다. API에 직접 스크립팅하는 경우 알아두면 좋습니다. 태그된 이벤트를 기다리는 클라이언트는 중단되기 때문입니다. 여기서 클라이언트는 이를 처리합니다.

제한 사항

partial_fanout은 2.3.0보다 새로운 노드가 필요합니다. 이 명령은 릴리스 이후에 나왔으며(hydra PR #2750, 커밋 a271cced2), 고정된 데모 이미지에서는 거부됩니다. 노드는 알고 있는 명령을 나열하고 PartialFanout은 그중에 없습니다. 도구는 이를 정확히 감지하고 버전 차이를 보고합니다. 코드 경로는 master에서 빌드된 노드에 대해 준비되어 있지만 해당 거부까지만 테스트되었습니다.

수수료는 0입니다. tx_builder.py는 fee=0을 하드코딩하며, 이는 데모의 프로토콜 매개변수에 대해서는 올바르지만 다른 모든 곳에서는 잘못되었습니다. 이 도구가 preview/preprod 또는 메인넷을 가리키기 전에 실제 수수료 추정과 코인 선택이 필요합니다.

데브넷 형태의 가정. 알려진 키 이름을 가진 세 당사자, cardano-node 컨테이너 내에서 읽을 수 있는 키, L1 쿼리 및 로그에 사용 가능한 docker compose. 헤드 API 계층은 일반적이지만 L1 도우미는 그렇지 않습니다.

ADA만 지원. 트랜잭션 빌드는 순수 lovelace UTXO를 처리합니다. 네이티브 토큰, 스크립트, 데이터 또는 민팅은 없습니다.

recover_deposit은 실제로 고정된 예치금에 대해 테스트되지 않았습니다. API를 따르지만 데모 데브넷은 예치금을 너무 안정적으로 흡수하여 요청 시 생성할 수 없습니다.

인증 없음. 서버에 접근할 수 있는 사람은 누구나 헤드를 운영할 수 있습니다. 이는 로컬 운영자 도구에 적합하며 노출된 경우에는 적합하지 않습니다.

확장

도구 추가: 관련 tools/ 모듈에 ok() / err() / needs_confirmation()을 반환하는 일반 함수를 작성한 다음 server.py에 얇은 래퍼를 등록합니다. 도구 모듈은 FastMCP를 가져오지 않으므로 테스트에서 직접 호출할 수 있습니다. 두 테스트 스위트가 이를 구동하는 방식입니다.

프로토콜 명령 추가: _command_and_wait(command, ok_tags)를 사용하여 HydraClient에 메서드를 추가합니다. 이 메서드는 명령을 보내고 결과 이벤트를 기다리며 CommandFailed와 태그되지 않은 구문 분석 거부를 모두 오류로 처리합니다.

다른 배포 대상 지정: NODES를 엔드포인트로, HYDRA_DEMO_DIR / HYDRA_REPO를 올바른 경로로 지정합니다. 데모의 3자 레이아웃을 넘어서는 경우 cardano.py 및 tx_builder.py의 키 처리와 수수료를 재검토해야 합니다.

추가 자료

프로토콜 자체에 대한 Hydra 문서와 이 도구로 헤드를 운영하는 가이드 투어를 위한 RUNBOOK.md를 참조하세요.