# Yandex Browser MCP

Управление **уже открытым Яндекс Браузером** из агента с поддержкой MCP.
Обычные вкладки, текущая авторизация, клики, клавиатура, чтение страниц и
редактирование через интерфейс сайта. Без отдельного рабочего профиля и
подтверждения каждого действия.

```text
MCP-клиент → локальный Node.js сервер → расширение → твои вкладки
```

Проект состоит из расширения Manifest V3 и сервера. В самом проекте нет LLM,
API-ключей модели или облачного посредника. Агент и его провайдер определяются
тем приложением, в котором ты подключишь MCP.

## Быстрый запуск

**Установка по заданию агенту:** скачай [комплект для Windows](https://github.com/Dizory/yandex-browser-mcp/releases/latest)
и передай агенту текст из [AGENT_PROMPT.txt](AGENT_PROMPT.txt). Подробная процедура
для агента — [INSTALL_AGENT.md](INSTALL_AGENT.md).

В распакованном комплекте запусти `install.ps1` через PowerShell. Он установит
зависимости, запустит сервер и создаст настройки MCP с абсолютными путями.
Флаг `-RegisterCodex` добавит подключение в Codex. Расширение загружается через
`browser://extensions` агентом с доступом к интерфейсу или пользователем.

Для установки из исходников вручную:

Нужны Node.js 22+ и настольный Яндекс Браузер с поддержкой Manifest V3.

```sh
git clone https://github.com/Dizory/yandex-browser-mcp.git
cd yandex-browser-mcp
npm ci
npm start
```

На Windows можно запустить `start.cmd`: при первом запуске он установит
зависимости, затем запустит сервер. Окно сервера нужно оставить работающим.

Открой в Яндексе `browser://extensions`, включи режим разработчика, нажми
**Загрузить распакованное расширение** и выбери папку `extension` из этого
репозитория. Это одноразовая установка; браузер останется в твоём текущем
профиле. В окне расширения будет виден статус соединения. Если в твоей версии
Яндекса загрузка распакованных расширений ограничена, это нужно проверить
отдельно — обход ограничений браузера проект не устанавливает.

Состояние сервера: <http://127.0.0.1:37891/health>.
`"connected":true` означает, что расширение подключено.

## Подключение агента

Адрес MCP (Streamable HTTP):

```text
http://127.0.0.1:37891/mcp
```

Для Codex добавь в `config.toml`:

```toml
[mcp_servers.yandex_browser]
url = "http://127.0.0.1:37891/mcp"
```

Или выполни:

```sh
codex mcp add yandex_browser --url http://127.0.0.1:37891/mcp
```

Если клиент поддерживает только stdio, укажи полный путь к `server/stdio.js`:

```json
{
  "mcpServers": {
    "yandex_browser": {
      "command": "node",
      "args": ["C:/path/to/yandex-browser-mcp/server/stdio.js"]
    }
  }
}
```

Сервер `npm start` нужен и для stdio: переходник соединяет агента с тем же
локальным сервером. Несколько MCP-клиентов могут подключаться одновременно.
На каждой вкладке команды выполняются последовательно, но последовательности
из нескольких вызовов разных агентов могут перемежаться — распределяй им
разные вкладки. Подключается один экземпляр расширения за раз.

Пример задания агенту:

> Найди открытую вкладку с CRM. Прочитай карточку текущего клиента и заполни
> комментарий «Перезвонить завтра». Сохрани изменение.

## Команды

| Инструмент | Назначение |
|---|---|
| `browser_tabs` | Список вкладок, адреса и идентификаторы |
| `browser_open` | Открыть HTTP(S)-страницу |
| `browser_activate` | Выбрать вкладку и окно |
| `browser_close` | Закрыть вкладку |
| `browser_navigate` | Перейти по адресу в существующей вкладке |
| `browser_snapshot` | Текст страницы и элементы с CSS-селекторами |
| `browser_click` | Клик по селектору или координатам; двойной/правый клик |
| `browser_type` | Ввод текста, в том числе в contenteditable; замена содержимого |
| `browser_press` | Клавиша или сочетание: Enter, Tab, Control+A и др. |
| `browser_scroll` | Прокрутка страницы или вложенной области |
| `browser_screenshot` | PNG текущей видимой области вкладки |
| `browser_evaluate` | JavaScript-выражение в странице с ожиданием Promise |
| `browser_cdp` | Произвольная доступная команда Chrome DevTools Protocol |

Начинай с `browser_tabs`, затем `browser_snapshot`. После переходов и изменения
страницы запрашивай новый снимок. Для таблиц с canvas используй screenshot,
координаты и клавиатуру; для специфичных операций — evaluate/CDP. Обычный
снимок читает главный документ, максимум 300 элементов и по умолчанию 20 000
символов. `maxChars` увеличивает лимит текста до 100 000. Неподгруженные строки,
вложенные фреймы и закрытые Shadow DOM не превращаются автоматически в текст.

Клик и клавиатура используют CDP Input, поэтому события приходят сайту как
браузерный ввод. Выбор по CSS требует единственного подходящего элемента.
Это важно для чатов и таблиц, которые игнорируют простой DOM `.click()`.

## Вход и пароли

Уже выполненный вход используется автоматически. Клик в поле может вызвать
обычное автозаполнение браузера. Универсального управления меню менеджера
паролей, системным подтверждением и MFA здесь нет: если браузер требует
твоего участия, заверши вход и продолжай работу с агентом.

Обычный snapshot не возвращает значения password-полей. Это удобное исключение
из вывода, **не изоляция секретов**: evaluate/CDP дают полный доступ к странице,
а снимок экрана показывает то, что отображается в ней. Данные, прочитанные
агентом, могут попасть к его LLM-провайдеру. Сервер не пишет содержимое страниц
в файлы или журналы и слушает только `127.0.0.1`.

## Проверка

```sh
npm test
```

Проверяются настоящий MCP-handshake, схемы инструментов, маршрутизация ответов
между клиентами, ошибки ввода, обрыв связи, timeout без повторения действия и
ответы с изображениями. Расширение проверяется отдельно в тестах его логики.

После запуска сервера и установки расширения:

```sh
npm run test:browser
```

Этот тест открывает **свою локальную страницу**, вводит русский текст,
нажимает кнопку, меняет ячейку, проверяет двойной клик, клавиатуру, прокрутку,
снимок экрана, CDP и переход. Затем закрывает свою вкладку. Реальные чаты и
документы тест не изменяет. Значение тестового password-поля проверяется на
отсутствие в snapshot.

## Если что-то не работает

- `Browser extension is not connected`: запусти сервер, включи расширение,
  нажми переподключение в его окне. При перезапуске сервера оно переподключается.
- Порт занят: проверь `/health`. Если сервер уже запущен, используй его.
- Ошибка debugger: служебные страницы браузера и страницы других расширений
  могут быть недоступны; открытые DevTools могут мешать подключению.
- После ошибки или timeout сначала прочитай страницу: действие могло успеть
  выполниться. Сервер не повторяет изменения автоматически.
- Изменения исходников расширения требуют кнопки перезагрузки на странице
  `browser://extensions`; изменения сервера — его перезапуска.
- MCP не делает агента постоянно работающим. Для непрерывного наблюдения за
  чатом нужен работающий агент с циклом проверки или планировщик его клиента.
- Удалённый облачный агент не видит `127.0.0.1` твоего компьютера. В этой версии
  подключение рассчитано на MCP-клиенты, работающие локально.

Протокол между сервером и расширением описан в [PROTOCOL.md](PROTOCOL.md).

Чтобы собрать ZIP-комплект и SHA256: `powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/package.ps1`.
Результат появится в `artifacts`. В архив входят исходники, тесты и инструкции;
`node_modules`, локальные настройки MCP, журналы и данные браузера не включаются.

## Статус

Версия 0.1 — первая реализация. 4 ноября 2026 года `npm run test:browser`
успешно проверил все 13 инструментов в установленном Яндекс Браузере: русский
текст, отправку тестового сообщения, редактирование ячейки, доверенный клик,
двойной клик, клавиатуру, вложенную прокрутку, PNG, CDP и переходы. Значение
тестового password-поля не попало в snapshot; тестовая вкладка закрыта.

Это не подтверждает совместимость со всеми сайтами или версиями Яндекса.
Для своей версии браузера запусти `npm run test:browser`; встроенное
автозаполнение паролей пока не проверено.

MIT License.