opencode2-mcp

v0.2.2

Published

10 days ago

MCP server that lets Claude Code, Codex CLI, Cursor-agent (or any MCP client) delegate bounded coding tasks to a local OpenCode v2.x instance

0High
0Medium
0Low

yuriisamohvalov

opencode-v2-mcp

English version

MCP-сервер, который позволяет Claude Code, Codex CLI, Cursor-agent (или любому другому MCP-клиенту) делегировать выполнение ограниченных задач по написанию кода локальному OpenCode v2.x. Один инструмент — opencode_execute — запускает opencode run --format json, парсит NDJSON-вывод и возвращает компактный отчёт: текст ответа, git diff --stat, git status --short, код возврата и sessionID.

Сервер реализован через стандартный @modelcontextprotocol/sdk (stdio-транспорт) — он не завязан на конкретного клиента и работает одинаково с любым MCP-совместимым хостом без каких-либо доработок кода. Подключение к Claude Code, Codex CLI и Cursor-agent подтверждено вживую (разделы ниже).

Написан по мотивам референсной реализации из community-инструкции «Claude Code Desktop → OpenCode v2 как субагент-исполнитель кода» и доработан тремя фиксами, без которых обёртка не работает с реальной установкой opencode v2.0.12 (подробности — раздел «Известные баги экосистемы» ниже).

Полная история разработки, диагностики и сравнения с другими community MCP-обёртками (все они не работают против opencode v2.x по разным причинам) — в second-brain/opencode-subagent-mcp.md (личная заметка, не публикуется).

Требования

OpenCode v2.x, установленный и доступный в PATH (opencode --version должен показывать 2.x). Бинарь ищется в PATH; путь можно переопределить переменной OPENCODE_BIN.
Node.js 18+.
Настроенный провайдер/модель в OpenCode (opencode auth login, opencode auth list).
Проект, где будет выполняться opencode_execute, должен содержать opencode.json с JSON-блоком agent (см. ниже — markdown-агенты .opencode/agent/*.md в этой версии зависают).

Установка

Вариант 1 — из npm (npmjs.org, рекомендуется)

Пакет опубликован как opencode2-mcp — полностью публичный, ставится без авторизации:

npm install -g opencode2-mcp

Вариант 2 — из исходников

git clone [email protected]:yuriisamohvalov-creator/opencode-mcp.git ~/tools/opencode-mcp
cd ~/tools/opencode-mcp
npm install

Вариант 3 — из GitHub Packages

Тот же пакет также зеркалирован в GitHub Packages под именем @yuriisamohvalov-creator/opencode-v2-mcp. Важно: в отличие от npmjs.org, GitHub Packages требует аутентификации даже для публичных пакетов — понадобится .npmrc со scoped-registry и GitHub-токеном с правом read:packages:

# ~/.npmrc или в проекте
echo "@yuriisamohvalov-creator:registry=https://npm.pkg.github.com" >> ~/.npmrc
npm login --registry=https://npm.pkg.github.com --scope=@yuriisamohvalov-creator

npm install -g @yuriisamohvalov-creator/opencode-v2-mcp

Подключение к Claude Code

NODE_BIN="$(which node)"
claude mcp add --scope user opencode-v2 -- "$NODE_BIN" "$HOME/tools/opencode-mcp/server.mjs"

Если для выхода в интернет (облачные провайдеры моделей) нужен прокси — передайте его переменными окружения при регистрации, они наследуются дочерним процессом opencode:

claude mcp add --scope user opencode-v2 \
  -e HTTPS_PROXY=http://127.0.0.1:10808 -e HTTP_PROXY=http://127.0.0.1:10808 \
  -- "$NODE_BIN" "$HOME/tools/opencode-mcp/server.mjs"

Проверка:

claude mcp get opencode-v2
# Status: ✔ Connected

После подключения новой сессии Claude Code (или рестарта текущей) инструмент opencode_execute доступен как mcp__opencode-v2__opencode_execute.

Подключение к Codex CLI

NODE_BIN="$(which node)"
codex mcp add opencode-v2 \
  --env HTTPS_PROXY=http://127.0.0.1:10808 --env HTTP_PROXY=http://127.0.0.1:10808 \
  -- "$NODE_BIN" "$HOME/tools/opencode-mcp/server.mjs"
codex mcp list   # должен показать opencode-v2 в статусе enabled

Важно: по умолчанию Codex блокирует вызовы MCP-инструментов approval- политикой, даже если approval выставлен в never — это особенность самого Codex, не обёртки. Запускайте с флагом --approve-for-me (безопасный режим через workspace-write sandbox, не с --dangerously-bypass-approvals-and-sandbox):

codex exec --approve-for-me "Use the opencode-v2 MCP tool opencode_execute with cwd=/path/to/project, agent=claude-worker, task='...'"

Если запускаете codex exec вне git-репозитория — понадобится ещё --skip-git-repo-check.

Подключение к Cursor-agent

Cursor не предоставляет CLI-команду для добавления MCP-сервера — правьте конфиг-файл напрямую: ~/.cursor/mcp.json (глобально) или .cursor/mcp.json в конкретном проекте. Формат идентичен Claude Code/Codex:

{
  "mcpServers": {
    "opencode-v2": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/opencode-mcp/server.mjs"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:10808",
        "HTTP_PROXY": "http://127.0.0.1:10808"
      }
    }
  }
}

После правки файла сервер нужно явно одобрить:

cursor-agent mcp list             # должен показать opencode-v2
cursor-agent mcp enable opencode-v2

Использование в неинтерактивном режиме:

cursor-agent -p --output-format json --force \
  "Use the opencode-v2 MCP tool opencode_execute with cwd=/path/to/project, agent=claude-worker, task='...'"

Первый вызов после добавления сервера обычно заметно медленнее последующих (холодный старт сессии cursor, наблюдалось ~20с против обычных 6–10с у прямого CLI-вызова opencode).

Конфигурация проекта — только JSON-агент

В корне проекта, где будет работать opencode_execute, создайте opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "claude-worker": {
      "description": "Implements a bounded coding task delegated by Claude Code",
      "mode": "primary",
      "prompt": "You are an implementation worker. Work only inside the current project. Make the smallest coherent change. Run relevant tests. Never commit, push, or delete broad paths. End with a concise summary."
    }
  }
}

Не используйте markdown-файлы агентов (.opencode/agent/<name>.md) — в установленной opencode v2.0.12 они приводят к зависанию opencode run без единой строки вывода, воспроизведено многократно с разным содержимым frontmatter. JSON-агент через opencode.json работает надёжно.

Использование инструмента

{
  "task": "Add a slugify() helper in src/lib/slug.ts with tests. Acceptance: kebab-case, trims whitespace. Verify with `npm test -- slug`.",
  "cwd": "/absolute/path/to/project",
  "agent": "claude-worker",
  "model": "openai/gpt-5.5",       // опционально, provider/model
  "timeoutMs": 900000               // опционально, по умолчанию 15 минут
}

Ответ:

{
  "ok": true,
  "exitCode": 0,
  "sessionID": "ses_...",
  "toolCalls": 2,
  "toolsUsed": ["write", "shell"],
  "text": "...финальный ответ модели...",
  "diffStat": "...git diff --stat...",
  "statusShort": "...git status --short..."
}

Защитная проверка: запуск без вызовов инструментов

opencode run завершается с кодом 0 и тогда, когда модель не умеет вызывать инструменты и просто описывает работу текстом (так ведут себя, например, небольшие локальные модели Ollama): файлов нет, а ответ выглядит как успех. Поэтому обёртка считает завершённые события tool_use, и если их ноль, возвращает ok: false:

{
  "ok": false,
  "reason": "no_tool_calls",
  "warning": "OpenCode finished without a single completed tool call: ...",
  "exitCode": 0,
  "toolCalls": 0,
  "toolsUsed": []
}

В ответе всегда есть toolCalls (число завершённых вызовов) и toolsUsed (уникальные имена инструментов, например ["write", "shell"]).
Если OpenCode прислал события error (скажем, provider.quota: credit_balance_exhausted), их тексты лежат в поле errors — на ok оно не влияет, но избавляет от поиска причины по пустому text.
Параметр allowNoTools: true отключает проверку — только для чисто текстовых ответов. Для задач на изменение кода его не нужно ставить.
Проверка ловит именно «ноль вызовов». Если модель вызвала read, но ничего не записала, ok останется true — смотрите statusShort и toolsUsed.

Модель важна. Используйте модель с рабочим tool calling: задайте model в opencode.json (ключ верхнего уровня) или передавайте параметр model в вызове. С моделью без tool calling задача не будет выполнена, но теперь это видно сразу, а не после проверки диска.

Известные баги экосистемы, исправленные в этой обёртке

Референсная реализация, взятая за основу, не работала «из коробки» против opencode v2.0.12. Три причины и фиксы:

Отсутствовал флаг --auto. Без него opencode не может неинтерактивно подтверждать edit/shell-разрешения — добавлен в runOpenCode() безусловно.
spawn("opencode", ...) без абсолютного пути. GUI-приложения (включая Claude Code Desktop) не всегда наследуют пользовательский PATH, где установлен opencode — используется абсолютный путь к бинарнику. Проверьте и при необходимости поправьте путь в server.mjs (spawn("/home/USER/.opencode/bin/opencode", ...)) под вашу установку — which opencode подскажет актуальный путь.
opencode v2 резолвит текущий проект через переменную окружения $PWD, а не через реальный cwd процесса. child_process.spawn() в Node корректно меняет OS-уровневый cwd дочернего процесса, но НЕ обновляет PWD в его env — без явного env: { ...process.env, PWD: input.cwd } opencode не находит определённого в opencode.json агента и падает с "Agent not found". Это не специфично для данной обёртки — баг актуален для любой Node/Bun-обёртки вокруг opencode run, использующей spawn() с cwd.

Ограничения

Одна задача — один запуск opencode run, без параллелизма в рамках одного вызова инструмента.
Инструмент не проверяет permission-конфигурацию OpenCode сам — если агент запрещает нужную команду, opencode run завершится без изменений и с пустым text; смотрите stderrTail/exitCode в ответе.
Не подменяет ревью: вызывающая сторона должна самостоятельно проверять diffStat/statusShort и результаты тестов, а не доверять только полю ok.

Смежные пакеты

Тот же синхронный паттерн (один блокирующий MCP-тул, без отдельного check/kill) применён и к трём другим шагам цепочки делегирования:

codex-cli-sync-mcp — аналогичная обёртка над Codex CLI (codex exec).
cline-sync-mcp — аналогичная обёртка над Cline CLI (cline).
cursor-agent-sync-mcp — аналогичная обёртка над Cursor-agent CLI (cursor-agent -p).

Лицензия

MIT