MCP Appium Server

mcp-appium-visual は、Model Context Protocol（MCP）と連携する AI 搭載のモバイル自動化プラットフォームです。Appium を通じて Android デバイスと iOS デバイスをシームレスに操作でき、インテリジェントな視覚要素の検出と復旧機能を備えています。

特徴

• デバイス制御のための Appium 連携
• 視覚要素の検出と復旧（AI ベース）
• エージェント主導の高度なテストワークフロー向け MCP サポート
• Android と iOS プラットフォームに対応
• インテリジェントな自動化を実現する AI エージェントとの使用を想定

前提条件

1. Node.js（v14 以降）
2. Java Development Kit（JDK）
3. Android SDK（Android のテスト用）
4. Xcode（iOS のテスト用、macOS のみ）
5. Appium サーバー
6. Android デバイスまたはエミュレーター／iOS デバイスまたはシミュレーター

環境の設定

コマンドを実行する前に、環境変数が適切に設定されていることを確認してください。

1. .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

2. MCP-Appium を実行する前に、環境ファイルを読み込みます。

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

注：ドライバーの初期化時にシステムが .bash_profile を自動的に読み込もうとしますが、新しいターミナルセッションでテストを実行する前に、手動で環境が適切に設定されていることを確認することをおすすめします。

Xcode コマンドラインツールの設定

iOS のテストでは、Xcode コマンドラインツールを適切に設定する必要があります。

1. 未インストールの場合は、Xcode コマンドラインツールをインストールします。

xcode-select --install

2. インストールを確認し、現在の Xcode のパスを確認します。

xcode-select -p

3. 必要に応じて、正しい Xcode のパスを設定します（特に複数の Xcode バージョンがある場合）。

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

4. Xcode のライセンス契約に同意します。

sudo xcodebuild -license accept

5. iOS 実機テストでは、Xcode で Apple Developer アカウントが適切に設定されていることを確認します。

   • Xcode を開きます
   • 「Preferences > Accounts」に移動します
   • まだ追加していない場合は、Apple ID を追加します
   • 必要なプロビジョニングプロファイルをダウンロードします

6. iOS 開発用の環境変数を設定します。

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

7. 更新した設定を読み込みます。

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

セットアップ

1. 依存関係をインストールします。

npm install

2. Appium サーバーをインストールして起動します。

npm install -g appium
appium

3. Android デバイス／エミュレーターをセットアップします。

   • Android デバイスで開発者向けオプションを有効にします
   • USB デバッグを有効にします
   • デバイスを USB で接続するか、エミュレーターを起動します
   • adb devices を使用してデバイスが接続されていることを確認します

4. iOS のテスト（macOS のみ）：

   • Xcode コマンドラインツールがインストールされていることを確認します：xcode-select --install
   • iOS シミュレーターをセットアップするか、実機を接続します
   • 実機を使用する場合は、iOS デバイスで開発用コンピューターを信頼します

テストの実行

1. プロジェクトをビルドします。

npm run build

2. MCP サーバーを起動します。

npm run dev

3. 新しいターミナルでテストを実行します。

npm test

テストの設定

Android の設定

サンプルテストでは、デモとして Android 設定アプリを使用します。独自のアプリをテストするには：

1. examples/appium-test.ts を編集します。

   • deviceName をデバイスに合わせて更新します
   • app に APK ファイルのパスを設定するか、
   • インストール済みアプリの場合は appPackage と appActivity を更新します

2. 一般的な機能の設定：

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 をテストする場合：

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

1. 要素の操作：

   • 要素を検索する
   • W3C Actions API で要素をタップ／クリックする（「W3C 標準ジェスチャー」セクションを参照）
   • テキストを入力する
   • W3C Actions API で要素までスクロールする
   • 長押しする

2. アプリの管理：

   • アプリを起動／終了する
   • アプリをリセットする
   • 現在のパッケージ／アクティビティを取得する

3. デバイスの制御：

   • 画面の向き
   • キーボードの操作
   • デバイスのロック／ロック解除
   • スクリーンショット
   • バッテリー情報

4. 高度な機能：

   • コンテキストの切り替え（ネイティブ／WebView）
   • ファイル操作
   • 通知
   • カスタムジェスチャー

5. Xcode コマンドラインツール（iOS のみ）：

   • iOS シミュレーターを管理する（起動、シャットダウン）
   • シミュレーターにアプリをインストール／アンインストールする
   • アプリを起動／終了する
   • スクリーンショットを撮影する
   • 動画を録画する
   • シミュレーターを作成／削除する
   • デバイスの種類とランタイムを取得する

W3C 標準ジェスチャー

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

要素のタップに使う W3C Actions

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 Actions

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 関数の使用

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

トラブルシューティング

1. デバイスが見つからない場合：

   • adb devices の出力を確認する
   • USB デバッグが有効になっていることを確認する
   • デバイスを再接続してみる

2. アプリをインストールできない場合：

   • APK のパスが正しいことを確認する
   • デバイスに十分なストレージがあることを確認する
   • アプリがデバッグ用に署名されていることを確認する

3. 要素が見つからない場合：

   • Appium Inspector を使ってセレクターを確認する
   • 要素が画面に表示されているか確認する
   • 別のロケーター戦略を試す

4. 接続に問題がある場合：

   • Appium サーバーが実行中であることを確認する
   • ポートの競合を確認する
   • 正しいケイパビリティが設定されていることを確認する

5. iOS シミュレーターに問題がある場合：

   • Xcode コマンドラインツールがインストールされていることを確認する：xcode-select -p
   • xcrun simctl list devices を使って、シミュレーターの UDID が正しいことを確認する
   • シミュレーターが応答しなくなった場合は、終了して再起動する

コントリビューション

追加機能やバグ修正に関するイシューやプルリクエストをお気軽にお送りください。

ライセンス

MIT