DevCDP
Real Chrome DevTools access for an AI assistant, over MCP. Your assistant reads the
console, watches the network, queries the DOM, resolves source maps, sets
breakpoints and inspects live variables — so it can tell you why something broke
instead of guessing from a pasted error.
Works with any assistant that speaks MCP, and with any web app: nothing about a
particular framework, product or company is built in.
74 tools — see docs/TOOLS.md for the full reference, generated
from the server itself, and docs/PERFORMANCE.md for measured
token costs and how to lower them.
Что делает
| Console | Логи, предупреждения и непойманные исключения с указанием файла, строки (1‑based) и стека. |
| Network | Каждый запрос с момента подключения — метод, статус, время выполнения, размер, инициатор и тела ответов по запросу. |
| DOM | Поисковые запросы к селекторам с реальной видимостью и геометрией, именованные вычисляемые стили, история мутаций, поддержка iframe и структурная детекция диалогов. |
| Sources | Загруженные скрипты, плюс оригинальные файлы до упаковки, восстановленные по source maps — включая внешние .map файлы за аутентификацией. Полнотекстовый поиск по обоим наборам. |
| Debugger | Точки останова в оригинальных файлах по оригинальной строке, пошаговый режим и инспекция области видимости, которая разворачивает вложенные объекты вместо вывода Object. |
| Discovery | Спрашивает приложение, что оно такое: фреймворк, маршрутизация, рабочие селекторы для кнопок и полей, поверхность API backend, и документы вашего проекта. |
| Collaboration | Вы можете взять управление в любой момент; что вы кликаете, выбираете и набираете — записывается и читается ассистентом. |
Четыре аспекта, в которых он проявляет осторожность
Он никогда не симулирует успех. Привязка breakpoint может не состояться — он помечается как bound: false и
объясняет почему. Тело, которое Chrome отбросил, говорит само за себя. Захват, пауза которого уже продолжилась, помечается как устаревший. Любая неудача оформляется как {ok: false, code, message, hint}
с следующим действием по имени.
Он говорит, где заканчиваются его знания. Chrome не может воспроизвести историю консоли в отладчик, который подключается позже, поэтому подключение сообщает именно об этом, а не пустой буфер как «нет ошибок».
Он не может застрять. Каждый вызов в страницу ограничен с нашей стороны —
тайм-аут у Runtime.evaluate контролируется рендерером, что бесполезно, когда рендерер зациклен. Страница, застрявшая в бесконечном цикле, падает за считанные секунды, и DevCDP прервет «уходящий» скрипт и попробует снова сам.
Он не оставляет ваше приложение в заморозке. Точки останова захватывают то, что нужно, и затем сами продолжают. Сворачивание паузы преднамеренно — всё всё равно разблокируется после maxPauseMs, и отключение очищает всё.
Установка
Требования: Node 18+, Chrome и ассистент с поддержкой MCP.
Выбирайте клиента, который подходит вашему клиенту. Все они запускают один и тот же сервер на вашей машине; ничего не размещается в интернете.
Любой MCP клиент из npm. Добавьте в конфигурацию MCP клиента:
{ "mcpServers": { "devcdp": { "command": "npx", "args": ["-y", "devcdp"] } } }
На родном Windows некоторые клиенты требуют "command": "cmd", "args": ["/c", "npx", "-y", "devcdp"].
Claude Code, как плагин (сервер плюс навык, который говорит Claude, когда обращаться к какому инструменту):
/plugin marketplace add Dayananda-D/DevCDP
/plugin install devcdp@devcdp
Cursor: ,
или добавьте выше JSON в файл ~/.cursor/mcp.json.
Gemini CLI, как расширение, которое также несет руководство по использованию:
gemini extensions install https://github.com/Dayananda-D/DevCDP
opencode: opencode mcp add, или в opencode.json:
{ "mcp": { "devcdp": { "type": "local", "command": ["npx", "-y", "devcdp"], "enabled": true } } }
Codex (CLI, настольная версия, расширение VS Code), как плагин:
codex plugin marketplace add Dayananda-D/DevCDP
VS Code: Установка в VS Code, или запустите MCP: Add Server, выберите NPM Package, и введите devcdp. Copilot CLI: /mcp add с командой npx -y devcdp. DevCDP доступен в
официальном MCP Registry: https://registry.modelcontextprotocol.io/?q=devcdp; picker
в VS Code показывает curated subset этого реестра, который является отдельной записью.
Из исходников, с мастером установки, который также записывает руководство по использованию в файл инструкций вашего ассистента: см. Setup, далее.
Затем запустите Chrome с удаленной отладки (debug-chrome.bat, или
chrome --remote-debugging-port=9222 --user-data-dir=<профиль>), откройте приложение
и опишите баг.
Setup
1. node initialize_MCP.js (или двойной щелчок initialize_MCP.bat)
2. Полностью выйдите из ассистента и снова запустите его
3. Двойной щелчок debug-chrome.bat, откройте приложение
4. Опишите проблему
Мастер настройки определяет установленные редакторы, записывает правильную конфигурацию для каждого и
создает лаунчер. Он никогда не перезаписывает конфигурационный файл, который не может распарсить — выводит фрагмент для вставки — каждое изменение атомарно с резервной копией с отметкой времени, и дубликаты регистрации из старых установок удаляются. Этот путь покрыт 23 тестами, потому что ошибка в нём может повредить ваш компьютер, а не просто дать сбой.
Настройки
Все опционально. Попросите ассистента запустить devcdp_settings, чтобы увидеть
эффективные значения и источник их происхождения, или devcdp_settings_init, чтобы записать
аннотированный файл, который можно отредактировать.
Файлы объединяются, позже взвешиваются, так что базовый уровень установки можно переопределить для проекта:
/devcdp.settings.json или /settings.json /.devcdp/settings.json /devcdp.settings.json">``` <install>/devcdp.settings.json или <install>/settings.json <cwd>/.devcdp/settings.json <cwd>/devcdp.settings.json
затем переменные окружения DEVCDP_* и аргументы инструментов. Комментарии и завершающие запятые допускаются.
| Настройка | По умолчанию | |
| --- | --- | --- |
| toasts | true | показывать живые сообщения статуса |
| toastMs · toastOpacity · toastMaxVisible | 3500 · 0.78 · 3 | сколько длится, как видно, сколько видно |
| badge · badgeCorner · edgePulse | true · "tc" · true | индикатор во вкладке и «дышащая» рамка |
| badgeCorner positions | tc · bc · tl · tr · bl · br | где оверлей «паркуется». Перетащите чип, чтобы переместить его в любом месте; эта позиция запоминается для каждого origin. Сообщения следуют за ним, поэтому toastCorner следует за badgeCorner |
| showCursor · highlightInspected | true · true | показывать, где происходит взаимодействие, и что было инспектировано |
| ownerTimeoutMs | 45000 | как долго индикатор остается активным без отклика сессии, прежде чем удалиться |
| followNewTabs | true | помечать и удерживать вкладки, которые приложение открывает само по себе, чтобы попап никогда не был незаметной зоной |
| chromeProfile | "isolated" | или "default" для повторного использования вашего вошедшего в Chrome аккаунта, или путь |
| disableWebSecurity | false | отключать: это скрывает те ошибки CORS, которые вы бы отлаживали |
| chromeFlags | [] | дополнительные флаги Chrome |
| evalTimeoutMs · toolTimeoutMs | 8000 · 30000 | пределы живости |
| autoResumeDefault · maxPauseMs | true · 30000 | автономный контроль паузы |
| captureInputValues | false | постоянный захват введенных значений |
| docsRoot | auto | где читать README и документы вашего проекта |
| sharedMemoryDir | null | пул обученных исправлений для команды |
| tabGroupMode | "session" | одна группа вкладок на сессию, или "single" для всех |
`docsRoot` и `sharedMemoryDir` — два параметра, которые стоит задать: первый позволяет ассистенту выучить терминологию вашего домена, второй — то, что делает «ф fixes команды» действительно суммирующимися.
---
## Несколько сессий одновременно
Несколько агентов могут безопасно отлаживать на одном устройстве. Каждая сессия **заявляет владение** вкладкой в реестре под `~/.devcdp/registry/`, что делается атомарно, чтобы две процессы не захватили одну и ту же вкладку. Сессия, которая погибает, прекращает «сердцебиение» и её претензия удаляется, поэтому ничего не застревает.
- Новая сессия получает незанятую вкладку; если все заняты — открывается своя собственная — на той
странице, которая вам нужна, а не на пустой, и она объясняет почему.
- Перезагрузка ассистента: кратковременное пересечение двух серверных процессов, поэтому короткий период грации позволяет уходящей сессии освободить свою вкладку, и новая просто повторно подключается.
- `browser: 'new'` запускает отдельный Chrome, свой порт и профиль.
- `window: 'new'` даёт сессии отдельное окно браузера.
- `sessions_list` показывает, какая сессия держит какую вкладку.
## Как понять, какая вкладка сейчас используется
Каждая заявленная вкладка имеет **1‑пиксельную боковую рамку** и маленький идентификационный чип. Рамка означает, кто ведет управление:
- **дыхание синего свечения** — DevCDP работает
- **немого зелёного** — управление передано вам
- **молнией красного** — что-то сломалось
Три состояния, три цвета, и каждый цвет значит ровно одно вне зависимости от числа сессий. Сессии различаются по тексту чипа и их собственной группе вкладок Chrome — не по оттенку, потому что оттенок мог бы превратить рамку в головоломку, когда самое главное — понять, ожидает ли вкладка вашего вмешательства.
**Вкладки, которые приложение открыл само** — `window.open`, `target="_blank"`, детальный экран в собственном окне — тоже помечаются и удерживаются, с пометкой "opened tab". `devtools_status` перечисляет их в разделе `tabsAppOpened`, с вызовом переключения на одну из них.
**Индикатор не может пережить сессию, которая его нарисовала.** Обычное завершение — вы закрываете ассистента, он отключается, сессия заканчивается — рамка исчезает немедленно. Если сервер «убит» и не успел очиститься, оверлей замечает, что перестал получать сигналы от своей сессии, и снимает себя в течение `ownerTimeoutMs` (45s), забирая вкладку вместе с собой. Так или иначе, наличие рамки на экране означает, что сессия действительно активна. Для вкладки, оставшейся после сборки старой версии, `node scripts/sweep.mjs` удаляет те, что не принадлежат ни одной живой сессии (`--dry` — чтобы посмотреть заранее).
Статусные сообщения появляются как полупрозрачные самоугасающие тосты. Кольцо следит за активностью указателя, а затрещивание помечает каждый клик, чтобы действия агента были отслеживаемы. Когда отладчик делает паузу, появляется собственный баннер Chrome «Paused in debugger» — UI браузера, который не добавляет ничего на страницу.
Ничто из этого не может перехватить клик: весь слой имеет `pointer-events: none`, кроме кнопки подтверждения во время handover, tamanho 91×24 пикселя. Есть тест, который проводит реальные события мыши через него.
**Реальные вкладки Chrome, связанные с группами вкладок, рисуются за счет встроенного расширения**, которое размещает вкладки каждого сеанса в синей группе с названием. Chrome не позволяет инструменту устанавливать расширение за вас — брендовый Google Chrome игнорирует `--load-extension` («не разрешено в Google Chrome», по его журналу) и не предоставляет `Extensions.loadUnpacked` через порт отладки — поэтому выбирайте одно из:
- **Без ручного шага:** укажите `chromePath` на Chromium или Chrome for Testing. Эти сборки поддерживают переключение, поэтому расширение загружается само по себе и группировка работает. Если такой бинарник уже есть на вашей машине, `devtools_status` скажет, где он находится.
- **Брендированный Chrome:** установите его один раз — `chrome://extensions` → Режим разработчика → Load unpacked → выберите `extension/`. Режим отладки профиля устойчив и разделяемый между `debug-chrome.bat` и собственным лаунчером DevCDP, поэтому разово — разово.
`devtools_status.tabGrouping` сообщает, находится ли вкладка действительно в группе, и если нет — потому что не установлен расширитель или потому что установленный расширитель не сработал — с указанием ошибки. Ничто другое от группировки не зависит: рамка, чип и `window:'new'` работают без неё.
---
## Работа с ассистентом
Вам не обязательно ждать запроса. Кликните, наберите, выберите — всё записывается, и ассистент читает это через `session_get_user_actions`: какой элемент, какой параметр и какое значение вы набрали.
**Ctrl+Shift+D** во вкладке явно передает управление вам. Это также открывает
окно, в котором фиксируются введённые значения, чтобы «использовать этот referenс» дошло до ассистента. Вне этого окна значения остаются приватными, а поля вроде паролей redacted независимо от контекста.
Когда ассистенту нужно что-то, что может сделать только вы, он спрашивает на странице и ждёт кнопку «I've done it ✓» — αυτή кнопка единственный недвусмысленный сигнал. Chrome сообщает автоматизированный ввод как доверенный тоже, поэтому действие не может быть помечено как «человек» и инструменты говорят это, а не притворяются.
---
## Типичное расследование
"The save button does nothing. Find the exact line."
- `devtools_connect` — подключается, заявляет вкладку, помечает её
- `source_search("save")` — находит обработчик по содержанию, путь не нужен
- `debugger_set_breakpoint(file, line)` — отвечает `bound: true`
- кликается
- `debugger_get_capture` — область видимости, консоль и сеть из паузы, один вызов
- ответ — значение, которое реально наблюдалось, на существующей строке
Точки останова продолжают работу сами по себе, поэтому клик, который их активировал, всё равно завершает действие.
Когда вы знаете функцию, но не файл — что обычно встречается с фреймворками —
`debugger_set_breakpoint_at_function("app.store.save")` спрашивает движок, где эта функция была определена, и ставит точку остановки на её первой инструкции. Поиск по названию в исходниках ненадёжен: функция, присвоенная как `Foo.bar = function`, не может быть найдена по запросу `"bar: function"`, и такой запрос зачастую возвращает смежные методы на других классах.
Захват остаётся маленьким даже в графе объектов фреймворка: важная переменная печатается, и всё, что слишком велико, сообщает, что это за объект (`"constructor", 77747 bytes expanded`), чтобы вы могли прочитать только нужную часть с помощью `debugger_evaluate_at_frame`.
---
## Безопасность
Лаунчер использует **отдельный Chrome профайл**, поэтому ваши обычные сессии не затрагиваются, и включённая **web security** остаётся включённой — отключение скрывает именно те cross-origin ошибки, которые вы бы дебагродили.
Введённые значения не записываются, если вы не включаете это или не участвуете в совместной работе, а поля типа паролей остаются redacted независимо от контекста.
Удалённая отладка даёт полный контроль над профилем браузера любому, кто может достучаться до порта. Используйте debug-профиль для разработки, а не для личных аккаунтов.
---
## Макет
index.js точка входа server.js заглушка для старых конфигураций, указывающих сюда src/ core/ конфигурация, контекст, буферы, структурированные ошибки, реестр инструментов cdp/ соединение, выбор цели, реестр претензий к сессии, запуск browser/ встроенный агент на странице debug/ source maps, разворачивание области видимости store/ хранилище обученной памяти tools/ по модулю на каждую группу инструментов extension/ сопутствующее расширение для групп вкладок в Chrome plugins/devcdp/ Claude Code плагин: манифест, лаунчер, навык (сгенерировано) server.json манифест MCP Registry; должен совпадать с package.json scripts/gen-docs.mjs регенерирует docs/TOOLS.md и плагин-скилл docs/TOOLS.md полный справочник инструментов (сгенерировано) docs/PUBLISHING.md как каждый листинг на marketplace создаётся и поддерживается в актуальном виде test/ validate.mjs оффлайн проверки, браузер не нужен installer.test.mjs мастер настройки, проверяется на реальных файлах integration.mjs реальный Chrome против фиктивного приложения fixture-app/ небольшое приложение с заготовленной багой и реальной source map BACKLOG.md каждый дефект, его исправление и что осталось
## Работа над DevCDP
'' вызов одного инструмента, увидеть точный ответ и его стоимость
node scripts/mcp-probe.mjs то же самое через реальный MCP, сырой JSON-RPC">```
node scripts/call.mjs <tool> '<json>' вызов одного инструмента, увидеть точный ответ и его стоимость
node scripts/mcp-probe.mjs то же самое через реальный MCP, сырой JSON-RPC
Тайминг, логи и ловушки, в которые этот кодобаз уже попадал:
Tests
npm run validate оффлайн проверки
npm run test:installer мастер настройки
npm test все три секции
npm run docs регенерировать справочник инструментов
199 проверок. Интеграционный набор подключается к странице, которая уже загрузилась — потому что именно в этом случае предыдущая версия ошибалась. npm run validate падает, если docs/TOOLS.md устарел, поэтому справочник не должен расходиться.
Устранение неполадок
Инструменты не появляются — полностью выйдите из ассистента (tray/menu, а не просто окно) и повторно откройте. Повторная настройка, если всё ещё пропадает.
«Chrome недоступен» — запустите через debug-chrome.bat, затем проверьте
http://localhost:9222/json/version. Доступен только один Chrome, который может владеть портом.
Точка останова никогда не срабатывает — используйте debugger_list_breakpoints и смотрите на bound. Непривязанная точка останова сообщает, почему.
Поддержка проекта
DevCDP бесплатен и распространяется по MIT-лицензии; работает и поддерживается одним человеком. Если он спас вам debugging-сьёмку дня, поддержка на GitHub (sponsors) помогает держать проект в движении. Команды, которым нужен hosted-setup, общий learned memory между инженерами или воркшоп по внедрению, могут открыть issue для начала разговора.
Конфиденциальность и лицензия
DevCDP работает локально и ничего не отправляет куда-либо, кроме MCP client, к которому вы подключились: PRIVACY.md. MIT-лицензия: LICENSE.
A selector finds nothing — dom_list_frames; контент может находиться в iframe.
Повторная попытка с frame: 'all'.
Пустой консоль или сеть сразу после подключения — ожидаемо. Захват начинается при подключении; повторная загрузка страницы через page_reload воспроизводит страницу с наблюдением DevCDP.
Страница перестает отвечать — её главный поток заблокирован, обычно в цикле JS приложения. page_interrupt прерывает запускаемый скрипт; повторная загрузка не освободит его.
Таб недоступен — sessions_list показывает, какая сессия держит его.