mobile-mcp-ai 2.3.4__py3-none-any.whl → 2.5.9__py3-none-any.whl

mobile_mcp/mcp_tools/mcp_server.py

@@ -5,7 +5,7 @@ Mobile MCP Server - 统一入口
 
 纯 MCP 方案，完全依赖 Cursor 视觉能力：
 - 不需要 AI 密钥
-- 20 个核心工具
+- 24 个核心工具（含 4 个长按工具）
 - 支持 Android 和 iOS
 - 保留 pytest 脚本生成
 
@@ -34,9 +34,21 @@ from pathlib import Path
 from typing import Optional
 
 # 添加项目根目录到 Python 路径
-# __file__ 在 mcp/ 目录下，需要往上两级到项目根目录
-project_root = Path(__file__).parent.parent
-sys.path.insert(0, str(project_root))
+# 支持两种运行方式：
+# 1. 从源码运行：__file__ 在 mcp_tools/ 目录下，往上两级到项目根目录
+# 2. 从已安装包运行：包已安装时，mobile_mcp 应该可以直接导入
+# 先尝试从已安装的包导入，如果失败则从源码路径导入
+try:
+    # 尝试导入已安装的包
+    import mobile_mcp.core.mobile_client
+    import mobile_mcp.core.basic_tools_lite
+    # 如果成功，说明包已安装，不需要添加路径
+except ImportError:
+    # 包未安装或导入失败，从源码运行
+    # __file__ 在 mcp_tools/ 目录下，往上两级到项目根目录
+    project_root = Path(__file__).parent.parent
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
 
 # 尝试导入 MCP，处理可能的路径冲突
 try:
@@ -89,6 +101,7 @@ class MobileMCPServer:
         self.client = None
         self.tools = None
         self._initialized = False
+        self._last_error = None  # 保存最后一次连接失败的错误
     
     @staticmethod
     def format_response(result) -> str:
@@ -99,24 +112,73 @@ class MobileMCPServer:
     
     async def initialize(self):
         """延迟初始化设备连接"""
-        if self._initialized:
-            return
+        # 如果已成功初始化，检查连接是否仍然有效
+        if self._initialized and self.tools is not None:
+            # 验证设备连接是否仍然有效
+            if self._is_connection_valid():
+                return
+            else:
+                # 连接已失效，重置状态
+                print("⚠️ 检测到设备连接已断开，正在重新连接...", file=sys.stderr)
+                self._initialized = False
+                self.client = None
+                self.tools = None
         
         platform = self._detect_platform()
         
         try:
-            from mobile_mcp.core.mobile_client import MobileClient
-            from mobile_mcp.core.basic_tools_lite import BasicMobileToolsLite
+            # 尝试导入，如果失败会抛出 ImportError
+            try:
+                from mobile_mcp.core.mobile_client import MobileClient
+                from mobile_mcp.core.basic_tools_lite import BasicMobileToolsLite
+            except ImportError as import_err:
+                # 如果导入失败，尝试从源码路径导入
+                # 这通常发生在开发模式下，包未安装时
+                project_root = Path(__file__).parent.parent
+                if str(project_root) not in sys.path:
+                    sys.path.insert(0, str(project_root))
+                # 再次尝试导入
+                from mobile_mcp.core.mobile_client import MobileClient
+                from mobile_mcp.core.basic_tools_lite import BasicMobileToolsLite
             
             self.client = MobileClient(platform=platform)
             self.tools = BasicMobileToolsLite(self.client)
+            self._initialized = True  # 只在成功时标记
             print(f"📱 已连接到 {platform.upper()} 设备", file=sys.stderr)
         except Exception as e:
-            print(f"⚠️ 设备连接失败: {e}", file=sys.stderr)
-            self.client = type('MockClient', (), {'platform': platform})()
+            error_msg = str(e)
+            print(f"⚠️ 设备连接失败: {error_msg}，下次调用时将重试", file=sys.stderr)
+            self.client = None
             self.tools = None
-        
-        self._initialized = True
+            self._last_error = error_msg  # 保存错误信息
+            # 不设置 _initialized = True，下次调用会重试
+    
+    def _is_connection_valid(self) -> bool:
+        """检查设备连接是否仍然有效"""
+        try:
+            if self.client is None:
+                return False
+            
+            # Android: 检查 u2 连接
+            if hasattr(self.client, 'u2') and self.client.u2:
+                # 尝试获取设备信息，如果失败说明连接断开
+                self.client.u2.info
+                return True
+            
+            # iOS: 检查 wda 连接
+            if hasattr(self.client, 'wda') and self.client.wda:
+                self.client.wda.status()
+                return True
+            
+            # iOS (通过 _ios_client)
+            if hasattr(self.client, '_ios_client') and self.client._ios_client:
+                if hasattr(self.client._ios_client, 'wda') and self.client._ios_client.wda:
+                    self.client._ios_client.wda.status()
+                    return True
+            
+            return False
+        except Exception:
+            return False
     
     def _detect_platform(self) -> str:
         """自动检测设备平台"""
@@ -142,33 +204,36 @@ class MobileMCPServer:
         # ==================== 元素定位（优先使用）====================
         tools.append(Tool(
             name="mobile_list_elements",
-            description="📋 列出页面所有可交互元素（⚠️ 录制测试脚本时必须优先调用！）\n\n"
-                       "返回 resource_id, text, bounds 等信息。\n\n"
-                       "🎯 【生成测试脚本时的定位策略】按稳定性排序：\n"
-                       "1️⃣ 【必须】先调用此工具获取元素列表\n"
-                       "2️⃣ 【推荐】有 id → 用 mobile_click_by_id（最稳定）\n"
-                       "3️⃣ 【推荐】有 text → 用 mobile_click_by_text（稳定）\n"
-                       "4️⃣ 【兜底】游戏/无法获取元素 → mobile_click_at_coords（自动转百分比）\n\n"
-                       "💡 优先使用 ID/文本定位，生成的脚本跨设备兼容性更好！",
+            description="📋 列出页面所有可交互元素\n\n"
+                       "⚠️ 【重要】点击元素前必须先调用此工具！\n"
+                       "如果元素在控件树中存在，使用 click_by_id 或 click_by_text 定位。\n"
+                       "只有当此工具返回空或找不到目标元素时，才使用截图+坐标方式。\n\n"
+                       "📌 控件树定位优势：\n"
+                       "- 实时检测元素是否存在\n"
+                       "- 元素消失时会报错，不会误点击\n"
+                       "- 跨设备兼容性好",
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
         # ==================== 截图（视觉兜底）====================
         tools.append(Tool(
             name="mobile_take_screenshot",
-            description="📸 截图（视觉定位用）。返回截图路径、屏幕尺寸和图片尺寸。\n\n"
-                       "🎯 使用场景：\n"
-                       "- 游戏（Unity/Cocos）无法获取元素时\n"
-                       "- mobile_list_elements 返回空时\n"
-                       "- 需要确认页面状态时\n\n"
-                       "⚠️ 【重要】截图会被压缩！\n"
-                       "   - screen_width/screen_height = 原始屏幕尺寸\n"
-                       "   - image_width/image_height = 压缩后图片尺寸（AI 看到的）\n"
-                       "   - 点击时必须传入 image_width/image_height 让工具自动转换坐标！",
+            description="📸 截图查看屏幕内容\n\n"
+                       "⚠️ 【推荐使用 mobile_screenshot_with_som 代替！】\n"
+                       "SoM 截图会给元素标号，AI 可以直接说'点击几号'，更精准！\n\n"
+                       "🎯 本工具仅用于：\n"
+                       "- 快速确认页面状态（不需要点击时）\n"
+                       "- 操作后确认结果\n"
+                       "- compress=false 时可获取原始分辨率截图（用于添加模板）\n\n"
+                       "💡 如需点击元素，请用 mobile_screenshot_with_som + mobile_click_by_som",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "description": {"type": "string", "description": "截图描述（可选）"}
+                    "description": {"type": "string", "description": "截图描述（可选）"},
+                    "compress": {"type": "boolean", "description": "是否压缩，默认 true。设为 false 可获取原始分辨率（用于模板添加）", "default": True},
+                    "crop_x": {"type": "integer", "description": "局部裁剪中心 X 坐标（屏幕坐标，0 表示不裁剪）"},
+                    "crop_y": {"type": "integer", "description": "局部裁剪中心 Y 坐标（屏幕坐标，0 表示不裁剪）"},
+                    "crop_size": {"type": "integer", "description": "裁剪区域大小（推荐 200-400，0 表示不裁剪）"}
                 },
                 "required": []
             }
@@ -180,13 +245,78 @@ class MobileMCPServer:
             inputSchema={"type": "object", "properties": {}, "required": []}
         ))
         
+        tools.append(Tool(
+            name="mobile_screenshot_with_som",
+            description="📸🏷️ Set-of-Mark 截图（⭐⭐ 强烈推荐！默认截图方式）\n\n"
+                       "【智能标注】给每个可点击元素画框+编号，检测弹窗时额外标注可能的X按钮位置（黄色）。\n"
+                       "AI 看图直接说'点击 3 号'，调用 mobile_click_by_som(3) 即可！\n\n"
+                       "🎯 优势：\n"
+                       "- 元素有编号，精准点击不会误触\n"
+                       "- 自动检测弹窗，标注可能的关闭按钮位置\n"
+                       "- 适用于所有页面和所有操作\n\n"
+                       "⚡ 推荐流程：\n"
+                       "1. 任何需要操作的场景，都先调用此工具\n"
+                       "2. 看标注图，找到目标元素编号\n"
+                       "3. 调用 mobile_click_by_som(编号) 精准点击\n"
+                       "4. 🔴【必须】点击后再次截图确认操作是否成功！",
+            inputSchema={"type": "object", "properties": {}, "required": []}
+        ))
+        
+        tools.append(Tool(
+            name="mobile_click_by_som",
+            description="🎯 根据 SoM 编号点击元素\n\n"
+                       "配合 mobile_screenshot_with_som 使用。\n"
+                       "看图后直接说'点击 3 号'，调用此函数即可。\n\n"
+                       "⚠️ 【重要】点击后建议再次截图确认操作是否成功！",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "index": {
+                        "type": "integer",
+                        "description": "元素编号（从 1 开始，对应截图中的标注数字）"
+                    }
+                },
+                "required": ["index"]
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_screenshot_with_grid",
+            description="📸📏 带网格坐标的截图（精确定位神器！）\n\n"
+                       "在截图上绘制网格线和坐标刻度，帮助快速定位元素位置。\n"
+                       "如果检测到弹窗，会用绿色圆圈标注可能的关闭按钮位置。\n\n"
+                       "🎯 适用场景：\n"
+                       "- 需要精确知道某个元素的坐标\n"
+                       "- 关闭广告弹窗时定位 X 按钮\n"
+                       "- 元素不在控件树中时的视觉定位\n\n"
+                       "💡 返回信息：\n"
+                       "- 带网格标注的截图\n"
+                       "- 弹窗边界坐标（如果检测到）\n"
+                       "- 可能的关闭按钮位置列表（带优先级）\n\n"
+                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "grid_size": {
+                        "type": "integer", 
+                        "description": "网格间距（像素），默认 100。值越小网格越密，建议 50-200"
+                    },
+                    "show_popup_hints": {
+                        "type": "boolean",
+                        "description": "是否显示弹窗关闭按钮提示位置，默认 true"
+                    }
+                },
+                "required": []
+            }
+        ))
+        
         # ==================== 点击操作 ====================
         tools.append(Tool(
             name="mobile_click_by_text",
-            description="👆 通过文本点击（⭐ 录制脚本时推荐！）\n\n"
-                       "✅ 优势：跨设备兼容，不受屏幕分辨率影响\n"
-                       "📋 使用前请先调用 mobile_list_elements 确认元素有文本\n"
-                       "💡 生成的脚本使用 d(text='...') 定位，稳定可靠",
+            description="👆 通过文本点击元素（推荐）\n\n"
+                       "✅ 实时检测元素是否存在，元素不存在会报错\n"
+                       "✅ 不会误点击到其他位置\n"
+                       "📋 使用前先调用 mobile_list_elements 确认元素文本",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -198,14 +328,16 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_click_by_id",
-            description="👆 通过 resource-id 点击（⭐⭐ 录制脚本时最推荐！）\n\n"
-                       "✅ 最稳定的定位方式，跨设备完美兼容\n"
-                       "📋 使用前请先调用 mobile_list_elements 获取元素 ID\n"
-                       "💡 生成的脚本使用 d(resourceId='...') 定位，最稳定",
+            description="👆 通过 resource-id 点击元素（最推荐）\n\n"
+                       "✅ 最稳定的定位方式\n"
+                       "✅ 实时检测元素是否存在，元素不存在会报错\n"
+                       "📋 使用前先调用 mobile_list_elements 获取元素 ID\n"
+                       "💡 当有多个相同 ID 的元素时，用 index 指定第几个（从 0 开始）",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "resource_id": {"type": "string", "description": "元素的 resource-id"}
+                    "resource_id": {"type": "string", "description": "元素的 resource-id"},
+                    "index": {"type": "integer", "description": "第几个元素（从 0 开始），默认 0 表示第一个", "default": 0}
                 },
                 "required": ["resource_id"]
             }
@@ -213,22 +345,26 @@ class MobileMCPServer:
         
         tools.append(Tool(
             name="mobile_click_at_coords",
-            description="👆 点击指定坐标（⚠️ 兜底方案，优先用 ID/文本定位！）\n\n"
-                       "🎯 仅在以下场景使用：\n"
-                       "- 游戏（Unity/Cocos）无法获取元素\n"
-                       "- mobile_list_elements 返回空\n"
-                       "- 元素没有 id 和 text\n\n"
-                       "⚠️ 【重要】如果坐标来自压缩截图，必须传入 image_width 和 image_height！\n"
-                       "   截图返回的 image_width/image_height 字段就是需要传入的值。\n"
-                       "   工具会自动将图片坐标转换为屏幕坐标。\n\n"
-                       "✅ 自动记录百分比坐标，生成脚本时会转换为跨分辨率兼容的百分比定位",
+            description="👆 点击指定坐标（兜底方案）\n\n"
+                       "⚠️ 【重要】优先使用 mobile_click_by_id 或 mobile_click_by_text！\n"
+                       "仅在 mobile_list_elements 无法获取元素时使用此工具。\n\n"
+                       "⚠️ 【时序限制】截图分析期间页面可能变化：\n"
+                       "- 坐标是基于截图时刻的，点击时页面可能已不同\n"
+                       "- 如果误点击，调用 mobile_press_key(back) 返回\n"
+                       "- 对于定时弹窗（如广告），建议等待其自动消失\n\n"
+                       "📐 坐标转换：截图返回的 image_width/height 等参数直接传入即可\n\n"
+                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
             inputSchema={
                 "type": "object",
                 "properties": {
-                    "x": {"type": "number", "description": "X 坐标（像素，来自截图分析或屏幕坐标）"},
-                    "y": {"type": "number", "description": "Y 坐标（像素，来自截图分析或屏幕坐标）"},
-                    "image_width": {"type": "number", "description": "截图的宽度（可选，传入后自动转换坐标）"},
-                    "image_height": {"type": "number", "description": "截图的高度（可选，传入后自动转换坐标）"}
+                    "x": {"type": "number", "description": "X 坐标（来自 AI 分析截图）"},
+                    "y": {"type": "number", "description": "Y 坐标（来自 AI 分析截图）"},
+                    "image_width": {"type": "number", "description": "压缩后图片宽度（截图返回的 image_width）"},
+                    "image_height": {"type": "number", "description": "压缩后图片高度（截图返回的 image_height）"},
+                    "original_img_width": {"type": "number", "description": "原图宽度（截图返回的 original_img_width）"},
+                    "original_img_height": {"type": "number", "description": "原图高度（截图返回的 original_img_height）"},
+                    "crop_offset_x": {"type": "number", "description": "局部截图 X 偏移（裁剪截图时传入）"},
+                    "crop_offset_y": {"type": "number", "description": "局部截图 Y 偏移（裁剪截图时传入）"}
                 },
                 "required": ["x", "y"]
             }
@@ -243,7 +379,8 @@ class MobileMCPServer:
                        "   - (10, 5) = 左上角附近\n"
                        "   - (85, 90) = 右下角附近\n\n"
                        "✅ 优势：同样的百分比在不同分辨率设备上都能点到相同相对位置\n"
-                       "💡 录制一次，多设备回放",
+                       "💡 录制一次，多设备回放\n\n"
+                       "🔴 【必须】点击后必须再次截图确认操作是否成功！",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -254,6 +391,89 @@ class MobileMCPServer:
             }
         ))
         
+        # ==================== 长按操作 ====================
+        tools.append(Tool(
+            name="mobile_long_press_by_id",
+            description="👆 通过 resource-id 长按（⭐⭐ 最稳定！）\n\n"
+                       "✅ 最稳定的长按定位方式，跨设备完美兼容\n"
+                       "📋 使用前请先调用 mobile_list_elements 获取元素 ID\n"
+                       "💡 生成的脚本使用 d(resourceId='...').long_click() 定位，最稳定",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "resource_id": {"type": "string", "description": "元素的 resource-id"},
+                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                },
+                "required": ["resource_id"]
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_long_press_by_text",
+            description="👆 通过文本长按（⭐ 推荐！）\n\n"
+                       "✅ 优势：跨设备兼容，不受屏幕分辨率影响\n"
+                       "📋 使用前请先调用 mobile_list_elements 确认元素有文本\n"
+                       "💡 生成的脚本使用 d(text='...').long_click() 定位，稳定可靠",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text": {"type": "string", "description": "元素的文本内容（精确匹配）"},
+                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                },
+                "required": ["text"]
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_long_press_by_percent",
+            description="👆 通过百分比位置长按（跨设备兼容！）\n\n"
+                       "🎯 原理：屏幕左上角是 (0%, 0%)，右下角是 (100%, 100%)\n"
+                       "📐 示例：\n"
+                       "   - (50, 50) = 屏幕正中央\n"
+                       "   - (10, 5) = 左上角附近\n"
+                       "   - (85, 90) = 右下角附近\n\n"
+                       "✅ 优势：同样的百分比在不同分辨率设备上都能长按到相同相对位置\n"
+                       "💡 录制一次，多设备回放",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "x_percent": {"type": "number", "description": "X 轴百分比 (0-100)"},
+                    "y_percent": {"type": "number", "description": "Y 轴百分比 (0-100)"},
+                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"}
+                },
+                "required": ["x_percent", "y_percent"]
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_long_press_at_coords",
+            description="👆 长按指定坐标（⚠️ 兜底方案，优先用 ID/文本定位！）\n\n"
+                       "🎯 仅在以下场景使用：\n"
+                       "- 游戏（Unity/Cocos）无法获取元素\n"
+                       "- mobile_list_elements 返回空\n"
+                       "- 元素没有 id 和 text\n\n"
+                       "⚠️ 【坐标转换】截图返回的参数直接传入：\n"
+                       "   - image_width/image_height: 压缩后尺寸（AI 看到的）\n"
+                       "   - original_img_width/original_img_height: 原图尺寸（用于转换）\n"
+                       "   - crop_offset_x/crop_offset_y: 局部截图偏移\n\n"
+                       "✅ 自动记录百分比坐标，生成脚本时转换为跨分辨率兼容的百分比定位",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "x": {"type": "number", "description": "X 坐标（来自 AI 分析截图）"},
+                    "y": {"type": "number", "description": "Y 坐标（来自 AI 分析截图）"},
+                    "duration": {"type": "number", "description": "长按持续时间（秒），默认 1.0"},
+                    "image_width": {"type": "number", "description": "压缩后图片宽度"},
+                    "image_height": {"type": "number", "description": "压缩后图片高度"},
+                    "original_img_width": {"type": "number", "description": "原图宽度"},
+                    "original_img_height": {"type": "number", "description": "原图高度"},
+                    "crop_offset_x": {"type": "number", "description": "局部截图 X 偏移"},
+                    "crop_offset_y": {"type": "number", "description": "局部截图 Y 偏移"}
+                },
+                "required": ["x", "y"]
+            }
+        ))
+        
         # ==================== 输入操作 ====================
         tools.append(Tool(
             name="mobile_input_text_by_id",
@@ -285,7 +505,11 @@ class MobileMCPServer:
         # ==================== 导航操作 ====================
         tools.append(Tool(
             name="mobile_swipe",
-            description="👆 滑动屏幕。方向：up/down/left/right",
+            description="👆 滑动屏幕。方向：up/down/left/right\n\n"
+                       "💡 左右滑动时，可指定高度坐标或百分比：\n"
+                       "- y: 指定高度坐标（像素）\n"
+                       "- y_percent: 指定高度百分比 (0-100)\n"
+                       "- 两者都未指定时，使用屏幕中心高度",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -293,6 +517,14 @@ class MobileMCPServer:
                         "type": "string",
                         "enum": ["up", "down", "left", "right"],
                         "description": "滑动方向"
+                    },
+                    "y": {
+                        "type": "integer",
+                        "description": "左右滑动时指定的高度坐标（像素，0-屏幕高度）"
+                    },
+                    "y_percent": {
+                        "type": "number",
+                        "description": "左右滑动时指定的高度百分比 (0-100)"
                     }
                 },
                 "required": ["direction"]
@@ -374,6 +606,48 @@ class MobileMCPServer:
         ))
         
         # ==================== 辅助工具 ====================
+        tools.append(Tool(
+            name="mobile_find_close_button",
+            description="""🔍 智能查找关闭按钮（只找不点，返回位置）
+
+从元素树中找最可能的关闭按钮，返回坐标和百分比位置。
+
+🎯 识别策略（优先级）：
+1. 文本匹配：×、X、关闭、取消、跳过 等
+2. 描述匹配：content-desc 包含 close/关闭
+3. 小尺寸 clickable 元素（右上角优先）
+
+✅ 返回内容：
+- 坐标 (x, y) 和百分比 (x%, y%)
+- 推荐的点击命令：mobile_click_by_percent(x%, y%)
+- 多个候选位置（供确认）
+
+💡 使用流程：
+1. 调用此工具找到关闭按钮位置
+2. 确认位置正确后，用 mobile_click_by_percent 点击
+3. 百分比点击兼容不同分辨率手机""",
+            inputSchema={"type": "object", "properties": {}, "required": []}
+        ))
+        
+        tools.append(Tool(
+            name="mobile_close_popup",
+            description="""🚫 智能关闭弹窗
+
+通过控件树识别并点击关闭按钮（×、关闭、跳过等）。
+
+✅ 控件树有元素时：直接点击，实时可靠
+❌ 控件树无元素时：截图供 AI 分析
+
+⚠️ 【时序限制】如果需要截图分析：
+- 分析期间弹窗可能自动消失
+- 对于定时弹窗（如广告），建议等待其自动消失
+- 点击前可再次截图确认弹窗是否还在
+
+🔴 【必须】点击关闭后，必须再次截图确认弹窗是否真的关闭了！
+如果弹窗仍在，需要尝试其他方法或位置。""",
+            inputSchema={"type": "object", "properties": {}, "required": []}
+        ))
+        
         tools.append(Tool(
             name="mobile_assert_text",
             description="✅ 检查页面是否包含指定文本。用于验证操作结果。",
@@ -432,6 +706,90 @@ class MobileMCPServer:
             }
         ))
         
+        # ==================== 广告弹窗关闭工具 ====================
+        tools.append(Tool(
+            name="mobile_close_ad",
+            description="""🚫 【推荐】智能关闭广告弹窗
+
+专门用于关闭广告弹窗，按优先级自动尝试多种方式：
+
+1️⃣ **控件树查找**（最可靠）
+   - 自动查找"关闭"、"跳过"、"×"等关闭按钮
+   - 找到直接点击，实时可靠
+
+2️⃣ **模板匹配**（次优）
+   - 用 OpenCV 匹配已保存的 X 按钮模板
+   - 需要积累模板库，模板越多成功率越高
+
+3️⃣ **返回截图供 AI 分析**（兜底）
+   - 如果前两步失败，返回截图
+   - AI 分析后用 mobile_click_by_percent 点击
+   - 点击成功后用 mobile_template_add 添加模板（自动学习）
+
+💡 使用流程：
+1. 遇到广告弹窗 → 调用此工具
+2. 如果成功 → 完成
+3. 如果失败 → 看截图找 X → 点击 → 添加模板""",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_template_close",
+            description="""🎯 模板匹配关闭弹窗（仅模板匹配）
+
+只用 OpenCV 模板匹配，不走控件树。
+一般建议用 mobile_close_ad 代替（会自动先查控件树）。
+
+⚙️ 参数：
+- click: 是否点击，默认 true
+- threshold: 匹配阈值 0-1，默认 0.75""",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "click": {"type": "boolean", "description": "是否点击，默认 true"},
+                    "threshold": {"type": "number", "description": "匹配阈值 0-1，默认 0.75"}
+                },
+                "required": []
+            }
+        ))
+        
+        tools.append(Tool(
+            name="mobile_template_add",
+            description="""➕ 添加 X 号模板
+
+遇到新样式 X 号时，截图并添加到模板库。
+
+⚙️ 两种方式（二选一）：
+1. 百分比定位（推荐）：提供 x_percent, y_percent, size
+2. 像素定位：提供 screenshot_path, x, y, width, height
+
+📋 流程：
+1. mobile_screenshot_with_grid 查看 X 号位置
+2. 调用此工具添加模板
+3. 下次同样 X 号就能自动匹配
+
+💡 百分比示例：X 在右上角 → x_percent=85, y_percent=12, size=80""",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "template_name": {"type": "string", "description": "模板名称"},
+                    "x_percent": {"type": "number", "description": "X号中心水平百分比 (0-100)"},
+                    "y_percent": {"type": "number", "description": "X号中心垂直百分比 (0-100)"},
+                    "size": {"type": "integer", "description": "裁剪正方形边长（像素）"},
+                    "screenshot_path": {"type": "string", "description": "截图路径（像素定位时用）"},
+                    "x": {"type": "integer", "description": "左上角 X 坐标"},
+                    "y": {"type": "integer", "description": "左上角 Y 坐标"},
+                    "width": {"type": "integer", "description": "裁剪宽度"},
+                    "height": {"type": "integer", "description": "裁剪高度"}
+                },
+                "required": ["template_name"]
+            }
+        ))
+        
         return tools
     
     async def handle_tool_call(self, name: str, arguments: dict):
@@ -439,25 +797,63 @@ class MobileMCPServer:
         await self.initialize()
         
         if not self.tools:
-            return [TextContent(type="text", text="❌ 设备未连接，请检查连接状态")]
+            # 提供详细的错误信息和解决方案
+            error_detail = self._last_error or "未知错误"
+            help_msg = (
+                f"❌ 设备连接失败\n\n"
+                f"错误详情: {error_detail}\n\n"
+                f"🔧 解决方案:\n"
+                f"1. 检查 USB 连接: adb devices\n"
+                f"2. 重启 adb: adb kill-server && adb start-server\n"
+                f"3. 初始化 uiautomator2: python -m uiautomator2 init\n"
+                f"4. 手机上允许 USB 调试授权\n"
+                f"5. 确保手机已解锁\n\n"
+                f"完成后请重试操作。"
+            )
+            return [TextContent(type="text", text=help_msg)]
         
         try:
             # 截图
             if name == "mobile_take_screenshot":
-                result = self.tools.take_screenshot(arguments.get("description", ""))
+                result = self.tools.take_screenshot(
+                    description=arguments.get("description", ""),
+                    compress=arguments.get("compress", True),
+                    crop_x=arguments.get("crop_x", 0),
+                    crop_y=arguments.get("crop_y", 0),
+                    crop_size=arguments.get("crop_size", 0)
+                )
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_get_screen_size":
                 result = self.tools.get_screen_size()
                 return [TextContent(type="text", text=self.format_response(result))]
             
+            elif name == "mobile_screenshot_with_grid":
+                result = self.tools.take_screenshot_with_grid(
+                    grid_size=arguments.get("grid_size", 100),
+                    show_popup_hints=arguments.get("show_popup_hints", True)
+                )
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_screenshot_with_som":
+                result = self.tools.take_screenshot_with_som()
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_click_by_som":
+                result = self.tools.click_by_som(arguments["index"])
+                return [TextContent(type="text", text=self.format_response(result))]
+            
             # 点击
             elif name == "mobile_click_at_coords":
                 result = self.tools.click_at_coords(
                     arguments["x"], 
                     arguments["y"],
                     arguments.get("image_width", 0),
-                    arguments.get("image_height", 0)
+                    arguments.get("image_height", 0),
+                    arguments.get("crop_offset_x", 0),
+                    arguments.get("crop_offset_y", 0),
+                    arguments.get("original_img_width", 0),
+                    arguments.get("original_img_height", 0)
                 )
                 return [TextContent(type="text", text=self.format_response(result))]
             
@@ -466,13 +862,53 @@ class MobileMCPServer:
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_click_by_id":
-                result = self.tools.click_by_id(arguments["resource_id"])
+                result = self.tools.click_by_id(
+                    arguments["resource_id"],
+                    arguments.get("index", 0)
+                )
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_click_by_percent":
                 result = self.tools.click_by_percent(arguments["x_percent"], arguments["y_percent"])
                 return [TextContent(type="text", text=self.format_response(result))]
             
+            # 长按
+            elif name == "mobile_long_press_by_id":
+                result = self.tools.long_press_by_id(
+                    arguments["resource_id"],
+                    arguments.get("duration", 1.0)
+                )
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_long_press_by_text":
+                result = self.tools.long_press_by_text(
+                    arguments["text"],
+                    arguments.get("duration", 1.0)
+                )
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_long_press_by_percent":
+                result = self.tools.long_press_by_percent(
+                    arguments["x_percent"],
+                    arguments["y_percent"],
+                    arguments.get("duration", 1.0)
+                )
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_long_press_at_coords":
+                result = self.tools.long_press_at_coords(
+                    arguments["x"],
+                    arguments["y"],
+                    arguments.get("duration", 1.0),
+                    arguments.get("image_width", 0),
+                    arguments.get("image_height", 0),
+                    arguments.get("crop_offset_x", 0),
+                    arguments.get("crop_offset_y", 0),
+                    arguments.get("original_img_width", 0),
+                    arguments.get("original_img_height", 0)
+                )
+                return [TextContent(type="text", text=self.format_response(result))]
+            
             # 输入
             elif name == "mobile_input_text_by_id":
                 result = self.tools.input_text_by_id(arguments["resource_id"], arguments["text"])
@@ -484,7 +920,11 @@ class MobileMCPServer:
             
             # 导航
             elif name == "mobile_swipe":
-                result = await self.tools.swipe(arguments["direction"])
+                result = await self.tools.swipe(
+                    arguments["direction"],
+                    y=arguments.get("y"),
+                    y_percent=arguments.get("y_percent")
+                )
                 return [TextContent(type="text", text=self.format_response(result))]
             
             elif name == "mobile_press_key":
@@ -522,6 +962,14 @@ class MobileMCPServer:
                 result = self.tools.list_elements()
                 return [TextContent(type="text", text=self.format_response(result))]
             
+            elif name == "mobile_find_close_button":
+                result = self.tools.find_close_button()
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_close_popup":
+                result = self.tools.close_popup()
+                return [TextContent(type="text", text=self.format_response(result))]
+            
             elif name == "mobile_assert_text":
                 result = self.tools.assert_text(arguments["text"])
                 return [TextContent(type="text", text=self.format_response(result))]
@@ -543,6 +991,46 @@ class MobileMCPServer:
                 )
                 return [TextContent(type="text", text=self.format_response(result))]
             
+            # 智能关闭广告弹窗
+            elif name == "mobile_close_ad":
+                result = self.tools.close_ad_popup(auto_learn=True)
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            # 模板匹配（精简版）
+            elif name == "mobile_template_close":
+                click = arguments.get("click", True)
+                threshold = arguments.get("threshold", 0.75)
+                if click:
+                    result = self.tools.template_click_close(threshold=threshold)
+                else:
+                    result = self.tools.template_match_close(threshold=threshold)
+                return [TextContent(type="text", text=self.format_response(result))]
+            
+            elif name == "mobile_template_add":
+                template_name = arguments["template_name"]
+                # 判断使用哪种方式
+                if "x_percent" in arguments and "y_percent" in arguments:
+                    # 百分比方式
+                    result = self.tools.template_add_by_percent(
+                        arguments["x_percent"],
+                        arguments["y_percent"],
+                        arguments.get("size", 80),
+                        template_name
+                    )
+                elif "screenshot_path" in arguments:
+                    # 像素方式
+                    result = self.tools.template_add(
+                        arguments["screenshot_path"],
+                        arguments["x"],
+                        arguments["y"],
+                        arguments["width"],
+                        arguments["height"],
+                        template_name
+                    )
+                else:
+                    result = {"success": False, "error": "请提供 x_percent/y_percent 或 screenshot_path/x/y/width/height"}
+                return [TextContent(type="text", text=self.format_response(result))]
+            
             else:
                 return [TextContent(type="text", text=f"❌ 未知工具: {name}")]
         
@@ -565,7 +1053,7 @@ async def async_main():
     async def call_tool(name: str, arguments: dict):
         return await server.handle_tool_call(name, arguments)
     
-    print("🚀 Mobile MCP Server 启动中... [20 个工具]", file=sys.stderr)
+    print("🚀 Mobile MCP Server 启动中... [26 个工具]", file=sys.stderr)
     print("📱 支持 Android / iOS", file=sys.stderr)
     print("👁️ 完全依赖 Cursor 视觉能力，无需 AI 密钥", file=sys.stderr)