opencode-chromium

Сообщество и дорожная карта

Дорожная карта формируется пользователями — открывайте предложения, голосуйте с помощью реакций и следите за анонсами в GitHub Discussions:

• Запросы функций — начните предложение (шаблон сохраняет структуру): опишите проблему и рабочий процесс, который оно должно открыть; другие голосуют с помощью реакций 👍/❤️. Мейнтейнеры распределяют получившие голоса предложения в предстоящую работу и помечают их статусом (planned, in progress, released). Открыть предложение →

• Анонсы — релизы, статус дорожной карты и заметки мейнтейнеров. Следить за анонсами →

• Протокол — запросы функций касаются того, что публикует этот репозиторий (runtime, расширение, нативный хост, навыки); сообщения об ошибках и находки в области безопасности относятся к GitHub Issues.

Related MCP server: chrome-devtools-mcp

Что он предоставляет

• Четыре компактных инструмента по умолчанию: browser_run, browser_observe, browser_session и browser_finalize.

• Полный многоперационный браузерный движок с явными режимами совместимости и возможностей.

• Экономные по контексту данные: сводки наблюдений опускают пустые поля, повторяющийся текст и подробные html/styles (доступны только через detail: "debug"), а встроенные ответы остаются в пределах бюджета в 4 096 символов, при этом избыточные выходные данные выносятся в ресурсы-артефакты.

• Нативные наведение, обработка диалогов JavaScript с подтверждением и скриншоты png/jpeg/webp с контролем качества.

• Ненавязчивая фоновая автоматизация: клики, ввод и навигация никогда не активируют вкладку и не выводят её окно на передний план, так что вы можете продолжать работать, пока инструмент управляет фоновой вкладкой.

• Политика источников на уровне сервера (glob-шаблоны разрешённых/заблокированных источников) и ограничения корневых каталогов файлов для загрузок.

• Постоянная эмуляция сеанса (viewport, network, CPU, geolocation, color scheme, user agent, headers, init scripts) с автоматическим сбросом при финализации.

• Детализация сетевых запросов по requestId с выносом тела запроса в артефакты и трассировками стека консоли с исходными картами.

• Диагностика производительности: режим diagnostic инструмента browser_observe записывает CDP-трассы и вычисляет LCP, CLS, длинные задачи, TBT и другое в нативном хосте; сырые трассы сохраняются в первую очередь как артефакты, а данные CrUX/полевые данные остаются отключёнными.

• Поиск по странице со Snowflake по умолчанию, с явными лексическими/автоматическими альтернативами и глубоким поиском Qwen без загрузки моделей в расширение.

• Сеансы с учётом профилей, владение вкладками, восстановление устаревших целей, ограниченные повторные попытки чтения, условное ожидание, подтверждения и ресурсы-артефакты.

• Транспорты MCP stdio и loopback/аутентифицированный HTTP с чистым по протоколу stdout.

• Нативный адаптер OpenCode V2 и общие адаптеры схем OpenAI, Anthropic, Gemini и MCP.

Быстрый старт (npm)

Установите опубликованный пакет один раз, затем подключайте любой поддерживаемый клиент. Пакет включает CLI (opencode-chromium), бинарник MCP-сервера (opencode-chromium-mcp), расширение для браузера и установщик нативного хоста:

npx -y opencode-chromium-mcp

1. Установите пакет

npm install -g opencode-chromium

2. Загрузите расширение браузера

Установите opencode-chromium из Chrome Web Store. Описанный ниже процесс с распакованным расширением остаётся доступным для разработки и локального тестирования.

Откройте chrome://extensions, включите режим разработчика и загрузите распакованную папку extension/ из установленного пакета:

npm root -g
# load "<that path>\opencode-chromium\extension" as an unpacked extension

Идентификатор расширения определяется путём загрузки, поэтому оставьте папку на месте. Запомните ID, показанный в chrome://extensions.

3. Установите нативный хост обмена сообщениями

node "$(npm root -g)/opencode-chromium/scripts/install-native-host.js" --extension-id <extension-id> --browsers chrome

4. Подключите клиент

OpenCode V2 — добавьте имя пакета в глобальный ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

Codex — зарегистрируйте необходимый MCP-сервер:

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp

Любой MCP-клиент — добавьте stdio-сервер:

{
  "mcpServers": {
    "opencode-browser-plugin": {
      "command": "npx",
      "args": ["-y", "opencode-chromium-mcp"]
    }
  }
}

Прямой JavaScript — импортируйте SDK runtime или MCP-сервер программно (см. docs/direct-sdk.md).

5. Проверьте

opencode-chromium doctor --json
opencode-chromium verify

Все четыре инструмента (browser_run, browser_observe, browser_session, browser_finalize) становятся доступны в каждом подключённом клиенте. Не включайте одновременно нативный адаптер OpenCode и MCP-сервер в одном клиентском сеансе, если только дублирующиеся инструменты не являются намеренными.

Требования

• Node.js 20 или новее для npm-пакета и SDK.

• Bun 1.1 или новее при сборке из исходников или запуске скриптов репозитория.

• Браузер на основе Chromium с загруженным распакованным extension/.

• Установленный нативный хост обмена сообщениями для идентификатора расширения.

Установка и сборка

bun install --frozen-lockfile
bun run build
bun test
bun run check

Пакет выпущен как 1.6.1 под npm-именем opencode-chromium. Стабильный идентификатор runtime и MCP-сервера остаётся opencode-browser-plugin для совместимости с клиентами.

MCP

Запустите сервер с четырьмя инструментами через stdio:

bun run mcp

Или используйте упакованный бинарник:

opencode-chromium-mcp

Loopback Streamable HTTP доступен с помощью:

bun run mcp:http

Для HTTP не на loopback требуется bearer-токен в AGENT_BROWSER_AUTH_TOKEN (или переменная, выбранная с помощью --auth-token-env). Имя сервера по умолчанию — opencode-browser-plugin. Конфигурация безопасности источников и корневых каталогов файлов выполняется на уровне сервера: передавайте glob-шаблоны --allowed-origin / --blocked-origin или задайте AGENT_BROWSER_ALLOWED_ORIGINS, AGENT_BROWSER_BLOCKED_ORIGINS и AGENT_BROWSER_ALLOWED_FILE_ROOTS (см. docs/mcp.md).

OpenCode V2

Корень пакета экспортирует нативный адаптер, использующий официальную форму модуля path-plugin OpenCode 1.18.x — { id, server() }, вместе с контрактом настройки V2:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

Для локальной сборки укажите клиенту на dist/adapters/opencode/index.js или используйте команду opencode-chromium install --client opencode. Адаптер регистрирует ровно четыре инструмента, устанавливает codemode: false и возвращает функцию очистки для перезагрузок.

Тот же браузерный runtime доступен через режим совместимости MCP; не включайте обе поверхности в одном клиентском сеансе, если только дублирующиеся инструменты не являются намеренными.

Codex

Зарегистрируйте MCP-сервер из npm-пакета:

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp
codex mcp list

Из локальной копии зарегистрируйте dist/adapters/mcp/server.js с помощью Bun:

codex mcp add opencode-browser-plugin -- bun C:\absolute\path\to\dist\adapters\mcp\server.js

Встроенный навык находится в skills/opencode-browser-plugin/SKILL.md. Он следует открытому стандарту Agent Skills и охватывает маршрутизацию через коннектор, выбор профиля, пакетирование действий, поиск со Snowflake по умолчанию, токены подтверждения, артефакты и финализацию. В комплект входит agents/openai.yaml для выбора навыков в десктопных ChatGPT/Codex и метаданные зависимостей MCP.

Установите его сразу для всех клиентов, совместимых с навыками:

opencode-chromium install --client skills
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client skills

Это копирует навык в ~/.codex/skills/, ~/.claude/skills/ и ~/.agents/skills/ (в каталог opencode-browser-plugin/) и регистрирует включённую запись [[skills.config]] в ~/.codex/config.toml, удаляя при этом устаревшую запись opencode-browser-adapter.

Нативный хост и расширение

Загрузите extension/ как распакованное расширение, затем установите хост:

bun run install:native-host -- --extension-id <extension-id> --browsers chrome
bun run check:native-host -- --json

Используйте переменные окружения AGENT_BROWSER_* для новой конфигурации. Более старые имена OPENCODE_BROWSER_* остаются алиасами с более низким приоритетом в течение окна совместимости 1.x.

CLI

opencode-chromium doctor --json
opencode-chromium verify
opencode-chromium install --client opencode --dry-run
opencode-chromium install --client opencode-mcp --dry-run
opencode-chromium install --client codex --dry-run
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client codex --dry-run
opencode-chromium uninstall --client skills --dry-run

Установка и удаление создают резервную копию указанной конфигурации перед её изменением, затрагивают только каноническую запись, поддерживают пробный запуск и сообщают об изменённых файлах.

Контекст и возможности

Схемы инструментов по умолчанию остаются компактными. Запросите расширенные описания через:

{"mode":"capabilities","pack":"downloads"}

Выполняйте расширенную работу через browser_run, не добавляя инструменты верхнего уровня:

{
  "steps": [{
    "action": "capability",
    "capability": "downloads.events",
    "input": {}
  }]
}

Для глубокой отладки запросов/ответов запрашивайте ленивый сетевой пакет только при необходимости:

{"mode":"capabilities","pack":"network"}

Затем выполните network.inspect в browser_run с целевым tabId. Он отслеживает жизненный цикл CDP-запросов/ответов вкладки, поддерживает фильтры по URL/method/type/status/requestId и возвращает редактированные заголовки только при запросе includeHeaders. Тела остаются отключёнными, если они явно не запрошены и не одобрены; bodyDelivery: "artifact" выносит включённые тела в хранилище артефактов вместо встроенных предпросмотров. Режим inspect инструмента browser_observe с target.requestId возвращает детали жизненного цикла одного запроса.

Большие результаты и скриншоты сохраняются в первую очередь как артефакты. MCP-клиенты получают их через browser://sessions/<session-id>/artifacts/<artifact-id>; OpenCode может запросить тот же URI с помощью режима artifact инструмента browser_observe.

Структура репозитория

src/core/                 shared runtime, schemas, safety, artifacts, versions
src/browser/              profile-aware IPC client, policies, and operation engine
src/adapters/mcp/         universal MCP server and transports
src/adapters/opencode/    native OpenCode V2 adapter
src/adapters/sdk/         provider schema adapters and direct agent API
src/cli/                  install, configure, uninstall, doctor, verify
extension/                Manifest V3 browser integration
native-host/              native messaging host and semantic workers
skills/                   provider-neutral browser skill
tests/                    unit, contract, browser, and adapter regression tests
docs/                     architecture, compatibility, security, and migration guides

Проверка и релиз

bun run build
bun run check:schemas
bun run check:package
bun run check:mcp
bun run test:contracts
bun run test:opencode
bun run pack
bun run test:tarball
bun run check:release

Проверка релиза отклоняет устаревшие пути V1, личное состояние, дублирующиеся поверхности устаревших пакетов, рост схемы сверх бюджета и tarball без собранных адаптеров.

GitHub Actions запускает ту же проверку для pull request и push в master. Релиз публикуется только из соответствующего тега v* через защищённое окружение npm-production с использованием npm Trusted Publishing; ни в репозитории, ни в workflow не хранится npm-токен.

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

Содержимое браузера не является доверенным. Действия с последствиями требуют короткоживущих неизменяемых токенов подтверждения; записи никогда не повторяются автоматически после неопределённого выполнения. Артефакты ограничены сеансом, истекают, запрещают обход путей и не записываются в журналы. Данные протокола MCP остаются в stdout, а диагностика — в stderr.

См. docs/architecture.md, docs/security.md, docs/compatibility.md и docs/migration-1.0.md.

Лицензия

MIT