JinDaGe - mcp-appium-server MCP Details

article

README

🚀 MCP Appium Server

Model Context Protocol (MCP) Appium 服务器 — 一个 Node.js 服务器，它将移动自动化功能作为 MCP 工具提供给大语言模型（LLM）代理。

状态 - 仍在开发中

🚀 快速开始

前提条件

Node.js 18+
```
node --version  # 版本应 >= 18.0.0
```

Appium 2.x

npm install -g appium
appium driver install uiautomator2  # 用于 Android
appium driver install xcuitest      # 用于 iOS

Android 环境设置（用于 Android 测试）
- 安装 Android SDK
- 有可用的模拟器或物理设备
- adb devices 能显示你的设备
iOS 环境设置（用于 iOS 测试）
- 安装 Xcode（仅适用于 macOS）
- 有可用的 iOS 模拟器
- 安装 Xcode 命令行工具

安装

克隆项目并安装依赖：
```
cd mcp-appium-server
npm install
```
构建 TypeScript 代码：
```
npm run build
```

测试服务器（可选）：

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 代理会：

理解你的意图
调用 MCP 工具与移动应用进行交互
观察结果（截图、元素状态）
自主做出决策
提供人类可读的报告

这不是一个测试框架 — 而是一个由 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 代理（内部推理）：

使用 Android 功能调用 create_mobile_session
接收会话 ID
使用“5”按钮的选择器调用 tap_element
向用户返回成功信息

结果：计算器应用打开并自动点击“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 已安装并在系统路径中

已知限制

仅支持本地执行：目前不支持云设备农场
仅支持 stdio 传输：目前不支持 WebSocket/HTTP
基本元素交互：目前不支持手势（滑动、捏合）
无辅助功能树导出：未来版本将支持
无视觉集成：截图分析需要外部 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。