diff --git a/doc/MCP_DESIGN.md b/doc/MCP_DESIGN.md
new file mode 100644
index 0000000..e796ac7
--- /dev/null
+++ b/doc/MCP_DESIGN.md
@@ -0,0 +1,244 @@
+# MCP 手机控制（Mobile Control MCP Server）设计文档
+
+> 分支：dev:mcp | 状态：设计稿 | 日期：2026-09-04
+
+## 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    │  （220 独立进程） │
+│ Claude Code  │ ◀──────────────────────────────── │  mcp/ 包         │
+└──────────────┘   截图图像 / 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` |
+| 输入文字 | ClipInject 通道（core.clipboard_helper）+ u2 input | 封装 `type_text` |
+| 剪贴板 | `POST /api/tools/clipboard/set`（ClipInject 通道） | 封装 `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`、`httpx`、`Pillow`（图像处理）、`mcp[cli]`
+- 日志：logging → 平台同款格式（时间/级别/模块）
+
+### 5.2 进程与容器
+
+- 独立容器 `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` | 空=全部 | 设备白名单（逗号分隔；为空时自动=设备池内设备） |
+| `MCP_HTTP_PORT` | `8033` | HTTP 传输端口 |
+| `MCP_SCREENSHOT_WIDTH` | `540` | 截图宽度（等比缩放，控图像 token 成本） |
+| `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
+| `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志路径 |
+
+## 6. Tools 规格
+
+命名空间 `de_`（device）前缀避免与常见工具冲突。全部工具对**未配置白名单/离线设备**返回明确错误，不做静默跳过。
+
+### 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)`
+- 实现：优先 ClipInject 通道（`core.clipboard_helper.inject_clipboard` 语义：写入剪贴板 + paste 到焦点输入框），失败回退 u2 input
+- 中文/emoji 全支持（ClipInject 实测通过）
+
+#### `de_set_clipboard(serial, text: str)`
+- 写入设备剪贴板（ClipInject 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` / `busy`（设备被任务占用）
+- 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 设备**（平台口径）
+4. **占用互斥**：操作前查设备 `worker_status`——running/connecting 中拒绝操作（`busy`），避免 MCP 与任务打架
+5. **审计**：每次调用（含只读）写审计日志：`ts|tool|serial|args摘要|result`；落盘 `MCP_AUDIT_FILE`
+6. **传输安全**：内网部署（host 网络 8033）默认无 TLS；若外网暴露需前置 TLS/网络隔离（平台红线：设备控制接口不进公网）
+7. **无状态**：MCP Server 不存设备数据，全量透传平台
+
+## 9. 部署（220 docker-compose 追加）
+
+```yaml
+  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"
+    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）：
+
+```json
+// .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 周无异常 |
+
+## 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 需授权 ClipInject——M0 阶段在受控设备集验证，必要时 fallback 链已在 core 层
+
+## 12. 附录：平台 API 映射（MCP → 平台）
+
+| MCP tool | 平台调用 |
+|---|---|
+| de_screenshot | GET /api/screen/thumb?serial= |
+| de_tap / de_swipe / de_press_key | POST /api/screen/tap|swipe|key |
+| de_type_text / de_set_clipboard | POST /api/tools/clipboard/set（ClipInject）+ u2 input |
+| de_ui_tree | GET /api/uiauto/…（或 core 直连） |
+| de_ocr | core.ocr（进程内或新只读端点） |
+| de_list_devices | GET /api/status + /api/devices/pool |
+| de_open_app | core device app_start（或任务层 open_app 动作） |
+| de_screen_state | dumpsys（core.common._device_screen_state） |
+
+> 实现时对平台缺失的只读入口（如 ocr/open_app 的直连面）优先在平台加**只读端点**（复用现有权限体系），MCP 不越权直连设备。