auto_control/doc/MCP_DESIGN.md

MCP 手机控制（Mobile Control MCP Server）设计文档

状态：设计稿 / 演进记录——凡与实现不符处，以 MCP.md（使用手册，含 20 个工具的权威清单）与 mcp_server/ 代码为准。 本文保留设计取舍与里程碑，便于回溯"为什么这么做"；文中的"演进备选"均未落地。 最后核对：2026-09-10（对照 dev 现状）。

1. 背景与目标

平台（auto_control，生产 220:18050）已具备完整的手机远程控制与自动化能力：设备池管理、u2 控制（tap/swipe/key/输入/剪贴板）、minicap 看屏（截图/流）、uiautodev 元素树、RapidOCR、任务调度与动作编辑器。

本设计的目标：新增一个 MCP Server，把平台能力以 MCP 协议暴露给多模态 AI（Claude 等），使 AI 能像人一样"看到手机屏幕 → 理解 → 操作 → 再看到"地闭环控制手机。

核心判断：平台能力全部已有，MCP Server 是薄封装层——主要工作在：工具规格设计、多模态图像链路、认证与安全、部署。

2. 术语

术语	说明
MCP	Model Context Protocol，模型上下文协议（客户端-服务器，工具调用）
Tools	MCP 暴露的可调用能力（本设计按 L1/L2/L3 分层）
serial	设备标识，如 192.168.20.66:5555（设备池唯一主键）
平台	指 auto_control web 服务（18050）及其 core 层能力
宿主	MCP Server 运行进程/容器

3. 总体架构

┌──────────────┐   MCP (Streamable HTTP / stdio)   ┌──────────────────┐
│  多模态 AI    │ ────────────────────────────────▶ │   MCP Server     │
│ Claude Desktop│   tools + image content block    │  （与平台同容器） │
│ Claude Code  │ ◀──────────────────────────────── │  mcp_server/ 包  │
└──────────────┘   截图图像 / JSON 结果             └────────┬─────────┘
                                                            │ 内部调用
                                                            ▼
                                                 ┌──────────────────┐
                                                 │ auto_control     │
                                                 │ 18050 REST API   │
                                                 │ （登录会话 token）│
                                                 ├──────────────────┤
                                                 │ core 层能力：     │
                                                 │ u2 / minicap /   │
                                                 │ uiautodev / OCR /│
                                                 │ 任务调度 / 设备池 │
                                                 └──────────────────┘

• 图像方向：MCP 协议支持 image content block（base64），截图以此返回，多模态模型原生可读——这是"AI 看到手机"的关键链路。
• 控制方向：AI 返回结构化工具调用（tap/swipe/type…），MCP Server 转发平台执行。
• 循环：截图 → 模型视觉推理 → 工具调用 → 平台执行 → 截图验证。

4. 平台现有能力复用清单

平台能力	现有入口	MCP 复用方式
设备列表/状态	GET /api/status、/api/devices/pool	MCP server 内部 HTTP 调用（带会话）
截图	GET /api/screen/thumb?serial=（单帧 JPEG）	直接转发为 image block（亦可直连 core u2 screenshot）
看屏流	/api/screen/stream（MJPEG）	M0-M2 不需要；M3 可选（视频理解场景）
点击	POST /api/screen/tap {serial,x,y}	封装 tool tap
滑动	POST /api/screen/swipe	封装 swipe
按键	POST /api/screen/key	封装 press_key
输入文字	设备端 Agent 通道（core.clipboard_helper）+ u2 input	封装 type_text
剪贴板	POST /api/tools/clipboard/set（设备端 Agent 通道）	封装 set_clipboard
元素树	GET /api/uiauto/...（uiautodev）	封装 get_ui_tree
OCR	core.ocr（RapidOCR）	封装 ocr_screen
打开 App	u2 app_start（经任务层/直连）	封装 open_app（走 core device 直连）
设备在线状态/亮熄屏	/api/device/screen_all、dumpsys	封装 screen_state/wake

决策：MCP Server 优先走 HTTP API（薄封装，认证简单、与平台解耦、平台安全逻辑全复用）。对延迟敏感且 HTTP 无入口的能力（u2 直连截图/输入），经平台 core 模块进程内调用或新增少量只读端点，不绕过平台安全层。

5. MCP Server 设计

5.1 技术栈

• 语言/运行时：Python 3.11（与平台一致）
• 框架：FastMCP（fastmcp，官方 SDK 之上，装饰器式 tools，自带 Streamable HTTP/stdio 双传输）
• 依赖：fastmcp（requirements.txt 已含，>=2.0）、httpx、Pillow（图像处理）、mcp[cli]（设计依赖，未落地——当前 requirements 未含，仅 fastmcp）
• 日志：logging → 平台同款格式（时间/级别/模块）

5.2 进程与容器

实现现状：当前 MCP 与 web_server 同容器，由 scripts/start.sh 后台拉起（MCP_ENABLED=1 默认，=0 可关），监听 8033。下方独立容器方案为演进备选。

• 独立容器 mcp-server（220 docker-compose 追加），image python:3.11-slim（演进备选）
• 挂载：无数据挂载（无状态，配置走环境变量）；网络 host 或独立端口（候选：8033，避免与 18050/18051 冲突）
• 独立于 auto_control 重启，互不阻塞；MCP Server 崩溃不影响平台，平台不可用时 MCP tools 返回明确错误

5.3 配置（环境变量）

变量	默认	说明
MCP_PLATFORM_URL	http://127.0.0.1:18050	平台地址
MCP_PLATFORM_USER / MCP_PLATFORM_PASS	空	平台登录账号（admin）
MCP_ALLOW_WRITE	0	写操作总开关（0=只读感知，1=可操作）
MCP_ALLOWED_SERIALS	空=全部	设备白名单（逗号分隔；为空时自动=设备池内设备）——设计目标，代码未实现（实现仅校验 serial 非空，见 §8.3 注）
MCP_HTTP_HOST	0.0.0.0	HTTP 监听地址
MCP_HTTP_PORT	8033	HTTP 传输端口
MCP_PLATFORM_TIMEOUT	30	平台请求超时（秒）
MCP_SCREENSHOT_WIDTH	540	截图宽度（等比缩放，控图像 token 成本）
MCP_JPEG_QUALITY	70	截图 JPEG 质量
MCP_AUDIT_FILE	/var/log/mcp/audit.log	审计日志路径

MCP_ENABLED 由 scripts/start.sh 消费（默认 1），非 MCP 进程内配置；MCP_PLATFORM_PASS 在 start.sh 兜底 admin123，改 admin 密码须同步（见 doc/MCP.md）。

6. Tools 规格

命名空间 de_（device）前缀避免与常见工具冲突。全部工具对未配置白名单/离线设备返回明确错误，不做静默跳过。

实现现状对照（本节以下是设计规格；实际实现以 mcp_server/ 与 doc/MCP.md 为准，主要差异）：

• de_screen_state 未独立实现：并入 de_screenshot 返回的 screen_state 字段
• 实际另有（设计稿未列）：de_tap_text / de_tap_element / de_stop_app / de_read_clipboard / de_foreground_app / de_list_apps / de_list_tasks
• de_type_text 实际签名 (serial, text)，走 u2 EditText.set_text（非设计稿的 ClipInject+paste 优先）
• de_tap 坐标语义已是截图坐标系、server 按比例换算原生（非设计稿「原生像素、调用方自换算」）
• de_open_app 是 adb monkey 直启（非 u2 app_start）
• de_find_and_tap / de_wait_until / de_get_task_state 未实现；语义点击由 de_tap_text / de_tap_element 承担
• 平台级工具层未实现：任务 CRUD/提交、分组/设备池/自定义动作/APK/备份等 REST 只给前端用，未 MCP 化；补齐规划见 doc/AI_TASK_GEN.md §9——P0 只补 list_task_types / list_groups / list_pool + submit_task（校验不落库），不暴露写 CRUD，维持「AI 提案 → 人工确认」

L1 感知层

de_list_devices

• 描述：列出可控制设备及其状态（在线/任务/型号/前台 App）
• 返回：[{serial, model, online, task_job, worker_status, foreground_app, screen_state}]
• 错误：平台不可达 → platform_unavailable

de_screenshot(serial: str) -> image

• 描述：截取设备当前屏幕（JPEG），返回 image content block；同时返回 width/height/serial 元信息
• 实现：平台 /api/screen/thumb（X-Screen-State 头复用判断亮熄屏）；失败（离线/超时）→ 明确错误
• 图像规格：宽 ≤ MCP_SCREENSHOT_WIDTH（默认 540），质量 MCP_JPEG_QUALITY；需保证图像方向正确（设备可能横竖屏，含 EXIF 或由调用方按截图尺寸推断）
• 限制：截图频率 ≥ 1s/次（防 AI 疯狂截图），可配置（未落地：现状无频率限制）

de_ui_tree(serial: str) -> str

• 描述：获取当前界面元素树（扁平 JSON：resource-id/text/content-desc/class/bounds），供定位
• 返回：文本 JSON（大树截断至 MCP_UI_TREE_MAX 字符，默认 20000，防 context 爆炸）
• 空界面/无元素 → 明确错误

de_ocr(serial: str) -> str

• 描述：OCR 识别当前屏幕文字，返回 [{text, score, box}]
• 场景：图片/画布/WebView 渲染文字（UI 树里没有的）

de_screen_state(serial: str) -> str

• 描述：亮屏/熄屏/未知

L2 操作层（受 MCP_ALLOW_WRITE=1 门控）

de_tap(serial, x: int, y: int)

• 坐标：设备原生分辨率像素（与截图 1:1 换算——调用方用截图尺寸按比例换算，server 不做猜测）

de_swipe(serial, x1,y1,x2,y2, duration: float=0.2)

de_press_key(serial, key: str)

• key ∈ back/home/recent/menu/power/enter/delete…

de_type_text(serial, text: str, clear_first: bool=True)

• 实现：优先设备端 Agent 通道（core/clipboard_helper.inject_clipboard 语义：写入剪贴板 + paste 到焦点输入框），失败回退 u2 input
• 中文/emoji 全支持（Agent 通道实测通过）

de_set_clipboard(serial, text: str)

• 写入设备剪贴板（设备端 Agent 的 am start 通道），读回验证

de_open_app(serial, package: str)

• 打开指定 App（u2 app_start）；package 需在已知清单或完全限定名

de_wake(serial) / de_sleep(serial)

L3 语义层（M2 里程碑）

de_find_and_tap(serial, target: str, by: "text"|"id"|"ocr"|"desc"=...)

• UI 树/OCR 定位含 target 的元素 → 自动点击其中心；多命中返回候选列表让 AI 选择
• 复用平台元素选择器策略（属性唯一/重复序号消歧）

de_wait_until(serial, condition: str, timeout: int=15)

• 轮询 OCR/UI 树直到出现条件文本（或消失），返回命中的坐标/文本

de_get_task_state(serial)（若二期接任务系统）

• 设备当前任务状态；可选 de_run_task(task_id) 需单独授权

工具返回约定

• 全部工具返回结构化 JSON：{ok: true, data: ...} 或 {ok: false, error: {code, message}}
• 错误码：platform_unavailable / device_offline / device_not_allowed / invalid_param / write_disabled / device_busy（设备被任务占用，running/connecting 拒写） / text_not_found（de_tap_text 屏幕上无该文字）
• image 返回：{ok:true, image: <content block>, width, height}

7. 图像链路细节

1. 平台截图（/api/screen/thumb）→ JPEG 字节
2. MCP Server 校验尺寸 → 等比缩放到 MCP_SCREENSHOT_WIDTH（用 Pillow，不重压缩已够质量则跳过）
3. 组装 MCP image content block（{"type":"image","data":<base64>,"mimeType":"image/jpeg"}）
4. 客户端（Claude）原生把 image 传入视觉上下文

性能预算：540px JPEG ~40-80KB/张；模型一次多步操作 5-15 张 ≈ 1MB 以内，可接受。

8. 认证与安全

1. 平台会话：MCP Server 启动时用 MCP_PLATFORM_USER/PASS 登录平台拿会话（Cookie），会话失效自动重登；不向客户端暴露平台凭据
2. 写操作门控：MCP_ALLOW_WRITE=0（默认）时 L2/L3 操作全部拒绝（write_disabled）——先部署只读，验证感知链路后再开写
3. 设备白名单：MCP_ALLOWED_SERIALS 指定；为空时自动限制为设备池 enabled 设备（平台口径）——此为设计目标，当前代码未实现：实现只校验 serial 非空，空名单不按设备池过滤（如需收紧请配置白名单）
4. 占用互斥：写操作前查设备 worker_status——running/connecting 中拒绝（device_busy），避免 MCP 与任务打架（已实现，只读工具不受限）
5. 审计：每次调用（含只读）写审计日志：ts|tool|serial|args摘要|result；落盘 MCP_AUDIT_FILE
6. 传输安全：内网部署（host 网络 8033）默认无 TLS；若外网暴露需前置 TLS/网络隔离（平台红线：设备控制接口不进公网）
7. 无状态：MCP Server 不存设备数据，全量透传平台

9. 部署（220 docker-compose 追加）

演进备选：下方「独立 mcp-server 容器」为演进方案。当前实现＝与 web_server 同容器，由 scripts/start.sh 后台拉起（MCP_ENABLED=1 默认、MCP_ALLOW_WRITE=1、MCP_PLATFORM_PASS 兜底 admin123），见 doc/MCP.md 与 DEPLOY §2.4。

  mcp-server:
    container_name: mcp-server
    image: dockerproxy.net/library/python:3.11-slim
    restart: unless-stopped
    working_dir: /app
    volumes:
      - "./mcp_server:/app"
    command: sh -c "pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt && python -m mcp_server.mcp_server"
    environment:
      - MCP_PLATFORM_URL=http://127.0.0.1:18050
      - MCP_PLATFORM_USER=admin
      - MCP_PLATFORM_PASS=${MCP_PLATFORM_PASS}   # .env 提供
      - MCP_ALLOW_WRITE=1
      - MCP_ALLOWED_SERIALS=
    network_mode: host

客户端接入（Claude Code / Desktop）：

// .mcp.json / claude_desktop_config.json
{ "mcpServers": { "mobile": {
    "url": "http://192.168.20.220:8033/mcp",
    "transport": "streamable-http"
}}}

10. 里程碑与验收

里程碑	内容	验收标准
M0	Server 骨架 + de_list_devices + de_screenshot + de_tap/de_swipe（HTTP 传输、登录会话、审计骨架）	Claude Code 连上后：能列设备、截图（AI 能描述屏幕内容）、点击指定坐标生效
M1	L1 完备（ui_tree/ocr/screen_state）+ L2 全量（key/type/clipboard/open_app/wake）	AI 完成「打开抖音搜索『奚学东』」多步操作
M2	L3 语义层（find_and_tap/wait_until）+ 图像尺寸/性能调优	AI 用自然语言指令（含中文输入）完成跨 3 步以上操作且自适应页面变化
M3	生产化：安全加固复核、审计看板、部署脚本、接入文档、任务系统互斥回归	日常稳定使用 1 周无异常

实现状态备注：M0/M1 已实现；M2 部分实现（de_tap_text / de_tap_element 已实现，de_find_and_tap / de_wait_until 未实现）；M3 未验收。

11. 风险与开放问题

1. AI 误操作：模型点击错位/误触关键按钮（如删除）——缓解：L3 定位优先于裸坐标、写门控先行、审计可追溯；不做二次确认（破坏自动化体验），靠白名单+占用互斥兜底
2. 截图成本：长会话多截图 → token/延迟成本——缓解：尺寸/质量可调、截图上限、de_ui_tree 作为低成本替代（文本树比图像便宜）
3. 横竖屏/分辨率异构：设备多样 → 坐标换算依赖截图 1:1；de_find_and_tap（语义层）不受分辨率影响
4. 图像 content block 兼容性：Claude 系原生支持；其他多模态客户端需验证（M0 用 Claude Code 验证）
5. 是否接任务系统：二期决策——de_run_task 语义与"单设备操作"不同（任务面向多设备调度），倾向二期用独立命名空间
6. clipboard/input 通道差异：个别 MIUI 需授权写入剪贴板的透明 Activity——M0 阶段在受控设备集验证，必要时 fallback 链已在 core 层（设备端 Agent → 旧版 ClipInject）

12. 附录：平台 API 映射（MCP → 平台）

MCP tool	实际平台调用（现状）
de_list_devices	GET /api/status
de_screenshot	GET /api/screen/thumb?serial=（X-Screen-State 头 → screen_state；另 GET /api/screen/size 取原生分辨率）
de_ui_tree	GET /api/uiauto/elements（uiautodev）
de_ocr	direct_ops.ocr：u2 截图 + core.ocr RapidOCR
de_tap	POST /api/screen/tap（snap=1 自动吸附）
de_swipe	POST /api/screen/swipe
de_press_key	POST /api/screen/key
de_tap_text	POST /api/screen/tap_text（UI 树子串匹配 → OCR 兜底）
de_tap_element	u2 元素直连（uiautomator2 d(by=value).click()，无平台端点）
de_type_text	u2 EditText.set_text（direct_ops.type_text，不走剪贴板通道）
de_set_clipboard	core.clipboard_helper 设备端 Agent 通道（inject_clipboard，读回验证）
de_read_clipboard	u2 d.clipboard
de_open_app	adb monkey 直启（direct_ops.open_app）
de_stop_app	adb am force-stop（direct_ops.stop_app）
de_foreground_app	adb dumpsys window（direct_ops.foreground_app，mCurrentFocus/mFocusedApp 兜底）
de_list_apps	adb pm list packages -3（direct_ops.list_apps）
de_wake / de_sleep	POST /api/device/screen_all（mode=on/off）
de_list_tasks	GET /api/jobs

de_screen_state 无独立工具，已并入 de_screenshot 的 screen_state 字段；设计稿中 de_find_and_tap/de_wait_until/de_get_task_state 未实现，不在此表。现状中 MCP 直连面（u2/adb）不经平台 REST，但安全（白名单/写门控/busy/审计）仍在 MCP 工具层统一把关，绝不越权触碰平台红线。