Mobiledevice MCP Zed Extension

移动设备MCP服务器

    

用于移动设备自动化的综合模型上下文协议（MCP）服务器。通过标准化界面以编程方式控制Android和iOS设备，非常适合测试、自动化和人工智能辅助的移动应用程序开发。

🚀 特性

• 19移动自动化工具 -通过MCP完成设备控制
• 完全支持Android -100%覆盖物理设备和模拟器（19/19工具）
• 全面的iOS支持 -模拟器覆盖率为95%，物理设备覆盖率为42%（18/19工具）
• 电脑屏幕截图工具 -带有base64 PNG输出的可视化设备状态（所有平台）
• UI元素检查 -基于XML的Android层次结构解析
• 应用生命周期管理 -安装、启动、终止和卸载应用程序
• 触摸和手势自动化 -点击、滑动、长按，然后键入
• 跨平台构建 -适用于macOS、Linux和Windows
• 原生二进制+WASM -独立服务器和Zed扩展支持
• 整洁架构 -模块化、文档完善的Rust代码库

📋 可用工具

所有工具都使用 mobile_device_mcp_* 命名空间的前缀。

设备信息（5个工具）

屏幕交互（6个工具）

输入（2个工具）

应用程序管理（4个工具）

导航（2个工具）

平台概述：

• 安卓： 19/19工具（100%覆盖-所有设备）
• iOS模拟器： 18/19工具（95%覆盖率-仅限macOS）
• iOS物理设备： 8/19个工具（42%的覆盖率-基本自动化）

传说：

• ✅ 全力支持
• ✅\* 模拟器支持（iOS）或部分支持
• ⚠️\*\* 支持有限（需要WebDriver Agent等其他工具）

🏗️ 建筑

mobile-mcp-zed-extension/
├── src/
│   ├── main.rs              # Native MCP server (JSON-RPC 2.0)
│   ├── lib.rs               # Zed WASM extension
│   ├── types.rs             # Shared type definitions
│   ├── devices/
│   │   ├── android.rs       # Android automation (adb_client)
│   │   └── ios.rs           # iOS automation (xcrun simctl)
│   ├── mcp/
│   │   └── protocol.rs      # MCP protocol implementation
│   └── tools/
│       ├── definitions.rs   # Tool schemas (19 tools)
│       └── handlers.rs      # Tool implementations
├── extension.toml           # Zed extension manifest
└── Cargo.toml              # Dependencies

Tech Stack:
- Protocol: JSON-RPC 2.0 via MCP
- Android: adb_client crate + shell commands
- iOS: xcrun simctl + libimobiledevice (macOS only)
- Cross-Platform: Runs on macOS, Linux, and Windows
- XML Parsing: quick-xml for UI hierarchy
- Build: Native binary + WASM extension

📦 安装

先决条件

Android支持（所有平台）： 无需额外工具！服务器使用纯Rust-ADB实现(adb_client 板条箱）。

• 只需在您的Android设备上启用USB调试
• 服务器以本机方式处理所有ADB通信
• 无需安装 android-platform-tools 或 adb 分别

iOS模拟器支持（仅限macOS）：

# Install Xcode Command Line Tools (REQUIRED for simctl)
xcode-select --install

# Verify
xcrun simctl list devices

iOS真实设备支持（仅限macOS）：

# Install libimobiledevice (REQUIRED for physical devices)
brew install libimobiledevice

# Verify
idevice_id -l  # Lists connected physical devices

从源代码构建

# Clone repository
git clone https://github.com/sorinirimies/mobiledevice-mcp-zed-extension
cd mobile-device-mcp

# Build native binary
# macOS (with iOS support)
cargo build --release --features "native-binary,ios-support"

# Linux/Windows (Android only)
cargo build --release --features native-binary

# Binary location
./target/release/mobile-device-mcp-server

# Or build Zed extension (WASM)
rustup target add wasm32-wasip1
cargo build --release --target wasm32-wasip1

作为Zed扩展安装

1. 打开Zed编辑器
2. 转到扩展（Cmd+Shift+X）
3. 搜索“移动设备MCP”
4. 单击安装

或手动：

# Copy to Zed extensions directory
mkdir -p ~/.config/zed/extensions
cp -r . ~/.config/zed/extensions/mobile-device-mcp

🚦 快速开始

使用Just（推荐）

就 是一个简化常见任务的命令运行器：

# Install just
cargo install just

# Show all available commands
just

# Quick development setup
just dev-setup

# Build and run
just build
just run

# Run tests
just test

# Install Zed extension
just install-zed

# Format, lint, and test
just pre-commit

请参阅 justfile 对于所有可用命令。

启动MCP服务器（独立）

# Run the server
./target/release/mobile-device-mcp-server

# Set debug mode (optional)
export MOBILE_DEVICE_MCP_DEBUG=1
./target/release/mobile-device-mcp-server

# Or using just
just run
just run-debug

MCP请求示例

列出设备：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_list_available_devices",
    "arguments": {}
  }
}

拍摄屏幕截图：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_take_screenshot",
    "arguments": {
      "device_id": "emulator-5554",
      "platform": "android"
    }
  }
}

列出UI元素：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mobile_device_mcp_list_elements_on_screen",
    "arguments": {
      "device_id": "emulator-5554",
      "platform": "android",
      "filter": "Sign in"
    }
  }
}

🧪 测试

# Run unit tests
just test

# Run tests with coverage
just test-coverage

# Run integration tests (requires connected device/emulator)
just test-integration

# Quick smoke test
just test-smoke

# Or manually
./scripts/test-all-tools.sh
./scripts/test-tools.sh

# Expected output:
# Total Tests:  18
# Passed:       18 ✅
# Failed:       0 ❌

📱 设备设置

模拟器

# Start emulator
emulator -avd Pixel_6_API_34

# Verify connection
adb devices
# Output: emulator-5554   device

Android物理设备

# Enable USB debugging on device
# Settings > Developer Options > USB Debugging

# Connect via USB and verify
adb devices

iOS模拟器（macOS）

# List available simulators
xcrun simctl list devices

# Boot a simulator
xcrun simctl boot "iPhone 15 Pro"

# Verify
xcrun simctl list devices | grep Booted

🔧 配置

环境变量

• MOBILE_DEVICE_MCP_DEBUG=1 -启用调试日志记录
• MOBILE_PLATFORM=android|ios|auto -默认平台（自动=两者）

货物特征

• native-binary -构建独立的MCP服务器（本机构建所需）
• default -作为Zed WASM扩展构建

📚 文档

综合指南

• iOS实施指南 -完整的iOS自动化文档
• Android实施指南 -完整的Android自动化文档
• Windows支持指南 -Windows特定的设置和使用
• 跨平台指南 -多操作系统部署和测试
• 特征奇偶校验 -iOS与Android的详细比较

📖 API 文档

工具响应格式

所有工具均返回符合MCP的响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool output here"
      }
    ]
  }
}

屏幕截图响应使用图像类型：

{
  "result": {
    "content": [
      {
        "type": "image",
        "data": "",
        "mimeType": "image/png"
      }
    ]
  }
}

错误处理

错误遵循MCP错误格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "Device not found: emulator-5554"
  }
}

🛠️ 发展

从Just快速开始

# Complete development setup
just dev-setup

# Daily development workflow
just build        # Build debug binary
just test         # Run tests
just lint         # Run clippy
just fmt          # Format code
just pre-commit   # Run all checks before committing

# Watch for changes
just watch        # Auto-run tests on file changes
just watch-run    # Auto-restart server on file changes

项目结构

• src/设备/ -特定于平台的设备管理器

- android.rs -ADB客户端、UI自动化、应用管理 - ios.rs -simctl包装器、屏幕截图、基本输入

• src/工具/ -MCP工具定义

- definitions.rs -所有19个工具的JSON模式 - handlers.rs -每个工具的实施逻辑

• src/mcp/ -协议层

- protocol.rs -JSON-RPC 2.0结构

添加新工具

1. 在中定义工具架构 src/tools/definitions.rs
2. 在中实现处理程序 src/tools/handlers.rs
3. 在中添加调度案例 src/main.rs
4. 更新测试 scripts/test-all-tools.sh
5. 跑 just test 验证

运行测试

# Using just (recommended)
just test                    # All tests
just test-integration        # Integration tests
just test-coverage          # With coverage report

# Or manually
cargo build --release --features native-binary
./scripts/test-all-tools.sh

# Run specific test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mobile_device_mcp_take_screenshot","arguments":{"device_id":"emulator-5554","platform":"android"}}}' | ./target/release/mobile-device-mcp-server

🐛 故障排除

Android问题

未检测到设备：

• 在设备上启用USB调试（设置→ 开发人员选项→ USB调试）
• 服务器的内置ADB客户端将自动检测连接的设备
• 对于模拟器，请确保它们正在运行： emulator -list-avds
• 铁锈 adb_client 本机处理所有通信-不需要外部ADB工具

设备未经授权：

• 检查您的Android设备屏幕是否有授权提示
• 接受“允许USB调试”对话框
• 一旦获得授权，服务器将自动重新连接

iOS问题

未找到simctl：

# Install Xcode Command Line Tools
xcode-select --install

模拟器未启动：

# Kill all simulators
killall Simulator
# Boot specific device
xcrun simctl boot "iPhone 15"

🌐 与跨平台支持

支持的平台

快速设置：

• macOS： xcode-select --install （适用于iOS模拟器）， brew install libimobiledevice （适用于iOS设备）
• Linux： 无需额外工具（仅限Android）
• 窗户： 无需额外工具（仅限Android）

注： Android支持使用纯Rust-ADB实现-不需要平台工具！

看 跨平台指南 详细说明。

🔄 CI/CD

此项目使用轻量级的GitHub Actions工作流进行基本检查：

工作流

• 持续集成 (.github/workflows/ci.yml)-每次推送和公关都会运行

- ✅ 测试（仅限Ubuntu） - ✅ 代码格式(cargo fmt) - ✅ 用Clippy打毛

• 发布 (.github/workflows/release.yml)-在版本标签上触发

- 📦 为Linux、macOS（ARM）和Windows构建二进制文件 - 📦 创建GitHub版本 - 📦 上传发布工件

本地检查

# Run formatting and linting
just fmt
just lint
just test

# Or all at once
just pre-commit

创建发布

# Tag and push
git tag -a "v0.2.0" -m "Release v0.2.0"
git push origin main --tags

发布工作流将自动为支持的平台构建和上传二进制文件。

🗂️ 更新日志

看 更改日志.md 发布历史。

使用生成 吉特悬崖.

🤝 贡献

欢迎投稿！感兴趣的领域：

1. iOS功能奇偶校验 -实现缺少的iOS工具（请参阅功能奇偶校验文档）
2. 真实设备支持 -iOS真实设备自动化
3. 用户界面测试 -视觉元素匹配、断言
4. 演出 -优化XML解析、缓存
5. 平台支持 -Windows/Linux改进

开发流程

1. 分叉并克隆存储库
2. 跑 just dev-setup 配置您的环境
3. 创建要素分支
4. 进行更改并添加测试
5. 跑 just pre-commit 验证所有检查是否通过
6. 提交拉取请求

所有PR在合并之前必须通过CI检查。

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• adb客户端 -Rust-ADB客户端库
• 快速xml -快速XML解析
• MCP协议 -模型上下文协议规范
• Zed编辑 -扩展平台
• 仅仅 -开发任务的命令运行器
• 吉特悬崖 -变更日志生成器

📞 支持

• 问题：
• 讨论：

______________________________________________________________________

版本： 0.1.0\ 状态： 生产就绪（Android完整版，iOS模拟器），测试版（iOS物理设备）\ 最后更新时间： 2024年11月1日\ 平台覆盖范围： macOS（完整版）、Linux（Android）、Windows（Android）