MCP Appium サーバー

Appium を使用したモバイルアプリ自動化のためのモデルコンテキストプロトコル (MCP) サーバー実装。

前提条件

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 の実際のデバイスをテストする場合は、Xcode で Apple Developer アカウントが適切に設定されていることを確認してください。
- Xcodeを開く
- 「設定」>「アカウント」へ移動
- 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設定アプリをデモとして使用します。独自のアプリをテストするには、以下の手順に従ってください。

examples/appium-test.tsを編集します。
- deviceNameデバイスに合わせて更新します
- APKファイルへのappを設定するか、
- インストールされたアプリの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 設定

新しい Xcode コマンドラインサポートを使用した iOS テストの場合:

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 アクションをサポートしています。

要素の相互作用:
- 要素を見つける
- W3C Actions API を使用した要素のタップ/クリック (「W3C 標準ジェスチャ」セクションを参照)
- テキストを入力
- W3C Actions API で要素までスクロールする
- 長押し
アプリ管理:
- アプリを起動/閉じる
- アプリをリセット
- 現在のパッケージ/アクティビティを取得する
デバイスコントロール:
- 画面の向き
- キーボード操作
- デバイスのロック/ロック解除
- スクリーンショット
- バッテリー情報
高度な機能:
- コンテキスト切り替え（ネイティブ/WebView）
- ファイル操作
- 通知
- カスタムジェスチャー
Xcode コマンドラインツール (iOS のみ):
- iOS シミュレーターの管理 (起動、シャットダウン)
- シミュレータ上でのアプリのインストール/アンインストール
- アプリの起動/終了
- スクリーンショットを撮る
- ビデオを録画する
- シミュレータの作成/削除
- デバイスの種類とランタイムを取得する

W3C標準ジェスチャー

MCP-Appium ライブラリは、モバイル自動化の最新標準であるタッチジェスチャ用の W3C WebDriver Actions API を実装するようになりました。

タップ要素のW3Cアクション

tapElementメソッドは、インテリジェントなフォールバックを備えた W3C Actions API を使用するようになりました。

// 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メソッドは 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 );

カスタム W3C ジェスチャー

executeMobileCommandメソッドを使用して、独自のカスタム W3C ジェスチャを作成できます。

// 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
- xcrun simctl list devicesを使用してシミュレータのUDIDが正しいことを確認します。
- シミュレータが応答しなくなった場合は閉じて再起動してください

貢献

追加機能やバグ修正に関する問題やプルリクエストをお気軽に送信してください。

ライセンス

マサチューセッツ工科大学

MCP Appium Server