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.

• Парсит вакансию.

• Помогает подготовить сопроводительное письмо.

• Находит вопросы работодателя.

• Заполняет ответы и письмо только после подтверждения пользователя.

• Не отправляет отклик без явного подтверждения.

Related MCP server: LinkedIn Buddy

Архитектура

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-сессия пользователя"]

Стек

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

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

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 нет, потому что одинаковых вкладок может быть несколько.

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

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

Разработка

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

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