hh-apply-agent-mcp

Локальный MCP-агент с открытым исходным кодом для безопасной автоматизации откликов на вакансии hh.ru через Chrome-сессию пользователя.

Проект не является официальным продуктом hh.ru. Это локальная прослойка для личной автоматизации: Codex вызывает MCP tools, MCP-сервер управляет Chrome через Playwright/CDP, а пользователь подтверждает опасные действия.

Что делает MVP

• Открывает ссылку вакансии в Chrome с текущей пользовательской сессией.
• Проверяет, что пользователь авторизован на hh.ru.
• Парсит вакансию.
• Помогает подготовить сопроводительное письмо.
• Находит вопросы работодателя.
• Заполняет ответы и письмо только после подтверждения пользователя.
• Не отправляет отклик без явного подтверждения.

Архитектура

flowchart LR
    User["Пользователь"] --> Codex["Codex"]
    Codex --> MCP["Local MCP server"]
    MCP --> Playwright["Playwright connectOverCDP"]
    Playwright --> Chrome["Chrome с hh.ru-сессией"]

Стек

Компонент	Выбор
Язык	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
APPLICATION_STORE_PATH=storage/applications.json

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

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

• только домены из allowlist;
• без хранения логинов, паролей, cookies и токенов;
• без автоматического входа в аккаунт;
• по умолчанию включён dry-run;
• без отправки отклика без явного подтверждения пользователя;
• остановка на неизвестных вопросах или недостающих данных кандидата.

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

Tool	Ответственность
health_check	Проверить конфиг MCP и доступность CDP
open_vacancy	Открыть URL вакансии в Chrome
check_hh_session	Проверить авторизованную hh.ru-сессию
parse_vacancy	Извлечь данные вакансии
parse_resume_context	Извлечь контекст резюме кандидата
extract_questions	Найти вопросы работодателя
fill_question_answers	Заполнить ответы в видимые поля
attach_cover_letter	Приложить сгенерированное сопроводительное письмо
submit_response	Отправить отклик только после явного подтверждения
screenshot	Вернуть текущее состояние браузера для отладки

Разработка

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

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