opencode-mcp-bridge

opencode の HTTP サーバー (opencode serve) を MCP (Model Context Protocol) サーバーとして公開するブリッジです。 MCP しか接続できない AI チャット（tool calling API を直接使えないクライアント）から、opencode のコーディングエージェントとシェルをフル機能で操作するために作りました。

設計上の最重要ポイント: すべての MCP ツールは 必ず 55 秒以内にレスポンスを返します。 60 秒でタイムアウトする MCP クライアントでも「呼び出し失敗」にならないよう、長時間処理は必ず 「開始 → ジョブ ID を返す → ポーリング」の非同期パターンに分解しています。

なぜブリッジが必要か

Related MCP server: mcp_server_for_claudes_toolbox

アーキテクチャ

  MCP クライアント (60 秒制限あり)
        │  Streamable HTTP: POST /mcp    （または stdio）
        ▼
  opencode-mcp-bridge  ──  HTTP  ──▶  opencode serve (127.0.0.1:4096)
        │                                   │
        │                                   ├── /session, /session/{id}/prompt_async
        │                                   ├── /api/pty（本物の端末・モデル不要）
        │                                   ├── /api/shell（v2）または /session/{id}/shell（legacy）
        │                                   ├── /file/content, /find, /find/file
        │                                   └── /permission, /question
        └── 55 秒ハードキャップ + ジョブ管理 + コマンドガード

モデル向けツールの MCP 移植（tool calling の代替）

opencode がモデルに渡すツールは GET /experimental/tool/ids で確認できる 14 個で、 実際のスキーマは GET /experimental/tool?provider=&model= が返す。 ただし ツールを実行する HTTP エンドポイントは存在しない（一覧系の 2 本だけ）。 そこでブリッジ側でスキーマを 1:1 で写し取り、実行はブリッジ自身が行う。

これにより tool calling に対応していない MCP クライアント（Notion AI など）が モデルの位置に入り、プロバイダの API キーを一切登録せずに 調査 → 編集 → テスト → diff 確認までを回せる。

写していないもの（opencode_model_tools が理由付きで返す）:

• task … サブエージェント起動。モデルが必要。ここでは MCP クライアント自身が実行する

• skill … モデルの文脈にプロンプトを差し込むだけ。opencode_skills で中身を読めば足りる

• question … 操作者への質問。ここでは MCP クライアントが操作者なので自分のユーザーに聞く

• websearch … プロバイダの認証情報が必要

• apply_patch … 一部プロバイダにしか出さない。edit と write で代替できる

• invalid … 不正なツール呼び出し用のプレースホルダ

opencode が更新されて 14 個の構成が変わったら opencode_model_tools を呼ぶと not_mirrored と mirrored_but_missing_upstream に差分が出る。

write と edit はブリッジのプロセスが直接ファイルを書くため、 opencode の permission 機構（OPENCODE_PERMISSION）は通らない。 bash は pty 経由なのでブリッジの deny / allow パターンで守られる。

ツール一覧（29 個）

モデル向けツール（opencode が本来モデルに渡すもの）

bash / read / write / edit / glob / grep / webfetch / todowrite / opencode_model_tools （詳細は上の表を参照）

エージェント

シェル

シェルの実行経路（重要）

opencode_shell 系は、接続先 opencode の能力に応じて次の順に経路を選びます。ツール名・引数・cursor の意味は経路が変わっても同じです。

OPENCODE_MCP_SHELL_BACKEND で経路を固定できます（auto / pty / v2 / legacy）。PTY 経路では TERM=dumb を渡し、色や制御文字を除去した素のテキストを返します。

能力検出は起動時に一度走りますが、opencode 本体の起動が遅れていると /api/pty を取り逃すことがあります。その一度きりの失敗で以降ずっとモデル依存の旧 API に落ちないよう、auto / pty では「pty なし」と判定してから 15 秒以上経っていればシェル実行時に再判定します。pty の起動そのものを拒否したビルドでは、この再判定は行いません。

ファイル・検索

承認（permission / question）

診断

すべてのツールは JSON テキストを返し、ok と next_action（次に呼ぶべきツールのヒント）を含みます。 これにより、tool calling に不慣れなチャット AI でも「次に何をすればよいか」を迷いません。

セットアップ

git clone https://github.com/nmt3325/opencode-mcp-bridge.git
cd opencode-mcp-bridge
npm install
npm run build

# 1) opencode をサーバーモードで起動
opencode serve --port 4096 --hostname 127.0.0.1

# 2) ブリッジを起動（HTTP モード）
OPENCODE_BASE_URL=http://127.0.0.1:4096 \
OPENCODE_MCP_TOKEN=$(openssl rand -hex 24) \
node dist/index.js --http --port 8787

stdio で使う場合は node dist/index.js --stdio。

MCP クライアント設定例

Streamable HTTP:

{
  "mcpServers": {
    "opencode": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer <OPENCODE_MCP_TOKEN>" }
    }
  }
}

stdio:

{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp-bridge/dist/index.js", "--stdio"],
      "env": { "OPENCODE_BASE_URL": "http://127.0.0.1:4096" }
    }
  }
}

環境変数

既定の拒否パターン: rm -rf /, rm -rf /*, rm -rf ~, mkfs*, dd if=* of=/dev/*, shutdown*, reboot*, halt*, chmod -R 777 /*, フォークボム など。

セキュリティ

• 必ず 127.0.0.1 にバインドしてください。opencode のサーバーモードは認証が無く、シェル実行 API を含みます（過去に /find 経由のコマンドインジェクション事例あり）。外部公開する場合は Tailscale / SSH トンネル + OPENCODE_MCP_TOKEN を併用してください。

• ブリッジのガードは二重防御の 1 枚目です。opencode 側の permission 設定（examples/opencode.json）も必ず設定してください。

• 可能なら専用コンテナ / VM 内で動かし、ホストの鍵や本番環境の認証情報を置かないこと。

テスト

npm test     # test/e2e.sh

test/mock-opencode.mjs（依存ゼロのモック opencode）を起動し、curl だけで MCP over HTTP を叩いて 49 項目を検証します。

• v2 API 構成: initialize / tools/list / 各ツール / permission 承認フロー / セッション無し時 400 応答

• --legacy 構成: /api/shell と prompt_async を 404 にして、旧 API への自動フォールバックを検証

• --html-spa / --spa-post 構成: /api/shell が Web UI の HTML を 200 で返すビルドでも誤検出しないことを検証（下記の実機バグの回帰テスト）

===================================
 passed: 49   failed: 0
===================================

実物の opencode に対する疎通確認は bash test/smoke-real.sh（opencode serve が起動している必要あり）。

実機検証で見つかったバグと修正

モックだけでなく実際の opencode serve に繋いだところ、次の不具合を検出して修正しました。

• 現象: 一部のビルドは未定義のパスに対して Web UI の HTML を HTTP 200 で返す。そのため GET /api/shell が 200 になり、ブリッジが「v2 シェル API あり」と誤検知 → シェル実行が shell id missing in response で失敗した。

• 修正: 能力検出をステータスコードだけでなく ボディが本当に JSON か（isJsonPayload）で判定するように変更。さらに POST /api/shell が JSON でない応答を返した場合も実行時に legacy ルートへ自動ダウングレードするようにした。

• 回帰テスト: モックに --html-spa / --spa-post モードを追加し、両ケースを e2e に組み込み。

修正後の実機実行結果（bash test/smoke-real.sh）:

{ "ok": true, "capabilities": { "reachable": true, "shellApi": "legacy", "promptAsync": true, "sessionStatusEndpoint": true, "vcsBase": "/api/vcs" } }
{ "ok": true, "shell_id": "local-90c75649", "api": "legacy", "status": "completed", "exit_code": 0, "output": "real-opencode-ok\nLinux\n" }

ライセンス

MIT