opencode-hermes-mcp

[(#version-pin-opencode-11821)

Hermes(감독 LLM)와 상주(supervisor LLM)와 OpenCode 서버 사이의 결정적(deterministic) MCP 컨트롤러입니다. 컨트롤러는 LLM이 아닌 상태 머신(state machine)으로, OpenCode의 턴에서 블록하고 질응/권한을 Hermes에게 표시해, 감독 LLM이 판단한 뒤 같은 턴을 재개할 수 있게 합니다.

Architecture

Hermes (LLM)  --MCP stdio-->  opencode_hermes_mcp.server (FastMCP, 6 tools)  --HTTP + SSE-->  OpenCode server :4096

• Layer 1 — Hermes: 상독 LLM입니다. opencode_run로 코딩 작업을 위임하고, 컨트롤러가 needs_agent_input(질은/권한)을 리포트하면 판단합니다.

• Layer 2 — 이 컨트롤러(opencode_hermes_mcp/: server.py + controller.h + client.py + models.y): Hermes가 MCP stdio를 통해 생성한 NO-LLM 프로세스입니다. 작업을 제출하고 SSE + REST에서 대기하며, 턴이 완료/오류/입력 요구 상태가 될 때까지 블록합니다. 그 후 슈퍼바이저의 판단을 동일한 OpenCode 턴에 다시 전달합니다(프롬프프트는 다시 제출되지 않습니다).

• Layer 3 — OpenCode 서버: 상주 opencode serve 프로세스(systemd 사용자 서비스 opencode-server, 프백 :4096, HTTP 베이스 인증)입니다. LLM은 ~/.config/opencode/opencode.json에서 구멘하는 지원 프롬바이더(OpenAI 호환 엔드포인트, OpenAI, An Thropic) 중 어떠 것이든 사양할 수 있습니다.

Hermes에 노출된 로그: opencode_run, opencode_answer, opencode_permmision, opencode_abort, opencode_inspect(진단 전용), opencode_sessions.

Related MCP server: opencode-mcp

필요 조건

• ~/.hermes/config.yaml이 있는 Hermes 설치

• python3 >= 3.11(Hermes 구멘vin용 PyYAML 포함)

• 네트워크 액세스(OpenCode 바이너리 설치, mcp 패키지, LLM 엔드포인트)

• systemd 사용자 세션(opencode-server 서비스용)

설치(명령 2개)

git clone <repo-url> opencode-hermes-mcp && cd opencode-hermes-mcp
scripts/install.sh

scripts/install.sh는 설치 위자드(opencode_hermes_mcp/installer.py, Python + rich)의 잇은 퍼입니다. 배너, 번호 매 단계, 스타일된 프롬프트, 진행률, 그리고 프로스를 제버닐니다. 보여줍니다. 위자드 스스로 부트스트래프합니다. repo venv가 없으면(또는 rich·pyyaml·mcp==1.12.4·editable 패째지가 없는 경우) venv를 생성한 뒤 재고동하므로, 기본 python3 >= 3.11만 있으면 됩니다.

설치는 멱등적입니다 — 다시 실행하면 에이미 설처된 것은 건너니다. 고정된 OpenCode 바이너리, venv(mcp==1.12.4가 고정된 opencode_hermes_mcp 패키지), LLM 프로바이더 구멘과 시크릿, 서버 좌격 증명, 지된 보호출 2개, systemd 사용자 서비스, 그리고 ~/.hermes/config.yaml 패치(백업 .bak 유지)를 설치합니다. 마지막으로 헬스 체크(제한 헐는 curl --max-time 3, 마지막 오류 노출)와 python -m opencode_hermes_es.moke_client(tool: surface OK 출력)를 마친습니다.

LLM 프로바이더

설치기는 프로바이더에 구속되지 않습니다. 권장하는 세 가지 프롬바이더를 운지합니다:

상호작용 모드: 메뉴에서 프로윕더를 선택하고 프롬프트에 답하세요 — openai-compatible은 base URL + API key + model, openai/anthropic은 API key + model, 그다음 LLM 속도(ロー컬 LLM)라면 slow가 프로바이더 옵션에 timeout:false / headerTimeout:false / chunkTimeout:120000을 추가합니다. fast가 기본값), 그리고 모델 제(컨텍스트/출력, 기본 128000 / 32000)을 지정합니다.

비대화형(--yes): 모든 것을 인자 변수에서 읽습니다. 로컬 OpenAI-호환 로кал(Ollama / vLLM / Unsloth / ...):

OPENCODE_PROVIDER=openai-compatible \
OPENCODE_LLM_BASE_URL=http://127.0.0.1:11434/v1 \
OPENCODE_API_KEY=... \
OPENCODE_LLM_MODEL=qwen3.8-27b \
OPENCODE_LLM_SPEED=slow \
scripts/install.sh --yes

OpenAI(클라우드):

OPENCODE_PROVIDER=openai OPENCODE_API_KEY=sk-... OPENCODE_LLM_MODEL=gpt-4o \
scripts/install.sh --yes

Anthropic(클라우드):

OPENCODE_PROVIDER=anthropic OPENCODE_API_KEY=sk-ant-... \
OPENCODE_LLM_MODEL=claude-sonnet-4-5 scripts/install.sh --yes

플래그: --yes(비대화형, OPENCODE_PROVIDER / OPENCODE_LLM_BASE_URL / OPENCODE_API_KEY / OPENCODE_LLM_MODEL / OPENCODE_LLM_SPED / OPENCODE_CONFEXT_LIMIT / OPENCODE_OUTPUT_LIMIT), --port N(기본값 4096), --skip-binary, --force-config, --dry-run, --skip-verify(최종 헬스 + 스모크 인증 생략 — sandbox/CI에 유용).

UNSLOTH_API_KEY는 OPENCODE_API_KEY의 디프리케이트 폴백으로 계속 지원됩니다(기존 스크립트는 그대로 작동).

설치 후 MCP 서버를 로드하려면 새 Hermes 세션이 필요합니다.

Hermes 통합(수동)

설치기가 ~/.hermes/config.yaml을 대신 패치해 주지만, Hermes의 스킬 레이아웃을 변경할 수 없으므로 의도적으로 Hermes 스킬은 설치하지 않습니다. 패키지에 전체 매뉴얼이 포함되어 있습니다:

• docs/hermes-integration.md — MCP가 필요한 이유, 정확한 구성 항목, 수동 통합(직접), 6개 도구, 문지 해결, 실행 제거

• docs/skill.example.md — ~/.hermes/skills/에 넣고 실행할 수 있는 준비된 Hermes 스킬(작업 위임 프로토콜)

사용법

Hermes는 도구를 통해 작업을 위임합니다 — CLI를 수동으로 시작할 필요:

• opencode_run(directory, task, agent) — 작업을 제출하고, 허턴이 완료되거나 오류가 나거나 입력을 요구할 때까지 블록합니다. 새 세션을 시작하려면 agent가 필요합니다(프로젝트의 기본 에이전트, 예: build, plan 또는 프로젝트 특화 agent).

• 도구가 state=needs_agent_input를 반환하면 Hermes가 판단합니다: opencode_answer(정확한 옵션 값 선택) 또는 opencode_permission(once / always / reject) — 두 가지 모두 같은 턴을 재개합니다.

• opencode_abort는 더 진행되지 실행 중지; opencode_sessions는 디렉토리의 허턴을 나열합니다; opencode_inspect는 예외 진단용(작업 실행 중 폴링 금지).

Hermes 측 연결 설정(scripts/install.sh이 ~/.hermes.config.yaml에 작성):

mcp_servers:
  opencode:
    command: ~/.local/bin/opencode-mcp-launch.sh
    enabled: true
    timeout: 14400
    connect_timeout: 30
    supports_parallel_tool_calls: false
timeouts:
  tools:
    sequential_call: 14400
    concurrent_batch: 14400

런처는 ~/.config/hermes/opencode-server.json에서 OpenCode 서버 자격 증명을 읽고, repo venv 내에서 python -m opencode_hermes_mcp.server를 실행합니다 — config.yaml에는 시크릿가 없이 유지됩니다.

TUI 부착 헬퍼(OpenCode 실시간 보기)

install.sh는 또한 ~/.local/bin/에 두 개의 헬퍼를 넣습니다(소스: scripts/helpers/):

ocattach <repo-abs> [ses_...]   # open the OpenCode TUI on a repo / session
oc-current                      # attach to the session Hermes is supervising NOW

• ocattach — 상주 서버 :4096에 대해 OpenCode TUI(opencode attach)를 엽니다 — 별도 tmux 불필요. 세션 ID를 지정하지 않으면 최신 세션을 열거나 선택 옵션을 제공합니다.

• oc-current 현재 가장 최신의 ~/.local/state/opencode-hermes-mcp/turn_*.json(컨트롤러의 진행 중 상태 상태)를 읽고 해당 세션에 부착합니다 — Hermes가 OpenCode를 구동 중일 때, 실시간으로 실행중 추론을 보기 위해 사용합니다.

모집 ~/.config/hermes/opencode-server.json에서 서버 자격 증명을 읽습니다(컨트롤러 런처와 동일 소스). 허턴이 활성인 동안 TUI에서 Esc/Ctrl+C를 누르지 마요 — OpenCode 측에서 실행 중인 턴이 제공됩니다.

업그레이드 / 제거

scripts/upgrade.sh            # controller only: git pull + venv deps + restart + smoke
scripts/upgrade.sh --binary   # install the PINNED OpenCode binary (idempotent) — see "Version pin" below
scripts/uninstall.sh          # service, launchers, venv, hermes entry, credentials
scripts/uninstall.sh --purge  # + OpenCode provider config + API key secret
scripts/uninstall.sh --purge-binary  # + the OpenCode binary

uninstall.sh는 purge flags가 아닐 때 git clone, OpenCode 프로바이더 구멘, API 키 시크릿, 바이너리를 건드지 않습니다.

버전 고정: OpenCode 1.18.21

컨트롤러는 버전 앞에 **1.18.21**이 검증된 OpenCode 1.18.21에 대해서인 (해당 버전의 라이브 /doc(시 위의 endpoint contract에 검증됐)이며, 웹 문서 문서의 아님). 고정 값은 opencode_hermes_mcp/in.txt에 있는 단일 진실 소스입니다(한 줄, v 없이): installer.py와 scripts/upgrade.sh 모두 이 것을 참조하고, 파일이 없거나 비어 있을 때 내장 상수로 폴백합니다(예: pip 설치에서 파일이 코드와 함께 제공되지 않는 경우). install.sh는 바이너리를 그 버전으로 고정하고, upgrade.sh은 기본적으로 바이너리를 업그레이드하지 않습니다.

scripts/upgrade.sh --binary(버전 생략)는 고정된 버전을 설치하며 멱등적입니다(이미 고정 버전이면 no-op). --binary latest는 최신 "bleeding edge"를 명시적으로 선택하는 것입니다. --binary X.Y.Z는 요청한 버전을 합니다. 고정 값이 아닌 다른 버전라면 스크릅트를 경고하며, 반드시 컨트롤러를 재검증한 뒤여 신할 수 있습니다:

.venv/bin/python tests/run_tests.py

(모든 검증을 통과해야 합니다; 트는 실서 그러한 in 서버를 상대로 MCP std가 컨트롤러를 구동합니다). 실패하면 다시 고정: scripts/upgrade.sh --binary.

Timeouts

세 개의 독립된 타임아웃이 파이프라인을 제한합니다: 컨트롤러 실행 타임아웃(DEFAULT_RUN_TIMEOUT = 36000 s — 단일 opencode_run/opencode_answer/opencode_permission 시도는 1시간 후 포기), MCP 서버 타임아웃(~/.hermes/config.yaml의 mcp_servers.opencode.timeout= 1440 초,connect_timeout = 30 초), **Hermes** 도구 타임아웃 (timeouts.tools.sequential_call/concurrent_batch` = 1440 초) — 바깖 두 개는 컨트롤러의 4배로 설정되어, 길지만 정상인 턴이 감독 계층에서 종료되지 않습니다.

Development

CONTRIBUTING.md에서 config를 확인하세요. 스모크 테스트* 실행법, 통합 스쥐트 실행법, 기여 규칙을 설명합니다.

파일

라이선스

MIT — Copyright (c) 2026 Arthur Hottier.