ndthanhdev/mcp-browser-kit

Capture tab screenshot

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

Click at coordinates

Выполняет клик по пиксельным координатам внутри вкладки. Когда: Запасной вариант для MV2, когда нет доступного readablePath. Как: x/y из последнего скриншота captureTab (одинаковые ширина/высота); browserId, windowId, tabId из контекста. Требует: browserId, windowId, tabId, x, y. Возвращает: ok=true при успехе; при ok=false — повторно захватывает вкладку и пересчитывает x/y. Избегать: на MV3 (нет источника скриншота); предпочитать clickOnElement, когда существует readablePath.

Click element

Кликает по элементу с помощью readablePath. Используется: основной метод клика в MV2 и MV3. Как работает: читает {tabUri}/readable-elements; фильтрует наборы [path, role, text, value?] по роли и тексту; копирует путь точно (например, 0.2.1) — не CSS-селектор. Специальные выпадающие списки/комбобоксы/выбор даты: кликает по триггеру, чтобы открыть их, затем повторно читает readable-elements и кликает по опции или ячейке дня. Нативные <select>: клик по опции может сработать для listbox-select (multiple или size>1), но однострочные выпадающие списки используют нативное всплывающее окно, которое игнорирует синтетические клики: для них нужен invokeJsFn (MV2) или showHumanHint (MV3). Проверяет повторным чтением и переходит к более сложным действиям. Подробнее в разделе Complex inputs. Требует: browserId, windowId, tabId, readablePath. Возвращает: ok=true при успехе; при ok=false повторно читает readable-elements и выбирает новый путь. Избегает: выдумывания путей; повторно читает элементы после навигации, если клик не удался.

Close tab

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

Fill text at coordinates

Нажимает в точке (x, y), затем вводит текст в активное поле ввода. Когда: резервный вариант для MV2 для полей ввода без readablePath. Как: координаты из последнего captureTab; отправляет через clickOnCoordinates на кнопку отправки или hitEnterOnCoordinates. Требует: browserId, windowId, tabId, x, y, value. Возвращает: ok=true при успехе; при ok=false — повторно захватывает вкладку и пересчитывает x/y. Избегайте: на MV3; предпочитайте fillTextToElement, когда доступен readablePath.

Fill text into element

Вводит текст в <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 на кнопке отправки или hitEnterOnElement. Требует: browserId, windowId, tabId, readablePath, value. Возвращает: ok=true при успехе; при ok=false — повторно читает readable-elements и выбирает новый путь. Избегайте: CSS-селекторы в качестве readablePath; устаревшие пути после изменений DOM. Не работает в contenteditable-редакторах форматированного текста (в MV2 используйте invokeJsFn вместо этого), нативных <select> или пользовательских выпадающих списках/выборах даты — используйте лестницу стратегий в разделе Complex inputs в инструкциях сервера.

Get browser context

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

Get readable element HTML

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

Get readable elements

Получает интерактивные элементы вкладки в виде кортежей [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 — это древовидный индекс, разделённый точками (например, 0.2.1). Используется как readablePath в инструментах взаимодействия. Пагинация: если hasNextPage равен true, вызывается getSnapshotPage с полученными snapshotId и nextPageNumber.

Get readable text

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

Get text selection

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

Get snapshot page

Получает страницу продолжения для снимка 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.

Hit enter at coordinates

Кликает по (x, y) и нажимает Enter для отправки формы. Когда: запасной вариант для MV2 для отправки, если не существует readablePath кнопки отправки. Как: координаты из последнего captureTab. Требует: browserId, windowId, tabId, x, y. Возвращает: ok=true при успехе; при ok=false повторно захватывает вкладку и пересчитывает x/y. Не использовать на MV3; предпочтительнее hitEnterOnElement, когда readablePath доступен.

Hit enter on element

Фокусируется на элементе по readablePath, затем нажимает Enter. Когда: при отправке формы, если нет явной кнопки отправки. Как: readablePath из кортежа readable-elements (индекс через точку, например 0.2.1). Требуется: browserId, windowId, tabId, readablePath. Возвращает: ok=true при успехе; при ok=false повторно читает readable-elements и выбирает новый путь. Избегайте: использования, когда доступен readablePath кнопки отправки — вместо этого нажмите на неё.

Invoke JavaScript function

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

Open tab

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

Scroll an element

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

Scroll the page

Прокручивает область просмотра страницы в заданном направлении. Когда: целевой контент или элементы находятся за пределами экрана; покажите больше страницы перед чтением или взаимодействием. Работает в MV2 и MV3 (скриншот не требуется). Как: направление - up/down/left/right; необязательное количество пикселей - опустите его для прокрутки примерно на один viewport (страницу). browserId, windowId, tabId из bk:///context. Требуется: browserId, windowId, tabId, direction. Возвращает: ok=true после прокрутки. Если уже достигнут край (прокручивать нечего), всё равно возвращается ok=true. Избегайте: предполагать, что появились новые элементы - после прокрутки заново читайте readable-elements, снимки устаревают.

Show human hint

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