Раннер как MCP-сервер — дайте своему ИИ-агенту браузер

Любой агент, говорящий по MCP — Claude Code, Cursor, ваш собственный агент на
SDK — может управлять раннером Mockarty напрямую: открывать страницы, читать их,
кликать, вводить текст, делать скриншоты и управлять подключённым
Android-телефоном.

Браузерным инструментам не нужен сервер Mockarty, аккаунт или лицензионный
ключ. Скачайте раннер, запустите в режиме MCP, подключите агента — этой
поверхностью можно пользоваться где угодно, как альтернативой полноценному
стеку браузерной автоматизации.

Управление устройствами и остальные механики тестирования — часть платформы:
они появляются только после рукопожатия раннера с сервером Mockarty
(COORDINATOR_URL + API_TOKEN, на сборке с лицензионным ключом Mockarty).
Неспаренный раннер их вообще не показывает — вы всегда видите ровно те
инструменты, которые сработают.

Зачем это агенту

Полноценный браузер стоит 50–150 МБ на инстанс и медленно стартует. Раннер
использует лёгкий headless-движок: сотни параллельных сессий помещаются на
скромной машине, а страницы возвращаются текстом или markdown — именно тем,
что модель реально читает, без лишнего круга со скриншотами.

Запуск

# stdio — транспорт, который локальные MCP-клиенты запускают сами
mockarty-runner mcp

# или по сети (нужен токен)
MOCKARTY_RUNNER_MCP_TOKEN=ваш-секрет mockarty-runner mcp --http 127.0.0.1:9800

Подключите MCP-клиент. Для Claude Code — в .mcp.json:

{
  "mcpServers": {
    "mockarty-runner": {
      "command": "mockarty-runner",
      "args": ["mcp"]
    }
  }
}

Через HTTP:

{
  "mcpServers": {
    "mockarty-runner": {
      "type": "http",
      "url": "http://127.0.0.1:9800/mcp",
      "headers": { "X-API-Key": "ваш-секрет" }
    }
  }
}

Инструменты

Сначала вызовите runner_info — он расскажет, что умеет эта машина (браузерный
движок, подключённые устройства, платформа), чтобы агент не гадал.

Мобильные инструменты (для спаренных раннеров)

Когда раннер подключён к серверу Mockarty И к нему подключено Android-устройство
(adb в PATH, отладка по USB включена), появляется мобильная поверхность —
всё, что нужно агенту для управления телефоном, без установки Appium:

runner_info сообщает, в каком вы режиме, и — в публичном — как разблокировать
остальное.

Мобильный сценарий

device_app     {"deviceId":"…","action":"launch","package":"com.example.app"}
device_wait_for{"deviceId":"…","text":"Вход"}
device_source  {"deviceId":"…"}              → ref=5 Button "Подключиться" @541,750
device_tap     {"deviceId":"…","ref":5}
device_assert  {"deviceId":"…","kind":"text_contains","expected":"Готово"}

Тап по ref, а не по пикселям, — именно это позволяет сценарию пережить другой
размер экрана и делает историю прогона читаемой.

Рабочий цикл

browser_open     {"url": "https://example.com"}          → sessionId
browser_snapshot {"sessionId": "s1"}                     → ref=2 textbox "Username", ref=1 button "Sign in"
browser_act      {"sessionId": "s1", "ref": 2, "kind": "fill", "value": "demo"}
browser_act      {"sessionId": "s1", "ref": 1}           → клик
browser_wait_for {"sessionId": "s1", "text": "Welcome"}  → дождаться асинхронного результата
browser_read     {"sessionId": "s1", "mode": "markdown"} → проверить
browser_close    {"sessionId": "s1"}

Используйте одну сессию на весь сценарий. browser_snapshot показывает, что
можно нажать; browser_read — что страница говорит. Действие по ref надёжнее
рукописного CSS-селектора и переживает перерисовки. После асинхронных действий —
browser_wait_for, а не опрос чтением.

Когда сценарий устоялся, оберните его в browser_case — прогон как один
повторяемый тест с единым вердиктом PASS/FAIL, как нужно CI:

browser_case {"url": "https://app/login", "steps": "[
  {\"do\":\"fill_form\",\"fields\":[{\"selector\":\"#user\",\"value\":\"demo\"}],\"submit\":\"button[type=submit]\"},
  {\"do\":\"wait\",\"text\":\"Welcome\"},
  {\"do\":\"assert\",\"kind\":\"text_contains\",\"expected\":\"Welcome, demo\"}
]"}
→ CASE PASSED (3/3 steps)     (или CASE FAILED at step N — останавливается там)

Чтобы прогнать кейс за логином одним вызовом, передайте storageState (JSON,
который вернул предыдущий browser_storage_state) вместе с url — свежая сессия
стартует уже аутентифицированной, и весь кейс идёт залогиненным без шага логина.
Требует движок Chromium (лёгкий движок не восстанавливает сохранённое состояние).

Типы шагов кейса: goto (переход), back/forward/reload (история навигации), act (click/fill/press по селектору или
ref), select (выбрать values в <select>), check (поставить галку —
checked по умолчанию true; передайте false, чтобы снять), key (клавиша —
Enter/Escape/Tab/ArrowDown), hover (навести указатель на селектор/ref —
раскрывает hover-меню), drag (перетащить источник селектор/ref на цель
to/toRef), resize (задать вьюпорт width×height — тестирование
адаптивности на любом разрешении), upload (прикрепить files с диска раннера
к file-<input> — по сетевому транспорту нужен RUNNER_MCP_UPLOAD_DIR),
fill_form (целая форма, опциональный
submit-селектор или submitRef), wait (ждать text/selector/gone, опциональный ms) и assert
(text_contains/text_matches/text_absent/visible/hidden/value/count/url_contains/title_contains/attribute/checked/enabled/disabled). Этого хватает на реальную форму —
включая выпадающие списки и чекбоксы — одним вызовом.

Разбор странного поведения страницы: browser_capture → воспроизвести →
browser_console и browser_network.

Чего он не сделает

• Только http и https. file:// и прочие схемы отклоняются, поэтому
  чтение страницы никогда не превратится в чтение локальных файлов.
• Адреса проверяются. Метаданные облака и некорректные хосты отклоняются.
  Если вы намеренно тестируете такой адрес — MOCKARTY_VIEW_ALLOW_ANY_TARGET=1.
  Переключатель один и снимает ту же проверку для каждого браузера, которым
  управляет Mockarty, — включая UI-тесты и интерактивные сессии, а не только
  для этого.
• Платформенные инструменты без рукопожатия не появятся. Устройства и
  механики тестирования бэкенда — это возможности Mockarty; публичная
  поверхность — браузер.
• HTTP-транспорт требует токен. Эти инструменты управляют настоящим
  браузером на вашей машине, поэтому без токена сетевой режим не стартует.
• Относитесь к токену как к доступу к шеллу. Держатель токена может навести
  браузер на любой http(s)-адрес, достижимый с вашей машины, прочитать то, что
  рендерит любая страница, и приложить любой локальный файл, доступный процессу
  раннера (browser_upload), к странице. Привязывайте --http к loopback
  (127.0.0.1) или доверенной сети и выдавайте токен только агентам, которым
  доверяете так же, как доверили бы шелл на этой машине.

Параметры

Какой движок браузера

По умолчанию сервер работает на полном Chromium. Он открывает https://
на любой машине, а сам браузер скачивается автоматически при первом открытии
страницы — ставить руками ничего не нужно.

RUNNER_MCP_ENGINE=light переключает на лёгкий движок: он держит гораздо
больше параллельных сессий при той же памяти — это удобно для массовых
скриптовых прогонов. Для открытия https:// ему нужно хранилище сертификатов
хоста, поэтому используйте его на сервере, где оно есть, а не на ноутбуке.
servo-ядро рендера лёгкого движка меняет размер окна на каждый скриншот, поэтому
смена viewport между кадрами (browser_resize перед снимком, разные viewport)
действует на обоих движках — тест может снимать одну сессию в нескольких
разрешениях на любом из них.

Изолированная среда: раннер с движками внутри

Обычная сборка скачивает движок браузера при первом обращении. В изолированном
контуре скачивать неоткуда, поэтому раннер можно собрать самодостаточным:
лёгкие движки запекаются в бинарь и распаковываются при первом использовании.
Один файл, ноль сети, работает за air gap.

GOOS=linux GOARCH=amd64 bash scripts/fetch-engines.sh   # один раз скачать движки
go build -tags embedengines -o mockarty-runner ./cmd/mockarty-runner

На выходе — единый бинарь (~270 МБ, движки внутри), который выполняет
browser_* вообще без скачиваний. Без тега получится «лёгкая» сборка (~70 МБ),
которая догружает движки по требованию — это правильный выбор, когда на машине
есть интернет.

Настоящие браузеры Playwright (Chromium/Firefox/WebKit) остаются отдельной
подключаемой историей — они не запекаются никогда. Либо укажите раннеру заранее
установленный браузер, либо пропишите пути к заранее положенным файлам движков
через RUNNER_LIGHTPANDA_PATH / RUNNER_SERVO_PATH.

Что дальше

Тот же раннер может войти в грид Mockarty (COORDINATOR_URL + API_TOKEN) и
выполнять UI-, нагрузочные, фаззинг- и мобильные тесты, приходящие с платформы,
с отчётами, историей и гридом устройств. См. Браузерный
раннер и Метки раннеров.