AIRI 通过 MCP 让 LLM 操控安卓手机：airi-android 开发实录与 MCP 工具机制解读

AIRI 通过 MCP 让 LLM 操控安卓手机airi-android 开发实录与 MCP 工具机制解读【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI 是一套自托管的 AI 桌面伙伴项目。在 2025.04.22 的这期 DevLog 中作者 LemonNeko 记录了把一个能通过 ADB 与安卓手机交互的 MCP Serverairi-android从想法变成演示 Demo 的全过程从误把设备列表写成 Resource、到理解 MCP 中 Resource 与 Tool 的本质区别再到总结出截图 → UI 自动化定位 → 点击/滑动 → 重复的 LLM 操作手机通用循环并提出了游戏画面无法定位、长流程分步执行、动画等待与 AI 直接操控手机的安全问题等四个值得深思的开放问题。读完本文你将掌握 MCP 三大核心概念Resources / Prompts / Tools的实操辨析方法、用 FastMCP ppadb 编写安卓控制 Server 的入门写法以及 AIRI 桌面端当前已经落地的 MCP 配置与调用链路mcp.json配置格式、主进程会话管理、builtIn_mcpListTools/builtIn_mcpCallTool内置工具能够直接对照仓库源码继续深入。背景从桌面宠物到想让 AIRI 玩手机这篇 DevLog 的起点是 AIRI 形态的两次变化两个月前AIRI 的 Web 界面被移植到 Electron使其能以桌面宠物的形式出现在屏幕上后已重构为 Tauri 实现与此同时作者一直有一个搁置的想法——让 AIRI 使用手机。2025.04.20周末这个想法终于落地为一个可运行的 MCP Server 演示airi-android。这个 Server 通过 ADBAndroid Debug Bridge与安卓设备交互为 AIRI 提供基础的移动端交互能力。作者特别强调由于走的是标准 MCP 协议事实上大多数 LLM 都能通过它操作手机。除演示外它还被打包成了 Docker 镜像并提交到了公开的 MCP Server 列表供他人尝试。作者坦言最初的想法很简单写一些 Tool Calling 代码、改一改 Prompt、告诉 LLM我们能用这些工具操作手机就行了只是因为当时 MCP 生态火热最终选择了用 MCP 来实现。MCP 是什么Resources、Prompts、Tools 三大核心概念为了写 MCP Server必须先理解 MCPModel Context Protocol模型上下文协议。按作者在 DevLog 中的概括MCP 是一个**试图标准化应用如何向 LLM 提供上下文**的协议它提出了几个核心概念Resources资源Server 可以将数据和内容作为上下文提供给 LLM。Prompts提示词创建可复用的提示模板与工作流。Tools工具允许 LLM 通过你的 Server 执行动作。这三个概念中Resources 与 Tools 的边界最容易被初学者混淆而这篇 DevLog 恰好用一次真实的踩坑把两者的区别讲透了见下一节。值得一提的是AIRI 仓库当前的 MCP 集成也严格遵循这套概念划分渲染进程侧只暴露工具给共享 LLM 运行时见 packages/stage-ui/src/tools/mcp.ts工具的描述、输入 Schema 与调用入口都被建模为结构化的McpToolDescriptor与McpCallToolPayload这与 MCP 协议中 Tools 的描述 → 列表 → 调用流程一一对应。第一次踩坑设备列表到底该写成 Resource 还是 Tool作者用 Ruby on Rails 的资源概念做类比在 Rails 里用户是一种 resource那么 ADB 设备是不是也能当成 resource于是最初的实现是这样写的from mcp.server.fastmcp import FastMCP from ppadb.client import Client mcp FastMCP(airi-android) adb_client Client() mcp.resource(adb://devices) def get_devices(): return adb_client.devices()结果是错的。当作者让 Cursor 去获取设备列表时它完全不知道怎么操作。Cursor 的回答点出了关键它需要主动去检查当前有哪些设备连接——这是一个动作因此应该是一个Tool而不是 Resource。这个案例背后是 MCP 概念边界的一个实用判据Resource 是被动提供的只读上下文LLM 在需要背景信息时去读取它类似查询语义Tool 是 LLM 主动发起的一次调用/动作会触发 Server 侧的真实行为类似执行语义。列出当前连接的设备在语义上是每次连接状态都可能变化、需要现查现报的动作因而属于 Tool。按这个思路修正后的写法大致如下示意基于上述判据from mcp.server.fastmcp import FastMCP from ppadb.client import Client mcp FastMCP(airi-android) adb_client Client() mcp.tool() def get_devices(): return [d.serial for d in adb_client.devices()]AIRI 仓库中的工具建模也印证了同样的边界工具必须能被枚举和按名调用。在 packages/stage-ui/src/tools/mcp.ts 中McpToolDescriptor携带serverName、name、toolName、description与inputSchema而McpCallToolPayload只有name与arguments两个字段——即 LLM 侧永远先通过listTools发现工具再通过callTool携带 JSON 参数去执行这正是 MCP Tools 的动作语义在代码层面的落地。LLM 操作手机的通用循环截图 → 定位 → 点击/滑动 → 重复作者承认还没完全想清楚如何让 LLM 操作手机的最佳方案但给出了 Cursor 当前实际采用的操作范式这也是目前 LLM 操控图形界面最通用的循环截图用截图功能大致了解手机屏幕上有什么UI 自动化定位用 UI 自动化工具拿到想要操作的元素的精确位置点击或滑动对这个位置执行操作重复以上步骤循环直到目标达成。这套感知截图→ 解析UI 树/坐标→ 动作点击/滑动的闭环本质上与 MCP Server 侧需要暴露的能力一一对应一个screenshot类工具提供画面输入一个 UI 自动化类工具提供元素坐标一个tap/swipe类工具执行动作。AIRI 桌面端目前的 MCP 调用链也采用了同样的发现-调用两步模式共享层注册了两个内置工具builtIn_mcpListTools先枚举所有可用 MCP 工具与builtIn_mcpCallTool按名调用参数为 JSON 字符串格式为serverName::toolName具体实现见 packages/stage-ui/src/tools/mcp.ts。这里有一个值得注意的工程细节builtIn_mcpCallTool的arguments参数被声明为z.string()JSON 字符串而非结构化对象代码注释解释了原因——z.unknown()会产出{}缺少type键而z.record()会产出propertyNames两者都会被 OpenAI 拒绝。也就是说给 LLM 的 Tool Schema 必须经过真实运行时的校验这也是开发 MCP 工具时容易忽略的兼容性陷阱。四个悬而未决的问题游戏、长流程、动画与安全在看起来目前效果还行的同时作者提出了四个尚未解决的疑问这些也是让 LLM 直接操作手机走向实用化的核心挑战纯图形渲染应用无法定位如果屏幕上是一个直接使用图形 API 绘制内容而非原生 UI 组件的游戏UI 自动化工具拿不到元素位置也就无法操作。这指向 UI 树信息的失效场景需要依赖纯视觉方案。LLM 响应长度限制下的分步执行复杂操作可能无法在单次响应内完成能否像 airi-factorio 那样在每一步执行完成后自动通知 LLM触发下一步动作这本质上是一个多轮工具调用 事件驱动的编排问题。动画与截图的时序问题某些 App 的动效较酷操作后立刻截图可能看不到效果。是否需要等待一段时间再截图还是直接改用屏幕录制这涉及感知层的数据形态选择。AI 直接操作手机的安全风险把手机控制权交给 AI 会带来哪些风险这是权限模型与沙箱设计层面的开放问题。这四个问题恰好覆盖了感知、编排、时序、安全四个维度可以作为后续实现手机操控能力时的设计 checklist。与 AI 结对编程Cursor 既是客户又是同事作者形容这是第一次和人类一起与 AI 结对写代码因为目标是要让 AI 使用自己写的工具AI 变成了自己的客户需要不断根据它的反馈调整代码同时也变成了自己的同事需要一起思考、一起解决问题。期间还学到了一些实用小技巧比如用命令行直接启动安卓模拟器从而不必打开 Android Studioemulator -avd Pixel_6_Pro_API_34这条命令直接以-avd指定虚拟设备名称启动模拟器可以显著降低内存压力对内存敏感的开发环境非常友好。下一步计划把桌面宠物接上 MCP与 AIRI 的 MCP 基建对照作者的下一步计划是把 AIRI 桌面宠物连接到 MCP Server 上看它自己想做什么——比如自己打开 Telegram 和我们聊天就像 ReLU 现在做的那样但不需要依赖 Telegram 的官方 API。这个桌面端接入 MCP Server的设想在 AIRI 当前仓库中其实已经有相当完整的基建可以作为落地时的直接对照配置层桌面端在用户数据目录下维护mcp.json默认内容为{ mcpServers: {} }每个 Server 条目由严格 Zod Schema 校验字段包括command必填非空字符串、args、env、cwd与enabled可选见 apps/stage-tamagotchi/src/shared/mcp-config.ts。形如{ mcpServers: { airi-android: { command: docker, args: [run, --rm, -i, airi-android], enabled: true } } }主进程会话管理层McpStdioManager负责ensureConfigFile、openConfigFile、applyAndRestart、listTools、callTool、stopAll等完整生命周期基于modelcontextprotocol/sdk的Client与StdioClientTransport建立 stdio 连接并设置单次请求超时 10 秒、总超时 15 秒、测试 stderr 最大 16000 字符见 apps/stage-tamagotchi/src/main/services/airi/mcp-servers/index.ts。工具名使用::作为 Server 与工具名的分隔符并对stdio::等传输前缀做了容错解析。渲染进程接入层useTamagotchiMcpToolsStore把 MCP 工具注册进共享 LLM 工具运行时工具 ID 统一加mcp:前缀通过refresh/dispose动态增删见 apps/stage-tamagotchi/src/renderer/stores/tools/mcp.ts。UI 层设置页已有 MCP 模块目前标注为 WIP并配套McpServerForm、McpJsonEditor、McpConnectionTestPanel等组件见 apps/stage-tamagotchi/src/renderer/pages/settings/modules/components/跨窗口的 MCP 连接状态则通过settings/mcp/server-cmd、settings/mcp/server-args、mcp/connected等 localStorage 键同步见 packages/stage-ui/src/stores/mcp.ts。可以看到把 airi-android 这类 Server 挂进 AIRI只需在mcp.json里新增一条command/args配置点击应用重启后LLM 即可通过builtIn_mcpListTools发现其工具并调用这正与 DevLog 中让 AIRI 自己决定要做什么的设想衔接。结语这期 DevLog 篇幅不长、略显随性却浓缩了给 LLM 造工具这一新开发范式的核心体验理解 MCP 的 Resource / Prompt / Tool 划分需要靠真实调用去检验AI 操作手机要走截图 → 定位 → 动作 → 重复的感知-动作闭环而游戏定位、分步编排、动画时序与安全风险仍是开放问题。对于想在 AIRI 生态里复现这套能力的开发者仓库中的 MCP 配置校验、主进程会话管理与共享工具注册三层代码已经给出了可以直接借鉴的完整骨架。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考