](https://www.npmjs.com/package/mcp-appium-visual)   
mcp-appium-visual 是一个集成了模型上下文协议（MCP）的AI驱动的移动自动化平台。它通过Appium实现了对Android和iOS设备的无缝控制，具有智能视觉元素检测和恢复功能。
特性
- 与Appium集成以实现设备控制
- 视觉元素检测和恢复（基于AI）
- MCP支持高级代理驱动的测试工作流程
- 支持Android和iOS平台
- 专为与AI代理配合使用而设计，实现智能自动化
先决条件
- Node.js（v14或更高版本）
- Java开发工具包（JDK）
- Android SDK（用于Android测试）
- Xcode（用于iOS测试，仅限macOS）
- Appium服务器
- 安卓设备或模拟器/iOS设备或模拟器
环境设置
在执行任何命令之前，请确保您的环境变量已正确设置：
- 确保你的
.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- 在运行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真实设备测试，请确保您的Apple Developer帐户在Xcode中配置正确：
- 打开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 匹配您的设备 - 集 app APK文件的路径，或 - 更新 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对Tap元素的操作
这 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手势
您可以使用以下命令创建自己的自定义W3C手势 executeMobileCommand 方法：
// 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]);看 examples/w3c-actions-swipe-demo.ts 了解W3C标准手势实现的更多示例。
使用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检查器验证选择器 - 检查屏幕上是否可见元素 - 尝试不同的定位器策略
- 连接问题：
- 验证Appium服务器是否正在运行 - 检查端口冲突 - 确保设置了正确的功能
- iOS模拟器问题：
- 验证Xcode命令行工具是否已安装： xcode-select -p - 使用以下工具检查模拟器UDID是否正确 xcrun simctl list devices - 如果模拟器变得无响应，请关闭并重新启动模拟器
贡献
请随时提交问题，并提取对其他功能或错误修复的请求。
许可证
麻省理工学院