Umbra

Управляйте собственным браузером Chrome, в котором вы уже вошли, через AI-агента — по одной сессии за раз, не передавая агенту ваши cookie.

Umbra — это две части, связанные общим ключом, который вы генерируете: MV3-расширение Chrome, владеющее всеми вызовами Chrome API, и локальный MCP-сервер, предоставляющий поверхность браузерных инструментов любому MCP-клиенту. Они общаются только через аутентифицированный loopback WebSocket. Ничего не покидает машину.

Зачем это существует

Удалённая отладка браузера даёт агенту всё сразу: каждую вкладку, каждое хранилище cookie, каждый профиль. Umbra занимает противоположную позицию. Агент получает группу вкладок, которую он создал, вкладки внутри неё и ничего больше. Попросите его прочитать вкладку, которая ему не принадлежит, — и расширение откажет ещё до того, как Chrome будет затронут.

Два инструмента намеренно находятся за пределами этой границы, и оба перечислены как таковые в docs/permissions.md: browser_find_tabs и browser_find_groups сообщают заголовок и URL вкладок, не принадлежащих сессии, — так вы передаёте вкладку другой сессии, а browser_cleanup_groups сопоставляет группы вкладок по заголовку во всём профиле, чтобы можно было очистить группы, оставленные завершившейся сессией. Дайте browser_cleanup_groups префикс заголовка, который не совпадает с вашими собственными группами, или запустите его с dryRun: true.

Именно эта граница делает инструмент пригодным для использования с браузером, в который вы уже вошли. Агент может прочитать панель, в которую вы вошли, заполнить форму, выгрузить CSV и закрыть свои вкладки по завершении, а ваши остальные окна останутся нетронутыми и недоступными для чтения.

Проект намеренно скучный:

• настоящий Chrome, настоящий профиль, настоящее состояние входа — выбираете вы

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

• владение вкладками на уровне сессии проверяется при каждом действии

• никакого экспорта cookie, никакого извлечения токенов, никакого решения CAPTCHA, никакого фонового fetch

• loopback-транспорт с HMAC-рукопожатием в обоих направлениях

Related MCP server: agent-browser-ga MCP

Установка

Полное пошаговое руководство со всеми переменными, необходимыми для обычной установки, — в docs/install.md. Краткая версия:

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

Зависимости живут в mcp-server/, а не в корне репозитория, поэтому npm install в корне ничего не устанавливает, а npm test там падает, пока не выполнена команда выше. После этого npm test, npm run doctor и npm run release:check работают из корня.

Загрузите extension/ как распакованное расширение на chrome://extensions с включённым режимом разработчика, откройте страницу параметров расширения, нажмите Generate Key, затем нажмите Copy Environment Line и вставьте эту строку в конфигурацию вашего MCP-клиента. Перезапустите клиент — инструменты появятся. Нажмите Grant Site Access на той же странице перед первым чтением страницы, потому что Umbra не запрашивает доступ к сайтам при установке.

Установка — это клонирование из публичного репозитория. После клонирования выше node mcp-server/cli.js pair генерирует ключ, записывает его в ~/.umbra/shared-key и печатает блок конфигурации клиента. Публичный checkout не содержит необязательных локальных плагинов.

Поверхность инструментов

Сессия и вкладки browser_create_tab, browser_list_tabs, browser_switch_tab, browser_close_tab, browser_close_session_tabs, browser_freeze_session_tabs, browser_group_tabs, browser_cleanup_groups, browser_mark_debug_group, browser_tabs_context, browser_get_session_status, browser_get_bridge_pressure

Принятие вкладок, которые вы уже открыли browser_find_tabs, browser_adopt_tab, browser_find_groups, browser_adopt_group

Навигация browser_navigate, browser_navigate_back, browser_navigate_forward, browser_wait, browser_resize

Чтение browser_get_page_content, browser_read_page, browser_read_interactive, browser_find, browser_get_technical_snapshot, browser_screenshot, browser_console_messages

Взаимодействие browser_click, browser_click_text, browser_type, browser_fill, browser_form_input, browser_select_option, browser_hover, browser_press_key, browser_shortcut, browser_scroll, browser_file_upload

Композитные операции, экономящие обходы browser_batch, browser_wait_click_read, browser_navigate_wait_read, browser_click_wait_selector_read

Запасные выходы browser_javascript, browser_run_page_action, browser_wait_for_download

browser_reload_extension существует только для распакованных установок для разработчиков. Он анонсируется при UMBRA_ALLOW_EXTENSION_RELOAD=1, а установки из магазина отказывают в нём. Кнопка Reload на странице параметров покрывает тот же рабочий процесс без раскрытия кросс-сессионного инструмента.

Список выше — это вся поверхность каждого опубликованного сборка. В checkout могут входить необязательные локальные плагины страничных рецептов, которые не входят ни в один опубликованный сборк: модуль в mcp-server/plugins/ в паре с рецептом страницы в extension/recipes/. Обе папки не отслеживаются и не публикуются, и плагин добавляет свои собственные инструменты и свои собственные значения browser_run_page_action в список только в той установке, где он присутствует.

Замечания, которые стоит знать перед вызовом этих инструментов:

• browser_get_page_content по умолчанию возвращает только текст и поддерживает ограничение по селектору плюс лимит maxChars. Передавайте includeImages: true только когда нужен перечень видимых изображений.

• browser_batch выполняет ограниченный рабочий процесс create, navigate, wait, read, click, fill, press, scroll, close за один вызов MCP. Дочерние параметры могут ссылаться на более ранние результаты через {"$ref":"prev.tabId"} для последнего успешного шага, {"$ref":"0.tabId"} для шага по индексу или {"$ref":"create.tabId"}, если тот более ранний вызов задал label: "create".

• browser_read_interactive возвращает компактный список видимых элементов управления с короткоживущими ссылками, привязанными к текущей версии DOM. browser_click, browser_fill, browser_scroll и browser_screenshot принимают эти ссылки; устаревшая ссылка возвращает ошибку, говорящую вызывающему прочитать заново.

• browser_get_bridge_pressure сообщает давление одной сессии: количество принадлежащих ей вкладок и выборку этих вкладок, количество подключённых слушателей и глубину очереди контент-агента. Он также убирает записи владения для вкладок, которых больше не существует, так что это не чисто read-only.

• browser_freeze_session_tabs отбрасывает принадлежащие неактивные вкладки через chrome.tabs.discard, чтобы освободить память рендерера. По умолчанию dryRun: true и никогда не нацеливается на вкладку, принадлежащую другой сессии.

• browser_run_page_action выполняет предопределённые именованные действия страницы и возвращает JSON-безопасный вывод. Это не инструмент произвольных скриптов; browser_javascript — это он, и он маршрутизируется через отладчик на принадлежащей вкладке.

Как это устроено

1. Ваш MCP-клиент общается с локальным сервером через stdio.

2. Сервер регистрирует сессию либо напрямую на loopback-мосту, либо через Rust-брокер.

3. Офскрин-документ расширения Chrome держит WebSocket и поддерживает его живым при смене service worker.

4. Расширение аутентифицирует каждое соединение HMAC-вызовом на основе общего ключа плюс одноразовых nonce для каждой сессии.

5. Фоновый service worker назначает каждой сессии свою группу вкладок и проверяет владение перед каждым вызовом Chrome.

Существуют два транспорта. Rust-брокер — это запуск по умолчанию: один WebSocket расширения, множество лёгких MCP-шимов, регистрирующих сессии за ним через локальный Unix-сокет, при этом брокер владеет маршрутизацией, аутентификацией, счётчиками давления и очисткой запросов. Легаси-режим даёт каждой сессии собственный loopback-слушатель и включается одной настройкой UMBRA_BROKER_MODE=legacy. В любом случае расширение — единственное, что касается Chrome API.

Параллельность и владение

• Один профиль Chrome размещает много сессий одновременно.

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

• Открытие, навигация и взаимодействие с DOM по умолчанию работают с неактивными вкладками, так что рутинная работа никогда не выводит Chrome на передний план. Передавайте activate: true, когда фокус действительно нужен.

• Umbra запоминает выделенное окно Chrome для своих вкладок и направляет новые вкладки сессии туда. Он отказывается переиспользовать это окно, пока оно в фокусе, так что никогда не добавляет вкладки в окно, в котором вы работаете.

• Навигация ограничена по схеме на границе расширения: разрешены http:, https:, file: и about:blank, а рискованные схемы, такие как javascript: и data:, отклоняются до того, как Chrome их увидит.

• По завершении задачи агент должен вызвать browser_close_session_tabs, который закрывает всю принадлежащую группу. Он закрывает целое окно только когда каждая вкладка в этом окне принадлежит сессии, так что непринадлежащие пустые вкладки выживают.

• Чистое завершение сервера по умолчанию выполняет ту же очистку. Установите UMBRA_KEEP_TABS_OPEN=1 или UMBRA_CLOSE_ON_SHUTDOWN=0, когда запуск должен оставить вкладки открытыми для проверки.

• Диапазон портов по умолчанию — 47821-47852, что достаточно широко, чтобы обычная многозадачная работа агентов никогда не исчерпала место. Расширение ограничивает настроенный порт диапазоном 1024-65535; задайте одинаковый диапазон на обеих сторонах.

Чего Umbra не будет делать

• выгружать или синхронизировать cookie

• извлекать токены

• выставлять чтение и запись хранилища как инструменты

• выполнять фоновый fetch от имени страницы

• решать CAPTCHA

• трогать закладки, историю или буфер обмена

• использовать native messaging

• автообновляться, автоподтягиваться или автоустанавливаться

Известные ограничения

• Скриншоты по умолчанию активируют вкладку, принадлежащую сессии, перед захватом. silent: true избегает этого, подключая chrome.debugger к принадлежащей вкладке для одного Page.captureScreenshot, из-за чего Chrome показывает свой баннер автоматизации.

• Доступ к сайтам — необязательное разрешение, запрашиваемое кнопкой Grant Site Access на странице параметров, а не при установке. Пока оно не выдано, чтение страниц и скриншоты падают с собственной ошибкой разрешения Chrome, потому что Chrome требует буквального широкого разрешения хоста для программного захвата видимой вкладки. docs/permissions.md обосновывает каждое разрешение, которое объявляет расширение.

• Завершение загрузки определяется наблюдением за файловой системой, потому что расширение не запрашивает разрешение Chrome downloads. Укажите UMBRA_DOWNLOAD_DIR на папку загрузок вашего браузера, если вы её переместили.

• browser_read_interactive намеренно компактен. Umbra не выставляет полный дамп дерева доступности.

• Общие клики по тексту могут попасть не в тот элемент управления в плотных интерфейсах приложений, например в пагинации поиска. Используйте browser_read_interactive со ссылками или browser_run_page_action с inspect_controls, а затем click_control, вместо угадывания.

• Смена диапазона портов требует перезагрузки обеих сторон: перезапустите MCP-клиент, чтобы новые процессы сервера унаследовали окружение, и перезагрузите распакованное расширение, чтобы сохранённое хранилище расширения нормализовалось.

Структура

• extension/ — MV3-расширение: фоновый воркер, офскрин-мост, контент-агент, страница параметров, попап

• extension/recipes/ — необязательные рецепты страниц для конкретных сайтов, внедряемые по требованию и отсутствующие в опубликованном пакете

• mcp-server/ — stdio MCP-сервер, loopback-мост, клиент-шим Rust-брокера и локальный харнесс разработки

• rust-broker/ — среда выполнения Tokio-брокера, мультиплексирующая сессии через один WebSocket расширения

• tests/ — покрытие аутентификации, владения, изоляции сессий, жизненного цикла расширения и упаковки

• scripts/ — изолированный лаунчер тестового профиля Chrome и обёртки smoke-тестов

• launchd/ — шаблон для необязательной macOS-задачи, поддерживающей брокер запущенным

• docs/ — установка, архитектура, разрешения и заметки по smoke-тестам

Документация

• docs/install.md — настройка от клонирования до подключённой сессии, плюс каждая переменная окружения

• docs/architecture.md — компоненты, поток и обоснование разделения офскрин и фонового

• docs/permissions.md — каждое разрешение Chrome с его риском и его смягчением

• docs/smoke-test.md — автоматические и ручные пути проверки

• docs/performance/performance-work.md — что изменил проход по производительности и что он измерил

• MCP_PROTOCOL.md — проводной протокол между расширением и сервером

• THREAT_MODEL.md — активы, границы доверия, атакующие и смягчения

• SECURITY_REVIEW.md — позиция ревью, матрица «оставить и убрать» и выводы аудита вышестоящих

• rust-broker/README.md — область брокера и как его запускать

• rust-broker/LEGACY_FALLBACK.md — триггеры отката и форма перехода

Прочитайте THREAT_MODEL.md и SECURITY_REVIEW.md, прежде чем направлять это на браузер, в котором есть что-то, что вам дорого.