ff-mcp

ff-mcp даёт локальным MCP-клиентам контролируемый доступ к вашему профилю Firefox. Он состоит из WebExtension Firefox на базе Manifest V3 и Python-хоста Native Messaging, который предоставляет MCP через Streamable HTTP на 127.0.0.1.

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

Текущие возможности

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

• Запрашивать READ, INTERACT, SCRIPT и SCREENSHOT для конкретной вкладки.

• Выдавать доступ однократно, на время документа, на время сессии вкладки или постоянно для хоста.

• Читать ограниченные сериализованные снимки и результаты CSS-запросов. Живые DOM-объекты никогда не пересекают мост.

• Выполнять клики, ввод, прокрутку и навигацию через структурированные операции.

• Захватывать вкладку только при отдельном разрешении SCREENSHOT.

• Выполнять произвольный JavaScript в изолированном мире пользовательских скриптов или в основном мире страницы только при отдельном разрешении SCRIPT и необязательном разрешении Firefox userScripts.

• Сопоставлять сохраняемые политики с предикатами host, glob, regex и scheme, объединяемыми операторами AND, OR и NOT.

• Аудировать решения об авторизации и чувствительные операции внутри Firefox.

• Привязывать MCP только к loopback, требовать сгенерированный bearer-токен и отклонять HTTP-источники по умолчанию.

Related MCP server: gecko-mcp

Требования

• Firefox 150 или новее.

• Python 3.14 (пакет зафиксирован на минорной ветке 3.14).

• Для установки рекомендуется uv.

Разовое выполнение SCRIPT требует Firefox 153 или новее, поскольку в этом выпуске появился userScripts.execute(). Остальные возможности поддерживаются начиная с Firefox 150.

Установка из рабочей копии

Установите нативный вспомогательный компонент как постоянный инструмент, затем зарегистрируйте его в Firefox:

uv tool install .
ff-mcp install-native

Для разработки загрузите extension/manifest.json через about:debugging → Этот Firefox → Временная загрузка дополнения.

Откройте всплывающее окно ff-mcp на панели инструментов и нажмите Запуск. При первом запуске создаётся приватный файл конфигурации со случайным токеном:

• Linux: $XDG_CONFIG_HOME/ff-mcp/config.json или ~/.config/ff-mcp/config.json

• macOS: ~/.config/ff-mcp/config.json

• Windows: %APPDATA%\ff-mcp\config.json

Всплывающее окно показывает и позволяет скопировать типовой объект подключения:

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_GENERATED_TOKEN"
  }
}

Настройте указанные значения в MCP-клиенте, поддерживающем Streamable HTTP и произвольные заголовки. Эндпоинт существует только пока расширение удерживает открытым своё соединение Native Messaging.

Процедура выдачи прав

1. Вызовите browser_tabs и выберите идентификатор вкладки.

2. Вызовите browser_request_access с одной или несколькими возможностями.

3. Одобрите запрос в панели инструментов Firefox.

4. Вызовите инструмент чтения, взаимодействия или снимка экрана.

5. Отзовите доступ из панели инструментов или с помощью browser_revoke.

READ по умолчанию разрешён только для localhost, поддоменов .localhost, 127.0.0.0/8 и ::1. Это не включает по умолчанию взаимодействие, скриптинг или скриншоты.

Правила политик

Страница параметров содержит визуальный редактор политик. Каждое новое правило начинается с основного контейнера AND, внутри которого находится группа разрешения OR и группа исключевания NAND. Добавляйте условия host, шаблона URL, regex или scheme; при необходимости вкладывайте дополнительные контейнеры AND, OR, NAND или NOR; затем выбирайте возможности, которые предоставляет подходящее правило.

Пустые неотрицательные контейнеры не соответствуют ничему. Пустые отрицательные контейнеры соответствуют всему, поэтому новое правило остаётся неактивным, пока в его группе разрешения не появится хотя бы одно условие. Постоянно включённое правило READ для localhost отображается отдельно и не может быть изменено или удалено.

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

Регекс-шаблоны ограничены по длине и не допускают обратные ссылки, опережающие/ретроспективные проверки и явные вложенные квантификаторы. Это безопасное подмножество, а не полная реализация RE2.

Разработка

UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv sync --group dev
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q
# Opt-in: launches the installed Firefox headlessly with a fresh temporary profile.
FF_MCP_RUN_FIREFOX_TESTS=1 UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q tests/test_firefox_integration.py
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff check .
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff format --check .
node tests/policy.test.js
node tests/rule-model.test.js
node tests/background.test.js
node tests/content.test.js
node --check extension/background.js
node --check extension/content.js
node --check extension/options.js
node --check scripts/check-web-ext-lint.js

Задайте FIREFOX_BINARY для устанавливает, которые Selenium не может обнаружить автоматически. Интеграционный тест распознаёт стандартное расположение Linux Snap без дополнительной конфигурации.

Расширение Firefox не имеет сторонних зависимостей времени выполнения или шага сборки.

Релизы

Теги с именами vX.Y.Z запускают пайплайн релиза. Версия тега должна совпадать и с project.version в pyproject.toml, и с version в extension/manifest.json. Пайплайн запрашивает у Mozilla Add-ons подпись расширения в канале unlisted, проверяет полученный XPI и прикрепляет подписанный XPI с его контрольной суммой SHA-256 к релизу GitHub. Сгенерированные артефакты остаются неотслеживаемыми.

Настройте эти секреты в окружении release репозитория перед запуском тега:

• AMO_JWT_ISSUER — эмитент из учётных данных API AMO.

• AMO_JWT_SECRET — соответствующий секрет API AMO.

Учётные данные создаются на странице ключей API AMO. Подпись в канале unlisted не публикует расширение в поиске или списках AMO.

Ограничения безопасности

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

• Одобренные метаданные браузера, содержимое веб-сайтов и их активность передаются локальному собственному хосту и MCP-клиенту. AMO объявляет эти категории данных обязательными при установке.

• Ограниченные Firefox страницы, такие как about: и магазин дополнений, не могут быть прочитаны контентными скриптами.

• Доступ на время сессии вкладки намеренно переживает навигацию в этой вкладке; доступ на время документа — нет.

• Идентичность MCP-клиента всего лишь описательна в пределах единого домена доверия bearer-токена. Если взаимно не доверяющим локальным клиентам требунома изоляция, используйте отдельную конфигурацию и токен.

• Структурированные клики и ввод всё равно могут вызывать поведение страницы. Давайте право INTERACT с осторожностью.

• SCRIPT по сути является полным контролем над страницей. Во время одобрения Firefox запрашивает для него необязательное разрешение userScripts, а ff-mcp также требует отдельную возможность на вкладку. Скрипты в мире MAIN могут получать и изменять состояние JavaScript, принадлежащее странице. Выдавайте право такого скриптинга только клиентам и сайтам, которым доверяете.

См. firefox_mcp_extension_findings.html для дизайн-исследования, предшествующего этой реализации.

Лицензия

MIT. См. LICENSE и THIRD_PARTY.md.