MCP (Протокол Контексту Моделі)

Що він може робити?

WebdriverIO MCP — це сервер Протоколу Контексту Моделі (MCP), який дозволяє ШІ-асистентам, таким як Claude Desktop і Claude Code, автоматизувати та взаємодіяти з веб-браузерами та мобільними додатками.

Чому WebdriverIO MCP?

• Mobile-First: На відміну від MCP-серверів, що працюють лише з браузерами, WebdriverIO MCP підтримує автоматизацію нативних додатків для iOS та Android через Appium
• Крос-платформні селектори: Розумне виявлення елементів автоматично генерує кілька стратегій пошуку (accessibility ID, XPath, UiAutomator, предикати iOS)
• Екосистема WebdriverIO: Побудований на перевіреному фреймворку WebdriverIO з його багатою екосистемою сервісів і репортерів

Він забезпечує уніфікований інтерфейс для:

• 🖥️ Десктопних браузерів (Chrome — у звичайному або безголовому режимі)
• 📱 Нативних мобільних додатків (Симулятори iOS / Емулятори Android / Реальні пристрої через Appium)
• 📳 Гібридних мобільних додатків (перемикання контексту Nativе + WebView через Appium)

через пакет @wdio/mcp.

Це дозволяє ШІ-асистентам:

• Запускати та керувати браузерами з налаштовуваними розмірами, безголовим режимом та опціональною початковою навігацією
• Навігувати по веб-сайтам та взаємодіяти з елементами (клікати, вводити текст, прокручувати)
• Аналізувати вміст сторінки через дерево доступності та виявлення видимих елементів з підтримкою пагінації
• Робити знімки екрана автоматично оптимізовані (змінений розмір, стиснуті до максимум 1МБ)
• Керувати cookies для обробки сесій
• Керувати мобільними пристроями, включаючи жести (натискання, свайп, перетягування)
• Перемикати контексти в гібридних додатках між нативним та webview
• Виконувати скрипти — JavaScript у браузерах, мобільні команди Appium на пристроях
• Керувати функціями пристрою, такими як поворот, клавіатура, геолокація
• і багато іншого, дивіться опції Інструментів та Конфігурації

інфо

ПРИМІТКА Для мобільних додатків Мобільна автоматизація вимагає запущеного сервера Appium з встановленими відповідними драйверами. Див. Передумови для інструкцій з налаштування.

Встановлення

Найпростіший спосіб використовувати @wdio/mcp — це через npx без локального встановлення:

npx @wdio/mcp

Або встановіть його глобально:

npm install -g @wdio/mcp

Використання з Claude

Щоб використовувати WebdriverIO MCP з Claude, змініть файл конфігурації:

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"]
        }
    }
}

Після додавання конфігурації перезапустіть Claude. Інструменти WebdriverIO MCP будуть доступні для задач автоматизації браузера та мобільних пристроїв.

Використання з Claude Code

Claude Code автоматично виявляє MCP-сервери. Ви можете налаштувати його в файлі .claude/settings.json або .mcp.json вашого проекту.

Або додати його глобально до .claude.json, виконавши:

claude mcp add --transport stdio wdio-mcp -- npx -y @wdio/mcp

Перевірте його, запустивши команду /mcp в claude code.

Приклади швидкого старту

Автоматизація браузера

Попросіть Claude автоматизувати задачі у браузері:

"Відкрий Chrome і перейди на https://webdriver.io"
"Натисни кнопку 'Get Started'"
"Зроби знімок екрана сторінки"
"Знайди всі видимі посилання на сторінці"

Автоматизація мобільних додатків

Попросіть Claude автоматизувати мобільні додатки:

"Запусти мій iOS-додаток на симуляторі iPhone 15"
"Натисни кнопку входу"
"Зроби свайп вгору, щоб прокрутити вниз"
"Зроби знімок поточного екрана"

Можливості

Автоматизація браузера (Chrome)

Функція	Опис
Керування сесіями	Запуск Chrome у звичайному/безголовому режимі з власними розмірами та опціональним URL для навігації
Навігація	Перехід за URL
Взаємодія з елементами	Клік на елементах, введення тексту, пошук елементів за різними селекторами
Аналіз сторінки	Отримання видимих елементів (з пагінацією), дерева доступності (з фільтрацією)
Знімки екрана	Захоплення знімків екрана (автоматично оптимізованих до макс. 1МБ)
Прокрутка	Прокрутка вгору/вниз на налаштовувану кількість пікселів
Керування cookies	Отримання, встановлення та видалення cookies
Виконання скриптів	Виконання власного JavaScript у контексті браузера

Автоматизація мобільних додатків (iOS/Android)

Функція	Опис
Керування сесіями	Запуск додатків на симуляторах, емуляторах або реальних пристроях
Жести дотику	Натискання, свайп, перетягування
Виявлення елементів	Розумне виявлення елементів з кількома стратегіями пошуку та пагінацією
Життєвий цикл додатку	Отримання стану додатку (через execute_script для активації/завершення)
Перемикання контексту	Перемикання між нативним та webview контекстами в гібридних додатках
Керування пристроєм	Поворот пристрою, керування клавіатурою
Геолокація	Отримання та встановлення GPS-координат пристрою
Дозволи	Автоматична обробка дозволів та сповіщень
Виконання скриптів	Виконання мобільних команд Appium (pressKey, deepLink, shell, тощо)

Передумови

Автоматизація браузера

• Chrome має бути встановлений у вашій системі
• WebdriverIO керує автоматизованим управлінням ChromeDriver

Мобільна автоматизація

iOS

1. Встановіть Xcode з Mac App Store
2. Встановіть інструменти командного рядка Xcode:

   xcode-select --install

3. Встановіть Appium:

   npm install -g appium

4. Встановіть драйвер XCUITest:

   appium driver install xcuitest

5. Запустіть сервер Appium:

   appium

6. Для симуляторів: Відкрийте Xcode → Window → Devices and Simulators для створення/керування симуляторами
7. Для реальних пристроїв: Вам знадобиться UDID пристрою (40-символьний унікальний ідентифікатор)

Android

1. Встановіть Android Studio і налаштуйте Android SDK
2. Встановіть змінні середовища:

   export ANDROID_HOME=$HOME/Library/Android/sdk
   export PATH=$PATH:$ANDROID_HOME/emulator
   export PATH=$PATH:$ANDROID_HOME/platform-tools

3. Встановіть Appium:

   npm install -g appium

4. Встановіть драйвер UiAutomator2:

   appium driver install uiautomator2

5. Запустіть сервер Appium:

   appium

6. Створіть емулятор через Android Studio → Virtual Device Manager
7. Запустіть емулятор перед запуском тестів

Архітектура

Як це працює

WebdriverIO MCP виступає мостом між ШІ-асистентами та автоматизацією браузера/мобільних пристроїв:

┌─────────────────┐     MCP Protocol      ┌─────────────────┐
│  Claude Desktop │ ◄──────────────────►  │    @wdio/mcp    │
│  or Claude Code │      (stdio)          │     Server      │
└─────────────────┘                       └────────┬────────┘
                                                   │
                                             WebDriverIO API
                                                   │
                    ┌──────────────────────────────┼──────────────────────────────┐
                    │                              │                              │
            ┌───────▼───────┐             ┌───────▼───────┐             ┌───────▼───────┐
            │    Chrome     │             │    Appium     │             │    Appium     │
            │   (Browser)   │             │     (iOS)     │             │   (Android)   │
            └───────────────┘             └───────────────┘             └───────────────┘

Керування сесіями

• Модель з однією сесією: Одночасно може бути активна лише одна сесія браузера АБО додатку
• Стан сесії підтримується глобально для всіх викликів інструментів
• Автовід'єднання: Сесії зі збереженим станом (noReset: true) автоматично від'єднуються при закритті

Виявлення елементів

Браузер (Веб)

• Використовує оптимізований скрипт браузера для пошуку всіх видимих, інтерактивних елементів
• Повертає елементи з CSS-селекторами, ID, класами та ARIA-інформацією
• За замовчуванням фільтрує видимі у області перегляду елементи

Мобільні (Нативні додатки)

• Використовує ефективний аналіз XML-джерела сторінки (2 HTTP-запити замість 600+ для традиційних запитів)
• Платформозалежна класифікація елементів для Android та iOS
• Генерує кілька стратегій локації для кожного елемента:
  • Accessibility ID (крос-платформний, найстабільніший)
  • Resource ID / атрибут Name
  • Відповідність тексту / мітки
  • XPath (повний та спрощений)
  • UiAutomator (Android) / Predicates (iOS)

Синтаксис селекторів

MCP-сервер підтримує кілька стратегій селекторів. Див. Селектори для детальної документації.

Веб (CSS/XPath)

# CSS-селектори
button.my-class
#element-id
[data-testid="login"]

# XPath
//button[@class='submit']
//a[contains(text(), 'Click')]

# Текстові селектори (специфічні для WebdriverIO)
button=Exact Button Text
a*=Partial Link Text

Мобільні (Крос-платформні)

# Accessibility ID (рекомендовано - працює на iOS і Android)
~loginButton

# Android UiAutomator
android=new UiSelector().text("Login")

# Предикатний рядок iOS
-ios predicate string:label == "Login"

# Ланцюжок класів iOS
-ios class chain:**/XCUIElementTypeButton[`label == "Login"`]

# XPath (працює на обох платформах)
//android.widget.Button[@text="Login"]
//XCUIElementTypeButton[@label="Login"]

Доступні інструменти

MCP-сервер надає 25 інструментів для автоматизації браузера та мобільних пристроїв. Див. Інструменти для повного довідника.

Інструменти браузера

Інструмент	Опис
start_browser	Запуск браузера Chrome (з опціональним початковим URL)
close_session	Закриття або від'єднання від сесії
navigate	Навігація за URL
click_element	Клік на елементі
set_value	Введення тексту у поле вводу
get_visible_elements	Отримання видимих/інтерактивних елементів (з пагінацією)
get_accessibility	Отримання дерева доступності (з фільтрацією)
take_screenshot	Захоплення знімку екрана (автооптимізованого)
scroll	Прокрутка сторінки вгору або вниз
get_cookies / set_cookie / delete_cookies	Керування cookies
execute_script	Виконання JavaScript у контексті браузера

Мобільні інструменти

Інструмент	Опис
start_app_session	Запуск додатку iOS/Android
tap_element	Натискання на елемент або координати
swipe	Свайп у певному напрямку
drag_and_drop	Перетягування між локаціями
get_app_state	Перевірка, чи додаток запущений
get_contexts / switch_context	Перемикання контексту гібридного додатку
rotate_device	Поворот у портретний/ландшафтний режим
get_geolocation / set_geolocation	Отримання або встановлення GPS-координат
hide_keyboard	Приховування екранної клавіатури
execute_script	Виконання мобільних команд Appium

Автоматична обробка

Дозволи

За замовчуванням MCP-сервер автоматично надає дозволи додаткам (autoGrantPermissions: true), усуваючи необхідність вручну обробляти діалогові вікна дозволів під час автоматизації.

Системні сповіщення

Системні сповіщення (наприклад, "Дозволити сповіщення?") автоматично приймаються за замовчуванням (autoAcceptAlerts: true). Це можна налаштувати для відхилення замість цього за допомогою autoDismissAlerts: true.

Конфігурація

Змінні середовища

Налаштуйте з'єднання з сервером Appium:

Змінна	За замовчуванням	Опис
APPIUM_URL	127.0.0.1	Ім'я хоста сервера Appium
APPIUM_URL_PORT	4723	Порт сервера Appium
APPIUM_PATH	/	Шлях сервера Appium

Приклад із власним сервером Appium

{
    "mcpServers": {
        "wdio-mcp": {
            "command": "npx",
            "args": ["-y", "@wdio/mcp"],
            "env": {
                "APPIUM_URL": "192.168.1.100",
                "APPIUM_URL_PORT": "4724"
            }
        }
    }
}

Оптимізація продуктивності

MCP-сервер оптимізовано для ефективного спілкування з ШІ-асистентом:

• Формат TOON: Використовує Token-Oriented Object Notation для мінімального використання токенів
• Аналіз XML: Виявлення мобільних елементів використовує 2 HTTP-запити (проти 600+ традиційно)
• Стиснення знімків екрана: Зображення автоматично стискаються до макс. 1МБ за допомогою Sharp
• Фільтрація області перегляду: За замовчуванням повертаються лише видимі елементи
• Пагінація: Великі списки елементів можуть бути розбиті на сторінки для зменшення розміру відповіді

Підтримка TypeScript

MCP-сервер написаний на TypeScript і включає повні визначення типів. Якщо ви розширюєте або інтегруєтеся з сервером програмно, ви отримаєте вигоду від автодоповнення та типової безпеки.

Обробка помилок

Усі інструменти розроблені з надійною обробкою помилок:

• Помилки повертаються як текстовий вміст (ніколи не викидаються), зберігаючи стабільність протоколу MCP
• Описові повідомлення про помилки допомагають діагностувати проблеми
• Стан сесії зберігається навіть при збоях окремих операцій

Варіанти використання

Забезпечення якості

• Виконання тестових випадків за допомогою ШІ
• Візуальне регресійне тестування зі знімками екрана
• Аудит доступності через аналіз дерева доступності

Веб-скрапінг та видобуток даних

• Навігація по складних багатосторінкових потоках
• Видобуток структурованих даних з динамічного контенту
• Обробка автентифікації та керування сесіями

Тестування мобільних додатків

• Крос-платформна автоматизація тестування (iOS + Android)
• Валідація процесу онбордингу
• Тестування глибоких посилань та навігації

Інтеграційне тестування

• Наскрізне тестування робочих процесів
• Перевірка інтеграції API + UI
• Перевірка узгодженості між платформами

Вирішення проблем

Браузер не запускається

• Переконайтеся, що Chrome встановлений
• Перевірте, що жоден інший процес не використовує порт відладки за замовчуванням (9222)
• Спробуйте безголовий режим, якщо виникають проблеми з відображенням

Збій підключення до Appium

• Переконайтеся, що сервер Appium запущений (appium)
• Перевірте конфігурацію URL та порту Appium
• Переконайтеся, що відповідний драйвер встановлено (appium driver list)

Проблеми з iOS Simulator

• Переконайтеся, що Xcode встановлено та оновлено
• Перевірте, що симулятори доступні (xcrun simctl list devices)
• Для реальних пристроїв перевірте правильність UDID

Проблеми з емулятором Android

• Переконайтеся, що Android SDK правильно налаштовано
• Перевірте, що емулятор запущений (adb devices)
• Перевірте, що змінна середовища ANDROID_HOME встановлена

Ресурси

• Довідник інструментів - Повний список доступних інструментів
• Посібник з селекторів - Документація з синтаксису селекторів
• Конфігурація - Опції конфігурації
• FAQ - Часті запитання
• GitHub репозиторій - Вихідний код та проблеми
• NPM пакет - Пакет на npm
• Model Context Protocol - Специфікація MCP