MCP Appium Server

Eine Model Context Protocol (MCP)-Serverimplementierung für die Automatisierung mobiler Apps mit Appium.

Voraussetzungen

1. Node.js (v14 oder höher)

2. Java Development Kit (JDK)

3. Android SDK (zum Testen von Android)

4. Xcode (für iOS-Tests, nur macOS)

5. Appium Server

6. Android-Gerät oder -Emulator / iOS-Gerät oder -Simulator

Related MCP server: DroidMind

Umgebungs-Setup

Stellen Sie vor der Ausführung von Befehlen sicher, dass Ihre Umgebungsvariablen richtig eingerichtet sind:

1. Stellen Sie sicher, dass Ihre .bash_profile , .zshrc oder andere Shell-Konfigurationsdatei die erforderlichen Umgebungsvariablen enthält:

# 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

2. Geben Sie Ihre Umgebungsdatei als Quelle ein, bevor Sie MCP-Appium ausführen:

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

Hinweis : Das System versucht beim Initialisieren des Treibers automatisch, Ihr .bash_profile zu beziehen. Es wird jedoch empfohlen, vor dem Ausführen von Tests in einer neuen Terminalsitzung manuell für eine ordnungsgemäße Umgebungseinrichtung zu sorgen.

Konfiguration der Xcode-Befehlszeilentools

Für iOS-Tests ist die richtige Konfiguration der Xcode-Befehlszeilentools unerlässlich:

1. Installieren Sie die Xcode-Befehlszeilentools, falls sie noch nicht installiert sind:

xcode-select --install

2. Überprüfen Sie die Installation und prüfen Sie den aktuellen Xcode-Pfad:

xcode-select -p

3. Legen Sie bei Bedarf den richtigen Xcode-Pfad fest (insbesondere, wenn Sie mehrere Xcode-Versionen haben):

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

4. Akzeptieren Sie die Xcode-Lizenzvereinbarungen:

sudo xcodebuild -license accept

5. Stellen Sie zum Testen von iOS-Geräten sicher, dass Ihr Apple-Entwicklerkonto in Xcode richtig konfiguriert ist:

   • Öffnen Sie Xcode

   • Gehen Sie zu Einstellungen > Konten

   • Fügen Sie Ihre Apple-ID hinzu, falls sie noch nicht hinzugefügt wurde

   • Laden Sie die erforderlichen Bereitstellungsprofile herunter

6. Richten Sie Umgebungsvariablen für die iOS-Entwicklung ein:

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

7. Quelle Ihrer aktualisierten Konfiguration:

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

Aufstellen

1. Installieren Sie Abhängigkeiten:

npm install

2. Installieren und starten Sie den Appium-Server:

npm install -g appium
appium

3. Android-Gerät/Emulator einrichten:

   • Aktivieren Sie die Entwickleroptionen auf Ihrem Android-Gerät

   • USB-Debugging aktivieren

   • Gerät per USB verbinden oder einen Emulator starten

   • Überprüfen Sie, ob das Gerät mit adb devices verbunden ist

4. Für iOS-Tests (nur macOS):

   • Stellen Sie sicher, dass die Xcode-Befehlszeilentools installiert sind: xcode-select --install

   • Richten Sie einen iOS-Simulator ein oder verbinden Sie ein echtes Gerät

   • Vertrauen Sie dem Entwicklungscomputer auf dem iOS-Gerät, wenn Sie ein echtes Gerät verwenden

Ausführen von Tests

1. Erstellen Sie das Projekt:

npm run build

2. Starten Sie den MCP-Server:

npm run dev

3. Führen Sie den Test in einem neuen Terminal aus:

npm test

Testkonfiguration

Android-Konfiguration

Der Beispieltest verwendet die Android-Einstellungen-App als Demo. So testen Sie Ihre eigene App:

1. Bearbeiten Sie examples/appium-test.ts :

   • Aktualisieren Sie deviceName , damit er mit Ihrem Gerät übereinstimmt.

   • Legen Sie app -Pfad zu Ihrer APK-Datei fest, oder

   • Aktualisieren Sie appPackage und appActivity für eine installierte App

2. Konfiguration allgemeiner Funktionen:

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-Konfiguration

Für iOS-Tests mit der neuen Xcode-Befehlszeilenunterstützung:

1. Beispielkonfiguration in 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,
};

Verfügbare Aktionen

Der MCP-Server unterstützt verschiedene Appium-Aktionen:

1. Elementinteraktionen:

   • Elemente suchen

   • Tippen/Klicken Sie auf Elemente mit der W3C Actions API (siehe Abschnitt „W3C-Standardgesten“)

   • Text eingeben

   • Mit der W3C Actions API zum Element scrollen

   • Langes Drücken

2. App-Verwaltung:

   • App starten/schließen

   • App zurücksetzen

   • Aktuelles Paket/Aktuelle Aktivität abrufen

3. Gerätesteuerung:

   • Bildschirmausrichtung

   • Tastaturbedienung

   • Gerät sperren/entsperren

   • Screenshots

   • Batterieinformationen

4. Erweiterte Funktionen:

   • Kontextwechsel (Native/WebView)

   • Dateivorgänge

   • Benachrichtigungen

   • Benutzerdefinierte Gesten

5. Xcode-Befehlszeilentools (nur iOS):

   • iOS-Simulatoren verwalten (Booten, Herunterfahren)

   • Apps auf Simulatoren installieren/deinstallieren

   • Apps starten/beenden

   • Screenshots machen

   • Videos aufnehmen

   • Simulatoren erstellen/löschen

   • Abrufen von Gerätetypen und Laufzeiten

W3C-Standardgesten

Die MCP-Appium-Bibliothek implementiert jetzt die W3C WebDriver Actions API für Touch-Gesten, den modernen Standard für mobile Automatisierung.

W3C-Aktionen für Tap-Elemente

Die Methode tapElement verwendet jetzt die W3C Actions API mit intelligenten Fallbacks:

// 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-Aktionen zum Scrollen

Die Methode scrollToElement verwendet jetzt die W3C Actions API:

// 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
);

Benutzerdefinierte W3C-Gesten

Sie können Ihre eigenen benutzerdefinierten W3C-Gesten mit der Methode executeMobileCommand erstellen:

// 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]);

Weitere Beispiele für die Implementierung von Gesten nach W3C-Standard finden Sie examples/w3c-actions-swipe-demo.ts .

Verwenden von Xcode-Befehlszeilentools

Die neue XcodeCommands Klasse bietet leistungsstarke Tools für iOS-Tests:

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");

Verwenden der Klickfunktion

Die Methode click() bietet eine intuitivere Alternative zu 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']");

Fehlerbehebung

1. Gerät nicht gefunden:

   • Überprüfen Sie die Ausgabe adb devices

   • Überprüfen Sie, ob das USB-Debugging aktiviert ist

   • Versuchen Sie, das Gerät erneut zu verbinden

2. App wird nicht installiert:

   • Überprüfen Sie, ob der APK-Pfad korrekt ist

   • Überprüfen Sie, ob das Gerät über genügend Speicherplatz verfügt

   • Stellen Sie sicher, dass die App zum Debuggen signiert ist

3. Elemente nicht gefunden:

   • Verwenden Sie Appium Inspector, um Selektoren zu überprüfen

   • Überprüfen Sie, ob Elemente auf dem Bildschirm sichtbar sind

   • Probieren Sie verschiedene Lokalisierungsstrategien aus

4. Verbindungsprobleme:

   • Überprüfen Sie, ob der Appium-Server ausgeführt wird

   • Überprüfen Sie Portkonflikte

   • Stellen Sie sicher, dass die richtigen Funktionen eingestellt sind

5. Probleme mit dem iOS-Simulator:

   • Überprüfen Sie, ob die Xcode-Befehlszeilentools installiert sind: xcode-select -p

   • Überprüfen Sie, ob die UDID des Simulators korrekt ist, indem Sie xcrun simctl list devices verwenden.

   • Schließen Sie den Simulator und starten Sie ihn neu, wenn er nicht mehr reagiert.

Beitragen

Sie können gerne Probleme und Pull Requests für zusätzliche Funktionen oder Fehlerbehebungen einreichen.

Lizenz

MIT