web-debug-mcp

web-debug-mcp — это локальный, ориентированный на агентов веб-отладочный сервер для Codex и других MCP-клиентов. Он предоставляет небольшой набор инструментов, который координирует сеанс браузера, отладчик JavaScript, ограниченные доказательства выполнения и воспроизводимую проверку потоков.

Текущая версия поддерживает независимые от фреймворка браузерные цели, Chromium/CDP, Safari WebDriver с доказательствами WebDriver BiDi, автоматически внедряемый мост разработки React, конечную точку модульного графа/HMR Vite, а также метаданные сервера разработки Next.js с ограниченными хвостами серверных журналов, компиляцией маршрутов, поиском Server Actions и наблюдаемыми доказательствами выполнения запросов. Ограничения, специфичные для браузера, остаются явными. Это сохраняет контекст, специфичный для фреймворка, за тем же фасадом MCP, а не добавляет отдельные каталоги инструментов.

Что включено

• Определение возможностей проекта без запуска процесса.

• Локальный режим подключения Chromium через явную конечную точку CDP.

• Явное удалённое подключение CDP поддерживается только с allowRemote: true; цели помечаются как неизолированные и никогда не обнаруживаются автоматически.

• Локальный режим запуска Chromium через явный путь к исполняемому файлу.

• Режим Safari WebDriver через локальный safaridriver или явную конечную точку WebDriver, с событиями консоли BiDi и сетевыми событиями, когда установленный Safari их предоставляет.

• Действия в браузере с тем же источником: переход, клик, заполнение, ожидание и перезагрузка.

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

• Консоль, метаданные сети, сводка DOM, скриншот и доказательства отладчика в одном редактируемом пакете.

• Дерево компонентов React, значения хуков, исходные расположения, количество рендеров, ограниченные сводки коммитов, длительности профилировщика, плоское представление пламени и предполагаемые причины рендера, когда сборка для разработки предоставляет коммиты React.

• Модульный/импортный граф Vite, статус HMR, различия преобразованного кода и сводки исходных карт через плагин разработки webDebugVitePlugin().

• Ограниченные, редактируемые хвосты журналов разработки Next.js, когда журнал остаётся в пределах обнаруженного корня проекта.

• Явная компиляция маршрутов Next.js и поиск Server Actions через web_next_inspect, а также нормализованные трассировки серверных запросов и связанные с запросами доказательства выполнения, когда браузер отправляет запрос Next-Action.

• Ограниченная временная шкала воспроизведения в захватах и поиск кадров через web_replay_seek; restore: true воспроизводит только безопасные сохранённые действия и отклоняет санитизированные вводы форм.

• Воспроизводимые сценарии действий с простыми проверками после исправления.

• Детерминированный ванильный фикстур и проверка собственного проекта.

• Живой фикстур React/Vite, автоматический мост React и проверка модульного графа/HMR.

• Живой фикстур Next.js App Router и проверка выполнения /_next/mcp.

Related MCP server: Kaboom Browser AI Devtools MCP

Требования

• Node.js 20 или новее. Safari BiDi требует Node 20.10+ с --experimental-websocket или Node 21+; более старые среды выполнения сохраняют действия Safari WebDriver и документированный сетевой запасной вариант, но сообщают об ограничениях консоли BiDi.

• Браузер на основе Chromium при запуске живого сеанса.

• Либо явный WEB_DEBUG_CHROME_EXECUTABLE_PATH, либо явный cdpEndpoint, переданный в web_session_start.

Команды разработки

npm install --no-audit --no-fund
npm test
npm run typecheck
npm run build
npm run harness:check
npm run smoke:live
npm run smoke:react-vite
npm run smoke:next
npm run smoke:safari

Запустите фикстур с помощью npm run serve:fixture. Сервер привязывается к 127.0.0.1 и по умолчанию использует порт 4173; установите WEB_DEBUG_FIXTURE_PORT, чтобы использовать другой порт.

Запустите npm run smoke:live после установки WEB_DEBUG_CHROME_EXECUTABLE_PATH, если путь к Chrome по умолчанию для macOS недоступен. Он запускает ванильный фикстур, устанавливает точку останова в app.js, нажимает кнопку, захватывает безопасный для паузы путь доказательств и очищает принадлежащие браузер и процессы фикстура.

Запустите npm run smoke:react-vite, чтобы запустить фикстур Vite, проверить доказательства компонентов/состояния React, приостановить выполнение в fixtures/react-vite/src/App.jsx и воспроизвести поток отправленного платежа.

Для приложения Vite добавьте плагин только для разработки в vite.config.ts:

import { webDebugVitePlugin } from "web-debug-mcp/vite";

export default {
  plugins: [webDebugVitePlugin()],
};

Плагин обслуживает локальную конечную точку модульного графа только для чтения, используемую во время сеанса отладки. Его не следует включать в производственном сервере.

Запустите npm run smoke:next, чтобы запустить фикстур Next.js App Router, запросить его встроенную конечную точку /_next/mcp, проверить метаданные маршрутов/проекта/компиляции и ограниченный хвост серверного журнала, а также выполнить поток обработчика клиентских маршрутов.

Запустите npm run smoke:safari, чтобы проверить ванильный фикстур через Safari WebDriver. Сначала включите Safari Настройки → Разработчик → Разрешить удалённую автоматизацию; Safari работает видимо, захватывает доказательства консоли BiDi и сообщает, поступили ли сетевые доказательства из BiDi или из ограниченного запасного варианта Performance Resource Timing. Отладчик JavaScript Safari остаётся недоступным через этот адаптер.

Safari 27 и Safari Technology Preview 247 включают официальный сервер MCP Safari от Apple. Используйте этот официальный сервер, когда его собственные инструменты DOM, сети, консоли и скриншотов являются желаемой поверхностью; этот репозиторий не добавляет дублирующий публичный каталог MCP Safari. Адаптер WebDriver остаётся полезным как путь совместимости с единым фасадом для старых версий Safari и для общей оркестрации сеансов/доказательств.

Запустите сервер MCP с помощью npm run dev во время разработки или node dist/index.js после npm run build. Сообщения протокола MCP используют stdout; диагностика должна оставаться на stderr.

Рабочий процесс MCP

1. Вызовите web_project_detect с корнем проекта.

2. Вызовите web_session_start с URL-адресом loopback и явным подключением к браузеру или исполняемым файлом.

3. Используйте web_browser_action и web_breakpoint_set, чтобы воспроизвести проблему.

4. Вызовите web_issue_capture для одного ограниченного пакета доказательств.

5. Для Next.js вызовите web_next_inspect, чтобы скомпилировать маршрут или разрешить идентификатор Server Action.

6. Сохраните поток с помощью web_repro_record и запустите его позже с помощью web_fix_verify.

7. Используйте web_replay_seek, чтобы просмотреть один сохранённый кадр; передавайте restore: true только когда кадр содержит безопасные, нечувствительные действия.

8. Вызовите web_session_close, когда сеанс больше не нужен.

Сервер не записывает в проект во время обычного сеанса. Скриншоты сохраняются во временном каталоге артефактов сеанса и возвращаются как пути.

Безопасность по умолчанию

• URL-адреса браузера ограничены loopback, если только allowRemote не включён явно.

• Навигация браузера остаётся на источнике сеанса.

• Внешнее подключение CDP помечается как неизолированное.

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

• Необработанные тела ответов, файлы cookie, значения авторизации и хранилище браузера не собираются базовым адаптером.

• Оценка отклоняет побочные эффекты, если только allowSideEffects не установлен явно.

Текущая граница

Этот репозиторий — локальный инструмент разработчика, а не размещённый сервис. У него нет производственного развёртывания, CI-процесса, неаутентифицированного/автообнаруживаемого удалённого управления браузером или полной паритетности с профилировщиком/пламенем React DevTools. Длительности React и детали причин рендера ограничены и выводятся из хука DevTools; происхождение Vite и исходные карты — это сводки, а не полный отладчик исходных карт; доказательства выполнения Next ограничены метаданными Server Actions, связанными с запросами, аналитикой запросов и ограниченными журналами; паритетность отладчика Safari недоступна, и Safari 26 может потребовать сетевой запасной вариант Performance Resource Timing; восстановление воспроизведения ограничено безопасными сохранёнными действиями и не является перемещением во времени состояния приложения. Явное удалённое подключение CDP, действия Safari WebDriver/DOM/скриншоты, явные предупреждения о возможностях и ограниченное восстановление воспроизведения доступны. Одобренный внешний удалённый хост и предоставленные вызывающим сертификационные доказательства испытательного стенда по-прежнему требуются для соответствующих утверждений.