Web Picker

Выберите элемент интерфейса на странице localhost в браузере, введите запрос на исправление, и ваш MCP-агент для кодинга (Claude Code, Codex, ...) заберёт его и отредактирует код.

Хватит описывать элементы словами. Нажмите на элемент. Захват содержит минимальные подсказки, необходимые агенту, чтобы найти именно этот элемент в вашей кодовой базе — при этом конфиденциальные значения никогда не утекают.

v1 по замыслу работает только с localhost. Никакого облака, аккаунтов и API-ключей.

Как это работает

 Browser (localhost page)            Local machine                Coding agent
 ┌────────────────────────┐     ┌───────────────────────┐     ┌──────────────────┐
 │ content script         │     │ Daemon (127.0.0.1)    │     │ MCP adapter      │
 │  pick + mask + rank    │     │  durable queue        │     │  connect / list  │
 │          │ runtime msg │     │  extension HTTP       │     │  pull / resolve  │
 │ service worker ────────┼HTTP►│  token IPC /ipc      │◄────┤  (7 MCP tools)   │
 └────────────────────────┘     └───────────────────────┘ IPC └──────────────────┘

• Демон привязывается только к 127.0.0.1. Воркер расширения принимает сообщения только от подтверждённых Chrome вкладок localhost, а эндпоинты расширения демона принимают только закреплённый chrome-extension://mnglicpibnccgcifnndemfpidkcgboli Origin. IPC MCP-адаптера защищён токеном, уникальным для каждого запуска.

• Не зависит от агента: демону неизвестно, является ли агент Claude Code или Codex. Различается только шаг регистрации.

• Маскирование сохраняет идентичность: значения полей ввода, email-адреса и токены никогда не экспортируются; короткие видимые метки, селектор, предки и landmark сохраняются, чтобы агент мог найти цель.

Related MCP server: claude-annotate

Требования

• Node.js >= 20.18.0 (проверено на 20.20.2)

• Google Chrome (MV3, загрузить распакованное)

• Агент для кодинга, поддерживающий MCP (Claude Code или Codex)

Установка

./bootstrap.sh          # macOS/Linux  (installs deps + builds)
# or
pwsh ./bootstrap.ps1    # Windows

Затем:

1. Загрузите расширение Chrome Откройте chrome://extensions → включите Режим разработчика → нажмите Загрузить распакованное → выберите папку extension/.

2. Зарегистрируйте MCP-сервер в вашем агенте:

   ./scripts/register-claude-code.sh   # Claude Code
   ./scripts/register-codex.sh         # Codex

   Оба способа указывают агенту на scripts/run.cjs, который лениво запускает демон.

Пятиминутный сценарий проверки (без ключей и аккаунтов)

Весь цикл воспроизводим с одной лишь демо-страницы. Автоматическая проверка обычно укладывается в пять минут на машине с установленным Chrome и графическим рабочим столом; не нужен ни API-ключ модели, ни загрузка браузера Playwright.

1. Настройка

   ./bootstrap.sh

2. Запустите демо-страницу на localhost

   python3 -m http.server 3000 --directory test-page

   Откройте http://localhost:3000. На ней есть три кнопки с одинаковой подписью 저장 — в шапке, основной части и подвале; это намеренный набор приманок.

3. Загрузите расширение (см. шаг 1 установки) и зарегистрируйте своего агента (шаг 2 установки).

4. Выберите элемент

   • Нажмите кнопку 픽 (справа внизу) → 요소 선택.

   • Наведите курсор на кнопку 저장 в основной области (в карточке профиля) и нажмите её.

   • Введите запрос, например 이 버튼을 파란색으로, и нажмите 보내기.

   • Вы должны увидеть 요청을 큐에 보냈습니다.

5. Заберите его с помощью агента В сессии Claude Code / Codex:

   • connect_web_picker → забирает пикер, показывает количество ожидающих.

   • list_web_requests → показывает ваш запрос с его id и статусом.

   • get_web_request с этим id → показывает подсказки о цели. Обратите внимание, что landmark: section (и селектор #profile-save) отличают его от приманок 저장 в шапке и подвале (landmark: header / landmark: footer), хотя у всех трёх одна и та же видимая подпись 저장.

   • resolve_web_request с этим id → помечает его решённым.

Этот цикл с приманками покрыт как безбраузерным интеграционным набором, так и настоящим E2E-тестом Chrome ниже.

Воспроизведение без браузера (полностью автоматизировано)

npm test

test/integration.test.ts отправляет три захвата-приманки, затем прогоняет реальные MCP-инструменты по цепочке connect → list → get → resolve, проверяя, что выбранный элемент идентифицируется однозначно. Он также выполняет холодный запуск собранного демона из dist/.

Воспроизведение с реальным расширением Chrome

npm run test:e2e открывает установленный Google Chrome в новом профиле с видимым окном, загружает распакованное расширение extension/, выполняет выбор кнопки профиля через реальный контентный интерфейс, а затем проверяет и помечает запрос из очереди решённым через MCP-клиент. Требуется графическая сессия рабочего стола; обычно выполнение занимает около 10 секунд. Браузер при этом не скачивается.

macOS или Linux:

npm run test:e2e

# For a non-standard Chrome install:
PLAYWRIGHT_CHROME_EXECUTABLE=/path/to/google-chrome npm run test:e2e

Windows PowerShell:

npm run test:e2e

# For a non-standard Chrome install:
$env:PLAYWRIGHT_CHROME_EXECUTABLE = 'C:\Path\To\chrome.exe'
npm run test:e2e

Если Chrome отсутствует или переопределение не указывает на установленный исполняемый файл, тест завершается ошибкой:

Google Chrome is required for npm run test:e2e; install Chrome or set PLAYWRIGHT_CHROME_EXECUTABLE

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

• Демон привязан только к 127.0.0.1.

• Расширение активируется только на страницах localhost / 127.0.0.1 / *.localhost.

• Воркер расширения принимает только подтверждённых Chrome отправителей из вкладок localhost; HTTP-эндпоинты расширения требуют точного закреплённого Origin расширения. IPC требует токен (сравниваемый за постоянное время), хранящийся с правами 0600 в ~/.web-picker/token.

• Значения полей ввода и строки, похожие на email, длинные числа или токены, никогда не экспортируются. Тот же фильтр применяется к селектору, id, class, role, aria-label, name, сводкам предков и замаскированному HTML, сохраняя при этом безопасные токены классов для идентификации цели. dataset отправляет только неконфиденциальные имена ключей после нормализации DOM; значения никогда не покидают страницу.

MCP-инструменты

Разработка

npm test          # vitest (unit + jsdom + integration; excludes real Chrome)
npm run test:e2e  # headed installed-Chrome round trip
npm run build     # tsc -> dist/
npm run benchmark # deterministic target-disambiguation benchmark -> artifacts/
npm run sbom      # CycloneDX 1.5 inventory -> artifacts/sbom.cdx.json

npm run sbom отклоняет версии Node ниже задокументированного минимального уровня engine, восстанавливает полученные из lock-файла метаданные integrity/development/optional, проверяет итоговый CycloneDX JSON и записывает канонические байты независимо от скрытого lock-кэша npm.

npm run benchmark измеряет только устранение неоднозначности цели на 30 статических HTML-фикстурах. Он включает сбалансированные контрольные случаи с неоднозначными и уникальными метками, а также как успешные, так и неуспешные разрешения локаторов. Это не показатель продуктивности агента для кодинга и не показатель поиска по исходникам. В результатах фиксируются: разрешение только по тексту, разрешение локатора Web Picker, глобальная и категорийная × калибровка достоверности, страты меток и размеры сериализованного payload захвата в байтах — в artifacts/benchmark-results.json и artifacts/benchmark-results.md.

Архитектура: чистое ядро (src/daemon/state.ts) + обработчики приложения (extension-api, ipc-api, tools) + тонкие адаптеры (server.ts, исходный код MCP-адаптера в src/shim/, spawn.ts). Порты внедряются, поэтому всё проходит модульные тесты без сокетов. См. docs/architecture.md.

Материалы для подачи: docs/dependencies.md, docs/video-script.md и docs/submission-checklist.md. URL публичного репозитория и YouTube остаются явными блокерами чек-листа, пока владелец не опубликует и не проверит их.

Лицензия

MIT. Лицензии зафиксированных зависимостей записаны из метаданных установленных пакетов в docs/dependencies.md. Зависимостей времени выполнения семейства GPL нет.