ndthanhdev/mcp-browser-kit

Делает скриншот вкладки. Когда: только для вкладок MV2; вам нужны пиксельные координаты для инструментов, работающих с координатами. Как: browserId, windowId, tabId из bk:///context; используйте полученные размеры для вычисления x/y. Требует: browserId, windowId, tabId. Возвращает: value { data (изображение base64), width, height, mimeType } - используйте width/height для масштабирования координат. Избегайте: вызова на manifestVersion 3 - используйте readable-elements.

Кликает по пиксельным координатам внутри вкладки. Когда: Резервный вариант для MV2, когда readablePath недоступен. Как: x/y из недавнего скриншота captureTab (такие же ширина и высота); browserId, windowId, tabId из контекста. Требует: browserId, windowId, tabId, x, y. Возвращает: после авто-ожидания значение { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает читаемые элементы: добавленные (+), удалённые (-) и близлежащие неизменённые, с их идентификаторами. Нет diff, когда tooLarge или navigated: перечитайте readable-elements. При ok=false: заново захватите вкладку и пересчитайте x/y. Избегайте: на MV3 (нет источника скриншотов); предпочитайте clickOnElement, когда readablePath существует.

Кликает по элементу по readablePath. Когда: основной способ клика в MV2 и MV3. Как: читает {tabUri}/readable-elements; фильтрует кортежи [path, role, text, value?] по role и text; копирует path точно (например, f1:e1a), а не CSS-селектор. Кастомный dropdown/combobox/datepicker: кликает по триггеру, чтобы открыть его, затем заново читает readable-elements и кликает по опции/ячейке дня. Нативный <select>: клик по опции может сработать для listbox-селектов (multiple или size>1), но однострочные выпадающие списки используют нативный попап, который игнорирует синтетические клики - для них нужен invokeJsFn (MV2) или showHumanHint (MV3). Проверяет повторным чтением и эскалирует. См. Complex inputs. Требует: browserId, windowId, tabId, readablePath. Возвращает: после автоожидания value { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает добавленные (+), удалённые (-) и соседние неизменённые readable-элементы, с их id элементов. Нет diff, когда tooLarge или navigated: заново читает readable-elements. При ok=false: reason говорит, почему (not visible, disabled, covered by <el>, detached); заново читает readable-elements и выбирает новый id. Избегайте: придумывать пути; заново читать элементы после навигации, если клик не сработал.

Закрывает вкладку. Необратимо. Когда: работа с вкладкой завершена и дальнейшее взаимодействие не требуется. Как: browserId, windowId, tabId из bk:///context. Требует: browserId, windowId, tabId. Возвращает: ok=true после закрытия. Избегайте: закрытия вкладки, которая ещё нужна для дальнейших взаимодействий.

Кликает в точке (x, y), затем вводит текст в сфокусированное поле ввода. Когда: запасной вариант для MV2 для полей без readablePath. Как: координаты из недавнего captureTab; отправка через clickOnCoordinates по кнопке отправки или hitEnterOnCoordinates. Требуется: browserId, windowId, tabId, x, y, value. Возвращает: после авто-ожидания значение { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает добавленные (+) и удалённые (-) читаемые элементы и соседние неизменённые, с их id элементов. Нет diff при tooLarge или navigated: перечитайте readable-elements. При ok=false: заново захватите вкладку и пересчитайте x/y. Нежелательно: на MV3; предпочтителен fillTextToElement, когда доступен readablePath.

Вводит текст в <input> или <textarea> по readablePath. Когда: основной метод заполнения в MV2 и MV3. Также обрабатывает нативные <input> date/time/datetime-local/month/color, когда значение в точном формате (date YYYY-MM-DD, time HH:MM, datetime-local YYYY-MM-DDTHH:MM, month YYYY-MM, color #rrggbb). Как: readablePath из первого элемента кортежа [path, role, text, value?] в readable-elements; отправляет через clickOnElement по кнопке submit или hitEnterOnElement. Требует: browserId, windowId, tabId, readablePath, value. Возвращает: после автоожидания значение { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает добавленные (+) и удалённые (-) readable-элементы и соседние неизменённые, с их element ids. Нет diff, когда tooLarge или navigated: перечитайте readable-elements. При ok=false: причина объясняет, почему (не виден, отключён, перекрыт <el>, отсоединён); перечитайте readable-elements и выберите свежий id. Избегайте: CSS-селекторов в качестве readablePath; id элементов, которые удалили или перерисовали. Не работает с contenteditable rich-text редакторами (в MV2 вместо этого invokeJsFn), нативным <select> или кастомными всплывающими dropdowns/datepickers - используйте лестницу стратегий в разделе Complex inputs в инструкциях сервера.

Получает агрегированное состояние каждого подключённого браузера. Когда: ищете доступные вкладки перед взаимодействием - это равносильно чтению ресурса bk:///context. Как: параметры не нужны. Требуется: ничего. Возвращает: serverVersion, browsers[] (каждый содержит browserId, extensionInfo, versionMismatch, когда мажорная версия расширения отличается от серверной, windows) и tabs (каждый содержит id (tabId), windowId, tabUri, url, title, active). Избегайте: повторных вызовов в плотном цикле - кэшируйте результат на время выполнения задачи.

Получает outerHTML одного элемента по readablePath. Когда: нужна точная разметка (атрибуты, классы, вложенная структура) одного элемента, что равнозначно чтению {tabUri}/readable-element-html/<readablePath>. Как: берёт readablePath из кортежа readable-elements (первое поле); browserId и tabId из getContext или bk:///context. Требуется: browserId, tabId, readablePath (стабильный id элемента, например f1:e1a, а не CSS-селектор). Возвращает: { snapshotId, data (HTML), hasNextPage, nextPageNumber, totalPages }. Пагинация: если hasNextPage имеет значение true, вызывает getSnapshotPage с возвращённым snapshotId, типом readable-element-html и nextPageNumber.

Получает интерактивные элементы вкладки в виде кортежей [path, role, text, value?]. Когда: нужны пути элементов для clickOnElement/fillTextToElement - эквивалентно чтению ресурса {tabUri}/readable-elements. Как: browserId и tabId из getContext или bk:///context. Требует: browserId, tabId. Возвращает: { snapshotId, data (кортежи [path, role, text, value?]), hasNextPage, nextPageNumber, totalPages }. path - стабильный идентификатор элемента (например, f1:e1a) - используется как readablePath в инструментах взаимодействия. Пагинация: если hasNextPage истинно, вызывается getSnapshotPage с возвращёнными snapshotId и nextPageNumber.

Получает читаемый внутренний текст вкладки. Когда: вам нужно текстовое содержимое страницы — эквивалентно чтению ресурса {tabUri}/readable-text. Как: browserId и tabId из getContext или bk:///context. Требует: browserId, tabId. Возвращает: { snapshotId, data (text), hasNextPage, nextPageNumber, totalPages }. Пагинация: если hasNextPage равно true, вызовите getSnapshotPage с возвращёнными snapshotId и nextPageNumber.

Получает текущее выделение текста пользователя во вкладке. Когда: нужен текст, который пользователь выделил на странице. Как: browserId, windowId, tabId из bk:///context. Требуется: browserId, windowId, tabId. Возвращает: value.selectedText - пустая строка, если ничего не выбрано. Избегайте: ожидать содержимое, когда ничего не выбрано.

Получает страницу продолжения для снимка readable-text, readable-elements или readable-element-html. Когда: предыдущий вызов getReadableText, getReadableElements или getReadableElementHtml вернул hasNextPage=true. Как: используй snapshotId и nextPageNumber из предыдущего ответа. Требуется: snapshotId, type (readable-text | readable-elements | readable-element-html), pageNumber. Возвращает: ту же структуру, что и исходный вызов: { snapshotId, data, hasNextPage, nextPageNumber, totalPages }. Не вызывайте без предварительного получения страницы 1 через getReadableText, getReadableElements или getReadableElementHtml.

Кликает по (x, y), затем нажимает Enter, чтобы отправить форму. Когда: резервный вариант в MV2 для отправки, если у кнопки submit нет readablePath. Как: координаты из недавнего captureTab. Требует: browserId, windowId, tabId, x, y. Возвращает: после автоожидания значение { changed, navigated, url, added, removed, tooLarge, diff? }, где diff показывает добавленные (+) и удалённые (-) readable-элементы и соседние неизменённые, с их element ids. diff отсутствует при tooLarge или navigated: перечитайте readable-elements. При ok=false: повторно захватите вкладку и пересчитайте x/y. Избегайте: на MV3; предпочитайте hitEnterOnElement, когда доступен readablePath.

Фокусирует элемент по readablePath, затем нажимает Enter. Когда: отправка формы, если явной кнопки отправки нет. Как: readablePath из кортежа readable-elements (стабильный id элемента, например f1:e1a). Требует: browserId, windowId, tabId, readablePath. Возвращает: после авто-ожидания значение { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает добавленные (+) и удалённые (-) readable-элементы, а также соседние неизменённые, с их id элементов. Нет diff, когда tooLarge или navigated: перечитайте readable-elements. При ok=false: причина объясняет, почему (не виден, отключён, перекрыт <el>, отсоединён); перечитайте readable-elements и выберите новый id. Избегайте: использования, когда доступен readablePath кнопки отправки - вместо этого кликните по ней.

Выполняет тело функции JavaScript в контексте страницы. Когда: только в MV2, и только когда инструменты для элементов/координат не могут выполнить задачу — например, установка нативного <select> (.value, затем dispatch change) или ползунок диапазона. Как: fnBodyCode — это только тело функции (без обёртки функции); используйте return, чтобы отправить значение обратно. Пример: return document.title; Требует: browserId, windowId, tabId, fnBodyCode. Возвращает: value.result = то, что вы возвращаете (должно быть сериализуемо в JSON). Избегайте: на manifestVersion 3; обёртывания в function () { ... }.

Открывает URL в новой вкладке. Когда: переход на страницу, которая ещё не открыта. Как: browserId и windowId из bk:///context; url должен содержать схему (https://); после успеха повторно прочитайте контекст для нового tabId и дождитесь загрузки страницы. Требует: browserId, windowId, url. Возвращает: значение { browserId, windowId, tabId } — используйте возвращённые идентификаторы для последующих вызовов. Избегайте: немедленного взаимодействия — вкладке нужно время на загрузку.

Сохраняет страницу вкладки в папку загрузок пользователя одним самодостаточным файлом. Когда: нужно заархивировать страницу на будущее; работает в любом браузере и с любой версией манифеста. Как: формат "zip" (по умолчанию) пишет index.html плюс папку assets/ - меньше по размеру, а распакованную папку можно листать и искать по ней grep'ом. Формат "html" пишет один файл, встраивая ресурсы как data: URI - больше по размеру, зато открывается двойным щелчком. Требует: browserId, windowId, tabId. Необязательно: format. Возвращает: значение { filename, bytes, format, resourceCount, skipped } - в skipped перечислены ресурсы, которые не удалось встроить, с причиной для каждого. Примечание: имя файла берётся из заголовка страницы; агент не может его выбрать. Скрипты не сохраняются никогда. Шрифты, srcset и iframe не встраиваются, а кросс-доменные ресурсы без заголовков CORS попадают в skipped. Избегай: считать, что список skipped пуст - проверяй его, когда важна точность.

Прокручивает содержимое внутри прокручиваемого элемента (панели, списка или любого контейнера с собственной полосой прокрутки). Когда: контент лежит в прокручиваемой области, которую scrollPage (весь вьюпорт) не сдвигает, например панель чата или длинный список внутри div. Работает на MV2 и MV3 (скриншот не нужен). Как: readablePath из кортежа readable-elements; direction принимает up/down/left/right; amount в пикселях необязателен, без него прокрутка идёт примерно на 90% размера элемента. Прокручивается элемент по readablePath, а если он сам не прокручивается - его ближайший прокручиваемый предок (так можно нацелиться на интерактивный дочерний элемент внутри панели). browserId, windowId, tabId берутся из bk:///context. Требует: browserId, windowId, tabId, readablePath, direction. Возвращает: после автоожидания значение { changed, navigated, url, added, removed, tooLarge, diff? }, где diff показывает добавленные (+) и удалённые (-) readable-элементы и соседние неизменённые, с их element id. diff отсутствует при tooLarge или navigated: перечитайте readable-elements. Если элемент уже у края или прокручиваемый контейнер не найден (прокручивать нечего), всё равно ok=true. Избегайте: использования для прокрутки всей страницы - для этого есть scrollPage; перечитывайте readable-elements после прокрутки, снимки устаревают.

Прокручивает область просмотра страницы в заданном направлении. Когда: целевой контент или элементы за пределами экрана; показывает больше страницы перед чтением или взаимодействием. Работает в MV2 и MV3 (скриншот не нужен). Как: direction принимает значения up/down/left/right; необязательный amount в пикселях - если его не указывать, прокрутка составит примерно один экран (страницу). browserId, windowId, tabId из bk:///context. Требует: browserId, windowId, tabId, direction. Возвращает: после автоожидания значение { changed, navigated, url, added, removed, tooLarge, diff? } - diff показывает читаемые элементы, добавленные (+), удалённые (-), и соседние неизменённые, с их id элементов. Нет diff, когда tooLarge или navigated: перечитайте readable-elements. Если уже у этого края (нечего прокручивать), всё равно ok=true. Чего избегать: предполагать, что появились новые элементы - перечитайте readable-elements после прокрутки, снимки устаревают.

Подсвечивает элемент и инструктирует человека действовать, когда автоматизация не удалась или шаг предназначен только для человека. Когда: CAPTCHA, 2FA, необратимые подтверждения, повторные сбои инструментов или элементы ввода MV3, которые инструменты не могут установить (нативный <select>, ползунок диапазона). Как: укажите ровно одну цель - readablePath (предпочтительно) ИЛИ x и y, но не оба сразу; действие fill требует значение. Требует: browserId, windowId, tabId, action (click | fill | hit-enter), message. Возвращает: humanMessage (передаёт дословно пользователю) и expiresInSeconds. Избегайте: одновременного указания readablePath и координат.