MCP Appium Server

🚀 MCP Appium Server

Model Context Protocol (MCP) Appium 服務器 — 一個 Node.js 服務器，它將移動自動化功能作為 MCP 工具提供給大語言模型（LLM）代理。

狀態 - 仍在開發中

🚀 快速開始

前提條件

1. Node.js 18+

   node --version  # 版本應 >= 18.0.0
   

2. Appium 2.x

   npm install -g appium
   appium driver install uiautomator2  # 用於 Android
   appium driver install xcuitest      # 用於 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
   # 服務器將啟動並監聽標準輸入輸出
   # 按 Ctrl+C 停止
   

使用方法

方式一：直接執行

node dist/index.js

服務器將：

• 開始監聽標準輸入輸出
• 首次創建會話時自動啟動 Appium
• 處理 SIGINT/SIGTERM 信號以實現優雅關閉

方式二：MCP 客戶端配置

配置你的 MCP 客戶端（例如 Claude Desktop、自定義 LLM 代理）以使用此服務器：

示例 MCP 配置 (~/.mcp/config.json)：

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

✨ 主要特性

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..."
}

示例 LLM 對話

用戶：“為計算器應用啟動一個 Android 會話，然後點擊數字 5 按鈕”

LLM 代理（內部推理）：

1. 使用 Android 功能調用 create_mobile_session
2. 接收會話 ID
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 已安裝並在系統路徑中

已知限制

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": "..." }
}

貢獻

這是一個用於 LLM 控制的移動自動化的生產級 MCP 服務器。歡迎貢獻代碼！

設計指南：

• 保持工具簡單且可組合
• 絕不暴露原始的 WebDriver API
• 保持向後兼容性
• 使用真實的 LLM 代理進行測試

📄 許可證

ISC

致謝

使用以下工具構建：

• @modelcontextprotocol/sdk - MCP 協議實現
• Appium - 移動自動化框架
• WebdriverIO - WebDriver 客戶端
• Winston - 日誌記錄

有疑問？ 查看 Model Context Protocol 文檔 或提交一個 issue。