# Firefox Local MCP Bridge

Локальный мост для подключения Firefox к AI-агентам через Model Context Protocol (MCP).

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

Поддерживает два режима: расширение Firefox и нативное управление через WebDriver BiDi.

> Проект находится на экспериментальной стадии. Основная проверенная платформа — Windows. Полная совместимость со всеми сайтами и редакторами не гарантируется.

## Возможности

- Получение списка открытых вкладок.
- Чтение текста страниц и поиск по вкладкам.
- Получение DOM-снимков с описанием элементов.
- Навигация, открытие и закрытие вкладок.
- Заполнение полей, выбор пунктов списков и переключение checkbox.
- Клики, ввод с клавиатуры и прокрутка.
- Работа с iframe.
- Создание скриншотов.
- Прикрепление локальных файлов и скачивание файлов через Firefox.

В режиме **WebDriver BiDi** дополнительно доступны:

- Нативные события клавиатуры и мыши.
- Hover с поддержкой CSS `:hover`.
- Перетаскивание указателем, включая взаимодействие с canvas.
- Скриншоты полного документа.
- Получение сообщений консоли и сетевых событий.
- Обработка JavaScript-диалогов `alert`, `confirm` и `prompt`.

## Требования

- **Node.js 24+**
- **Firefox Desktop**
- MCP-клиент с поддержкой **stdio**, например Codex.

Для работы сервера внешние библиотеки не требуются. Зависимости разработки нужны только для тестов и сборки.

## Установка

Клонируйте репозиторий:

```bash
git clone https://github.com/kirill-alex/firefox-local-mcp-bridge.git
cd firefox-local-mcp-bridge
```

Создайте локальную конфигурацию:

```bash
node scripts/setup.mjs
```

Будут созданы:

- `config.json` — параметры локального сервера и случайный токен.
- `.local/pairing.html` — локальная страница с токеном для подключения расширения.

Эти файлы исключены из Git и архивов исходников. Повторный запуск настройки сохраняет существующий токен.

**Не публикуйте токен и не передавайте его другим людям.**

## Подключение к MCP-клиенту

### Codex

При установленной CLI Codex выполните:

```bash
node scripts/register-mcp.mjs
```

Скрипт зарегистрирует сервер `firefox-bridge`, используя фактические пути к Node.js и проекту.

После регистрации откройте новый чат Codex, если список инструментов не обновился.

### Другие MCP-клиенты

Настройте запуск `bridge.mjs` через stdio. Пример конфигурации:

```json
{
  "mcpServers": {
    "firefox-bridge": {
      "command": "node",
      "args": [
        "C:/Projects/firefox-local-mcp-bridge/bridge.mjs"
      ]
    }
  }
}
```

Замените путь на расположение проекта на своём компьютере.

Если клиент не находит Node.js через PATH, укажите абсолютный путь к исполняемому файлу Node.js в поле `command`.

## Выбор режима работы

### Режим 1: расширение Firefox

Подходит для чтения страниц и обычного взаимодействия с HTML-интерфейсами.

1. Откройте в Firefox:

   ```text
   about:debugging#/runtime/this-firefox
   ```

2. Нажмите **«Загрузить временное дополнение»**.
3. Выберите `extension/manifest.json`.
4. Откройте меню расширения → **«Настройки»**.
5. Откройте созданный файл `.local/pairing.html` и скопируйте токен в настройки расширения.
6. Запустите MCP-клиент.

Расширение подключается к локальному серверу по адресу:

```text
http://127.0.0.1:17893
```

При необходимости сервер можно запустить отдельно:

```bash
npm start
```

Временное дополнение удаляется при перезапуске Firefox. Для постоянной установки в обычный Firefox требуется подпись Mozilla. Собранный проектом архив расширения не подписан.

### Режим 2: WebDriver BiDi

Подходит для нативного ввода, работы мышью, canvas и диагностики страниц.

**В этом режиме расширение не требуется.**

Сохраните незавершённую работу и полностью закройте Firefox. Затем запустите браузер с локальным интерфейсом автоматизации.

Пример для Windows PowerShell:

```powershell
& "C:\Program Files\Mozilla Firefox\firefox.exe" --remote-debugging-port 9222
```

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

```powershell
.\start-firefox-bidi.ps1
```

Скрипт не закрывает работающий Firefox. Если браузер уже запущен, потребуется закрыть его самостоятельно.

После запуска вызовите через MCP-клиент:

```text
firefox_bidi_status
firefox_bidi_contexts
```

BiDi использует строковые идентификаторы `contextId`. Инструменты расширения используют числовые `tabId`. Эти идентификаторы не взаимозаменяемы.

Подробнее: [WebDriver BiDi](docs/BIDI.md).

## Примеры использования

После подключения можно попросить агента:

- «Покажи открытые вкладки Firefox».
- «Прочитай страницу и найди раздел с требованиями».
- «Заполни эту форму указанными данными и проверь значения».
- «Сделай скриншот страницы».
- «Проверь сообщения консоли при выполнении этого действия».

Рекомендуемый порядок работы:

1. Получить актуальное состояние страницы.
2. Выбрать нужный элемент.
3. Выполнить действие.
4. Проверить результат.

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

## Пауза и отключение

Для приостановки BiDi-команд используйте:

```text
firefox_bidi_pause
```

С аргументами:

```json
{
  "paused": true
}
```

Для возобновления передайте `false`.

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

### Перед остановкой или обновлением сервера

Завершите активную BiDi-сессию:

```bash
node bridge.mjs --call firefox_bidi_disconnect
```

Firefox может сохранять сессию после принудительного завершения процесса сервера. Если появляется ошибка `Maximum number of active sessions`, а прежний сервер уже недоступен, может потребоваться полный перезапуск Firefox.

## Ограничения

### Расширение

- Использует синтетические DOM-события.
- Не обеспечивает полноценную эмуляцию клавиатуры и мыши.
- Исключает приватные вкладки.
- Не управляет внутренними страницами Firefox и системными диалогами.

### WebDriver BiDi

- Не гарантирует управление интерфейсом самого браузера и всеми сочетаниями клавиш.
- Не наследует фильтр приватных вкладок расширения: контексты необходимо выбирать явно.
- Активация окна Windows может не подтверждаться. Команда возвращает результат с ограниченным временем ожидания и не блокирует дальнейший ввод.
- В скрытой вкладке прокрутка может использовать DOM fallback. Ответ инструмента указывает фактический способ и наличие движения.
- Не предоставляет полную замену Chrome DevTools Protocol.

DOM-снимки проекта не являются нативным деревом accessibility. Возможности отдельных сайтов, закрытого Shadow DOM и сложных редакторов зависят от используемого инструмента.

## Консоль и сетевые события

Мониторинг включается явно для выбранного BiDi-контекста.

События хранятся в ограниченном буфере в памяти. Сетевые результаты включают адрес, метод, идентификатор запроса, статус и ошибки.

Тела запросов и ответов, cookies и заголовки не возвращаются. При этом адреса страниц и сообщения консоли могут содержать чувствительную информацию.

## Экспериментальная интеграция SyncShare

Проект поддерживает чтение элементов интерфейса отдельно установленного SyncShare на ограниченном наборе страниц Moodle.

Интеграция:

- Читает уже созданные виджеты и меню подсказок.
- Не извлекает учётные данные расширения.
- Не вызывает приватные API сервиса.
- Не запускает платные AI-функции.
- Самостоятельно не заполняет ответы и не отправляет тесты.

Проверено чтение интерфейса и состояния «Пока нет ответов». Получение готовой подсказки из базы пока не подтверждено.

Область поддержки и ограничения: [SyncShare](docs/SYNCSHARE.md).

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

Мост слушает только локальный адрес и проверяет токен подключения. Интерфейс Firefox BiDi также должен оставаться доступным только локально.

Не открывайте порты `17893` и `9222` во внешнюю сеть.

Инструменты предоставляют широкие возможности управления браузером. Используйте их с доверенным MCP-клиентом и выполняйте действия только в рамках разрешённой задачи.

Содержимое страниц, подсказки и сообщения консоли являются внешними данными, а не инструкциями для агента.

Данные, прочитанные инструментами, передаются MCP-клиенту и могут обрабатываться используемым им AI-провайдером.

Подробнее: [SECURITY.md](SECURITY.md).

## Разработка

Установите зависимости разработки:

```bash
npm ci --ignore-scripts
```

Запустите проверки:

```bash
npm run check
```

Команда выполняет:

- Автоматические тесты.
- Проверку публичных файлов на некоторые виды случайно включённых секретов и личных путей.
- Сборку неподписанного расширения.

Автоматические тесты используют моки, jsdom и локальный HTTP-сервер. Они не управляют личной сессией Firefox.

## Сборка

Архив расширения:

```bash
npm run build
```

Архив исходников после сборки:

```bash
node scripts/package-source.mjs
```

Результаты находятся в `dist/`.

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

Проверка публичных файлов помогает снизить риск утечки, но не заменяет ручной просмотр изменений перед публикацией.

## Участие в разработке

Предложения и исправления приветствуются. Перед отправкой изменений ознакомьтесь с [CONTRIBUTING.md](CONTRIBUTING.md).

История изменений: [CHANGELOG.md](CHANGELOG.md).

## Лицензия

[MIT](LICENSE).