VisBug MCP Bridge

Мост VisBug → Cursor: визуальные правки на localhost → буфер → вставка в чат → patch в исходниках агентом Cursor.

Что это

Recorder-only (модель mambari/visbug-mcp): расширение не пишет в файлы проекта. VisBug меняет DOM на странице → bridge сохраняет сырые мутации → вы копируете буфер → Cursor вносит правки в код по контракту.

Архитектура

Chrome (VisBug + расширение)
        │  WebSocket ws://127.0.0.1:4844
        ▼
┌─────────────────┐      ~/.visbug-mcp/projects/<id>/changes.json
│  ws-daemon.js   │ ◄──────────────────────────────►  src/server.js (MCP stdio)
│  (фон)          │                                    └─ опционально в Cursor
└─────────────────┘

• src/ws-daemon.js — WebSocket на 127.0.0.1:4844. Принимает live-мутации от content-script, дедуплирует, пишет в per-project store.
• src/server.js — MCP (stdio): get_changes / apply_changes / clear_changes. Запись в файлы не выполняет.
• extension/ — Chrome MV3: observer на localhost, popup «Скопировать» / «Очистить», красные направляющие с px.

Безопасность

• WebSocket только 127.0.0.1 — данные не уходят в интернет
• Store: ~/.visbug-mcp/projects/<projectId>/changes.json на вашем ПК
• Внешних HTTP-запросов нет

Установка

Полная инструкция: docs/INSTALL.ru.md
В Cursor: /visbug-mcp-start

git clone https://github.com/samsebeingener/visbug-mcp-ru.git
cd visbug-mcp-ru
npm install
npm run setup

npm run setup регистрирует workspace + localhost origin, запускает daemon и копирует в проект:

• команды /visbug-mcp-start, /visbug-mcp-update;
• rule .cursor/rules/visbug-buffer-apply.mdc — подсказка агенту при вставке буфера.

Расширения Chrome

1. VisBug (официальный)
2. visbug-mcp — chrome://extensions → режим разработчика → Загрузить распакованное → папка extension/ в клоне репо

Демон (если setup не запустил)

Одна команда на Windows, macOS и Linux:

npm run daemon:start

Логи в терминале (не фон): npm run daemon.

Safari не подходит — Chrome / Arc / Brave / Edge.

MCP в Cursor (опционально)

npm run setup добавляет запись в ~/.cursor/mcp.json. Для записи VisBug MCP не обязателен — достаточно popup «Скопировать».

После правок — Reload Window в Cursor.

Обновление

npm run update

git pull, npm install, перезапуск daemon, копирование недостающих команд и rule во все workspace из config (без перезаписи существующих).

Как пользоваться

Рабочий цикл (v0.26)

1. Запустите сайт на http://localhost:…, откройте в Chrome.
2. Убедитесь, что origin зарегистрирован (/visbug-mcp-start или npm run setup).
3. Popup: зелёная точка = daemon online.
4. Правьте layout в VisBug (красные направляющие с px — в расширении).
5. Popup → «Скопировать правки» → вставьте в чат Cursor.
6. Агент правит исходники (см. apply-buffer-contract).
7. Popup → «Очистить правки» (опционально).

Отдельная команда для apply не нужна.

Как Cursor понимает буфер

Кратко для агента: контейнер vs ребёнок, фильтр шума VisBug, bake left/top/transform, не копировать left 1:1 в transform.

Несколько проектов

Bridge сопоставляет точный origin с workspace. Пример: localhost:3001 → Next, localhost:3002 → static HTML. Незарегистрированный origin — запись блокируется.

Popup

MCP-инструменты (опционально)

Пример строки в буфере:

[0] section.hero-section … > h1… → стиль: left = -163px (было: не задано)

Техническое поведение

Live-захват + layout-delta (v0.14)

Content-script пишет inline-мутации VisBug. При отпускании drag дополнительно:

[#method-quote] → смещение: Δx=0px Δy=-65px (viewport 1440×900)

Δ — разница getBoundingClientRect() до/после drag; не зависит от того, писал ли VisBug только top без left. Агент: apply-buffer-contract.md.

Auto-stamp (v0.26)

Если у элемента, получившего записанную мутацию, нет ни id, ни data-vb*, content-script сам ставит ему data-visbug-id="vb-<tag>-<NN>" (например vb-div-01) — атрибут вне фильтра обсервера, петли нет. В буфере появляется секция stamps: (vb-div-01 → исходный DOM-path), рецепт идёт на стабильный #vb-div-01 с confidence high и warning stamp-pending. При первом apply агент обязан перенести этот id в исходный HTML (и использовать #vb-* в CSS) — с этого момента цель стабильна навсегда, без ручной разметки. Подробности: §11 apply-buffer-contract.md.

Store (v2)

~/.visbug-mcp/projects/<projectId>/changes.json:

{
  "version": 2,
  "workspace": "/abs/path/to/site",
  "changes": [ … ]
}

Парсер и шум

src/parser.js — дедуп по selector|type|property, фильтр overlay #visbug-mcp-guides-root и UI VisBug. Сырые left/top/transform не переводятся автоматически — bake делает агент по контракту.

Полезные команды

npm run health          # daemon, extension version, config
npm run setup           # первичная настройка + rule в workspace
npm run update          # git pull + sync commands/rule
npm run daemon:start    # фоновый демон (Windows / macOS / Linux)
npm run daemon          # демон на переднем плане (логи)
npm run daemon:watch    # разработка с --watch
npm test                # unit-тесты

Структура проекта

visbug-mcp-ru/
├── src/
│   ├── ws-daemon.js           # WebSocket, буфер
│   ├── server.js              # MCP stdio
│   ├── parser.js              # мутации → changes, формат буфера
│   ├── project-store.js       # per-project store v2
│   └── config.js
├── extension/                 # Chrome: content-script, popup, guides
├── shared/
│   └── apply-buffer-contract.md   # контракт для Cursor-агента
├── prompts/
│   └── buffer-for-cursor.md
├── .cursor/
│   ├── commands/              # visbug-mcp-start, visbug-mcp-update
│   └── rules/                 # visbug-buffer-apply.mdc → копируется в workspace
├── scripts/
│   ├── setup.mjs
│   ├── update.mjs
│   ├── sync-cursor-artifacts.mjs
│   ├── start-ws-daemon.mjs
│   ├── start-ws-daemon.sh
│   └── start-ws-daemon.ps1
├── docs/
│   └── INSTALL.ru.md
└── test/

Roadmap

Идеи auto-apply, layout-solver — в архиве спецификаций (не в репо). Актуальные планы: точность записи (transition, keyboard, JS-inline) и предсказуемость применения через Cursor.

Что на русском

• Popup расширения
• Строки буфера («стиль», «было», «текст»)
• Описания MCP-инструментов

Лицензия и upstream

Разработка Никита Куликов на базе идей mambari/visbug-mcp.
VisBug — GoogleChromeLabs/ProjectVisBug.

Никита Куликов
samsebeingener.ru · GitHub