这是一份专为 LLM（如 Claude Code、Cursor、GPT-4）阅读和理解优化的标准系统设计文档。你可以直接将这份文档喂给代码生成大模型，它能精准理解上下文并生成高质量的代码。 系统设计文档：Android Native MCP Server (基于 A11y)
- 项目概述 (Project Overview) 项目名称: Droid-MCP-Native 项目目标: 在 Android 设备端本地运行一个标准的 MCP (Model Context Protocol) Server，通过 HTTP Stream 传输向局域网内的 MCP Client（如 Claude）暴露 Android 系统的 UI 检视与操控能力。 核心技术栈: 语言: Kotlin UI 框架: Jetpack Compose 网络服务: Ktor Server (Netty / CIO) MCP 协议实现: 官方 modelcontextprotocol/kotlin-sdk 系统控制: Android AccessibilityService (A11y) 后台保活: Android ForegroundService
- 系统架构 (System Architecture) 系统采用单体 APK 架构，内部分为三层：UI 层、服务层、执行层。 Plaintext
[ MCP Client (Claude/Cursor) ]
| (LAN / Wi-Fi)
| HTTP Stream /mcp (MCP 单端点)
V
+---------------------------------------------------+
| Android APK |
| |
| [ 1. Presentation Layer (MainActivity) ] |
| - 显示内网 IP:Port |
| - 显示当前注册的 MCP Tools 列表 |
| - 权限状态指示器 (A11y, 通知权限) |
| |
| [ 2. Service Layer (McpForegroundService) ] |
| - 内置 Ktor Server 监听动态端口 |
| - 承载 modelcontextprotocol/kotlin-sdk 实例 |
| - 承载 MCP Stream 会话与生命周期 |
| |
| [ 3. Execution Layer (A11yActionDispatcher) ] |
| - 获取屏幕节点 (AccessibilityNodeInfo) |
| - 执行手势 (dispatchGesture) |
| - 执行全局动作 (GLOBAL_ACTION_HOME/BACK) |
+---------------------------------------------------+
- 核心模块设计 (Core Modules)
3.1 McpForegroundService (MCP 服务端)
职责: 作为 Android 前台服务运行，确保 Ktor 服务器在应用退到后台时不被系统休眠。
网络协议: 严格遵循 MCP 规范的 HTTP Stream 传输。
路由: 使用单端点
/mcp承载 MCP 会话与消息。 SDK 集成: 使用 kotlin-sdk 的 Server 类构建，通过官方 Ktor 扩展挂载 MCP 路由。 3.2 A11yService (无障碍服务执行器) 职责: 继承 AccessibilityService，是实际与 Android 系统 UI 交互的模块。 数据通信: 由于 A11yService 和 McpForegroundService 是独立的组件，需通过单例 (Singleton) 或 Kotlin Coroutines SharedFlow/Channel (如 ActionDispatcher 类) 进行指令下发和结果回调。 3.3 MainActivity (可视化面板) 职责: 提供直观的运行状态。 核心 UI 元素: Server Status: 运行中/已停止 (🟢/🔴)。 Network Info: http://<WIFI_IP>:/mcp (提供一键复制按钮)。 Tools List: 动态读取 MCP Server 实例中的 tools 列表并展示其 name 和 description。 Permission Requests: 检查并引导开启无障碍权限的按钮。 - MCP Tools 接口契约 (API Contract) 以下是注册到 MCP Server 的核心 Tools 定义，Client 通过调用这些 Tool 来控制手机。 Tool Name Input Schema (JSON) 返回值 (String/JSON) 功能描述 (Description for LLM) get_ui_tree {} (无参数) 序列化的精简 UI 树 捕获当前屏幕布局，提取可交互节点的 node_id、文本、描述和边界。 click_node {"node_id": "string"} 执行结果状态 根据 get_ui_tree 返回的 node_id，计算其中心坐标并模拟点击。 input_text {"node_id": "string", "text": "string"} 执行结果状态 点击指定节点并输入提供的文本字符串。 swipe {"direction": "up/down/left/right"} 执行结果状态 在屏幕中央执行对应方向的全局滑动操作。 system_action {"action": "home/back/recents"} 执行结果状态 触发 Android 系统级导航操作。
- 核心数据结构 (Data Structures) 为了降低 LLM 的 Token 消耗，get_ui_tree 返回的数据必须经过剪枝 (Pruning)，排除不可见或无意义的节点。 get_ui_tree Response Model (LLM 视图): JSON
{ "screen_resolution": {"width": 1080, "height": 2400}, "current_package": "com.tencent.mm", "nodes": [ { "node_id": "n_001", "class_type": "Button", "text": "发送", "content_desc": "", "clickable": true, "bounds": {"x_center": 950, "y_center": 2200} }, { "node_id": "n_002", "class_type": "EditText", "text": "", "content_desc": "聊天输入框", "clickable": true, "bounds": {"x_center": 400, "y_center": 2200} } ] }
注：node_id 是 APK 在内存中生成的临时短 ID（如基于 Hash 或自增），避免将复杂的 Android 原生 ID 暴露给大模型。
6. 关键交互流程 (Workflows)
6.1 Server 启动流程
用户打开 APK，触发 MainActivity。
检查 Wi-Fi 连接，获取局域网 IPv4 地址。
检查并请求 A11y 权限。
启动 McpForegroundService，初始化 Server 实例并注册 Tools。
启动 Ktor 引擎监听动态端口，绑定 MCP HTTP Stream 路由 /mcp。
UI 状态更新为“Server Running”，显示 IP 和 Tools 列表。
6.2 Tool Call 寻址与执行流程 (以点击为例)
Client 通过 MCP 会话调用 tools/call（如 click_node）。
Ktor 路由将消息交给 Kotlin MCP SDK。
MCP SDK 路由到 click_node 的处理函数。
处理函数通过 ActionDispatcher 将指令传递给后台运行的 A11yService。
A11yService 根据 n_001 在缓存树中查找到对应的屏幕坐标，调用 dispatchGesture 模拟点击。
执行完毕后，协程恢复，MCP SDK 向 Client 返回 ToolResult。
7. 约束与注意事项 (Constraints & Notes for LLM generation)
线程安全: Ktor 请求在后台线程执行，而某些 A11y 操作可能需要在主线程或特定协程上下文中调度。请合理使用 Dispatchers.Main 和 Dispatchers.IO。
内存泄露防护: 缓存的 AccessibilityNodeInfo 必须在屏幕变化或 AccessibilityEvent.TYPE_WINDOW_STATE_CHANGED 时及时 .recycle() 和清空。
网络权限: 必须在 AndroidManifest.xml 中声明 INTERNET, ACCESS_WIFI_STATE, FOREGROUND_SERVICE，以及为 A11y 服务配置 XML meta-data。