browser-control-mcp

Локальный MCP-сервер с открытым исходным кодом для безопасного управления существующей Chrome-сессией через Playwright и Chrome DevTools Protocol.

Codex вызывает MCP tools, сервер управляет вкладками в Chrome, а действия с повышенным риском требуют отдельного подтверждения. Автоматизация hh.ru остаётся специализированным модулем проекта. Проект не является официальным продуктом Google, Chromium или hh.ru.

Что делает MVP

• Подключается к существующей локальной Chrome-сессии через CDP.
• Открывает, читает и закрывает вкладки, нажимает элементы и заполняет поля.
• Сохраняет авторизацию внутри Chrome и не возвращает cookies или browser storage MCP-клиенту.
• Классифицирует риск действий и требует одноразовое подтверждение для опасных операций.
• Блокирует платёжные действия, покупки и денежные переводы.
• Предоставляет специализированные сценарии автоматизации hh.ru.
• Открывает ссылку вакансии в Chrome с текущей пользовательской сессией.
• Проверяет, что пользователь авторизован на hh.ru.
• Парсит вакансию.
• Помогает подготовить сопроводительное письмо.
• Находит вопросы работодателя.
• Заполняет ответы и письмо только после подтверждения пользователя.
• Не отправляет отклик без явного подтверждения.

Архитектура

flowchart LR
    User["Пользователь"] --> Codex["Codex"]
    Codex --> MCP["Local MCP server"]
    MCP --> HH["hh.ru flows"]
    MCP --> BrowserControl["Universal browser-control"]
    HH --> Playwright["Playwright connectOverCDP"]
    BrowserControl --> Playwright
    Playwright --> Chrome["Существующая Chrome-сессия пользователя"]

Стек

Компонент	Выбор
Язык	TypeScript
Runtime	Node.js 20+
MCP	@modelcontextprotocol/sdk
Управление браузером	Playwright + Chrome DevTools Protocol
Валидация	Zod
Логирование	pino
Тесты	Vitest

Локальный запуск

npm install
cp .env.example .env
npm run typecheck
npm test

Для MVP Chrome нужно запустить с локальным CDP-портом. Это даёт Playwright возможность подключиться к уже существующему профилю Chrome, где есть ваша hh.ru-сессия.

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/Library/Application Support/Google/Chrome"

Linux

google-chrome \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.config/google-chrome"

Если команда google-chrome недоступна, проверьте имя бинарника:

which google-chrome chromium chromium-browser

Windows PowerShell

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-address=127.0.0.1 `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:LOCALAPPDATA\Google\Chrome\User Data"

Если Chrome установлен в 32-bit путь:

& "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-address=127.0.0.1 `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:LOCALAPPDATA\Google\Chrome\User Data"

Важно: CDP-доступ к Chrome очень мощный. Не открывайте debug-port на внешний интерфейс. Для MVP используйте только 127.0.0.1.

Переменные окружения

NODE_ENV=development
LOG_LEVEL=info
CDP_URL=http://127.0.0.1:9222
ALLOWED_DOMAINS=hh.ru,ramenskoe.hh.ru
DRY_RUN=true
REQUIRE_CONFIRMATION=true
BROWSER_ALLOWED_DOMAINS=
BROWSER_DENIED_DOMAINS=
BROWSER_ALLOW_PRIVATE_NETWORK=false
APPLICATION_STORE_PATH=storage/applications.json

Модель безопасности

MVP намеренно ограничивает автоматизацию:

• без хранения логинов, паролей, cookies и токенов;
• без автоматического входа в аккаунт;
• по умолчанию включён dry-run;
• без отправки отклика без явного подтверждения пользователя;
• остановка на неизвестных вопросах или недостающих данных кандидата.
• universal browser-control не возвращает cookies, localStorage, sessionStorage, hidden inputs или значения полей;
• платёжные действия, покупки и денежные переводы полностью заблокированы в MVP;
• sensitive/irreversible действия выполняются только по одноразовому токену;
• private network и опасные URL-схемы по умолчанию заблокированы.

Реализованные MCP tools

Tool	Ответственность
health_check	Вернуть конфигурацию локального MCP-агента
inspect_vacancy	Открыть allowlisted hh.ru URL, проверить сессию, проверить страницу и распарсить
prepare_required_cover_letter_response	Проверить обязательность письма и создать одноразовый токен подтверждения
submit_required_cover_letter_response	Заполнить одобренное письмо и выполнить один submit, если выключен dry-run
prepare_attach_cover_letter	Проверить возможность добавить письмо к уже отправленному отклику
submit_attach_cover_letter	Добавить одобренное письмо к существующему отклику по одноразовому токену
prepare_response_with_cover_letter	Подготовить отклик с необязательным письмом и создать одноразовый токен
submit_response_with_cover_letter	Откликнуться и сразу отправить письмо в той же вкладке
browser_list_pages	Получить открытые Chrome-вкладки и их CDP pageId
browser_open_page	Открыть разрешённый публичный HTTP(S) URL
browser_get_page	Получить ограниченный semantic snapshot без значений полей
browser_click	Нажать элемент либо подготовить confirmation token
browser_fill	Заменить значение поля без логирования текста
browser_type	Дописать текст в поле без логирования текста
browser_close_page	Закрыть вкладку; изменённая вкладка требует подтверждения
browser_wait_for	Дождаться элемента, текста или URL
browser_screenshot	Вернуть PNG в памяти без сохранения на диск
browser_execute_confirmed_action	Один раз выполнить точное действие по confirmation token

inspect_vacancy пишет локальные диагностические логи в stderr. Это важно для MCP stdio: stdout должен оставаться чистым JSON-RPC транспортом.

Flow обязательного письма всегда состоит из двух вызовов. Токен действует 10 минут, привязан к вакансии и точному тексту письма и используется только один раз. При DRY_RUN=true второй tool открывает и заполняет форму, но не нажимает финальную кнопку. MCP-сервер не сохраняет письмо на диск и не пишет письмо или токен в логи.

Для отклика, который уже доставлен без письма, используется отдельная пара prepare_attach_cover_letter -> submit_attach_cover_letter. Токены двух flow имеют разное назначение и не могут использоваться взаимозаменяемо. Если письмо уже приложено, tool возвращает идемпотентный статус already_attached.

Для вакансий с необязательным письмом используется пара prepare_response_with_cover_letter -> submit_response_with_cover_letter. После одного клика «Откликнуться» tool классифицирует результат в той же вкладке:

• вопросы работодателя возвращаются как EmployerQuestion[] без заполнения;
• открытая форма письма заполняется подтверждённым текстом и отправляется один раз;
• после доставки резюме кнопка приложения письма ожидается до трёх секунд;
• если бот работодателя успел убрать кнопку, возвращается частичный успех resume_submitted_letter_unavailable.

executionMode: "full" выполняет полный сценарий. executionMode: "start_only" разрешает только первый разрушительный шаг и не отправляет письмо. При DRY_RUN=true оба режима безопасны: основная кнопка «Откликнуться» не нажимается. Если письмо обязательно, prepare-tool возвращает статус required_cover_letter и токен для существующего submit_required_cover_letter_response.

Универсальное управление браузером

Модуль src/browser-control работает поверх той же Chrome CDP-сессии, но не зависит от hh.ru. Cookies остаются внутри пользовательского BrowserContext: MCP использует авторизованные вкладки, не читая и не передавая cookies наружу.

pageId — Chrome CDP targetId. Пока вкладка и Chrome-процесс живы, MCP может после собственного перезапуска заново перечислить targets и продолжить работу с тем же ID. После закрытия вкладки ID становится stale. После перезапуска Chrome автоматического восстановления по URL/title нет, потому что одинаковых вкладок может быть несколько.

Риски определяет сервер:

Риск	Поведение
read	Выполняется без подтверждения
low	Выполняется сразу
sensitive	Возвращается одноразовый token с TTL 2 минуты
irreversible	Всегда требуется одноразовый token
critical	Payment/purchase/transfer блокируются без возможности подтверждения

requestedRisk может повысить риск, но не понизить вычисленный сервером. Перед confirmed action повторно проверяются pageId, URL, origin, версия документа и fingerprint элемента. После необратимого клика автоматических retry нет.

По умолчанию разрешены публичные HTTP(S)-домены. Ограничить их можно через BROWSER_ALLOWED_DOMAINS, запретить отдельные — через BROWSER_DENIED_DOMAINS. Доступ к localhost/private network включается только явно:

BROWSER_ALLOW_PRIVATE_NETWORK=true

Планируемые MCP tools

Tool	Ответственность
parse_resume_context	Извлечь контекст резюме кандидата
fill_question_answers	Заполнить ответы в видимые поля
submit_response	Поддержать остальные варианты отклика
screenshot	Вернуть текущее состояние браузера для отладки

Разработка

Перед изменениями читайте PROJECT_CONTEXT.md. Это рабочая память проекта, её нужно обновлять после важных решений.

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