OpenCode V2 MCP Bridge

MCP-сервер, который позволяет Cursor (и любому другому MCP-клиенту) запускать агентов OpenCode V2 с выбранной моделью: oc_task({ agent, model, prompt }).

Написан потому, что популярные community-мосты (opencode-mcp, mcp-server-opencode, opencode-mcp-bridge и т.п.) используют старый API OpenCode (/session, /agent) и на OpenCode V2 возвращают HTML веб-приложения вместо JSON.

Работает через общий фоновый сервис OpenCode, поэтому сессии видны и в TUI, и в Cursor. Пароль сервиса читается локально и никуда не отправляется.

Требования

• OpenCode V2 (opencode --version, проверено на 2.1.1)

• Node.js 22+

• Cursor с поддержкой MCP (или любой MCP-клиент)

• Linux/macOS (Windows — см. раздел «Windows»)

Related MCP server: opencode-mcp

Установка

tar -xzf opencode-v2-mcp-bridge-1.0.0.tar.gz
cd opencode-v2-mcp-bridge
./install.sh

Скрипт:

1. копирует мост в ~/.config/opencode/mcp-bridge;

2. добавляет сервер opencode в ~/.cursor/mcp.json (существующие серверы сохраняются);

3. кладёт примеры агентов в ~/.config/opencode/agents (если таких файлов ещё нет).

Затем перезапустите Cursor.

Опции:

./install.sh --dir ~/tools/opencode-mcp-bridge   # другой каталог установки
./install.sh --no-agents                        # не устанавливать агентов

Ручная установка:

mkdir -p ~/.config/opencode/mcp-bridge
cp -R dist run.sh README.md LICENSE ~/.config/opencode/mcp-bridge/
chmod +x ~/.config/opencode/mcp-bridge/run.sh

~/.cursor/mcp.json:

{
  "mcpServers": {
    "opencode": {
      "command": "/home/<you>/.config/opencode/mcp-bridge/run.sh",
      "args": []
    }
  }
}

Инструменты

oc_task по умолчанию ждёт 50 секунд — это меньше типичного таймаута MCP-клиента. Для длинных задач:

oc_task({ ..., background: true })  ->  sessionID
oc_status({ sessionID, waitSeconds: 120 })

Модели

По умолчанию используется модель, заданная у агента. Если у агента модели нет, он наследует модель родительской сессии (так же ведут себя его субагенты).

Переменные окружения (задаются в ~/.cursor/mcp.json → env):

Ретрай не срабатывает для background: true, таймаутов, отмены и отказов в permissions — чтобы не дублировать работу.

Пример: бесплатная модель + платный fallback

"env": {
  "OPENCODE_FORCE_MODEL": "opencode/deepseek-v4.1-flash-free",
  "OPENCODE_FALLBACK_MODEL": "deepseek/deepseek-flash"
}

deepseek/deepseek-flash — официальный id DeepSeek-V4.1-Flash у провайдера deepseek. Чтобы он появился, добавьте провайдера в ~/.config/opencode/opencode.json (ключ — из DEEPSEEK_API_KEY или файла):

"providers": {
  "deepseek": {
    "name": "DeepSeek",
    "package": "aisdk:@ai-sdk/openai-compatible",
    "settings": {
      "baseURL": "https://api.deepseek.com",
      "apiKey": "{file:~/.config/opencode/deepseek.key}"
    },
    "models": {
      "deepseek-flash": {
        "name": "DeepSeek V4.1 Flash",
        "limit": { "context": 1048576, "output": 393216 }
      }
    }
  }
}

После правки: opencode reload.

В ответе oc_task при срабатывании fallback появляется блок:

"fallback": {
  "from": "opencode/deepseek-v4.1-flash-free#default",
  "to": "deepseek/deepseek-flash",
  "reason": "Free usage limit reached...",
  "originalSessionID": "ses_..."
}

Агенты

Глобальные: ~/.config/opencode/agents/<name>.md. Проектные: .opencode/agents/<name>.md.

Чтобы агента можно было запускать из Cursor, он должен быть mode: all или mode: primary. Агенты mode: subagent запускаются только другим агентом OpenCode.

---
description: Дешёвый read-only ревьюер
mode: all
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---
Ты — лаконичный ревьюер. Не используй инструменты.

Модель в агенте можно не указывать — тогда он наследует модель сессии, и OPENCODE_FORCE_MODEL / OPENCODE_FALLBACK_MODEL действуют на всю цепочку включая субагентов.

Диагностика

Проверить, что сервис жив:

opencode service status

Проверить мост вручную (MCP Inspector):

npx -y @modelcontextprotocol/inspector ~/.config/opencode/mcp-bridge/run.sh

Логи Cursor:

tail -40 "$(ls -dt ~/.cursor/logs/*/ 2>/dev/null | head -1)mcp-server-user-opencode.log"
# или
tail -40 "$(ls -dt ~/.config/Cursor/logs/*/ 2>/dev/null | head -1)mcp-server-user-opencode.log"

Типичные ошибки:

Windows

run.sh рассчитан на bash. Варианты:

• WSL + Cursor в WSL;

• запускать напрямую: node dist/index.mjs с переменными OPENCODE_BASE_URL, OPENCODE_SERVER_PASSWORD, OPENCODE_DEFAULT_DIRECTORY;

• либо добавить в mcp.json:

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

Безопасность

Мост не хранит секретов: URL и пароль читаются из локального сервиса OpenCode (opencode service status, ~/.config/opencode/service.json). Наружу ничего не отправляется, кроме запросов к вашему локальному OpenCode.

Лицензия

MIT.