opencode-hermes-mcp

Hermes（スーパーバイザーの LLM）と常駐のOpenCodeサーバーの間を結ぶ、決定論的な MCP コントローラーです。このコントローラーは LLM を介さないステートマシンであり、OpenCode のターンでブロックし、質問/許可を Hermes に提示します。それによってスーパーバイザー LLM が判断し、同じターンを再開できます。

アーキテクチャ

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

• レイヤー 1 — Hermes: スーパーバイザー LLM。opencode_run でコーディングタスクを委譲し、コントローラーが needs_agent_input（質問/許可）を報告した際に判断します。

• レイヤー 2 — このコントローラー（opencode_hermes_mcp/: server.py + controller.py + client.py + models.py）: Hermes が MCP stdio 経由で起動する LLM 不使用プロセス。タクを送信し、SSE + REST を監視し、ターンが完了・エラー・入力を待つまでブロックし、スーパーバイザーの決定を同じ OpenCode ターンに書き戻します（プロンプトは再送信されません）。

• レイヤー 3 — OpenCode サーバー: 常設の opencode serve プロセス（systemd ユーザーサービ opencode-server、ループバック 127.0.0.1:4096、HTTP 基本認証）。その LLM はサポートされている任意のプロバイダ（OpenAI互換エンドポイント、OpenAI、または Anthropic）で、~/.config/opencode/opencode.json に設定されます。

Hermes に公開されるツール: opencode_run、opencode_answer、opencode_permission、opencode_abort、opencode_inspect（診断専用）、opencode_sessions。

Related MCP server: opencode-mcp

前提条件

• Hermes がインストール済みであること（~/.hermes/config.yaml が存在する）

• python3 >= 3.11（PyYAML.included を含む）

• ネットワークアクセス（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_mcl/installer.py。Python + rich）の薄いラッパーです。バナー、番号付きステップ、スタイルを適用したプロンプト、進表示、要約パネルを備えています。ウィザードは自己ブートストラップします。リポジトリの venv（rich / pyyaml / mcp==1.12.4、エジタブルパッケージ）がない・または欠けてえ sortedる場合、それを作成して再実行するため、素の python3 >= 3.11 だけが前提条件です。

インストールは冪等です。再実行すると、既に配置されたものをスキップします。固定済みの OpenCode バイナリ、venv（opencode_hermes_mcp パッケージと mcp==1.12.4 固定）、LLM プロバイダ設定＋シークレット、サーバー認証情報、2つのランチャ、systemd ユーザーサービをインストールし、~/.hermes/config.yaml をパッチします（バックアップは .bak として保持）。最後にヘルスチェック（制限付き curl --max-time 3、最後のエラーを表示）と python -m opencode_hermes_mclink ``open ...translate? No, need correct:python -m opencode_hermes_mcp.smoke_client を実行し、tool surface OK` と出力される必要があります。

LLM プロバイダ

インストーラはプロバイダ依存しません。次の3つのプロバイダをサポートしています:

対話型の場合、メニューからプロバイダを選択し、プロンプトに答えます — openai-compatible ではベース URL + API キー＋モデル、openai / anthropic では API キー＋モデル、次に LLM の速さ（ローカル LLM では slow。プロバイダのオプションに timeout:false / headerTimeout:false / chunkTimeout:120000 を追加します。デフォルトは fast）とモデルの制限（context / output、デフォルトは 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_SPEED / OPENCODE_CONTEXT_LIMIT / OPENCODE_OUTPUT_LIMIT を使用）、--port N（デフォルト 4096）、--skip-binary、--force-config、--dry-run、--skip-verify（最後のヘルス＋スモーク検証をスキップ — サンドボックス/CI で有用）。

UNSLOTH_API_KEY is still accepted as deprecated fallback for OPENCODE_API_KEY（既存のスクルが動くように）。

インストール後にMCP サーバーをロードするためには、新しい Hermes セッションが必要です。

Hermes 統合（手動）

インストーラーが ~/.hermes/config.yaml を自動パッチしますが、Hermes のスキルをインストールすることは意図的にしません（Hermes のスキル構成は変更される可能性があるため）。その代り、完全なマニュアルを同梱しています:

• docs/hermes-integration.md — この MCP の目的、書き込まれる正確な設定エントリ、手動統合、6つのツール、トラブルーシューティング、アンインストール。

• docs/skill.example.md — コピーして使える Hermes スキル（委譲プロトコル）を ~/.hermes/skills/ に入れて、それをあなたの環境に合わせて調整します。

使い方

Hermes は MCP ツールを介して作業を委譲します。手動の CLI は不要です。

• opencode_run(directory, task, agent) — タクを送信します。ターンが完了するか、エラー、或者は入力を待つまでブロックします。新しいセッションには agent が必ずです（プロジェクトの主流エージェンと。例: build、plan、または特定プロジェクト用のエージェン）。

• ツールが 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 サーバーの資格情報を読み取り、リポジトリの venv で code + python -m opencode_hermes_mcp.server を実行します。config.yaml はシークレットを含みません。

TUI アタッチ ヘルパー（OpenCode をライブで視察する）

install.sh は、~/.local/bin/ に2つのヘルパーを置きます（ソース: 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 は、git clone、OpenCode プロバイダ設定、API ーやシークレットを決して破壊しません（purge フラグ明示的に指定しない限り）。バイナリにも。

バージョン・ピン: OpenCode 1.18.21

コントローラーは OpenCode 1.18.21 でのみ検証済みです（エンドポイント契約は、ウェブドキュメントではなくそのバイナリのライブ /doc に対して検証しました）。ピンは opencode_hermes_mcp/pin.txt に常一の情報源として格納されています（1行、v フレフィックスなし）。installer.py と scripts/upgrade.sh はどちらもそれを読み取ります。ファイルが無いま空の場合（例: pip インストールでコーと一緒に配布されない場合）は、ビルトイン定数にフォームバックします。install.sh はそのバージョンをバイナリにピン留めします。upgrade.sh はデフォトではバイナリをアップグレードしません。

scripts/upgrade.sh --binary（バージョン指定なし）は fixedされるバージョンをインストールし、冪等です（既にピンと一致していれば何もしない）。--binary latest は最先端を明示的にオプトイン、--binary X.Y.Z は要求されたバージョンをインストールします。ピン以外のバージョンを指定すると、スクリプトが警告し、そのコントローラーを使用する前に再検証しなければなりません:

.venv/bin/python tests/run_tests.py

（すべてのチェックが障碍なく通与しなければなりません; このスイーごは MCP stdio でライブサーバーに対してコントローラーを駆動します）。失敗したら、scripts/upgrade.sh --binary でピンを戻してください。

タイムアウト

パイプラインを制約する3つの独立したタイムアウトがあります: コントローラーのラン制限（DEFAULT_RUN_TIMEOUT = 3600 秒 — 単一の opencode_run / opencode_answer / opencode_permission コールは1時間で放機する）、MCPのタイムアウト（~/.hermes/config.yaml 内の mcp_servers.opencode.timeout = 14400 秒、connect_timeout = 30 秒）、Hermes ツールのタイムアウト（for timeouts.tools.sequential_call/for? Actually "timeouts.tools.sequential_call" / concurrent_batch` = 14400 秒）— 外側の2つはコントローラーの4倍に設定されており、長くても正常なターンがスーパーバイザー層によて切られないようになっています。

開発

開発環境のセットアップ、スモークテストと統合スイートの実行方法、コントリビューション役約については CONTRIBUTING.md を参照してください。

Files

ラセンス

MIT — Copyright (c) 2026 Author Hottier.