MCP Appium Server

🚀 MCP Appium Server

Appium用のModel Context Protocol (MCP) サーバー — Node.jsサーバーで、モバイル自動化機能をLLMエージェント用のMCPツールとして公開します。

ステータス - まだ開発中です

🚀 クイックスタート

Model Context Protocol (MCP) は、アプリケーションが大規模言語モデル (LLM) にコンテキストを提供する方法を標準化するオープンプロトコルです。これは、GPT-4やClaudeなどのAIエージェントが外部のツールやサービスとやり取りできるようにする汎用アダプターのようなものです。

✨ 主な機能

Model Context Protocol (MCP) とは？

Model Context Protocol (MCP) は、アプリケーションが大規模言語モデル (LLM) にコンテキストを提供する方法を標準化するオープンプロトコルです。GPT-4やClaudeなどのAIエージェントが外部のツールやサービスとやり取りできるようにする汎用アダプターのようなものです。

主要概念

• MCPサーバー：LLMエージェントに機能（ツール、リソース、プロンプト）を公開するプログラム
• MCPクライアント：これらの機能を消費するLLMエージェントまたはアプリケーション
• ツール：LLMがアクションを実行するために呼び出せる関数（例：ボタンをクリックする、テキストを入力する）
• stdioトランスポート：標準入出力を介した通信（ローカル実行に最適）

モバイル自動化にMCPを使用する理由

命令型のテストスクリプトを書く代わりに、テストしたいことを自然言語で記述します。LLMエージェントは以下のように動作します。

1. あなたの意図を理解する
2. MCPツールを呼び出してモバイルアプリとやり取りする
3. 結果（スクリーンショット、要素の状態）を観察する
4. 自律的に決定を下す
5. 人間が読めるレポートを提供する

これはテストフレームワークではありません — これはLLMによって制御されるモバイル自動化コントロールプレーンです。

🔧 技術詳細

アーキテクチャ

┌─────────────────────────────────────┐
│   LLM Agent (GPT-4 / Claude)        │
│   "Tap the login button"            │
└────────────┬────────────────────────┘
             │ MCP Protocol
             │ (stdio)
             ▼
┌─────────────────────────────────────┐
│   MCP Appium Server (Node.js)       │
├─────────────────────────────────────┤
│  • Tool Registry (6 tools)          │
│  • Session Manager (stateful)       │
│  • Appium Launcher                  │
│  • Command Executor (WebdriverIO)   │
└────────────┬────────────────────────┘
             │ WebDriver Protocol
             ▼
┌─────────────────────────────────────┐
│   Appium Server (2.x)               │
└────────────┬────────────────────────┘
             │
             ▼
┌─────────────────────────────────────┐
│   Android Emulator / iOS Simulator  │
└─────────────────────────────────────┘

MCPツール

このサーバーは6つの本番環境で使用可能なMCPツールを公開しています。

1. create_mobile_session

目的：AndroidまたはiOS用のAppiumセッションを作成します。

入力：

{
  "platform": "android | ios",
  "capabilities": {
    "deviceName": "Pixel_5_API_31",
    "app": "/path/to/app.apk",
    "automationName": "UiAutomator2"
  }
}

出力：

{
  "success": true,
  "sessionId": "abc123...",
  "platform": "android"
}

2. tap_element

目的：UI要素をタップ/クリックします。

入力：

{
  "sessionId": "abc123...",
  "strategy": "id | xpath | accessibilityId",
  "selector": "com.example:id/login_button"
}

3. type_text

目的：要素にテキストを入力します。

入力：

{
  "sessionId": "abc123...",
  "strategy": "accessibilityId",
  "selector": "username_field",
  "text": "testuser@example.com"
}

4. navigate_back

目的：バックボタンを押す（Android）または戻る（iOS）

入力：

{
  "sessionId": "abc123..."
}

5. take_screenshot

目的：現在の画面状態をキャプチャします。

入力：

{
  "sessionId": "abc123..."
}

出力：

{
  "success": true,
  "imageBase64": "iVBORw0KGgoAAAANSUhEU...",
  "format": "png"
}

6. close_mobile_session

目的：セッションを閉じてクリーンアップします。

入力：

{
  "sessionId": "abc123..."
}

📦 インストール

前提条件

1. Node.js 18+

   node --version  # Should be >= 18.0.0
   

2. Appium 2.x

   npm install -g appium
   appium driver install uiautomator2  # For Android
   appium driver install xcuitest      # For iOS
   

3. Androidセットアップ (Androidテスト用)

   • Android SDKがインストールされている
   • エミュレータまたは物理デバイスが利用可能
   • adb devices でデバイスが表示される

4. iOSセットアップ (iOSテスト用)

   • Xcodeがインストールされている（macOSのみ）
   • iOSシミュレータが利用可能
   • Xcodeコマンドラインツールがインストールされている

インストール手順

1. クローンして依存関係をインストールする：

   cd mcp-appium-server
   npm install
   

2. TypeScriptをビルドする：

   npm run build
   

3. サーバーをテストする (オプション)：

   npm start
   # サーバーが起動し、stdioで待機します
   # Ctrl+Cで停止します
   

💻 使用例

オプション1: 直接実行

node dist/index.js

サーバーは以下のように動作します。

• stdioで待機を開始します。
• 最初のセッションが作成されたときにAppiumを自動起動します。
• SIGINT/SIGTERMで正常にシャットダウンします。

オプション2: MCPクライアントの設定

MCPクライアント（例：Claude Desktop、カスタムLLMエージェント）をこのサーバーを使用するように設定します。

MCP設定の例 (~/.mcp/config.json)：

{
  "mcpServers": {
    "appium": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-appium-server/dist/index.js"],
      "env": {}
    }
  }
}

サンプルのLLM会話

ユーザー："CalculatorアプリのAndroidセッションを開始し、次に数字の5ボタンをタップしてください"

LLMエージェント (内部の推論)：

1. Androidの機能を指定して create_mobile_session を呼び出す
2. sessionIdを受け取る
3. "5"ボタンのセレクターを指定して tap_element を呼び出す
4. ユーザーに成功を返す

結果：電卓アプリが開き、"5"が自動的にタップされます。

📚 ドキュメント

プロジェクト構造

mcp-appium-server/
├── src/
│   ├── index.ts                  # エントリーポイント、シグナルハンドラー
│   ├── mcp/
│   │   ├── server.ts             # MCPサーバーのセットアップとツール登録
│   │   └── tools.ts              # ツールの実装
│   ├── appium/
│   │   ├── appiumLauncher.ts     # Appiumプロセスの起動/停止
│   │   ├── sessionManager.ts     # セッションのライフサイクルと状態
│   │   └── commandExecutor.ts    # WebDriverコマンドのマッピング
│   └── types/
│       └── toolSchemas.ts        # ツールのJSONスキーマ
├── package.json
├── tsconfig.json
└── README.md

設計原則

1. MCP準拠

• ツール登録にMCP仕様に従う
• stdioトランスポートを使用する
• エラーコード付きの構造化エラーを使用する

2. ステートレスなツール、ステートフルなセッション

• 各ツール呼び出しは冪等である
• セッション状態はメモリ内で管理される
• セッションIDは明示的に渡される

3. 自律エージェントに安全

• 破壊的なコマンドは公開されない
• エラーを適切に処理する
• 各呼び出しでセッションの検証を行う

4. 本番環境向けの品質

• 包括的なロギング（Winston）
• TypeScriptの厳格モード
• クリーンアップ付きの正常なシャットダウン

エラー処理

すべてのエラーはMCP互換の構造化エラーとして返されます。

{
  "error": {
    "code": "InternalError",
    "message": "Session not found: xyz123. Create a session first using create_mobile_session."
  }
}

一般的なエラー：

• Session not found：最初に create_mobile_session を呼び出してください
• Element not found：セレクターの戦略/値を確認してください
• Appium startup timeout：AppiumがインストールされていてPATHに含まれていることを確認してください

既知の制限事項

1. ローカル実行のみ：まだクラウドデバイスファームのサポートはありません
2. stdioトランスポートのみ：まだWebSocket/HTTPのサポートはありません
3. 基本的な要素の操作：まだジェスチャー（スワイプ、ピンチ）はサポートされていません
4. アクセシビリティツリーのエクスポートなし：将来のバージョンで追加予定
5. ビジョン機能の統合なし：スクリーンショットの分析には外部のLLMビジョンが必要です

将来の拡張機能

• 🔄 ジェスチャーサポート（スワイプ、スクロール、ピンチ）
• 🌳 アクセシビリティツリーのエクスポート：要素の検出を改善する
• 📸 ビジョンAPIの統合：スクリーンショットの分析
• 🌐 WebSocketトランスポート：リモート実行用
• ☁️ クラウドデバイスファームのサポート（BrowserStack、Sauce Labs）
• 🔍 AIによるセレクターを使用した要素検出の強化

トラブルシューティング

"Appium startup timeout"

解決策：Appiumがグローバルにインストールされていることを確認してください。

npm install -g appium
appium --version

"Session creation failed"

解決策：デバイスの可用性を確認してください。

# Android
adb devices

# iOS
xcrun simctl list devices

"Element not found"

解決策：まずスクリーンショットを撮って要素の可視性を確認してください。

{
  "tool": "take_screenshot",
  "input": { "sessionId": "..." }
}

📄 ライセンス

ISC

クレジット

以下のツールを使用して構築されています。

• @modelcontextprotocol/sdk - MCPプロトコルの実装
• Appium - モバイル自動化フレームワーク
• WebdriverIO - WebDriverクライアント
• Winston - ロギング

質問がありますか？ Model Context Protocolのドキュメント を確認するか、イシューを開いてください。