MCP Appium Server

mcp-appium-visual 是一个集成了模型上下文协议（MCP）的 AI 驱动移动自动化平台。它通过 Appium 实现对 Android 和 iOS 设备的无缝控制，并具备智能视觉元素检测与恢复功能。

功能特性

• 集成 Appium 以控制设备
• 视觉元素检测与恢复（基于 AI）
• 支持 MCP，可实现高级 Agent 驱动的测试工作流
• 支持 Android 和 iOS 平台
• 专为 AI Agent 智能自动化而设计

前置条件

1. Node.js（v14 或更高版本）
2. Java Development Kit（JDK）
3. Android SDK（用于 Android 测试）
4. Xcode（用于 iOS 测试，仅限 macOS）
5. Appium Server
6. Android 设备或模拟器 / iOS 设备或模拟器

环境设置

执行任何命令之前，请确保已正确设置环境变量：

1. 确保 .bash_profile、.zshrc 或其他 shell 配置文件中包含所需的环境变量：

# 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. 高级功能：

   • 上下文切换（Native/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 服务正在运行
   • 检查端口冲突
   • 确保设置了正确的 capabilities

5. iOS 模拟器问题：

   • 确认已安装 Xcode 命令行工具：xcode-select -p
   • 使用 xcrun simctl list devices 检查模拟器 UDID 是否正确
   • 如果模拟器无响应，请关闭并重新启动

贡献

欢迎提交问题和拉取请求，以添加功能或修复错误。

许可证

MIT