MCP Appium-сервер

Реализация сервера Model Context Protocol (MCP) для автоматизации мобильных приложений с использованием Appium.

Предпосылки

Node.js (v14 или выше)
Комплект разработчика Java (JDK)
Android SDK (для тестирования Android)
Xcode (для тестирования iOS, только macOS)
Сервер Appium
Устройство Android или эмулятор / Устройство iOS или симулятор

Related MCP server: DroidMind

Настройка среды

Перед выполнением любых команд убедитесь, что переменные среды настроены правильно:

Убедитесь, что ваш .bash_profile , .zshrc или другой файл конфигурации оболочки содержит необходимые переменные среды:

# Example environment variables in ~/.bash_profile export JAVA_HOME=/path/to/your/java export ANDROID_HOME=/path/to/your/android/sdk export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

Перед запуском MCP-Appium создайте файл среды:

source ~/.bash_profile # For bash # OR source ~/.zshrc # For zsh

Примечание : система попытается автоматически получить ваш .bash_profile при инициализации драйвера, но рекомендуется вручную убедиться в правильности настройки среды перед запуском тестов в новом сеансе терминала.

Конфигурация инструментов командной строки Xcode

Для тестирования iOS необходима правильная настройка инструментов командной строки Xcode:

Установите инструменты командной строки Xcode, если они еще не установлены:

xcode-select --install

Проверьте установку и текущий путь Xcode:

xcode-select -p

При необходимости укажите правильный путь Xcode (особенно если у вас несколько версий Xcode):

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Примите лицензионные соглашения Xcode:

sudo xcodebuild -license accept

Для тестирования на реальном устройстве iOS убедитесь, что ваша учетная запись разработчика Apple правильно настроена в Xcode:
- Открыть X-код
- Перейдите в Настройки > Учетные записи.
- Добавьте свой Apple ID, если вы еще этого не сделали.
- Загрузите необходимые профили обеспечения
Настройте переменные среды для разработки iOS:

# Add these to your ~/.bash_profile or ~/.zshrc export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer" export PATH="$DEVELOPER_DIR/usr/bin:$PATH"

Источник вашей обновленной конфигурации:

source ~/.bash_profile # For bash # OR source ~/.zshrc # For zsh

Настраивать

Установить зависимости:

npm install

Установите и запустите сервер Appium:

npm install -g appium appium

Настройте Android-устройство/эмулятор:
- Включите параметры разработчика на вашем Android-устройстве
- Включить отладку по USB
- Подключите устройство через USB или запустите эмулятор
- Проверьте, подключено ли устройство с помощью adb devices
Для тестирования iOS (только macOS):
- Убедитесь, что установлены инструменты командной строки Xcode: xcode-select --install
- Настройте симулятор iOS или подключите реальное устройство
- Доверяйте компьютеру разработчика на устройстве iOS, если используете реальное устройство

Проведение тестов

Создайте проект:

npm run build

Запустите MCP-сервер:

npm run dev

В новом терминале запустите тест:

npm test

Тестовая конфигурация

Конфигурация Android

В примере теста в качестве демо используется приложение Android Settings. Чтобы протестировать собственное приложение:

Отредактируйте examples/appium-test.ts :
- Обновите deviceName , чтобы он соответствовал вашему устройству.
- Укажите путь app в вашем APK-файле или
- Обновление appPackage и appActivity для установленного приложения
Конфигурация общих возможностей:

const capabilities: AppiumCapabilities = { platformName: "Android", deviceName: "YOUR_DEVICE_NAME", automationName: "UiAutomator2", // For installing and testing an APK: app: "./path/to/your/app.apk", // OR for testing an installed app: appPackage: "your.app.package", appActivity: ".MainActivity", noReset: true, };

Конфигурация iOS

Для тестирования iOS с использованием новой поддержки командной строки Xcode:

Пример конфигурации в examples/xcode-appium-example.ts :

const capabilities: AppiumCapabilities = { platformName: "iOS", deviceName: "iPhone 13", // Your simulator or device name automationName: "XCUITest", udid: "DEVICE_UDID", // Get this from XcodeCommands.getIosSimulators() // For installing and testing an app: app: "./path/to/your/app.app", // OR for testing an installed app: bundleId: "com.your.app", noReset: true, };

Доступные действия

Сервер MCP поддерживает различные действия Appium:

Взаимодействие элементов:
- Найти элементы
- Элементы касания/щелчка с API действий W3C (см. раздел «Стандартные жесты W3C»)
- Введите текст
- Прокрутите до элемента с помощью W3C Actions API
- Длительное нажатие
Управление приложениями:
- Запустить/закрыть приложение
- Сбросить приложение
- Получить текущий пакет/активность
Элементы управления устройством:
- Ориентация экрана
- Управление клавиатурой
- Блокировка/разблокировка устройства
- Скриншоты
- Информация о батарее
Расширенные возможности:
- Переключение контекста (Native/WebView)
- Операции с файлами
- Уведомления
- Пользовательские жесты
Инструменты командной строки Xcode (только для iOS):
- Управление симуляторами iOS (загрузка, выключение)
- Установка/удаление приложений на симуляторах
- Запуск/завершение работы приложений
- Делайте скриншоты
- Запись видео
- Создать/удалить симуляторы
- Получить типы устройств и время выполнения

Стандартные жесты W3C

Библиотека MCP-Appium теперь реализует API W3C WebDriver Actions для сенсорных жестов, что является современным стандартом мобильной автоматизации.

Действия W3C для элементов Tap

Метод tapElement теперь использует API действий W3C с интеллектуальными резервными вариантами:

// The method will try in this order: // 1. Standard WebdriverIO click() // 2. W3C Actions API // 3. Legacy TouchAction API (fallback for backward compatibility) await appium.tapElement("//android.widget.Button[@text='OK']"); // or using the click alias await appium.click("//android.widget.Button[@text='OK']");

Действия W3C для прокрутки

Метод scrollToElement теперь использует API действий W3C:

// Uses W3C Actions API for more reliable scrolling await appium.scrollToElement( "//android.widget.TextView[@text='About phone']", // selector "down", // direction: "up", "down", "left", "right" "xpath", // strategy 10 // maxScrolls );

Пользовательские жесты W3C

Вы можете создать свои собственные жесты W3C, используя метод executeMobileCommand :

// Create custom W3C Actions API gesture const w3cActions = { actions: [ { type: "pointer", id: "finger1", parameters: { pointerType: "touch" }, actions: [ // Move to start position { type: "pointerMove", duration: 0, x: startX, y: startY }, // Press down { type: "pointerDown", button: 0 }, // Move to end position over duration milliseconds { type: "pointerMove", duration: duration, origin: "viewport", x: endX, y: endY, }, // Release { type: "pointerUp", button: 0 }, ], }, ], }; // Execute the W3C Actions using executeScript await appium.executeMobileCommand("performActions", [w3cActions.actions]);

Дополнительные примеры реализации жестов стандарта W3C см. в examples/w3c-actions-swipe-demo.ts

Использование инструментов командной строки Xcode

Новый класс XcodeCommands предоставляет мощные инструменты для тестирования iOS:

import { XcodeCommands } from "../src/lib/xcode/xcodeCommands.js"; // Check if Xcode CLI tools are installed const isInstalled = await XcodeCommands.isXcodeCliInstalled(); // Get available simulators const simulators = await XcodeCommands.getIosSimulators(); // Boot a simulator await XcodeCommands.bootSimulator("SIMULATOR_UDID"); // Install an app await XcodeCommands.installApp("SIMULATOR_UDID", "/path/to/app.app"); // Launch an app await XcodeCommands.launchApp("SIMULATOR_UDID", "com.example.app"); // Take a screenshot await XcodeCommands.takeScreenshot("SIMULATOR_UDID", "/path/to/output.png"); // Shutdown a simulator await XcodeCommands.shutdownSimulator("SIMULATOR_UDID");

Использование функции щелчка

Метод click() представляет собой более интуитивно понятную альтернативу tapElement() :

// Using the click method await appium.click("//android.widget.Button[@text='OK']"); // This is equivalent to: await appium.tapElement("//android.widget.Button[@text='OK']");

Поиск неисправностей

Устройство не найдено:
- Проверьте вывод adb devices
- Убедитесь, что отладка по USB включена.
- Попробуйте переподключить устройство.
Приложение не устанавливается:
- Проверьте правильность пути APK
- Проверьте, достаточно ли на устройстве памяти.
- Убедитесь, что приложение подписано для отладки
Элементы не найдены:
- Используйте Appium Inspector для проверки селекторов
- Проверьте, видны ли элементы на экране.
- Попробуйте разные стратегии поиска
Проблемы с подключением:
- Убедитесь, что сервер Appium запущен
- Проверьте конфликты портов
- Убедитесь, что установлены правильные возможности
Проблемы с симулятором iOS:
- Проверьте, установлены ли инструменты командной строки Xcode: xcode-select -p
- Проверьте правильность UDID симулятора с помощью xcrun simctl list devices
- Закройте и перезапустите симулятор, если он перестанет отвечать.

Внося вклад

Не стесняйтесь сообщать о проблемах и отправлять запросы на дополнительные функции или исправления ошибок.

Лицензия

Массачусетский технологический институт

MCP Appium Server