AYA 是一款跨平台的 Android adb 桌面工具。本分支在其基础上内置了 MCP（Model Context Protocol）服务，把设备能力封装成 42 个 aya_* 工具，让 CodeBuddy、WorkBuddy、Claude 等 AI 客户端直接用自然语言操控已连接的 Android 设备。

需要 Root 或安装 App 吗？

不需要 Root，也不需要在手机上安装任何 App。AYA 通过 adb 与设备通信，只需开启 USB 调试（或无线调试）并在电脑上启动 AYA。

数据会上传到云端吗？

不会。MCP 服务只监听 127.0.0.1，校验 Origin，请求体限制 2MB，并通过 Bearer Token 鉴权；令牌可随时在设置中重置。写操作默认隐藏，需手动开启“允许写入操作”。

和原版 AYA 有什么区别？

原版 AYA 提供投屏、文件管理、日志、性能、Shell 等桌面端能力；本分支完全保留这些能力，只新增了 MCP 服务层（设置 → MCP），不改变原有使用习惯。

MCP 服务已内置于 AYA 桌面端

让 AI 直接操控你的 Android 设备

AYA 内置一个只监听 127.0.0.1 的 MCP（Model Context Protocol）服务，把手机能力封装成 42 个 aya_* 工具。在 CodeBuddy、WorkBuddy、Claude 里说一句“打开设置，把字体调到最大并截图”，剩下的交给 AI —— 不用再写脚本、跑命令、粘输出。

3 步接入 MCP 查看 42 个工具了解原版 AYA

42MCP 工具（16 只读 / 26 写）

< 1 min从开启到 AI 接管设备

127.0.0.1仅本机监听，不出网

Win / mac / Linux跨平台 Electron 桌面端

Model Context Protocol

MCP 是什么？为什么手机需要它

MCP 是 AI 客户端与工具之间的开放协议。过去 AI 只能“教你怎么操作手机”，现在它能自己调工具、看结果、再决定下一步。 AYA MCP 就是把 adb 的几十年积累，翻译成 AI 听得懂、调得动的 42 个标准工具。

会说人话就够了

不用记 adb shell am start -n ...。自然语言描述目标，AI 自己选择并组合工具，失败还会根据返回的错误自我纠正。

看得见界面，不只是命令

aya_ui_dump 返回带坐标与索引的 UI 层级树，aya_screencap 回传截图。AI 既读结构也看画面，点得准、判得对。

一次调用干完一串动作

aya_batch 串行执行最多 20 个动作，中间不经过模型思考，彻底避开播放器控制栏、Toast 这类 1–3 秒就消失的控件。

关于二次开发：本分支基于开源项目 AYA（ liriliri/aya，作者 surunzi，AGPL-3.0）二次开发，完整保留原版投屏、文件管理、日志、性能、Shell 等桌面能力，仅新增 MCP 服务层：设置 → MCP → 启用即可，不影响原有使用习惯。

Tool Reference

42 个工具，覆盖一台手机的全部能力

工具名统一以 aya_ 开头。16 个只读工具默认开放；26 个写工具需在设置中勾选“允许写入操作”后才会出现在客户端。

设备与画面 6 个工具

工具	权限	说明
`aya_list_devices`	只读	列出在线设备，标出 AYA 当前选中设备
`aya_device_info`	只读	机型、系统版本、分辨率、CPU / 内存 / 电量摘要
`aya_screencap`	只读	截图（默认缩放到 900px 宽，返回 `scale`）
`aya_ui_dump`	只读	UI 层级树，节点带 `bounds` / `center` / 全局索引 `i`
`aya_current_app`	只读	前台包名与 pid
`aya_set_font_scale`	写	设置系统字体缩放（0.5–2.0），返回改动前后值

交互 7 个工具

工具	权限	说明
`aya_tap`	写	坐标 / `nodeIndex`+`snapshotId` / `text`·`id`·`desc` 选择器，默认点完立即回传新界面
`aya_tap_text`	写	`aya_tap{text}` 的语义化快捷方式
`aya_batch`	写	一次调用串行执行最多 20 个动作，最后统一回传界面
`aya_wait_for`	只读	轮询等待控件出现 / 消失，命中或超时都返回当前界面
`aya_swipe`	写	滑动，`duration` 默认 300ms
`aya_key`	写	`back` / `home` / `enter` / `recent` / `volume_up` 等按键
`aya_text`	写	输入文本（仅可打印 ASCII，中文走 `aya_shell` + 输入法）

应用管理 8 个工具

工具	权限	说明
`aya_list_packages`	只读	包名列表（apk 路径、是否系统应用），可关键字过滤 / 仅第三方
`aya_app_info`	只读	版本号、sdk、安装 / 更新时间、启用状态、运行状态与 pid
`aya_start_app`	写	启动 Launcher Activity
`aya_stop_app`	写	`am force-stop` 强杀进程
`aya_clear_app_data`	写	`pm clear` 清空数据与缓存（不可撤销）
`aya_set_app_enabled`	写	启用 / 禁用应用（`pm enable` / `pm disable-user`）
`aya_install_app`	写	安装本机 apk（覆盖安装保留数据）
`aya_uninstall_app`	写	卸载应用（含数据）

性能与进程 2 个工具

工具	权限	说明
`aya_performance`	只读	CPU 各核负载 / 温度、内存占用、电量、开机时长、前台帧率
`aya_list_processes`	只读	运行中的进程名与 pid，可关键字过滤

文件 7 个工具

工具	权限	说明
`aya_list_dir`	只读	列目录（目录优先，含大小 / 时间 / mime）
`aya_stat_path`	只读	路径属性：是否存在、文件 / 目录、大小、权限
`aya_pull_file`	写	设备 → 本机，省略目标路径时存到临时目录 `aya-mcp/`
`aya_push_file`	写	本机 → 设备
`aya_delete_path`	写	删除文件 / 目录，目录必须显式 `recursive: true`
`aya_make_dir`	写	`mkdir -p`
`aya_rename_path`	写	重命名 / 移动

日志与命令 3 个工具

工具	权限	说明
`aya_logcat`	只读	日志快照，按级别 / 标签 / 关键字过滤，返回结构化条目
`aya_clear_logcat`	写	清空日志缓冲区
`aya_shell`	写	adb shell，30s 超时，输出截断 20000 字符

端口映射与 WebView 4 个工具

工具	权限	说明
`aya_list_ports`	只读	列出 `adb forward` / `adb reverse` 的全部映射
`aya_add_port`	写	新增映射，`direction`: `forward`（主机→设备）或 `reverse`（设备→主机）
`aya_remove_port`	写	按 `local` / `remote` 移除，`all: true` 清空该方向
`aya_list_webviews`	只读	列出应用内 WebView 的调试页面（title / url / devtoolsFrontendUrl）

录屏与投屏 5 个工具

工具	权限	说明
`aya_start_recording`	写	设备端 `screenrecord` 后台开录，可设时长（≤180s）、码率、分辨率
`aya_stop_recording`	写	停止录制并拉回本机，返回路径、大小、时长
`aya_recording_status`	只读	是否在录、已录时长、剩余时长、设备端文件大小
`aya_cast_window`	写	打开 / 关闭 / 重启 AYA 投屏窗口
`aya_cast_settings`	写	读取或修改投屏码率、最大边长，`restart: true` 立即生效

点击定位小贴士：aya_ui_dump 返回的 i 是未过滤完整树的 DFS 前序号，过滤只减少返回节点、不改变 i。snapshotId 60s 过期，任何输入类工具执行后立即失效，返回 STALE_SNAPSHOT 时重新 dump 即可。

Quick Start

三步，把手机交给 AI

无需 Root，手机上也无需安装任何 App。只要开启 USB 调试 / 无线调试，电脑上跑着 AYA 就行。

开启 MCP 服务

设置 → MCP → 勾选「启用 MCP 服务」。服务随应用启动自动拉起，默认端口 7788，同时生成访问令牌。需要点击、安装、shell 等能力时，再勾选「允许写入操作」。

复制配置片段

弹窗里直接给出三种写好的配置：stdio（推荐）、stdio（无 env）、HTTP。点「复制」，片段里已带好端口与令牌。

粘贴到 AI 客户端

CodeBuddy：设置 → MCP → 添加 MCP，粘贴到 ~/.codebuddy/mcp.json。其他支持 MCP 的客户端同理，重连后即可看到 aya_* 工具列表。

// AYA 设置 → MCP → 查看配置，直接复制即可（令牌已填好）
{
  "mcpServers": {
    "aya": {
      "type": "stdio",
      "command": "C:/Path/To/AYA.exe",      // 客户端用 AYA 自带的 node 启动桥接脚本
      "args": [
        "resources/mcp/aya-mcp-stdio.cjs",
        "--url=http://127.0.0.1:7788/mcp",
        "--token=<your-token>"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1",
        "AYA_MCP_URL": "http://127.0.0.1:7788/mcp",
        "AYA_MCP_TOKEN": "<your-token>"
      },
      "description": "AYA Android device control"
    }
  }
}

// 客户端找不到 AYA.exe 时，用系统 node 直接跑桥接脚本
{
  "mcpServers": {
    "aya": {
      "type": "stdio",
      "command": "node",
      "args": [
        "resources/mcp/aya-mcp-stdio.cjs",
        "--url=http://127.0.0.1:7788/mcp",
        "--token=<your-token>"
      ],
      "description": "AYA Android device control (no env fallback)"
    }
  }
}

// HTTP 无状态：切换写权限后需重新 tools/list（或重连）
{
  "mcpServers": {
    "aya": {
      "type": "http",
      "url": "http://127.0.0.1:7788/mcp",
      "headers": { "Authorization": "Bearer <your-token>" },
      "description": "AYA Android device control"
    }
  }
}

桥接脚本通过 SSE 收到 notifications/tools/list_changed 后会通知客户端热刷新；客户端不支持热更新时重连一次即可。端口被占用可在设置里改（1024–65535），令牌泄露可点「重置访问令牌」。

Use Cases

AI 能替你干这些活

下面每条都是真实可跑的工具组合，把「写脚本 → 运行 → 解析输出」的往返压缩成一句话。

自动化回归与冒烟

“装上新构建，依次走完登录 → 下单 → 支付，每步截图，失败就把 logcat 的 E 级日志带回来。”——aya_install_app → aya_batch → aya_screencap → aya_logcat。

UI 走查与适配检查

“把字体缩放到 2.0，逐个页面截图，列出文字被截断的控件。”——aya_set_font_scale + aya_ui_dump + aya_screencap。

崩溃与 ANR 排查

“清一下日志，复现这个操作，把 E 级日志和 /sdcard 下的 tombstone 拉回本机。”——aya_clear_logcat → 操作 → aya_logcat{level:'E'} → aya_pull_file。

复现视频与缺陷留证

“开始录屏，执行刚才那串操作，停录，把 mp4 存到桌面。”——开录 → aya_batch → aya_stop_recording，全程不碰鼠标。

性能体检

“滚动首页 30 秒，采样帧率和内存，告诉我掉帧的时段。”——aya_performance + aya_swipe + aya_list_processes。

H5 / 混合应用调试

“列出前台应用的 WebView，把 devtools 调试地址给我。”——aya_list_webviews 自动 adb forward 并访问 /json；配合 aya_add_port 可把手机端口映射到本机。

Security

默认收紧，能力给你、风险留给自己可控

MCP 服务跑在你自己的电脑上，设备数据不出本机；危险能力需要你显式授权。

只监听 127.0.0.1：外部网络无法访问，端口范围 1024–65535，默认 7788。
Bearer Token 鉴权：令牌首次开启时生成并持久化，可随时「重置访问令牌」。
写操作默认隐藏：26 个写工具需勾选「允许写入操作」才暴露，只读工具始终可用。
Origin 校验 + 2MB 请求体限制：防止网页跨站调用与超大 payload 打爆服务。
shell 有兜底：aya_shell 30s 超时、输出截断 20000 字符，破坏性命令仍由客户端按 readOnlyHint 弹确认框。

FAQ

常见问题

AYA MCP 和原版 AYA 是什么关系？

本分支基于开源项目 AYA（liriliri/aya，作者 surunzi，AGPL-3.0）二次开发，完整保留原版投屏、文件管理、日志、性能、Shell、应用管理等桌面能力，只新增了 MCP 服务层。关闭 MCP 开关时，它就是原版 AYA。

需要 Root 或在手机上安装 App 吗？

都不需要。AYA 通过 adb 与设备通信，只需在手机上开启 USB 调试（或无线调试）并授权本机调试。

客户端只看到 16 个只读工具怎么办？

说明未勾选「允许写入操作」。勾选后重连 MCP 服务，或等待 tools/list_changed 热刷新，即可看到全部 42 个工具。

aya_tap 返回 STALE_SNAPSHOT？

UI 快照 60s 过期，且任何输入类工具执行后会立即失效。重新 aya_ui_dump 拿到新的 snapshotId 和 nodeIndex 再点。

点开播放器控制栏后读不到控件？

这类控件只停留 1–3 秒。用 aya_tap 默认的 withUi（点完立刻抓一帧）、或把「点击 → 等待 → 再点击」合成一次 aya_batch，就能避开模型思考延迟。

MCP 开关打不开，提示端口被占用？

默认 7788 被其他进程占了。在设置里换一个 1024–65535 的端口重试，设置项会直接显示错误原因。

支持哪些 AI 客户端？

任何支持 MCP 的客户端都可以，包括 CodeBuddy、WorkBuddy、Claude Desktop、Cursor、Cline 等。配置片段在 AYA 设置里一键复制。

现在就让 AI 帮你操作手机

下载 AYA（含 MCP 分支），设置 → MCP → 启用，复制配置粘贴进你的 AI 客户端。整个过程不到一分钟。

下载 AYA 查看接入配置