Browser Controller

Какую проблему решает этот проект

Вы выпускаете исправление. Ваш агент говорит: «Готово, проверьте, пожалуйста». Вы переключаетесь на Chrome, переходите на страницу, входите в систему, кликаете, находите баг.

Ваш агент только что написал код. Он мог бы и проверить его. У него уже открыт ваш браузер. Он просто не может его видеть.

Теперь может. Browser Controller даёт любому MCP-совместимому ИИ-агенту (Cursor, Claude Desktop, Windsurf, …) прямой контроль над браузером, который у вас уже открыт — ваши реальные сессии, ваши логины, ваши куки. Никакого headless-браузера, никакого нового профиля, никакой повторной аутентификации.

Related MCP server: Tabryn

Ключевые возможности

• Несколько агентов одновременно. Cursor может управлять вкладкой 10, пока Claude управляет вкладкой 11 — оба через один общий демон, не блокируя друг друга.

• Нацеливание на вкладку, а не на «активную вкладку». Каждое действие указывает tabId. Двигайте мышью, переключайте вкладки, смотрите YouTube — агент продолжает работать с той вкладкой, которую вы ему указали. Он никогда не захватывает страницу, которую вы читаете.

• Изоляция по вкладкам. Ссылки на элементы, журналы консоли и сетевые буферы привязаны к каждой вкладке. Ссылка из вкладки 10 никогда не сможет кликнуть что-то во вкладке 20.

• Параллельность по вкладкам. Два действия на одной и той же вкладке выполняются последовательно (без гонок); действия на разных вкладках выполняются параллельно.

• Блокировка вкладок. Агент может захватить вкладку, чтобы другие встали в очередь за ним вместо гонок (browser_tabs { action: "lock" }). Блокировки переживают перезапуск service worker'а Chrome (chrome.storage.session).

• Защита от перехвата управления агентом. Пока агент работает с вкладкой, вы видите полупрозрачную синюю внутреннюю рамку, а ваш ввод на этой вкладке блокируется (мышь, клавиатура, колесо) — бейдж показывает agent <name> controlling the tab и исчезает, когда действие завершается. Блокировка вкладки сохраняет простую рамку на всё время блокировки.

• Проникновение в iframe того же origin. Устаревшие/корпоративные интерфейсы, живущие внутри iframe (например, консоль ONT в iframe#mainFrame), доступны: все инструменты поиска элементов просматривают документы iframe, а find/click_text обходят каждый фрейм.

• Спасение от открытых диалогов. Нативный alert/confirm/prompt замораживает JS-поток страницы — browser_handle_dialog закрывает его в обход через CDP, без необходимости в JS страницы, что также разблокирует все остальные инструменты на этой вкладке. browser_tabs close/focus всегда работают, даже на замороженной вкладке.

• Аутентифицированное локальное соединение. Токен + одноразовый секрет регистрации, так что никакой другой локальный процесс не сможет незаметно управлять вашим браузером. Всё остаётся на localhost — никакого облака, никакой телеметрии.

• Нет баннера отладчика. browser_evaluate выполняется в MAIN-мире страницы через chrome.scripting — никакого жёлтого баннера «эта вкладка отлаживается», и реальные значения возвращаются через границу миров MV3.

• Честные ошибки. Каждый сбой инструмента доходит до вашего агента как настоящий результат isError с полной полезной нагрузкой — никаких «успешных» ответов, скрывающих сбои в середине рабочего процесса.

Как это работает

Три компонента, все на вашей машине. Ничего не покидает localhost.

  Agent (Cursor / Claude / Windsurf)        ── other agents connect too ──┐
                  │ stdio (MCP protocol)                                   │
                  ▼                                                        ▼
  ┌─────────────────────────────┐   ┌─────────────────────────────────────────┐
  │  thin MCP client            │   │  thin MCP client                        │
  │  (node mcp-server/dist/     │   │  (node mcp-server/dist/                 │
  │   index.js)                 │   │   index.js)                             │
  │  - speaks MCP over stdio    │   │  - spawns daemon if not running         │
  │  - forwards calls to daemon │   │  - gets its own sessionId               │
  └──────────────┬──────────────┘   └────────────────────┬───────────────────┘
                 │ local IPC socket (AF_UNIX / named pipe, token-auth)     │
                 ▼                                                          ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  DAEMON (single long-running process, owns port 7225)                     │
  │  - multiplexes N clients → 1 extension                                    │
  │  - tags every call with the client's sessionId                            │
  │  - heartbeat eviction, per-session rate limiting                          │
  └──────────────────────────────┬───────────────────────────────────────────┘
                                 │ WebSocket ws://127.0.0.1:7225 (token-auth)
                                 ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Chrome Extension (Manifest V3 service worker)                            │
  │  - resolves the target tabId (never "the active tab" implicitly)          │
  │  - serializes same-tab actions, parallelizes cross-tab actions            │
  │  - executes click/type/snapshot/evaluate against the named tab            │
  └──────────────────────────────────────────────────────────────────────────┘

Ключевая идея: при первом запуске любого агента тонкий клиент порождает фоновый демон, который владеет портом 7225 и соединением с расширением. Каждый последующий агент (даже из другого MCP-клиента) подключается к тому же демону через локальный IPC-сокет и получает собственный sessionId. Расширение видит одно стабильное соединение и направляет каждый вызов на ту вкладку, которую указал вызывающий.

Быстрый старт

Проект не размещён в Chrome Web Store и не в npm — вы устанавливаете его из этого репозитория. Две части: MCP-сервер (работает на вашей машине, общается с вашим ИИ-агентом) и расширение Chrome (находится в вашем браузере, выполняет команды).

Предварительные требования: Node.js ≥ 20 и Chrome/Chromium/Edge.

1. Клонируйте и соберите

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build        # compiles TypeScript → mcp-server/dist/

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

1. Откройте chrome://extensions и включите Режим разработчика (переключатель в правом верхнем углу)

2. Нажмите Загрузить распакованное и выберите папку extension/ из клонированного репозитория

3. Закрепите значок Browser Controller на панели инструментов

Серый кружок = ожидание демона. Зелёный = подключено.

3. Добавьте MCP-сервер в ваш клиент

Cursor: Settings → MCP → «Add new MCP server». Claude Desktop: отредактируйте claude_desktop_config.json. Windsurf: Settings → MCP. Подойдёт любой MCP-совместимый клиент.

Замените /path/to/browser-controller на абсолютный путь к вашему клону (Windows: используйте C:\\path\\to\\browser-controller\\mcp-server\\dist\\index.js):

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    }
  }
}

По умолчанию демон называет каждое соединение по имени родительской IDE («Cursor», «Claude», …). Чтобы переопределить — например, когда несколько агентов используют одну IDE, или чтобы пометить их по проектам — передайте --agent <name> в аргументах. Он имеет приоритет над любым автоопределением:

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js", "--agent", "My Project Agent"]
    }
  }
}

Имя появляется в списке Connected Agents во всплывающем окне. (Вы также можете задать переменную окружения MCP_AGENT_NAME — эквивалентно.) Повторное подключение с тем же именем заменяет старую запись, так что перезапуски IDE не накапливают дубликаты.

4. Свяжите расширение с демоном

Демон использует два секрета, оба генерируются при первом запуске в ~/.browser-controller/ (Windows: %USERPROFILE%\.browser-controller\). Запустите его один раз, попросив агента «list my browser tabs», затем:

1. Прочитайте секреты:

   cat ~/.browser-controller/enrollment.json   # one-time pairing secret
   cat ~/.browser-controller/token.json        # WebSocket auth token

   (Секрет регистрации также выводится в журнал MCP-клиента при первом запуске.)

2. Нажмите на значок расширения → вкладка Settings → вставьте Enrollment Secret и Auth Token (оставьте порт 7225, если вы не меняли WS_PORT).

Зелёный кружок = вы подключены. Ваш агент теперь видит ваш браузер.

Эти секреты не позволяют любому другому локальному процессу открыть WebSocket и управлять вашими аутентифицированными сессиями браузера. Чтобы их ротировать, остановите MCP-клиенты, удалите папку, и при следующем запуске оба секрета будут созданы заново. Полную модель угроз см. в SECURITY.md.

Использование

Модель ориентирована на вкладки: агент всегда указывает, на какой вкладке действовать. Он никогда не предполагает «активную вкладку».

Базовый рабочий процесс

1. Перечислите вкладки, чтобы получить tabId:

   browser_tabs { action: "list" }
   → [{ id: 15, url: "...", title: "...", active: true, lockedBy: null }, ...]

2. Сделайте снимок этой вкладки, чтобы увидеть её структуру и получить ссылки на элементы:

   browser_snapshot { tabId: 15 }
   → { tree: [ { ref: "e3", role: "button", name: "Sign in" }, ... ] }

   Ссылки действительны только для этого tabId. Если вы перешли по ссылке или DOM изменился, сделайте новый снимок. Новые элементы с момента последнего снимка помечаются isNew: true — после того как действие открыло оверлей/выпадающее меню, агент может сосредоточиться только на них, не перечитывая всё дерево.

3. Взаимодействуйте, используя ссылку и тот же tabId:

   browser_click { tabId: 15, ref: "e3" }
   browser_type  { tabId: 15, ref: "e5", text: "hello@example.com" }
   browser_press_key { tabId: 15, key: "Enter" }

   Если ссылка устарела, но элемент всё ещё существует, он находится автоматически через надёжный селектор + сканирование текста/роли (ответ содержит via: "fallback"). Если элемент был полностью прокручен за пределы видимости (виртуализированные ленты), ответ содержит freshRefs: [...] со свежим снимком прямо в нём — повторите с одной из этих новых ссылок в том же шаге, отдельный снимок не нужен.

4. Проверьте — сделайте снимок или прочитайте текст снова после действия.

Координация нескольких агентов (два агента, две вкладки)

1. Агент A перечисляет вкладки, выбирает вкладку 10, при желании блокирует её: browser_tabs { action: "lock", tabId: 10 }

2. Агент B перечисляет вкладки, выбирает вкладку 11, блокирует её: browser_tabs { action: "lock", tabId: 11 }

3. Оба работают параллельно. Вызовы каждого агента сериализуются относительно его собственной вкладки; две вкладки никогда не мешают друг другу.

4. По завершении: browser_tabs { action: "unlock", tabId: 10 }.

Всплывающее окно — ваша панель управления

Оболочка с вкладками фиксированной высоты (тело никогда не прокручивается, прокручиваются только списки):

• Tabs — каждая открытая вкладка с владельцем блокировки, плюс Unlock all на панели инструментов для мгновенного снятия блокировок, если агент упал посреди блокировки.

• Agents — каждый подключённый агент с именем, идентификатором сессии, временем работы и ✕ для немедленного отключения (очищает зомби, которого ещё не вычистил heartbeat).

• Settings — порт WebSocket, Auth Token, Enrollment Secret.

• Activity bar — сворачиваемая полоса внизу, показывающая последнюю активность инструментов; разверните её для прокручиваемого журнала.

Что стоит знать

• Забыли tabId? Вы получите понятную ошибку: tabId is required. Call browser_tabs list first.

• Защищённые страницы (chrome://, Web Store, devtools) нельзя скриптовать — вы получите Cannot access protected page (chrome://...) вместо тихого зависания.

• browser_navigate — единственный инструмент, где tabId необязателен (по умолчанию — активная вкладка), но для безопасности при нескольких агентах передавайте его явно. Изменения только хэша (например, /page → /page#section) разрешаются сразу после установки URL, без ожидания события complete (SPA не перезагружаются при изменении хэша, поэтому это событие никогда не срабатывает).

• browser_evaluate выполняется в MAIN-мире страницы (без баннера отладчика, безопасно для CSP) и возвращает реальные значения (JSON-сериализованные через границу миров). Он мощный, но неидемпотентный — не будет автоматически повторён при тайм-ауте.

• Прокрутка виртуализированных лент (Facebook/Instagram/Twitter): browser_scroll возвращает refsMayBeStale: true, потому что эти сайты перерабатывают узлы DOM. Сделайте новый снимок перед следующим взаимодействием.

• Дублирующиеся элементы: когда несколько элементов имеют одинаковый текст+роль (например, 3 кнопки «Like»), резервный резолвер выбирает правильный по порядковому номеру (nth), а не просто первое совпадение.

• Замороженная вкладка (нативный диалог блокирует) не заводит вас в тупик: browser_handle_dialog закрывает его через CDP, а browser_tabs { action: "close" } всегда работает как гарантированный выход.

🧠 Обучите своего агента

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

npm run setup:cursor   # or: node mcp-server/dist/index.js --setup cursor

Это устанавливает:

• ~/.cursor/rules/browser-controller.mdc — рабочий процесс нацеливания на вкладки, обработка выпадающих меню, когда блокировать вкладки

• ~/.cursor/commands/check-browser.md — добавляет /check-browser в ваш чат Cursor

После этого введите /check-browser в любом чате. Или просто скажите «проверь результат в моём браузере» — и агент будет знать, что делать.

npm run setup:claude

Добавляет AGENTS.md в корень вашего проекта. Claude Code обнаруживает его автоматически.

См. agent-config/ для ручной установки или настройки правил.

Что он умеет

22 инструмента. Каждый инструмент взаимодействия со страницей принимает tabId (единственное исключение — browser_navigate, где он необязателен).

Смотреть

Взаимодействие

browser_upload_file внедряет локальные файлы в <input type="file">, как если бы их выбрал пользователь: нативный диалог никогда не открывается, а события input/change срабатывают после, так что формы React/Vue реагируют.

browser_upload_file { tabId: 15, selector: "#resume", filePath: "/Users/me/resume.pdf" }
browser_upload_file { tabId: 15, ref: "e12", files: ["/tmp/a.png", "/tmp/b.png"] }

Пути абсолютные и локальные для машины, на которой запущен браузер. Опустите ref/selector, чтобы автоматически нацелиться на первый файловый input на странице; несколько файлов одновременно требуют input с атрибутом multiple.

Навигация

Отладка и продвинутые возможности

Сравнение с другими

Конфигурация

Файлы состояния демона

Демон хранит всё в ~/.browser-controller/ (Windows: %USERPROFILE%\.browser-controller\):

Для полного сброса: остановите ваши MCP-клиенты, удалите папку, и при следующем запуске она будет создана заново с новыми секретами.

Надёжность

• Демон автоматически запускается при первом запуске любого клиента и остаётся работать в откреплённом режиме.

• При обрывах соединения используется экспоненциальная задержка (1с → 30с), проверки работоспособности ping/pong каждые 10с; клиент, пропустивший 3 pong, вытесняется.

• Ограничение скорости 120 вызовов/мин на сессию защищает демон от зациклившегося агента.

• Таймауты на инструмент (5–15с для большинства действий, 60с для навигации), размещённые вместе с определением каждого инструмента, чтобы они не расходились с реестром.

• Идемпотентные инструменты чтения (snapshot, screenshot, text, find) повторяются при таймауте; инструменты с побочными эффектами (click, type, navigate, evaluate) — а также console/network (которые изменяют состояние при clear:true) — никогда не повторяются, поэтому клик не может сработать дважды.

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

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

{
  "mcpServers": {
    "browser-work": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    },
    "browser-personal": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"],
      "env": { "WS_PORT": "9333" }
    }
  }
}

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

Архитектура

Всё остаётся на вашей машине. Расширение подключается к демону через аутентифицированный WebSocket на localhost; MCP-клиенты подключаются к демону через локальный IPC-сокет. Никакого облака, никакого прокси, ничего не покидает ваш браузер.

browser-controller/
├── mcp-server/          MCP server (TypeScript)
│   └── src/
│       ├── daemon.ts        Single multi-client daemon (owns WS :7225)
│       ├── daemon-config.ts IPC protocol, paths, auth/enrollment tokens
│       ├── index.ts         Thin stdio MCP client (spawns daemon, multiplexes)
│       ├── bridge.ts        Extension WS server + cross-platform port probe
│       ├── register-tools.ts Progressive-disclosure wiring
│       └── tools/           One file per tool (22), registry pattern
├── extension/           Chrome extension (Manifest V3, plain JS, ES modules)
│   ├── background.js        Wiring only (~30 lines): inject router, register events, connect
│   ├── lib/                 state (buffers/locks/persistence), connection (WS lifecycle),
│   │                        router (dispatch + mutex/locks + control shield), page-exec,
│   │                        overlay, lock-ops, tab-concurrency (pure, unit-tested)
│   ├── handlers/            Tool implementations: navigation, interaction, inspection, tabs, cdp
│   ├── utils/               navigation + smart-selector fallback resolution
│   ├── events.js            chrome.* listeners (console capture, popup, webRequest, lifecycle)
│   ├── content.js           Console capture
│   └── popup/               Fixed tabbed shell (Tabs · Agents · Settings) + collapsible activity bar
├── agent-config/        Pre-built configs for Cursor + Claude Code
│   ├── cursor/              Rules and commands
│   ├── skills/              Browser automation skill
│   └── setup.mjs            One-command installer
└── tests/               15 suites / 215 tests

Стек: TypeScript (строгий) · MCP SDK · WebSocket · Chrome Extension Manifest V3 · Vitest

Разработка

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build
npm test

Набор покрывает WebSocket-мост (включая отклонение токен-аутентификации и единый канал ошибок), реестр инструментов, жизненный цикл демона (вытеснение по heartbeat, ограничение скорости, IPC-аутентификация), конкурентность по вкладкам (сериализация в одной вкладке + параллелизм между вкладками) и поведение расширения через мокированный API chrome (маршрутизация, семантика щита, round-trip evaluate, проникновение в iframe, спасение диалогов). CI запускает набор на Node 20 и 22, а также сканирование CodeQL и Scorecard.

Обновление существующей установки

git pull
npm install
npm run build

Затем два ручных шага: перезагрузите расширение в chrome://extensions (запущенный service worker сам по себе никогда не подхватывает изменения файлов) и перезапустите демон — он долгоживущий и тоже не перезагружает dist/ (убейте его или просто перезапустите ваш MCP-клиент, и при следующем запуске он будет пересоздан на новой сборке).

Часто задаваемые вопросы

В этом весь смысл. Расширение работает внутри вашего реального Chrome — те же куки, те же сессии, то же локальное хранилище. Повторная аутентификация не нужна.

Нет. MCP-клиенты, демон и расширение общаются через localhost (IPC-сокет + WebSocket). Ничего не покидает вашу машину. Никакой аналитики, никакой телеметрии, никакого облачного компонента. См. SECURITY.md — модель угроз, дизайн аутентификации и окно TOFU при первом контакте.

Любой MCP-совместимый клиент. Cursor, Claude Desktop, Claude Code, Windsurf, Cline и всё остальное, что говорит на протоколе MCP. Несколько таких клиентов могут одновременно работать с одним и тем же демоном.

Да. Каждый агент подключается к общему демону, получает собственный sessionId и нацеливается на конкретный tabId. Действия на одной вкладке сериализуются через мьютекс на вкладку; действия на разных вкладках выполняются параллельно. При желании агент может lock вкладку, чтобы получить исключительный доступ; другие агенты встают в очередь за блокировкой, а не завершаются с ошибкой.

Он не может — по крайней мере, незаметно. Каждый инструмент взаимодействия со страницей требует tabId, и если он отсутствует, вы получите понятную ошибку tabId is required. Агент никогда не сможет случайно воздействовать на вкладку, на которую вы смотрите. (Единственное исключение — browser_navigate без tabId, который использует активную вкладку, — но для многоагентного использования вам всегда следует передавать tabId.)

Без них любой локальный процесс на вашей машине мог бы открыть WebSocket на порт 7225 и управлять вашими аутентифицированными сессиями браузера (ваш банк, ваша почта, ваш корпоративный SSO). Секрет enrollment связывает расширение с демоном ровно один раз (вне полосы, до создания любого WebSocket); токен auth затем аутентифицирует каждое соединение. Оба хранятся в ~/.browser-controller/ с правами 0600.

Они запускают новый экземпляр браузера с нуля — без состояния, без куки, без сессий. Вам приходится заново проходить весь процесс входа каждый раз. Это подключается к браузеру, который у вас уже открыт, со всем уже загруженным.

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

Отчёты об ошибках, запросы функций и PR приветствуются в трекере задач. Для крупных изменений сначала откройте issue.

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

См. SECURITY.md — архитектура только для localhost, дизайн token + enrollment, модель угроз и рекомендации по сообщению об уязвимостях.

Лицензия

MIT