MCP Appium-сервер

Name: MCP Appium Server
Author: Rahulec08

Реализация сервера 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