qwen-code 仓库中 mobile-mcp 演进全解析从移动设备 MCP 服务器到 0-1000 相对坐标能力【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本篇技术指南以本仓库 packages/mobile-mcp/CHANGELOG.md 为骨架结合 packages/mobile-mcp/src 下的 TypeScript 源码与测试系统梳理qwen-code/mobile-mcp这个移动设备 MCP 服务器从 v0.0.11 到 v0.0.61 的完整演进脉络以及 fork 到 qwen-code 后新增的相对坐标归一化、Android 专属工具等本地化能力。读完本文你将掌握该 MCP 服务器的工具集全貌、底层驱动架构mobilecli / mobilewright、安全加固历史以及如何在 MCP 客户端中配置并启用 0-1000 相对坐标模式以对接 Qwen VL 模型的mobile_use坐标约定。一、mobile-mcp 是什么qwen-code/mobile-mcp是一个基于 Model Context Protocol 的 MCP 服务器它让 LLM Agent 能够通过截图、无障碍元素树、坐标触控三种通道与 iOS / Android 移动设备模拟器、仿真器、真机交互。本仓库中的实现是上游 mobile-next/mobile-mcp通过git subtree方式跟踪上游本地修改记录与同步脚本见 packages/mobile-mcp/scripts/sync-from-upstream.sh。从包配置 packages/mobile-mcp/package.json 可以看到它的技术栈运行时要求 Node.js 18核心依赖modelcontextprotocol/sdk1.26.0、express5.1.0SSE 传输、commanderCLI 参数、fast-xml-parserAndroid UI 树解析、mobilewrightiOS 模拟器驱动、zod工具参数校验提供了mcp-server-mobile这个 bin 入口即 packages/mobile-mcp/src/index.ts测试基于 Playwrightc8 playwright test。二、版本演进总览一条清晰的能力成长线CHANGELOG 覆盖了 2025-04 至 2026-07 的 0.0.11 ~ 0.0.61 共 50 余个版本可以归纳为几个阶段阶段版本区间核心主题起步期0.0.11 ~ 0.0.19多设备支持、iOS 真机go-ios、方向切换、元素识别增强工具丰富期0.0.20 ~ 0.0.30save_screenshot、use_default_device、长按、app 安装卸载、mobilecli 引入稳定性与兼容期0.0.31 ~ 0.0.43libc 兼容、多屏设备折叠屏截图、远程设备、超大截图 buffer安全加固期0.0.44 ~ 0.0.52URL 协议限制、路径遍历修复、SSE 认证、跨域/并发防护、依赖安全升级架构升级期0.0.53 ~ 0.0.61崩溃报告工具、iOS Device Kit 替换 WebDriverAgent、mobilewright SDK 化、信号处理从版本频率看该项目保持着约每 1~2 周一个版本的迭代节奏且大量版本包含安全依赖升级fast-xml-parser、path-to-regexp、hono、modelcontextprotocol/sdk 等这是其工程纪律的一个显著特征。三、底层驱动架构的两次大迁移CHANGELOG 揭示了 mobile-mcp 后端驱动能力的两次关键架构迁移这是理解整个项目的钥匙。1. mobilecli 统一二进制0.0.30 引入在 0.0.302025-10-06中项目明确宣告introduction of mobilecli tool, will replace imagemagick, sips, go-ios and adb in the future——即用统一的mobilecli二进制逐步替代四类外部依赖ImageMagick图像缩放sipsmacOS 图像缩放go-iosiOS 真机通信adbAndroid 通信在 packages/mobile-mcp/src/server.ts 中可以看到这一架构的落地ensureMobilecliAvailable()在每次获取设备 Robot 前都会校验 mobilecli 是否可用随后getRobotFromDevice()依次探测 iOS 真机IosManager、Android 设备AndroidDeviceManager、iOS 模拟器mobilecli.getDevices最终返回对应的IosRobot/AndroidRobot/MobileDevice实例。这一抽象 Robot 平台实现的模式定义在 packages/mobile-mcp/src/robot.ts 的Robot接口中getScreenSize、swipe、tap、longPress、listApps、installApp、sendKeys、pressButton、getElementsOnScreen、setOrientation等一应俱全。2. mobilewright SDK 化0.0.55 ~ 0.0.610.0.55 用 mobilewright SDK 替换了 mobilecliReplace mobilecli with mobilewright SDK后续 0.0.56、0.0.57、0.0.60 持续升级 mobilewright 版本0.0.38 → 0.0.41 → 0.0.53。mobilewright 承担了 iOS 模拟器的管理、WebDriverAgent 的自动下载安装0.0.38无需手动安装 WDA数秒内即可开始在模拟器上开发以及后续的 Device Kit 集成。从源码看iOS 模拟器的 agent 生命周期管理位于 packages/mobile-mcp/src/server.ts 的getRobotFromDevice()中通过agentVerifiedSimulators集合做去重对每个首次使用的模拟器执行mobilecli.agentStatus()检查失败则调用mobilecli.agentInstall()自动安装。3. iOS Device Kit 替换 WebDriverAgent0.0.530.0.53 是一个重要的架构节点iOS 侧从 WebDriverAgent 切换到开源的 iOS Device KitApache License同时修复了 testmanagerd 导致 Device Kit 卡死黑屏的问题并在视图树响应中新增placeholder字段。加上 0.0.58 的getRobot设备类型/平台识别、0.0.61 对通过 npm 安装的 go-iosbare semver 版本号的检测修复iOS 真机链路的健壮性逐步完善。四、工具集全貌从 CHANGELOG 到源码逐一对位CHANGELOG 中散落的工具新增记录最终都收敛为 packages/mobile-mcp/src/server.ts 中注册的具体 MCP 工具。完整工具清单如下与 packages/mobile-mcp/README.md 一致设备管理mobile_list_available_devices列出全部可用设备Android 仿真器 iOS 真机 iOS 模拟器。0.0.48 修复了getDeviceType错误导致设备列表为空的问题0.0.46 优化了工具描述便于 LLM 理解。mobile_get_screen_size/mobile_get_orientation/mobile_set_orientation屏幕尺寸与方向。0.0.13 开始支持方向切换。App 管理mobile_list_apps列出已安装应用Android 侧通过cmd package query-activities过滤出带 launcher activity 的应用见 packages/mobile-mcp/src/android.ts。mobile_launch_app/mobile_terminate_app启动/终止应用。0.0.47 起支持locale参数BCP 47 标签Android 侧在 Android 13 上通过cmd locale set-app-locales实现老版本静默忽略。mobile_install_app/mobile_uninstall_app安装/卸载。0.0.30 加入 app 安装卸载能力fork 版扩展了 Android 专属参数见下文第六节。屏幕交互mobile_take_screenshot/mobile_save_screenshot截图。0.0.20 引入save_screenshot供其他 MCP 服务器落盘复用0.0.43 增大了截图 buffer修复 4MB 截图的 bug0.0.23/0.0.24 修复了折叠屏等多屏设备的截图0.0.21 起 iOS 统一用 WDA 截屏。mobile_list_elements_on_screen列出带坐标的 UI 元素跨平台。Android 侧底层是uiautomator dumpXML 解析packages/mobile-mcp/src/android.ts 的collectElements仅保留有 text / content-desc / hint / resource-id / checkable 属性的节点并剔除宽高为 0 的节点iOS 侧 0.0.16 起支持 StaticText、Image 元素识别。mobile_click_on_screen_at_coordinates、mobile_double_tap_on_screen0.0.32 加入 Android/iOS 双击、mobile_long_press_on_screen_at_coordinates0.0.24 加入长按0.0.39 加入duration参数默认 500ms范围 1~10000ms、mobile_swipe_on_screen全部坐标类触控工具。输入与导航mobile_type_keys向聚焦元素输入文本submit参数控制是否回车提交0.0.11 起支持。Android 非 ASCII 文本通过 mobilenext devicekit 的剪贴板广播注入packages/mobile-mcp/src/android.ts 的sendKeys。mobile_press_buttonHOME / BACK / VOLUME_UP / VOLUME_DOWN / ENTER 以及 Android TV 的 DPAD 系列按键0.0.14 加入 Android TV dpad 导航支持。mobile_open_url打开 URL。录制与调试mobile_start_screen_recording/mobile_stop_screen_recording屏幕录制0.0.46 加入真机与模拟器/仿真器均支持。实现上通过mobilecli spawnCommand启动后台录制进程用activeRecordingsMap 管理生命周期停止时先 SIGINT、超时 5 分钟兜底 SIGKILLpackages/mobile-mcp/src/server.ts。mobile_list_crashes/mobile_get_crash崩溃报告0.0.53 加入。Android 专属fork 新增mobile_ui_dump、mobile_adb_pull、mobile_adb_push见第六节。远程设备可选当MOBILEFLEET_ENABLE1时注册mobile_list_remote_devices、mobile_allocate_remote_device、mobile_release_remote_device0.0.44 引入远程设备支持可在 Mobile Fleet 上分配 Android/iOS 设备。五、安全加固历程一个值得借鉴的演进样本CHANGELOG 是观察该项目安全意识的最佳窗口安全相关修复贯穿始终版本安全问题修复方式0.0.50open_url可打开任意 scheme默认仅允许 http/https需显式设置MOBILEMCP_ALLOW_UNSAFE_URLS1放开社区报告漏洞0.0.49截图/录屏保存路径穿越修复路径遍历社区报告漏洞0.0.52SSE 传输无认证新增MOBILEMCP_AUTHBearer token 认证未设置时启动告警0.0.52SSE 跨域/并发连接阻断跨域请求、拒绝并发连接而非静默替换、断开时清理 transport 以便重连0.0.51默认监听 0.0.0.0--port改为--listen [host:]port默认 localhost0.0.45Android shell 注入修复launchAppshell 转义、openUrlURL 转义0.0.25文本输入注入改进文本输入转义0.0.52CI 脚本注入通过环境变量传递github.ref_name多版本依赖漏洞fast-xml-parser、path-to-regexp、hono、modelcontextprotocol/sdk 等持续升级上述策略大多能在源码中直接印证URL 协议校验mobile_open_url在 packages/mobile-mcp/src/server.ts 中检查url.startsWith(http://) || url.startsWith(https://)否则抛出ActionableErrorSSE 防护startSseServer在 packages/mobile-mcp/src/index.ts 中实现 Bearer 校验req.headers.authorization ! Bearer token返回 401、跨域请求返回 403、重复连接返回 409shell 注入防护escapeShellText在 packages/mobile-mcp/src/android.ts 中转义\ 空格、管道、重定向符等全部 shell 特殊字符--listen参数解析支持[host:]port端口必须在 1~65535 整数范围内默认 host 为localhost。这些修复的共同特点是默认安全secure by default——新特性默认关闭或默认收紧需要用户显式 opt-in 才放开且对外部报告者致谢0.0.50、0.0.49 均致谢漏洞报告者。六、qwen-code fork 的本地化增强本仓库的 fork 在保持与上游同步的同时当前版本 0.20.1新增了几项面向 Qwen 系 Agent 的定制能力全部记载于 packages/mobile-mcp/README.md。1. 可选的 0-1000 相对坐标模式这是 fork 最核心的增强镜像了 cua-driver 的相对坐标 shim 设计。启用后所有坐标输入/输出归一化到 0-1000 刻度与 Qwen VL 模型computer_use/mobile_use的坐标约定对齐。环境变量变量取值默认说明MOBILE_MCP_COORDINATE_SPACE0关/1开0启用 0-1000 归一化坐标MOBILE_MCP_COORDINATE_SCALE任意正整数1000满刻度值mobile_use约定可设999工作原理实现见 packages/mobile-mcp/src/coord-norm.ts输入反归一化mobile_click_on_screen_at_coordinates、mobile_double_tap_on_screen、mobile_long_press_on_screen_at_coordinates、mobile_swipe_on_screen四个工具在真正执行前将 0-scale 输入换算回设备像素/逻辑点。换算函数normToPx为Math.round((norm / scale) * dim)并有越界校验超出[0, scale]直接报错提示请用归一化坐标swipe 的distance按滑动方向对应的轴上下按高度、左右按宽度换算。输出归一化mobile_list_elements_on_screen的元素坐标从像素换算到 0-1000mobile_get_screen_size报告为 1000x1000。屏幕尺寸在mobile_get_screen_size返回后被ingestScreenSizeFromResult解析并缓存到screenSizeCache坐标工具优先用缓存未命中时通过ensureScreenSize实时获取方向变更会触发invalidateScreenSize失效缓存。描述重写启用后工具描述中的 in pixels 自动替换为 in 0-scale normalized coordinatesserver的instructions也会追加归一化坐标使用说明引导模型先调用mobile_get_screen_size理解设备尺寸。默认关闭未配置时行为零变化完全向后兼容。归一化基准为getScreenSize()——iOS 是逻辑点Android 是物理像素shim 完全运行在 packages/mobile-mcp/src/server.ts底层android.ts/ios.ts等后端文件不被触碰。测试用例见 packages/mobile-mcp/test/coord-norm.test.ts例如normToPx(500, 800, 1000) 400中点映射、normToPx(333, 800, 1000) 266就近取整、hasCoordFields对四个坐标工具返回 true 而对mobile_take_screenshot返回 false。2. 扩展的 Android 安装选项mobile_install_app新增四个 Android 专属布尔参数映射到adb install标志实现见 packages/mobile-mcp/src/android.ts 的installApp选项类型定义在 packages/mobile-mcp/src/robot.ts 的InstallOptions参数标志说明默认值replace-r替换已存在的应用truegrant_permissions-g授予全部运行时权限falseallow_downgrade-d允许版本号降级falseallow_test-t允许安装测试 APKfalseiOS / 模拟器侧会静默忽略这些选项。3. Android 专属调试工具mobile_ui_dump通过uiautomator dump输出完整未过滤的 XML 视图树保留父子层级与全部节点属性区别于mobile_list_elements_on_screen的扁平 JSON支持--compressed缩减输出可指定output_path落盘。实现会重试最多 10 次以应对null root node returned by UiTestAutomationBridge的不稳定状态。mobile_adb_pull从设备拉取文件到本地。mobile_adb_push推送文件到设备默认仅允许推送到/sdcard/forcetrue才可越界且会校验本地文件存在。4. 遥测默认关闭上游的 PostHog 遥测在本 fork 中默认关闭需显式设置MOBILEMCP_ENABLE_TELEMETRY1才会上报packages/mobile-mcp/src/server.ts 的posthog函数先检查该开关。同时保留了MOBILEMCP_DISABLE_TELEMETRY环境变量以兼容上游约定。5. MCP 模型 Payload 过滤部分模型 API 路由会拒绝对话历史中包含特定厂商关键词的请求。fork 提供了MCP_MODEL_PAYLOAD_FILTER1开关在 mobile-mcp 边界启用可逆别名过滤packages/mobile-mcp/src/payload-filter.ts匹配文本被替换为__mcp_ref_hex__形式的引用令牌回传同一服务器时解码还原该过滤器默认关闭。注意被过滤的别名如果传给 shell 或其他 MCP 服务器不会在那里被解码。七、部署与配置实践1. MCP 客户端配置在 MCP 客户端如 Claude Code / VSCode / qwen-code 等支持 MCP 的 Agent 环境中标准配置方式详见 packages/mobile-mcp/README.md{ mcpServers: { mobile-mcp: { command: npx, args: [qwen-code/mobile-mcp] } } }启用相对坐标模式{ mcpServers: { mobile-mcp: { command: npx, args: [qwen-code/mobile-mcp], env: { MOBILE_MCP_COORDINATE_SPACE: 1 } } } }对特定路由启用 Payload 过滤{ mcpServers: { mobile-mcp: { command: npx, args: [qwen-code/mobile-mcp], env: { MCP_MODEL_PAYLOAD_FILTER: 1 } } } }2. 完整环境变量参考综合 CHANGELOG 与源码可用的环境变量汇总如下环境变量作用MOBILE_MCP_COORDINATE_SPACE启用 0-1000 相对坐标fork 新增MOBILE_MCP_COORDINATE_SCALE归一化满刻度默认 1000fork 新增MCP_MODEL_PAYLOAD_FILTER启用 MCP 响应厂商词过滤fork 新增默认关MOBILEMCP_ENABLE_TELEMETRY启用遥测上报fork 默认关MOBILEMCP_DISABLE_TELEMETRY禁用遥测上游变量MOBILEMCP_AUTHSSE 传输的 Bearer token 认证MOBILEMCP_ALLOW_UNSAFE_URLS允许open_url打开非 http/https 协议MOBILEFLEET_ENABLE启用远程设备池相关工具ANDROID_HOMEadb 所在目录$ANDROID_HOME/platform-toolsGO_IOS_PATH指定 go-ios 可执行文件路径3. 运行模式与前置条件CLI 入口packages/mobile-mcp/src/index.ts支持两种运行模式stdio默认mcp-server-mobile直接以标准输入输出与 MCP 客户端通信SSE--listen [host:]port启动 HTTP 服务GET /mcp建立 SSE 连接、POST /mcp提交消息默认 host 为localhost建议生产环境务必设置MOBILEMCP_AUTH。前置条件README 明确列出Android需 Android SDK Platform Toolsadb在 PATH 上或通过ANDROID_HOME定位packages/mobile-mcp/src/android.ts 的getAdbPath还会回退检查 macOS 的~/Library/Android/sdk与 Windows 的%LOCALAPPDATA%\Android\Sdk默认路径Windows 上始终使用adb.exeiOS 真机需 go-iosiOS 模拟器Xcode 模拟器运行时 mobilecli经 mobilewright 依赖自动安装首次使用会自动安装 agent。八、工程质量与发布实践CHANGELOG 还透露出值得借鉴的工程习惯可复现构建0.0.52CI 使用npm ci而非npm installtag 发布时移除npm update以保持 lockfile 完整性生产依赖锁定到精确版本测试框架迁移0.0.58从 mocha/nyc 迁移到 Playwright以减少依赖漏洞面本 fork 的测试同样基于 Playwright 运行见 packages/mobile-mcp/test 下的coord-norm.test.ts、payload-filter.test.ts、mobile-ui-dump.test.ts等优雅退出0.0.61捕获系统信号做干净的 v8 退出确保NODE_V8_COVERAGE输出被完整落盘stdio 模式在SIGINT/SIGTERM时process.exit(0)CI 最小权限0.0.53contents权限收窄为read并移除不必要的 Java 构建步骤依赖安全常态化几乎每个版本都伴随安全相关依赖升级形成了一种发布即安全检查的节奏。九、总结从 0.0.11 到 0.0.61mobile-mcp 走完了一条从能用到好用地用的路径统一了移动设备驱动mobilecli / mobilewright / Device Kit、补全了交互工具矩阵点按、双击、长按、滑动、方向、文本、按键、持续强化了安全边界认证、跨域、协议白名单、路径校验、注入转义并沉淀了可复现构建与 Playwright 测试的工程底座。而 qwen-code fork 在完全兼容上游的基础上通过 0-1000 相对坐标 shim 将移动端工具与 Qwen VL 的mobile_use坐标约定打通让模型可以稳定地在截图与坐标空间之间完成看图—定位—操作的闭环。对于任何希望让 LLM Agent 真正上手移动设备的开发者这个包既是一个可直接使用的 MCP 服务器也是一份研究移动端 Agent 工具设计的高质量参考实现。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
