{
"canonical_name": "mobile-next/mobile-mcp",
"compilation_id": "pack_88a4760c69e94450b622c42cac521d94",
"created_at": "2026-05-13T18:10:51.525080+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx @mobilenext/mobile-mcp@latest` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx @mobilenext/mobile-mcp@latest",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_1c2dc4fb752142ab883a9f15150274db"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_839030a17f16d00665955fa6fd8082fc",
"canonical_name": "mobile-next/mobile-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/mobile-next/mobile-mcp",
"slug": "mobile-mcp",
"source_packet_id": "phit_1e2fd7d22cad4b32b8c47b23de6350b3",
"source_validation_id": "dval_3293fbe150c74840ad45c6c4749acf6a"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 425,
"github_stars": 4882,
"one_liner_en": "Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)",
"one_liner_zh": "Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, server"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "mobile-mcp",
"title_zh": "mobile-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_1e2fd7d22cad4b32b8c47b23de6350b3",
"page_model": {
"artifacts": {
"artifact_slug": "mobile-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx @mobilenext/mobile-mcp@latest",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/mobile-next/mobile-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：mobile_type_keys not support Chinese words",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Default-on telemetry creates security and compliance risk for enterprise users",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：mobile fleet documentation link broken",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.49",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.54",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.45",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_e5939588c2f74a4f8e7ae874c9fee9f2 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.45",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.47",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_6f22eab42c4140bf9692e3ff9f80dc62 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.47",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.48",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_4e414a95529d4f27bb06648558502daa | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.48",
"user_impact": "可能增加新用户试用和生产接入成本。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 23,
"forks": 425,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 4882
},
"source_url": "https://github.com/mobile-next/mobile-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)",
"title": "mobile-mcp 能力包",
"trial_prompt": "# mobile-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mobile-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. client-configuration：客户端配置指南。围绕“客户端配置指南”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. device-management：设备管理。围绕“设备管理”模拟一次用户任务，不展示安装或运行结果。\n5. mcp-tools：MCP 工具详解。围绕“MCP 工具详解”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. client-configuration\n输入：用户提供的“客户端配置指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. device-management\n输入：用户提供的“设备管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. mcp-tools\n输入：用户提供的“MCP 工具详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / client-configuration：Step 2 必须围绕“客户端配置指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / device-management：Step 4 必须围绕“设备管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / mcp-tools：Step 5 必须围绕“MCP 工具详解”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mobile-next/mobile-mcp\n- https://github.com/mobile-next/mobile-mcp#readme\n- README.md\n- package.json\n- src/server.ts\n- src/robot.ts\n- src/mobilecli.ts\n- src/mobile-device.ts\n- src/android.ts\n- src/ios.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mobile-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Default-on telemetry creates security and compliance risk for enterprise（https://github.com/mobile-next/mobile-mcp/issues/330）；github/github_issue: mobile fleet documentation link broken（https://github.com/mobile-next/mobile-mcp/issues/328）；github/github_issue: iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't r（https://github.com/mobile-next/mobile-mcp/issues/323）；github/github_issue: feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd)（https://github.com/mobile-next/mobile-mcp/issues/322）；github/github_issue: mobile_type_keys not support Chinese words（https://github.com/mobile-next/mobile-mcp/issues/238）；github/github_issue: Founding Harness Doctor audit for Mobile MCP（https://github.com/mobile-next/mobile-mcp/issues/315）；github/github_issue: start/stop_screen_recording produces corrupt files on Android and silent（https://github.com/mobile-next/mobile-mcp/issues/321）；github/github_release: Version 0.0.54（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54）；github/github_release: Version 0.0.53（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53）；github/github_release: Version 0.0.52（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52）；github/github_release: Version 0.0.51（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51）；github/github_release: Version 0.0.49（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Default-on telemetry creates security and compliance risk for enterprise",
"url": "https://github.com/mobile-next/mobile-mcp/issues/330"
},
{
"kind": "github_issue",
"source": "github",
"title": "mobile fleet documentation link broken",
"url": "https://github.com/mobile-next/mobile-mcp/issues/328"
},
{
"kind": "github_issue",
"source": "github",
"title": "iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't r",
"url": "https://github.com/mobile-next/mobile-mcp/issues/323"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd)",
"url": "https://github.com/mobile-next/mobile-mcp/issues/322"
},
{
"kind": "github_issue",
"source": "github",
"title": "mobile_type_keys not support Chinese words",
"url": "https://github.com/mobile-next/mobile-mcp/issues/238"
},
{
"kind": "github_issue",
"source": "github",
"title": "Founding Harness Doctor audit for Mobile MCP",
"url": "https://github.com/mobile-next/mobile-mcp/issues/315"
},
{
"kind": "github_issue",
"source": "github",
"title": "start/stop_screen_recording produces corrupt files on Android and silent",
"url": "https://github.com/mobile-next/mobile-mcp/issues/321"
},
{
"kind": "github_release",
"source": "github",
"title": "Version 0.0.54",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54"
},
{
"kind": "github_release",
"source": "github",
"title": "Version 0.0.53",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53"
},
{
"kind": "github_release",
"source": "github",
"title": "Version 0.0.52",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52"
},
{
"kind": "github_release",
"source": "github",
"title": "Version 0.0.51",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51"
},
{
"kind": "github_release",
"source": "github",
"title": "Version 0.0.49",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)",
"effort": "安装已验证",
"forks": 425,
"icon": "link",
"name": "mobile-mcp 能力包",
"risk": "可发布",
"slug": "mobile-mcp",
"stars": 4882,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/mobile-next/mobile-mcp 项目说明书\n\n生成时间：2026-05-13 17:52:49 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [安装与配置](#installation)\n- [客户端配置指南](#client-configuration)\n- [系统架构](#system-architecture)\n- [设备管理](#device-management)\n- [MCP 工具详解](#mcp-tools)\n- [iOS 实现](#ios-implementation)\n- [Android 实现](#android-implementation)\n- [故障排除](#troubleshooting)\n- [安全配置](#security)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [安装与配置](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n \n\n# 项目概述\n\n## 简介\n\nMobile MCP（Mobile Model Context Protocol）是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 标准的移动设备自动化框架。它使 AI 代理能够通过标准化的接口与 iOS、Android 设备进行交互，支持真机、模拟器和仿真器。资料来源：[README.md:1-10]()\n\n该项目的核心目标是通过 MCP 协议为 AI 助手提供移动设备控制能力，实现自动化测试、数据采集、UI 交互等多种场景。开发者无需编写原生代码，即可通过自然语言指令驱动移动设备完成复杂任务。资料来源：[README.md:35-50]()\n\n## 核心特性\n\nMobile MCP 具有以下核心特性：\n\n| 特性 | 描述 |\n|------|------|\n| 快速轻量 | 利用原生无障碍树（Accessibility Tree）进行大多数交互，在无 a11y 标签时使用截图坐标方案 |\n| LLM 友好 | 无需计算机视觉模型即可进行屏幕分析 |\n| 视觉感知 | 可评估和分析屏幕实际渲染内容 |\n| 跨平台 | 同时支持 iOS 和 Android 设备 |\n| 灵活部署 | 支持 stdio 和 SSE 两种服务器模式 |\n| 安全认证 | SSE 模式支持 Bearer Token 授权验证 |\n\n资料来源：[README.md:50-60]()\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph MCP客户端 [\"MCP 客户端 (IDE/Agent)\"]\n A[Claude Desktop]\n B[Cursor]\n C[VS Code]\n D[其他 MCP 兼容客户端]\n end\n \n subgraph MCP协议层 [\"MCP 协议层\"]\n E[stdio 模式]\n F[SSE Server 模式]\n end\n \n subgraph Mobile MCP 核心 [\"Mobile MCP 核心\"]\n G[src/server.ts
MCP 服务器入口]\n H[设备管理器层]\n I[机器人抽象层]\n end\n \n subgraph 设备抽象层 [\"设备抽象层\"]\n J[Robot 接口]\n K[WebDriverAgent
iOS WDA]\n L[MobileDevice
Android ADB]\n M[iPhone Simulator
模拟器支持]\n end\n \n subgraph 物理设备 [\"物理/虚拟设备\"]\n N[iOS 真机/模拟器]\n O[Android 真机/仿真器]\n end\n \n A --> E\n B --> E\n C --> F\n D --> F\n E --> G\n F --> G\n G --> H\n H --> I\n I --> J\n J --> K\n J --> L\n J --> M\n K --> N\n L --> O\n M --> N\n```\n\n### 核心模块说明\n\n#### 1. MCP 服务器层 (`src/server.ts`)\n\nMCP 服务器是整个系统的入口点，负责：\n- 注册和暴露所有 MCP 工具\n- 管理设备连接和会话\n- 处理工具调用请求\n- 提供 SSE 服务器模式支持\n\n服务器通过 `mobilecli` 工具进行设备管理，并在启动时验证 `mobilecli` 的可用性。资料来源：[src/server.ts:1-50]()\n\n#### 2. 设备管理器层\n\n设备管理器负责设备的发现、连接和管理：\n\n| 管理器 | 职责 | 源码文件 |\n|--------|------|----------|\n| IosManager | iOS 设备发现和管理 | src/ios.ts |\n| AndroidDeviceManager | Android 设备管理 | src/android.ts |\n| IPhoneSimulator | iPhone 模拟器支持 | src/iphone-simulator.ts |\n\n资料来源：[src/ios.ts:1-80]()\n\n#### 3. 机器人抽象层 (`src/robot.ts`)\n\nRobot 接口定义了所有设备交互的统一抽象：\n\n```typescript\ninterface Robot {\n // 设备信息\n getScreenSize(): Promise;\n getOrientation(): Promise;\n setOrientation(orientation: Orientation): Promise;\n \n // 应用管理\n listApps(): Promise;\n launchApp(packageName: string, locale?: string): Promise;\n terminateApp(packageName: string): Promise;\n installApp(path: string): Promise;\n uninstallApp(bundleId: string): Promise;\n \n // 屏幕交互\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipe(direction: SwipeDirection): Promise;\n \n // 输入操作\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n openUrl(url: string): Promise;\n}\n```\n\n资料来源：[src/robot.ts:1-150]()\n\n#### 4. 平台特定实现\n\n##### iOS 实现 (`src/webdriver-agent.ts`)\n\niOS 设备通过 WebDriverAgent (WDA) 进行控制：\n- 通过 HTTP API 与 WDA 通信\n- 使用 `/source/?format=json` 获取页面元素\n- 使用 `/screenshot` 获取屏幕截图\n- 通过 `/actions` 端点执行手势操作\n\n元素筛选支持以下类型：`TextField`, `Button`, `Switch`, `Icon`, `SearchField`, `StaticText`, `Image`\n\n资料来源：[src/webdriver-agent.ts:1-100]()\n\n##### Android 实现 (`src/mobile-device.ts`)\n\nAndroid 设备通过 `mobilecli` 工具进行控制：\n- 使用 `dump ui` 命令获取界面元素\n- 使用 `io tap` 执行点击操作\n- 使用 `io text` 输入文本\n- 使用 `io button` 模拟按键\n- 使用 `device orientation` 管理屏幕方向\n\n资料来源：[src/mobile-device.ts:1-100]()\n\n## 主要功能\n\n### MCP 工具分类\n\nMobile MCP 提供了丰富的 MCP 工具，主要分为以下几类：\n\n#### 设备信息类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_available_devices` | 列出所有可用设备（模拟器、仿真器、真机） |\n| `mobile_get_screen_size` | 获取设备屏幕尺寸（像素） |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向（竖屏/横屏） |\n\n#### 应用管理类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_apps` | 列出设备上所有已安装应用 |\n| `mobile_launch_app` | 启动指定应用（通过包名） |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 安装应用（支持 .apk, .ipa, .app, .zip） |\n| `mobile_uninstall_app` | 卸载应用 |\n\n#### 屏幕交互类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_take_screenshot` | 截图以了解屏幕内容 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 列出屏幕元素及其坐标和属性 |\n| `mobile_click_on_screen_at_coordinates` | 在指定坐标点击 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 在屏幕上滑动（支持四个方向） |\n\n#### 输入与导航类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_type_keys` | 向焦点元素输入文本 |\n| `mobile_press_button` | 按下设备物理按钮 |\n\n资料来源：[README.md:100-130]()\n\n## 通信模式\n\nMobile MCP 支持两种通信模式：\n\n### stdio 模式（默认）\n\n默认模式，Mobile MCP 通过标准输入输出与客户端通信。适用于大多数本地场景。\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### SSE Server 模式\n\n当需要远程访问或多人协作时，可启用 SSE 服务器模式：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n可绑定到特定接口：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n连接地址：`http://:3000/mcp`\n\n#### 认证配置\n\nSSE 模式支持 Bearer Token 认证：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含：`Authorization: Bearer my-secret-token`\n\n资料来源：[README.md:180-210]()\n\n## 应用场景\n\n### 主要用例\n\n| 场景 | 描述 |\n|------|------|\n| 原生应用自动化 | iOS 和 Android 应用的测试或数据录入场景 |\n| 脚本化流程 | 无需手动控制模拟器/仿真器或真机即可完成表单交互 |\n| 多步骤用户旅程 | 由 LLM 驱动的自动化用户流程 |\n| 通用应用交互 | 基于代理框架的移动应用交互 |\n| 代理间通信 | 支持移动自动化的代理间通信和数据提取 |\n\n资料来源：[README.md:30-40]()\n\n### 典型工作流示例\n\n#### 示例 1：应用测试与截图\n\n```\n打开指定应用，截取当前屏幕截图，\n列出所有可见的 UI 元素，\n然后点击\"登录\"按钮\n```\n\n#### 示例 2：多步骤表单填写\n\n```\n打开 Settings 应用，\n导航到 \"General\" > \"About\"，\n滚动到页面底部，\n记录设备的序列号和型号\n```\n\n#### 示例 3：内容搜索与保存\n\n```\n打开 Substack 网站，\n搜索 \"Latest trends in AI automation 2025\"，\n打开第一篇文章，\n高亮标题为 \"Emerging AI trends\" 的章节，\n保存文章到阅读列表待稍后查看，\n评论一段随机的段落摘要\n```\n\n#### 示例 4：活动预约\n\n```\n打开 Eventbrite，\n搜索 \"Austin, TX\" 本周末的 AI 创业公司meetup 活动，\n选择最热门的一个，\n注册并确认参加，\n设置日历提醒\n```\n\n资料来源：[README.md:60-100]()\n\n## 环境要求\n\n### 前置条件\n\n使用 Mobile MCP 前，需要准备以下环境：\n\n| 平台 | 要求 |\n|------|------|\n| iOS | macOS + Xcode + WebDriverAgent |\n| Android | Android SDK + ADB |\n| 通用 | Node.js 环境用于运行 mobilecli |\n\n详细安装说明请参阅 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n资料来源：[README.md:105-110]()\n\n## 客户端集成\n\nMobile MCP 可与多种 MCP 兼容客户端集成：\n\n| 客户端 | 集成方式 |\n|--------|----------|\n| Claude Desktop | JSON 配置文件 |\n| Cursor | 手动配置或一键安装 |\n| VS Code | VS Code MCP 扩展 |\n| Claude Code | CLI 命令添加 |\n| Codex | TOML 配置文件 |\n| Copilot | MCP 配置 |\n| Gemini CLI | CLI 命令添加 |\n| Goose | 自定义扩展 |\n| Windsurf | MCP 服务器设置 |\n| Cline | MCP 设置文件 |\n| Amp | VS Code 扩展或 CLI |\n\n详细配置请参考各客户端的 MCP 文档或 [项目 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n## 技术栈\n\n| 层级 | 技术/工具 |\n|------|-----------|\n| 协议层 | Model Context Protocol (MCP) |\n| 运行时 | Node.js |\n| iOS 控制 | WebDriverAgent (WDA) |\n| Android 控制 | mobilecli / ADB |\n| iOS 连接 | go-ios 工具 |\n\n## 路线图\n\n项目团队持续优化 Mobile MCP，详细的路线图可在 [GitHub Projects](https://github.com/orgs/mobile-next/projects/3) 中查看。\n\n路线图涵盖的领域包括：\n- 新功能开发\n- 性能优化\n- 平台扩展\n- 文档完善\n- 社区反馈集成\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 项目首页 | https://github.com/mobile-next/mobile-mcp |\n| 官方文档 | https://github.com/mobile-next/mobile-mcp/wiki |\n| 问题反馈 | GitHub Issues |\n| Slack 社区 | https://mobilenexthq.com/join-slack |\n| 路线图 | https://github.com/orgs/mobile-next/projects/3 |\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n \n\n# 安装与配置\n\n## 概述\n\nMobile MCP (Model Context Protocol) 是一个用于移动端自动化和控制的服务端工具，支持 iOS 和 Android 平台的原生应用自动化、模拟器/真机控制、以及脚本化流程交互。该工具通过 MCP 协议与 AI 助手集成，使 LLM 能够操控移动设备完成各类自动化任务。\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 规格 |\n|--------|------|\n| Node.js 版本 | >= 18 |\n| 包管理器 | npm / npx |\n| 许可证 | Apache-2.0 |\n| 发布格式 | npm 包 (`@mobilenext/mobile-mcp`) |\n\n资料来源：[package.json:6-9](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n### 设备支持\n\n系统支持以下类型的移动设备连接：\n\n- **iOS 真机**：通过 WebDriverAgent (WDA) 进行控制\n- **iOS 模拟器**：通过 simctl 命令控制\n- **Android 真机**：通过 Android Debug Bridge (ADB) 命令控制\n- **Android 模拟器**：通过 ADB 连接\n\n设备发现和类型识别逻辑位于 `src/server.ts` 中的 `getRobotFromDevice` 函数：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n // 检查 iOS 真机\n const iosManager = new IosManager();\n const iosDevice = iosManager.listDevices().find(d => d.deviceId === deviceId);\n if (iosDevice) return new IosRobot(deviceId);\n\n // 检查 Android 设备\n const androidManager = new AndroidDeviceManager();\n const androidDevice = androidManager.getConnectedDevices().find(d => d.deviceId === deviceId);\n if (androidDevice) return new AndroidRobot(deviceId);\n\n // 检查 iOS 模拟器\n const response = mobilecli.getDevices({ platform: \"ios\", type: \"simulator\", includeOffline: false });\n // ...\n};\n```\n\n资料来源：[src/server.ts:31-52](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 安装方式\n\n### 方式一：npx 直接运行\n\n最简安装方式，通过 npx 直接启动服务：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n### 方式二：本地安装\n\n```bash\nnpm install -g @mobilenext/mobile-mcp\n```\n\n### 方式三：项目依赖安装\n\n```bash\nnpm install @mobilenext/mobile-mcp\n```\n\n## MCP 客户端配置\n\n### 标准配置模板\n\n大多数 MCP 客户端支持以下标准配置格式：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1-10](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### 各客户端配置详情\n\n#### VS Code (Copilot)\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": \"npx\",\n \"tools\": [\"*\"],\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Claude Desktop\n\n配置文件路径：`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Cursor\n\n在 Cursor 设置中添加新的 MCP Server，使用命令类型：\n\n```\n命令: npx -y @mobilenext/mobile-mcp@latest\n```\n\n#### Cline\n\n将标准配置添加到 MCP 设置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Windsurf\n\n在 MCP servers 设置中添加新服务器，使用命令类型：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n#### Codeium (Windsurf)\n\n配置路径：`~/.codex/config.toml`\n\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n\n#### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n\n#### Goose\n\n设置类型：`STDIO`\n命令：`npx -y @mobilenext/mobile-mcp@latest`\n\n#### Kiro\n\n配置文件路径：`.kiro/settings/mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Amp (VS Code 扩展)\n\n通过 Amp VS Code 扩展设置或 `settings.json` 添加：\n\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n\n或通过 CLI：\n\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n## SSE 服务器模式\n\n默认情况下，Mobile MCP 通过 stdio 通信运行。如需以 HTTP 服务器模式运行，使用 `--listen` 参数：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n这会将服务绑定到 `localhost:3000`。\n\n### 指定网络接口\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n### MCP 客户端连接配置\n\n配置客户端连接到 SSE 服务器：\n\n```\nhttp://:3000/mcp\n```\n\n资料来源：[README.md:1-20](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### 授权配置\n\nSSE 服务器支持 Bearer Token 授权。设置环境变量：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含头部：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n## 环境变量\n\n| 变量名 | 说明 | 必填 |\n|--------|------|------|\n| `MOBILEMCP_AUTH` | SSE 服务器的 Bearer Token 认证密钥 | 仅 SSE 模式 |\n| `PATH` | 需包含 mobilecli 可执行文件路径 | 是 |\n\n### mobilecli 可用性检查\n\n服务启动时会自动检查 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly...`);\n }\n};\n```\n\n资料来源：[src/server.ts:18-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 通信协议架构\n\n```mermaid\ngraph TD\n A[MCP 客户端
AI 助手] -->|MCP 协议| B[Mobile MCP Server
mobile-mcp]\n B -->|stdio 或 SSE| A\n B --> C[mobilecli]\n C -->|iOS 控制| D[iOS 模拟器
simctl]\n C -->|iOS 真机| E[WebDriverAgent
WDA 隧道]\n C -->|Android| F[ADB]\n D --> G[iOS 模拟器]\n E --> H[iOS 真机]\n F --> I[Android 设备/模拟器]\n```\n\n## 可用工具列表\n\n安装并配置完成后，以下工具将自动注册到 MCP 客户端：\n\n### 设备管理\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_available_devices` | 列出所有可用设备（模拟器、仿真器、真机） |\n| `mobile_get_screen_size` | 获取设备屏幕尺寸（像素） |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向（竖屏/横屏） |\n\n### 应用管理\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_apps` | 列出设备上安装的所有应用 |\n| `mobile_launch_app` | 通过包名启动应用 |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 从文件安装应用（.apk, .ipa, .app, .zip） |\n| `mobile_uninstall_app` | 卸载应用 |\n\n### 屏幕交互\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_take_screenshot` | 截取屏幕截图 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 列出屏幕上的 UI 元素及其坐标和属性 |\n| `mobile_click_on_screen_at_coordinates` | 点击指定坐标 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 在任意方向滑动 |\n\n### 输入与导航\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_type_keys` | 向焦点元素输入文本 |\n| `mobile_press_button` | 按下设备按钮 |\n| `mobile_open_url` | 打开 URL |\n\n### 崩溃日志\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_crashes` | 列出设备上的崩溃报告 |\n| `mobile_get_crash` | 获取指定 ID 的崩溃报告内容 |\n\n资料来源：[README.md:100-130](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 依赖项\n\n### 核心依赖\n\n```json\n{\n \"@modelcontextprotocol/sdk\": \"1.26.0\",\n \"ajv\": \"^8.18.0\",\n \"commander\": \"14.0.0\",\n \"express\": \"5.1.0\",\n \"fast-xml-parser\": \"5.5.7\",\n \"qs\": \"^6.15.0\",\n \"zod\": \"^4.1.13\",\n \"zod-to-json-schema\": \"3.25.0\"\n}\n```\n\n### 可选依赖\n\n```json\n{\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n`mobilecli` 为可选依赖，用于与 iOS/Android 设备通信。\n\n资料来源：[package.json:23-45](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 构建与开发\n\n### 项目构建\n\n```bash\nnpm run build\n```\n\n构建产物输出到 `lib` 目录。\n\n### 开发模式\n\n```bash\nnpm run watch\n```\n\n### 代码检查\n\n```bash\nnpm run lint\n```\n\n## 故障排除\n\n### mobilecli 不可用\n\n错误信息：\n```\nmobilecli is not available or not working properly\n```\n\n解决方案：访问 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) 查看 mobilecli 安装说明。\n\n### iOS 设备连接问题\n\niOS 真机需要以下服务正常运行：\n\n1. **iOS 隧道**：用于网络通信\n2. **WDA 端口转发**：WebDriverAgent 端口转发\n3. **WebDriverAgent**：设备上安装并运行\n\n连接检查逻辑位于 `src/ios.ts`：\n\n```typescript\nprivate async assertTunnelRunning(): Promise {\n if (await this.isTunnelRequired()) {\n if (!(await this.isTunnelRunning())) {\n throw new ActionableError(\"iOS tunnel is not running...\");\n }\n }\n}\n\nprivate async wda(): Promise {\n await this.assertTunnelRunning();\n if (!(await this.isWdaForwardRunning())) {\n throw new ActionableError(\"Port forwarding to WebDriverAgent is not running...\");\n }\n if (!(await wda.isRunning())) {\n throw new ActionableError(\"WebDriverAgent is not running on device...\");\n }\n return wda;\n}\n```\n\n资料来源：[src/ios.ts:60-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### 应用安装失败\n\n安装 .zip 文件时会进行以下验证：\n\n1. 路径安全检查（防止 zip-slip 攻击）\n2. 自动解压到临时目录\n3. 查找 .app bundle 文件\n\n如未找到 .app bundle，抛出错误：\n```\nNo .app bundle found in the .zip file\n```\n\n资料来源：[src/iphone-simulator.ts:80-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n\n## 更多资源\n\n- 完整文档：[官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)\n- 路线图：[项目路线图](https://github.com/orgs/mobile-next/projects/3)\n- 示例提示词：[Prompt Example 仓库](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- Slack 社区：[加入讨论](https://mobilenexthq.com/join-slack)\n\n---\n\n\n\n## 客户端配置指南\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [MCP 工具详解](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 客户端配置指南\n\n本指南详细说明如何在不同 IDE 和 AI 编程助手客户端中配置 Mobile MCP 服务器。Mobile MCP 是一个基于 Model Context Protocol (MCP) 的移动设备自动化框架，支持 iOS、Android、模拟器和真机等平台。\n\n## 标准配置模板\n\n无论使用何种客户端，大多数工具都使用相同的基础配置结构：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `command` | string | 执行命令，固定为 `npx` |\n| `args` | array | 命令参数，`-y` 表示自动确认，`@mobilenext/mobile-mcp@latest` 指定包名和版本 |\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Claude 系列客户端配置\n\n### Claude Desktop\n\n在 Claude Desktop 中配置 Mobile MCP，需要编辑 MCP 安装配置文件。详细步骤请参考 [MCP 快速入门指南](https://modelcontextprotocol.io/quickstart/user)，直接使用上述标准配置即可。\n\n### Claude Code\n\n使用 Claude Code CLI 添加 Mobile MCP 服务器：\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n\n或者手动编辑配置文件 `~/.claude/settings.json`，添加标准配置模板中的 JSON 内容。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Cline\n\nCline 客户端配置最为简单，只需将标准配置 JSON 添加到 MCP 设置文件即可：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n更多详情请参考 [Cline 配置文档](https://github.com/mobile-next/mobile-mcp/wiki/Cline)。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## AI IDE 客户端配置\n\n### Cursor\n\nCursor 提供两种安装方式：\n\n#### 方式一：点击安装按钮\n\n访问 Cursor 安装页面，点击安装按钮自动配置。\n\n#### 方式二：手动安装\n\n1. 进入 `Cursor Settings` → `MCP` → `Add new MCP Server`\n2. 根据喜好命名服务器\n3. 使用 `command` 类型，命令设为 `npx -y @mobilenext/mobile-mcp@latest`\n4. 可通过点击 `Edit` 验证配置或添加命令行参数\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Codex\n\n使用 Codex CLI 添加服务器：\n\n```bash\ncodex mcp add mobile-mcp npx \"@mobilenext/mobile-mcp@latest\"\n```\n\n或者编辑配置文件 `~/.codex/config.toml`：\n\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n\n更多配置信息请参考 Codex MCP 文档。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Copilot\n\n使用 Copilot CLI 交互式添加服务器：\n\n```bash\n/mcp add\n```\n\n或者手动编辑 `~/.copilot/mcp-config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": \"npx\",\n \"tools\": [\"*\"],\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 其他开发工具配置\n\n### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n\n### Goose\n\n#### 点击安装\n\n访问 Goose 安装页面，使用默认配置自动安装。\n\n#### 手动安装\n\n1. 进入 `Advanced settings` → `Extensions` → `Add custom extension`\n2. 自定义命名\n3. 选择类型为 `STDIO`\n4. 设置命令为 `npx -y @mobilenext/mobile-mcp@latest`\n5. 点击 \"Add Extension\"\n\n### Kiro\n\n在 `.kiro/settings/mcp.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n详细文档请参考 [Kiro MCP 文档](https://kiro.dev/docs/mcp/)。\n\n### opencode\n\n在 `~/.config/opencode/opencode.json` 中配置：\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"@mobilenext/mobile-mcp@latest\"],\n \"enabled\": true\n }\n }\n}\n```\n\n### Qodo Gen\n\n1. 在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板\n2. 进入 `Connect more tools` → `+ Add new MCP`\n3. 粘贴标准配置\n4. 点击 `Save`\n\n### Windsurf\n\n1. 打开 Windsurf 设置\n2. 导航至 MCP servers\n3. 添加新服务器，选择 `command` 类型\n4. 输入命令：`npx @mobilenext/mobile-mcp@latest`\n\n或在设置中的 `mcpServers` 下添加标准配置。\n\n### Amp\n\n#### VS Code 扩展方式\n\n通过 Amp VS Code 扩展设置界面添加，或更新 `settings.json`：\n\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n\n#### Amp CLI 方式\n\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## SSE 服务器模式配置\n\nMobile MCP 默认通过 stdio 通信。如需启动 SSE 服务器，使用 `--listen` 参数：\n\n### 基础配置\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n这将绑定到 `localhost:3000`。\n\n### 绑定特定网络接口\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n配置 MCP 客户端连接到 `http://:3000/mcp`。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Bearer Token 授权配置\n\n为 SSE 服务器启用 Bearer Token 认证，需设置 `MOBILEMCP_AUTH` 环境变量：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n启用后，所有请求必须包含认证头：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 设备连接架构\n\nMobile MCP 通过 `mobilecli` 工具与移动设备通信，支持多种设备类型：\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端\"\n A[Claude Code] --> B[配置解析]\n C[Cursor] --> B\n D[Copilot] --> B\n end\n \n subgraph \"Mobile MCP 服务器\"\n B --> E[服务器初始化]\n E --> F{设备类型检测}\n F -->|iOS| G[IosRobot]\n F -->|Android| H[AndroidRobot]\n F -->|Simulator| I[SimulatorRobot]\n end\n \n subgraph \"设备通信层\"\n G --> J[ios libimobiledevice]\n H --> K[Android Debug Bridge]\n I --> J\n end\n \n subgraph \"移动设备\"\n J --> L[iOS 设备]\n K --> M[Android 设备]\n end\n```\n\n### 设备类型检测流程\n\n1. 获取设备标识符\n2. 检查是否为 iOS 真机（通过 `IosManager.listDevices()`）\n3. 检查是否为 Android 设备（通过 `AndroidDeviceManager.getConnectedDevices()`）\n4. 检查是否为模拟器（通过 `mobilecli.getDevices()`）\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n> 资料来源：[src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## 环境要求\n\n### Node.js 版本\n\n要求 Node.js 版本 >= 18\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\n> 资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n### mobilecli 依赖\n\n`mobilecli` 是可选依赖项，用于底层设备通信：\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n服务器启动时会验证 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly.`);\n }\n};\n```\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 配置问题排查\n\n### 常见配置错误\n\n| 错误信息 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| `mobilecli is not available` | mobilecli 未安装或路径错误 | 参考 [Wiki 安装文档](https://github.com/mobile-next/mobile-mcp/wiki) |\n| `iOS tunnel is not running` | iOS 设备隧道未建立 | 确保 WebDriverAgent 和端口转发正常运行 |\n| `Port forwarding to WebDriverAgent is not running` | WDA 端口未转发 | 检查端口 8100 是否正常转发 |\n| `WebDriverAgent is not running on device` | WDA 应用未启动 | 重启设备上的 WDA 应用 |\n\n### 调试步骤\n\n1. **验证 mobilecli**：运行 `npx mobilecli --version` 确认安装\n2. **检查设备连接**：`mobilecli list-devices` 查看可用设备\n3. **查看服务端日志**：启用详细日志以诊断问题\n4. **参考 Wiki 文档**：访问 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) 获取详细故障排除指南\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n> 资料来源：[src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n## 完整配置示例\n\n### 开发环境完整配置\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"],\n \"env\": {\n \"MOBILEMCP_AUTH\": \"dev-token\"\n }\n }\n }\n}\n```\n\n### 生产环境 SSE 模式配置\n\n```bash\n# 启动带认证的 SSE 服务器\nMOBILEMCP_AUTH=secure-token npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n对应的客户端配置：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"],\n \"url\": \"http://localhost:3000/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer secure-token\"\n }\n }\n }\n}\n```\n\n## 进阶配置\n\n### iOS 设备专用配置\n\niOS 设备需要额外的 WebDriverAgent (WDA) 配置。服务器会自动处理：\n\n1. 隧道连接验证\n2. WDA 端口转发检查（默认端口 8100）\n3. WebDriverAgent 运行状态检测\n\n```typescript\nprivate async assertTunnelRunning(): Promise {\n if (await this.isTunnelRequired()) {\n if (!(await this.isTunnelRunning())) {\n throw new ActionableError(\"iOS tunnel is not running\");\n }\n }\n}\n\nprivate async wda(): Promise {\n await this.assertTunnelRunning();\n \n if (!(await this.isWdaForwardRunning())) {\n throw new ActionableError(\"Port forwarding to WebDriverAgent is not running\");\n }\n \n const wda = new WebDriverAgent(\"localhost\", WDA_PORT);\n \n if (!(await wda.isRunning())) {\n throw new ActionableError(\"WebDriverAgent is not running on device\");\n }\n \n return wda;\n}\n```\n\n> 资料来源：[src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android 设备专用配置\n\nAndroid 设备通过 ADB 通信，支持以下功能：\n\n- 应用安装（`.apk` 文件）\n- 应用卸载（通过 bundle ID）\n- 应用启动（支持设置 locale）\n- Shell 命令执行\n\n```typescript\npublic async launchApp(packageName: string, locale?: string): Promise {\n validatePackageName(packageName);\n \n if (locale) {\n validateLocale(locale);\n try {\n this.silentAdb(\"shell\", \"cmd\", \"locale\", \"set-app-locales\", packageName, \"--locales\", locale);\n } catch (error) {\n // set-app-locales requires Android 13+ (API 33)\n }\n }\n \n try {\n this.silentAdb(\"shell\", \"monkey\", \"-p\", packageName, \"-c\", \"android.intent.category.LAUNCHER\", \"1\");\n } catch (error) {\n throw new ActionableError(`Failed launching app with package name \"${packageName}\"`);\n }\n}\n```\n\n> 资料来源：[src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n\n## 相关资源\n\n- [官方 Wiki 文档](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Mobile MCP Roadmap](https://github.com/orgs/mobile-next/projects/3)\n- [Prompt 示例库](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- [Slack 社区](https://mobilenexthq.com/join-slack)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [设备管理](#device-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 系统架构\n\n## 概述\n\nMobile MCP 是一个基于 Model Context Protocol (MCP) 的移动端自动化服务框架，旨在为 AI Agent 提供统一的移动设备交互能力。该项目支持 iOS 和 Android 平台，能够控制真机、模拟器和模拟器，核心设计理念是通过原生无障碍树（Accessibility Tree）实现 UI 元素识别和交互，无需依赖计算机视觉模型。 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 整体架构\n\nMobile MCP 采用分层架构设计，从上到下依次为：MCP 协议层、工具调度层、机器人抽象层和设备适配层。这种设计确保了上层与具体设备实现的解耦，使得框架能够灵活支持多种移动设备类型。\n\n```mermaid\ngraph TD\n A[MCP Client
Claude/Cursor等] --> B[MCP SDK
协议通信]\n B --> C[Server
工具注册与调度]\n C --> D[Robot Interface
抽象接口层]\n D --> E1[iOS Robot
WebDriverAgent]\n D --> E2[Android Robot
mobilecli]\n D --> E3[Simulator Robot]\n E1 --> F1[iOS Device
真机/模拟器]\n E2 --> F2[Android Device
真机/模拟器]\n E3 --> F1\n```\n\n## 核心组件\n\n### MCP 服务层\n\n**src/server.ts** 是整个系统的核心入口，负责 MCP 协议的初始化、工具定义和执行调度。\n\n| 组件 | 职责 |\n|------|------|\n| tool() | 工具定义函数，使用 Zod 进行参数校验 |\n| getRobotFromDevice() | 根据设备 ID 返回对应的 Robot 实例 |\n| ensureMobilecliAvailable() | 验证 mobilecli 依赖是否可用 |\n\n服务层初始化时首先调用 `ensureMobilecliAvailable()` 验证 mobilecli 可用性，通过 `posthog(\"launch\", {})` 记录启动事件。随后通过 `getRobotFromDevice()` 方法实现设备类型的自动识别。 资料来源：[src/server.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n### 设备管理机制\n\n#### 设备识别流程\n\n```mermaid\ngraph TD\n A[设备ID] --> B{检查iOS设备列表}\n B -->|匹配| C[返回IosRobot]\n B -->|不匹配| D{检查Android设备列表}\n D -->|匹配| E[返回AndroidRobot]\n D -->|不匹配| F{检查iOS模拟器}\n F -->|匹配| G[返回IosRobot]\n F -->|不匹配| H[抛出异常]\n```\n\n设备识别按照 iOS 真机 → Android 真机 → iOS 模拟器的优先级顺序进行检测。每个设备类型都有对应的 Manager 类负责设备列表管理：\n\n- **IosManager**: 通过 `iosManager.listDevices()` 获取 iOS 设备列表\n- **AndroidDeviceManager**: 通过 `androidManager.getConnectedDevices()` 获取 Android 设备列表\n- **mobilecli**: 通过 `mobilecli.getDevices()` 获取模拟器列表\n\n资料来源：[src/server.ts:20-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n#### 设备列表工具\n\n系统提供 `mobile_list_available_devices` 工具用于列举所有可用设备，返回设备 ID、平台类型、设备名称和连接状态信息。\n\n## 机器人抽象层\n\n### Robot 接口定义\n\n**src/robot.ts** 定义了 Robot 抽象接口，规定了所有设备类型必须实现的核心方法：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| getScreenSize() | 获取屏幕尺寸 | 无 |\n| getOrientation() | 获取屏幕方向 | 无 |\n| setOrientation() | 设置屏幕方向 | orientation |\n| swipe() | 滑动操作 | direction, distance |\n| swipeFromCoordinate() | 从坐标滑动 | x, y, direction, distance |\n| tap() | 点击操作 | x, y |\n| doubleTap() | 双击操作 | x, y |\n| longPress() | 长按操作 | x, y, duration |\n| getScreenshot() | 获取截图 | 无 |\n| getElementsOnScreen() | 获取屏幕元素 | 无 |\n| listApps() | 列出已安装应用 | 无 |\n| launchApp() | 启动应用 | packageName, locale |\n| terminateApp() | 终止应用 | packageName |\n| installApp() | 安装应用 | path |\n| uninstallApp() | 卸载应用 | bundleId |\n| openUrl() | 打开 URL | url |\n| sendKeys() | 发送按键 | text |\n| pressButton() | 按压按钮 | button |\n\n资料来源：[src/robot.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n### 屏幕元素数据模型\n\n```typescript\ninterface ScreenElement {\n type: string; // 元素类型：TextField, Button, Switch 等\n label: string; // 无障碍标签\n name: string; // 元素名称\n value: string; // 元素值\n identifier: string; // 元素标识符\n rect: {\n x: number; // 左上角 X 坐标\n y: number; // 左上角 Y 坐标\n width: number; // 元素宽度\n height: number; // 元素高度\n };\n}\n```\n\n## iOS 实现\n\n### 架构特点\n\niOS 设备控制采用 WebDriverAgent (WDA) 作为底层交互协议，通过 `go-ios` 工具建立设备隧道和端口转发。\n\n```mermaid\ngraph LR\n A[MCP Server] -->|localhost:PORT| B[Port Forwarding]\n B --> C[WebDriverAgent]\n C --> D[iOS Device]\n \n E[go-ios tunnel] -->|WDA_PORT| B\n E -->|IOS_TUNNEL_PORT| F[iOS Device Network]\n```\n\n### 关键组件\n\n**src/ios.ts** 包含以下核心功能：\n\n| 组件 | 功能 |\n|------|------|\n| isTunnelRunning() | 检查 iOS 隧道是否运行 |\n| isWdaForwardRunning() | 检查 WDA 端口转发是否建立 |\n| assertTunnelRunning() | 确保隧道可用 |\n| wda() | 获取 WebDriverAgent 实例 |\n\niOS 实现层包含严格的状态检查机制，在执行任何设备操作前必须确保隧道和端口转发正常运行。 资料来源：[src/ios.ts:1-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### WebDriverAgent 交互\n\n**src/webdriver-agent.ts** 实现了 WebDriverAgent 协议，支持以下操作：\n\n| 操作 | 端点 | 方法 |\n|------|------|------|\n| 按压按钮 | /wda/pressButton | POST |\n| 指针动作 | /actions | POST |\n| 获取页面源码 | /source/?format=json | GET |\n| 打开 URL | /url | POST |\n\n元素识别通过 Accessibility Tree 实现，系统只返回特定类型的元素：TextField、Button、Switch、Icon、SearchField、StaticText、Image，并对元素可见性进行过滤。 资料来源：[src/webdriver-agent.ts:1-120](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n## Android 实现\n\n### mobilecli 集成\n\nAndroid 设备通过 mobilecli 命令行工具实现控制。**src/mobile-device.ts** 封装了所有 Android 特有的交互逻辑。\n\n| 命令 | 功能 |\n|------|------|\n| io tap x,y | 点击坐标 |\n| io longpress x,y --duration ms | 长按操作 |\n| io text \"text\" | 输入文本 |\n| io button BACK/HOME | 按压虚拟按键 |\n| dump ui | 获取 UI 层次结构 |\n| device orientation set/get | 屏幕方向控制 |\n\n资料来源：[src/mobile-device.ts:1-60](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n### UI 层级获取\n\nAndroid 设备通过 `dump ui` 命令获取屏幕元素，响应结构为 DumpUIResponse，包含 data.elements 数组，每个元素包含 type、label、text、name、value、identifier、rect 和 focused 属性。\n\n## 通信协议\n\n### STDIO 模式\n\n默认配置下，Mobile MCP 通过标准输入输出（STDIO）与 MCP Client 通信，适用于本地集成场景。启动命令：\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\n### SSE 服务器模式\n\n当需要远程连接时，可启用 SSE（Server-Sent Events）服务器模式：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n可通过环境变量配置认证令牌：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nSSE 模式下，所有请求需要携带 `Authorization: Bearer ` 头部。 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 工具系统\n\n### 工具注册机制\n\n所有工具通过 `tool()` 函数注册到 MCP 服务器，每个工具包含：\n\n| 属性 | 说明 |\n|------|------|\n| name | 工具名称，如 mobile_tap_on_screen |\n| description | 工具功能描述 |\n| inputSchema | Zod schema 定义参数 |\n| annotations | 工具标注，如 destructiveHint |\n| handler | 异步处理函数 |\n\n### 核心工具列表\n\n| 工具名 | 功能 | 破坏性提示 |\n|--------|------|------------|\n| mobile_list_available_devices | 列出可用设备 | 否 |\n| mobile_get_screen_size | 获取屏幕尺寸 | 否 |\n| mobile_get_orientation | 获取屏幕方向 | 否 |\n| mobile_set_orientation | 设置屏幕方向 | 是 |\n| mobile_list_apps | 列出已安装应用 | 否 |\n| mobile_launch_app | 启动应用 | 是 |\n| mobile_terminate_app | 终止应用 | 是 |\n| mobile_install_app | 安装应用 | 是 |\n| mobile_uninstall_app | 卸载应用 | 是 |\n| mobile_take_screenshot | 截图 | 否 |\n| mobile_list_elements_on_screen | 获取屏幕元素 | 否 |\n| mobile_click_on_screen_at_coordinates | 点击坐标 | 是 |\n| mobile_double_tap_on_screen | 双击坐标 | 是 |\n| mobile_long_press_on_screen_at_coordinates | 长按坐标 | 是 |\n| mobile_swipe_on_screen | 滑动屏幕 | 是 |\n| mobile_type_keys | 输入文本 | 是 |\n| mobile_press_button | 按压按钮 | 是 |\n| mobile_open_url | 打开 URL | 是 |\n\n资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP 协议实现 |\n| zod | ^4.1.13 | 参数校验 |\n| express | 5.1.0 | SSE 服务器 |\n| commander | 14.0.0 | CLI 参数解析 |\n| fast-xml-parser | 5.5.7 | XML 解析 |\n| qs | ^6.15.0 | 查询字符串处理 |\n| ajv | ^8.18.0 | JSON Schema 验证 |\n\n### 可选依赖\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| mobilecli | 0.3.70 | Android 设备控制 |\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 安全机制\n\n### URL 安全限制\n\n系统默认只允许 http:// 和 https:// 协议 URL，unsafe URL schemes 需要显式设置环境变量：\n\n```bash\nMOBILEMCP_ALLOW_UNSAFE_URLS=1\n```\n\n此检查在 `mobile_open_url` 工具中实现。 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 启动流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Server as Server\n participant Mobilecli as mobilecli\n participant Device as Device Manager\n \n MCP->>Server: 连接请求\n Server->>Mobilecli: 检查版本\n alt mobilecli 不可用\n Server-->>MCP: 抛出错误\n end\n Server->>Device: 获取设备列表\n Device-->>Server: 设备信息\n Server->>MCP: 注册工具\n MCP->>Server: 工具调用请求\n Server->>Device: 获取 Robot 实例\n Device-->>Server: Robot 对象\n Server->>Robot: 执行操作\n Robot-->>Server: 操作结果\n Server-->>MCP: 返回结果\n```\n\n## 扩展性设计\n\n系统通过 Robot 接口抽象层支持多种设备类型的扩展，新增设备类型只需：\n\n1. 实现 Robot 接口的所有方法\n2. 在 `getRobotFromDevice()` 中添加设备识别逻辑\n3. 注册对应的 Manager 类\n\n这种设计模式使得框架具有良好的可扩展性，能够适应新平台或新设备类型的集成需求。\n\n---\n\n\n\n## 设备管理\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [iOS 实现](#ios-implementation), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 设备管理\n\n## 概述\n\n设备管理是 Mobile MCP 的核心子系统，负责统一管理 iOS、Android 模拟器、 Android 模拟器以及物理真机等各类移动设备。该模块通过抽象层将不同平台的设备操作统一为一致的接口，使上层工具能够以平台无关的方式与设备进行交互。\n\n设备管理的核心职责包括：\n\n- 设备发现与枚举\n- 设备类型自动识别\n- 设备连接状态管理\n- 设备 Robot 实例化\n- Agent 状态维护与自动安装\n\n资料来源：[src/server.ts:16-18]()\n\n## 架构设计\n\n### 整体架构\n\nMobile MCP 采用分层架构设计，设备管理层位于服务层与平台实现层之间：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[Server.ts 工具层]\n B --> C[设备管理模块]\n C --> D[Robot 抽象接口]\n D --> E[iOS Robot 实现]\n D --> F[Android Robot 实现]\n D --> G[MobileDevice Robot 实现]\n C --> H[mobilecli 工具层]\n H --> I[iOS 平台层]\n H --> J[Android 平台层]\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `getRobotFromDevice()` | src/server.ts | 设备类型检测与 Robot 实例化工厂 |\n| `Robot` | src/robot.ts | 设备操作抽象接口定义 |\n| `IosRobot` | src/ios.ts | iOS 设备操作实现 |\n| `AndroidRobot` | src/android.ts | Android 设备操作实现 |\n| `MobileDevice` | src/mobile-device.ts | 模拟器设备操作实现 |\n| `IosManager` | src/ios.ts | iOS 设备枚举与管理 |\n| `AndroidDeviceManager` | src/android.ts | Android 设备枚举与管理 |\n\n资料来源：[src/server.ts:16-66]()\n\n## 设备发现流程\n\n### 设备列表获取\n\n当调用 `mobile_list_available_devices` 工具时，系统按以下顺序扫描各平台设备：\n\n```mermaid\ngraph TD\n A[开始] --> B[初始化 IosManager]\n B --> C[初始化 AndroidDeviceManager]\n C --> D[获取 Android 设备列表]\n D --> E[遍历 Android 设备详情]\n E --> F[获取 iOS 设备列表]\n F --> G[遍历 iOS 设备详情]\n G --> H[通过 mobilecli 获取模拟器]\n H --> I[合并去重]\n I --> J[返回设备列表]\n```\n\n设备发现函数实现：\n\n```typescript\nasync ({}) => {\n ensureMobilecliAvailable();\n const iosManager = new IosManager();\n const androidManager = new AndroidDeviceManager();\n const devices: MobilecliDevice[] = [];\n // 获取 Android 设备\n const androidDevices = androidManager.getConnectedDevices();\n // ... 合并各平台设备\n}\n```\n\n资料来源：[src/server.ts:100-130]()\n\n### 设备类型识别\n\n`getRobotFromDevice()` 函数负责将设备 ID 映射到对应的 Robot 实现：\n\n```mermaid\ngraph TD\n A[传入 deviceId] --> B{检查是否为 iOS 真机}\n B -->|是| C[返回 IosRobot]\n B -->|否| D{检查是否为 Android 真机}\n D -->|是| E[返回 AndroidRobot]\n D -->|否| F{检查是否为 iOS 模拟器}\n F -->|是| G[检查 agentVerifiedSimulators]\n G -->|未验证| H[调用 agentStatus]\n H -->|失败| I[调用 agentInstall]\n I --> J[添加到已验证集合]\n J --> K[返回 MobileDevice]\n F -->|是| L[返回 MobileDevice]\n```\n\n核心实现逻辑：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n ensureMobilecliAvailable();\n \n // 检查 iOS 真机\n const iosManager = new IosManager();\n const iosDevices = iosManager.listDevices();\n const iosDevice = iosDevices.find(d => d.deviceId === deviceId);\n if (iosDevice) {\n return new IosRobot(deviceId);\n }\n \n // 检查 Android 真机\n const androidManager = new AndroidDeviceManager();\n const androidDevices = androidManager.getConnectedDevices();\n const androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n if (androidDevice) {\n return new AndroidRobot(deviceId);\n }\n \n // 检查 iOS 模拟器\n const response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n });\n // ... 模拟器处理逻辑\n}\n```\n\n资料来源：[src/server.ts:16-66]()\n\n## Robot 抽象接口\n\n`Robot` 接口定义了所有设备类型的通用操作方法：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| `tap(x, y)` | 点击屏幕指定坐标 | x: number, y: number |\n| `doubleTap(x, y)` | 双击屏幕指定坐标 | x: number, y: number |\n| `longPress(x, y, duration)` | 长按屏幕指定坐标 | x, y, duration(ms) |\n| `swipeFromCoordinate(x, y, direction, distance?)` | 从坐标处滑动 | 方向、距离 |\n| `getScreenshot()` | 获取屏幕截图 | 无 |\n| `getElementsOnScreen()` | 获取屏幕元素列表 | 无 |\n| `listApps()` | 列出已安装应用 | 无 |\n| `launchApp(packageName, locale?)` | 启动应用 | 包名、区域 |\n| `terminateApp(packageName)` | 终止应用 | 包名 |\n| `installApp(path)` | 安装应用 | 文件路径 |\n| `uninstallApp(bundleId)` | 卸载应用 | 标识符 |\n| `openUrl(url)` | 打开 URL | 网址 |\n| `sendKeys(text)` | 发送文本输入 | 文本内容 |\n| `pressButton(button)` | 按下物理按钮 | 按钮类型 |\n| `setOrientation(orientation)` | 设置屏幕方向 | portrait/landscape |\n| `getOrientation()` | 获取屏幕方向 | 无 |\n\n资料来源：[src/robot.ts:1-80]()\n\n## 平台实现\n\n### iOS 设备管理\n\niOS 平台使用 `IosManager` 类进行设备管理，通过 WebDriverAgent 或 iOS Device Kit 实现与设备的通信：\n\n- 支持物理真机连接\n- 支持 iOS 模拟器\n- 自动检测 WebDriverAgent 安装状态\n- 支持应用启动时指定区域设置\n\n```typescript\nexport class IosManager {\n listDevices(): IosDevice[] {\n // 列出所有 iOS 设备\n }\n}\n\nexport class IosRobot implements Robot {\n constructor(deviceId: string) {\n // 初始化 iOS Robot 实例\n }\n}\n```\n\n资料来源：[src/ios.ts:1-50]()\n\n### Android 设备管理\n\nAndroid 平台使用 `AndroidDeviceManager` 类进行设备管理，通过 ADB 和 UI Automator 实现与设备的通信：\n\n- 支持物理真机连接\n- 支持 Android 模拟器\n- 支持折叠屏等多屏幕设备\n- 支持应用启动时指定区域设置\n\n```typescript\nexport class AndroidDeviceManager {\n getConnectedDevices(): AndroidDevice[] {\n // 获取已连接的 Android 设备\n }\n}\n\nexport class AndroidRobot implements Robot {\n constructor(deviceId: string) {\n // 初始化 Android Robot 实例\n }\n}\n```\n\n资料来源：[src/android.ts:1-50]()\n\n## mobilecli 集成\n\n### mobilecli 依赖\n\nmobilecli 是 Mobile MCP 的核心底层工具，提供跨平台的设备管理能力：\n\n| 属性 | 值 |\n|------|-----|\n| 包名 | mobilecli |\n| 版本 | 0.3.70 |\n| 类型 | 可选依赖 (optionalDependencies) |\n| Node 版本要求 | >=18 |\n\n资料来源：[package.json:28-29]()\n\n### 依赖检查\n\n在执行任何设备操作前，系统会通过 `ensureMobilecliAvailable()` 函数验证 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(\n `mobilecli is not available or not working properly. ` +\n `Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`\n );\n }\n};\n```\n\n资料来源：[src/server.ts:9-17]()\n\n### mobilecli API\n\n| API 方法 | 功能 | 返回类型 |\n|----------|------|----------|\n| `mobilecli.getVersion()` | 获取 mobilecli 版本 | string |\n| `mobilecli.getDevices(options)` | 获取设备列表 | DeviceResponse |\n| `mobilecli.agentStatus(deviceId)` | 检查设备 Agent 状态 | AgentStatus |\n| `mobilecli.agentInstall(deviceId)` | 在设备上安装 Agent | void |\n\n```typescript\ninterface DeviceResponse {\n status: \"ok\" | \"fail\";\n data?: {\n devices: MobilecliDevice[];\n };\n}\n\ninterface MobilecliDevice {\n id: string;\n name: string;\n platform: string;\n type: string;\n}\n```\n\n资料来源：[src/mobilecli.ts:1-30]()\n\n## 模拟器特殊处理\n\n### Agent 验证机制\n\n对于 iOS 模拟器，系统维护一个 `agentVerifiedSimulators` 集合来追踪已验证的模拟器：\n\n```typescript\nconst agentVerifiedSimulators = new Set();\n```\n\n首次使用模拟器时，系统自动执行 Agent 状态检查：\n\n```mermaid\ngraph TD\n A[模拟器 deviceId] --> B{agentVerifiedSimulators.has}\n B -->|未验证| C[调用 agentStatus]\n C -->|状态失败| D[调用 agentInstall]\n D --> E[添加到已验证集合]\n B -->|已验证| F[跳过验证]\n E --> G[返回 MobileDevice]\n F --> G\n```\n\n资料来源：[src/server.ts:50-60]()\n\n### 模拟器设备类型\n\n通过 mobilecli 获取的模拟器使用 `MobileDevice` 类进行管理，该类提供统一的设备操作接口。\n\n资料来源：[src/mobile-device.ts:1-30]()\n\n## 错误处理\n\n### ActionableError\n\n系统定义 `ActionableError` 类用于提供可操作的错误信息：\n\n```typescript\nclass ActionableError extends Error {\n constructor(message: string) {\n super(message);\n }\n}\n```\n\n### 常见错误场景\n\n| 错误场景 | 错误消息 | 解决方案 |\n|----------|----------|----------|\n| mobilecli 不可用 | \"mobilecli is not available or not working properly\" | 检查安装并参考 Wiki 文档 |\n| 设备未找到 | \"Device \\\"{deviceId}\\\" not found\" | 使用 mobile_list_available_devices 查看可用设备 |\n| Agent 安装失败 | \"agentInstall failed\" | 手动检查 WebDriverAgent/iOS Device Kit 安装状态 |\n\n资料来源：[src/server.ts:9-17, 64-66]()\n\n## 使用示例\n\n### 列出可用设备\n\n```bash\n# 使用 Claude Code\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n\n# 调用 mobile_list_available_devices 工具\n```\n\n### 选择设备并执行操作\n\n```typescript\n// 1. 获取设备列表\nconst devices = await server.tools.mobile_list_available_devices();\n\n// 2. 根据设备 ID 创建 Robot 实例\nconst robot = getRobotFromDevice(deviceId);\n\n// 3. 执行设备操作\nawait robot.tap(100, 200);\nawait robot.getScreenshot();\nawait robot.launchApp(\"com.example.app\");\n```\n\n## 相关工具\n\n设备管理模块提供以下 MCP 工具：\n\n| 工具名称 | 功能 | 只读 |\n|----------|------|------|\n| `mobile_list_available_devices` | 列出所有可用设备 | 是 |\n| `mobile_get_screen_size` | 获取屏幕尺寸 | 是 |\n| `mobile_get_orientation` | 获取屏幕方向 | 是 |\n| `mobile_set_orientation` | 设置屏幕方向 | 否 |\n| `mobile_list_apps` | 列出已安装应用 | 是 |\n| `mobile_launch_app` | 启动应用 | 否 |\n| `mobile_terminate_app` | 终止应用 | 否 |\n| `mobile_install_app` | 安装应用 | 否 |\n| `mobile_uninstall_app` | 卸载应用 | 否 |\n\n资料来源：[src/server.ts:100-200]()\n\n## 总结\n\n设备管理模块是 Mobile MCP 连接 MCP 协议与实际移动设备的桥梁。通过统一的 Robot 抽象接口，系统支持 iOS 物理设备、iOS 模拟器、Android 物理设备和 Android 模拟器四种设备类型。该模块利用 mobilecli 工具进行跨平台设备发现和通信，并针对不同平台特性（如 iOS 的 Agent 验证机制）进行了专门优化。\n\n---\n\n\n\n## MCP 工具详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [iOS 实现](#ios-implementation), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# MCP 工具详解\n\nMobile MCP 是一个基于 Model Context Protocol (MCP) 的移动设备自动化框架，通过标准化的工具接口实现对 iOS、Android、模拟器和真机的远程控制。本文详细介绍该项目中所有可用的 MCP 工具，包括其功能、参数定义和底层实现机制。\n\n## 工具系统架构\n\nMobile MCP 的工具系统采用注册式架构，所有工具通过统一的 `tool()` 函数注册到 MCP 服务器。每个工具包含名称、标题、描述、参数模式和回调函数四个核心组件。\n\n```mermaid\ngraph TD\n A[MCP Client] -->|tool request| B[McpServer]\n B --> C[tool registry]\n C --> D[回调函数执行]\n D --> E[device manager]\n E --> F[iOS Robot]\n E --> G[Android Robot]\n F --> H[WebDriverAgent/iOS]\n G --> I[ADB/Android]\n D --> J[返回结果]\n```\n\n### 工具注册机制\n\n工具注册函数定义于 `src/server.ts`，其签名如下：\n\n```typescript\nconst tool = (\n name: string, // 工具唯一标识符\n title: string, // 人类可读标题\n description: string, // 功能描述\n paramsSchema: ZodSchemaShape, // 参数模式\n annotations: ToolAnnotations, // 注解信息\n cb: (args: any) => Promise // 回调函数\n) => { ... }\n```\n\n`ToolAnnotations` 接口定义了工具的语义注解：\n\n| 注解字段 | 类型 | 说明 |\n|---------|------|------|\n| `readOnlyHint` | boolean | 指示工具是否只读操作 |\n| `destructiveHint` | boolean | 指示工具是否可能造成数据损坏 |\n\n资料来源：[src/server.ts:52-57]()\n\n## 设备管理工具\n\n### 列出可用设备\n\n**工具名称**: `mobile_list_available_devices`\n\n**功能描述**: 返回所有可用的移动设备列表，包括 iOS 模拟器、iOS 真机、Android 模拟器、Android 真机以及离线设备（可选）。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `includeOffline` | boolean | 否 | 是否包含离线设备 |\n\n**返回值**: JSON 格式的设备列表，包含每个设备的标识符、平台类型、设备类型和可用状态。\n\n资料来源：[src/server.ts:103-112]()\n\n### 获取设备类型\n\n**工具名称**: `mobile_get_device_type`\n\n**功能描述**: 获取指定设备的类型信息。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**实现逻辑**: 通过遍历 iOS 设备列表、Android 设备列表和模拟器列表来确定设备类型。\n\n```mermaid\ngraph TD\n A[输入 deviceId] --> B{查找 iOS 设备}\n B -->|找到| C[返回 ios]\n B -->|未找到| D{查找 Android 设备}\n D -->|找到| E[返回 android]\n D -->|未找到| F{查找模拟器}\n F -->|找到| G[返回 simulator]\n F -->|未找到| H[抛出异常]\n```\n\n资料来源：[src/server.ts:85-102]()\n\n## 屏幕与显示工具\n\n### 获取屏幕尺寸\n\n**工具名称**: `mobile_get_screen_size`\n\n**功能描述**: 获取移动设备的屏幕尺寸（像素单位）。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含 `width` 和 `height` 的屏幕尺寸对象。\n\n资料来源：[README.md]()\n\n### 获取屏幕方向\n\n**工具名称**: `mobile_get_orientation`\n\n**功能描述**: 获取当前设备的屏幕方向。\n\n**返回值**: `\"portrait\"` 或 `\"landscape\"`。\n\n资料来源：[src/robot.ts:67-70]()\n\n### 设置屏幕方向\n\n**工具名称**: `mobile_set_orientation`\n\n**功能描述**: 更改设备的屏幕方向。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `orientation` | string | 是 | 目标方向：`portrait` 或 `landscape` |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nsetOrientation(orientation: Orientation): Promise;\n```\n\n资料来源：[src/robot.ts:60-65]()\n\n## 应用管理工具\n\n### 列出已安装应用\n\n**工具名称**: `mobile_list_apps`\n\n**功能描述**: 列出目标设备上所有已安装的应用程序。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含应用名称、包名/Bundle ID 等信息的 JSON 数组。\n\n资料来源：[README.md]()\n\n### 启动应用\n\n**工具名称**: `mobile_launch_app`\n\n**功能描述**: 通过包名称（Android）或 Bundle ID（iOS）启动指定应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 应用标识符 |\n| `locale` | string | 否 | 启动时使用的语言环境（仅 iOS） |\n\n资料来源：[src/server.ts](), [CHANGELOG.md]()\n\n### 终止应用\n\n**工具名称**: `mobile_terminate_app`\n\n**功能描述**: 强制停止并终止正在运行的应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 要终止的应用标识符 |\n\n**Android 实现**: 使用 `adb shell am force-stop ` 命令。\n\n资料来源：[src/android.ts:126-128]()\n\n### 安装应用\n\n**工具名称**: `mobile_install_app`\n\n**功能描述**: 从本地文件安装应用。\n\n**支持格式**: `.apk`（Android）、`.ipa`（iOS）、`.app`、`.zip`\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appPath` | string | 是 | 应用文件路径 |\n\n### 卸载应用\n\n**工具名称**: `mobile_uninstall_app`\n\n**功能描述**: 卸载指定应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 应用标识符 |\n\n## 屏幕交互工具\n\n### 截图\n\n**工具名称**: `mobile_take_screenshot`\n\n**功能描述**: 拍摄当前屏幕截图，用于了解屏幕内容。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n### 保存截图\n\n**工具名称**: `mobile_save_screenshot`\n\n**功能描述**: 将截图保存到指定文件路径。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `outputPath` | string | 是 | 输出文件路径 |\n\n**安全修复**: 0.0.49 版本修复了路径遍历漏洞，防止通过 `../` 访问目录外文件。\n\n资料来源：[CHANGELOG.md]()\n\n### 点击坐标\n\n**工具名称**: `mobile_click_on_screen_at_coordinates`\n\n**功能描述**: 在指定屏幕坐标处执行点击操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n\n### 双击\n\n**工具名称**: `mobile_double_tap_on_screen`\n\n**功能描述**: 在指定坐标执行双击操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n\n### 长按\n\n**工具名称**: `mobile_long_press_on_screen_at_coordinates`\n\n**功能描述**: 在指定坐标执行长按操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n| `duration` | number | 是 | 长按持续时间（毫秒） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nlongPress(x: number, y: number, duration: number): Promise;\n```\n\n资料来源：[src/robot.ts:41-49]()\n\n### 滑动\n\n**工具名称**: `mobile_swipe_on_screen`\n\n**功能描述**: 在屏幕上执行滑动操作，支持任意方向。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `direction` | string | 是 | 滑动方向：`up`、`down`、`left`、`right` |\n\n## 输入工具\n\n### 输入文本\n\n**工具名称**: `mobile_type_keys`\n\n**功能描述**: 向当前焦点元素输入文本，支持可选的提交操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `text` | string | 是 | 要输入的文本 |\n| `submit` | boolean | 否 | 是否在输入后提交 |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nsendKeys(text: string): Promise;\n```\n\n资料来源：[src/robot.ts:29-33]()\n\n### 按键\n\n**工具名称**: `mobile_press_button`\n\n**功能描述**: 模拟物理按键按压。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `button` | string | 是 | 按键名称（如 `ENTER`、`HOME`、`BACK`） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\npressButton(button: Button): Promise;\n```\n\n**iOS 实现**（WebDriverAgent）:\n\n```typescript\nawait this.withinSession(async sessionUrl => {\n const url = `${sessionUrl}/wda/pressButton`;\n const response = await fetch(url, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ name: button }),\n });\n return response.json();\n});\n```\n\n资料来源：[src/webdriver-agent.ts](), [src/robot.ts:35-38]()\n\n## 元素检测工具\n\n### 列出屏幕元素\n\n**工具名称**: `mobile_list_elements_on_screen`\n\n**功能描述**: 列出屏幕上所有 UI 元素及其坐标和属性信息。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含元素类型、标签、名称、值、标识符和矩形区域的数组。\n\n**ScreenElement 数据结构**:\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `type` | string | 元素类型（如 `TextField`、`Button`、`Switch`） |\n| `label` | string | 元素标签 |\n| `name` | string | 元素名称 |\n| `value` | string | 元素值 |\n| `identifier` | string | 元素标识符（resource-id 或 rawIdentifier） |\n| `rect` | object | 元素矩形区域 `{x, y, width, height}` |\n\n**Android 元素收集逻辑**:\n\n```mermaid\ngraph TD\n A[获取 UI Automator XML] --> B[遍历 XML 节点]\n B --> C{节点是否包含可交互属性?}\n C -->|text/content-desc/hint/resource-id| D[创建 ScreenElement]\n C -->|无| E[跳过]\n D --> F{rect width > 0 && height > 0?}\n F -->|是| G[添加到元素列表]\n F -->|否| E\n G --> H{是否有子节点?}\n H -->|是| B\n H -->|否| I[返回元素列表]\n```\n\n**iOS 元素过滤逻辑**:\n\n```typescript\nconst acceptedTypes = [\"TextField\", \"Button\", \"Switch\", \"Icon\", \"SearchField\", \"StaticText\", \"Image\"];\n\nif (acceptedTypes.includes(source.type)) {\n if (source.isVisible === \"1\" && this.isVisible(source.rect)) {\n if (source.label !== null || source.name !== null || source.rawIdentifier !== null) {\n output.push({ ... });\n }\n }\n}\n```\n\n资料来源：[src/android.ts](), [src/webdriver-agent.ts:1-35]()\n\n## 崩溃日志工具\n\n### 列出崩溃报告\n\n**工具名称**: `mobile_list_crashes`\n\n**功能描述**: 列出设备上可用的崩溃报告。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 崩溃报告 ID 列表。\n\n**实现**:\n\n```typescript\nasync ({ device }) => {\n ensureMobilecliAvailable();\n const response = mobilecli.crashesList(device);\n return JSON.stringify(response.data);\n}\n```\n\n资料来源：[src/server.ts:201-211]()\n\n### 获取崩溃详情\n\n**工具名称**: `mobile_get_crash`\n\n**功能描述**: 根据崩溃 ID 获取完整崩溃报告内容。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `crashId` | string | 是 | 崩溃报告 ID |\n\n## 录制工具\n\n### 开始录制\n\n**工具名称**: `mobile_start_recording`\n\n**功能描述**: 开始录制屏幕操作视频。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `outputPath` | string | 是 | 输出文件路径 |\n\n**实现细节**:\n\n- 使用子进程启动录制命令\n- 设置 5 分钟超时保护\n- 返回 `ActiveRecording` 对象包含进程和开始时间\n\n### 停止录制\n\n**工具名称**: `mobile_stop_recording`\n\n**功能描述**: 停止正在进行的屏幕录制。\n\n**返回值**: 包含文件路径、大小（MB）和持续时间的信息字符串。\n\n**超时机制**:\n\n```typescript\nconst timeout = setTimeout(() => {\n child.kill(\"SIGKILL\");\n resolve();\n}, 5 * 60 * 1000);\n```\n\n资料来源：[src/server.ts:145-200]()\n\n## URL 导航工具\n\n### 打开 URL\n\n**工具名称**: `mobile_open_url`\n\n**功能描述**: 在设备浏览器或应用内打开指定 URL。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `url` | string | 是 | 目标 URL（支持 http://, https:// 或自定义 scheme） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nopenUrl(url: string): Promise;\n```\n\n**iOS 实现**（WebDriverAgent）:\n\n```typescript\npublic async openUrl(url: string): Promise {\n await this.withinSession(async sessionUrl => {\n await fetch(`${sessionUrl}/url`, {\n method: \"POST\",\n body: JSON.stringify({ url }),\n });\n });\n}\n```\n\n资料来源：[src/webdriver-agent.ts](), [src/robot.ts:25-28]()\n\n## 工具分类总览\n\n| 分类 | 工具数量 | 核心功能 |\n|------|---------|---------|\n| 设备管理 | 2 | 列表查询、类型获取 |\n| 屏幕显示 | 3 | 尺寸、方向管理 |\n| 应用管理 | 4 | 安装、卸载、启动、终止 |\n| 屏幕交互 | 5 | 点击、双击、长按、滑动、截图 |\n| 输入 | 2 | 文本输入、按键 |\n| 元素检测 | 1 | UI 元素枚举 |\n| 崩溃日志 | 2 | 列表查询、详情获取 |\n| 录制 | 2 | 开始/停止屏幕录制 |\n| 导航 | 1 | URL 打开 |\n\n## 技术依赖\n\nMobile MCP 工具系统的核心依赖：\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP 协议实现 |\n| `zod` | ^4.1.13 | 参数验证 |\n| `zod-to-json-schema` | 3.25.0 | Zod 转 JSON Schema |\n| `mobilecli` | 0.3.70 | 移动设备 CLI 接口 |\n\n资料来源：[package.json:23-34]()\n\n## 总结\n\nMobile MCP 通过统一的工具注册机制，封装了针对 iOS 和 Android 平台的大量自动化操作。所有工具遵循相同的接口规范，通过设备管理器自动路由到对应的平台实现（`IosRobot` 或 `AndroidRobot`）。这种设计使得 AI Agent 能够通过简单的工具调用完成复杂的移动端自动化任务，包括应用管理、UI 交互、数据采集和端到端工作流执行。\n\n---\n\n\n\n## iOS 实现\n\n### 相关页面\n\n相关主题：[设备管理](#device-management), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/android-robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android-robot.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# iOS 实现\n\n## 概述\n\nMobile MCP 的 iOS 实现模块负责与 iOS 设备（真机和模拟器）进行交互。该模块通过统一的抽象接口 `Robot` 提供跨平台自动化能力，同时针对 iOS 平台特性实现了特定的设备管理、元素获取和交互操作。\n\niOS 实现的核心目标包括：\n\n- 支持 iOS 模拟器（iPhone Simulator）和真机设备\n- 通过原生无障碍树（Accessibility Tree）获取 UI 元素信息\n- 提供截图、点击、滑动、文本输入等基础交互能力\n- 自动管理 WebDriverAgent 或 iOS Device Kit 生命周期\n\n资料来源：[src/robot.ts:1-50]()\n\n## 架构设计\n\n### 整体架构\n\nMobile MCP 采用分层架构设计，iOS 实现位于设备交互层：\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Server Layer]\n B --> C[Tool Handlers]\n C --> D[Robot Interface]\n D --> E[iOS Robot]\n D --> F[Android Robot]\n E --> G[IosManager]\n E --> H[Mobilecli]\n G --> I[WebDriverAgent]\n G --> J[iOS Device Kit]\n H --> K[iPhone Simulator]\n```\n\n### 设备类型识别\n\n服务器启动时通过 `getRobotFromDevice` 函数识别设备类型并返回对应的 Robot 实例：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n ensureMobilecliAvailable();\n \n // 检查是否为 iOS 真机\n const iosManager = new IosManager();\n const iosDevices = iosManager.listDevices();\n const iosDevice = iosDevices.find(d => d.deviceId === deviceId);\n if (iosDevice) {\n return new IosRobot(deviceId);\n }\n \n // 检查是否为 Android 设备\n const androidManager = new AndroidDeviceManager();\n const androidDevices = androidManager.getConnectedDevices();\n const androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n if (androidDevice) {\n return new AndroidRobot(deviceId);\n }\n \n // 检查是否为 iOS 模拟器\n const response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n });\n // ...\n};\n```\n\n资料来源：[src/server.ts:1-100]()\n\n## 核心组件\n\n### Robot 接口定义\n\n`Robot` 接口是所有设备交互的抽象基类，定义了统一的操作契约：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| `getScreenSize()` | 获取屏幕尺寸 | 无 |\n| `getOrientation()` | 获取屏幕方向 | 无 |\n| `setOrientation(orientation)` | 设置屏幕方向 | `portrait` 或 `landscape` |\n| `getScreenshot()` | 获取屏幕截图 | 无 |\n| `getElementsOnScreen()` | 获取屏幕元素列表 | 无 |\n| `tap(x, y)` | 点击指定坐标 | x, y 坐标 |\n| `doubleTap(x, y)` | 双击指定坐标 | x, y 坐标 |\n| `longPress(x, y, duration)` | 长按指定坐标 | x, y, duration(ms) |\n| `swipeFromCoordinate(x, y, direction, distance)` | 滑动操作 | 起点坐标、方向、距离 |\n| `sendKeys(text)` | 输入文本 | 文本内容 |\n| `pressButton(button)` | 按下物理按钮 | HOME, BACK, VOLUME_UP 等 |\n| `openUrl(url)` | 打开 URL | URL 字符串 |\n| `listApps()` | 列出已安装应用 | 无 |\n| `launchApp(packageName, locale?)` | 启动应用 | 包名，可选语言 |\n| `terminateApp(packageName)` | 终止应用 | 包名 |\n| `installApp(path)` | 安装应用 | 文件路径 |\n| `uninstallApp(bundleId)` | 卸载应用 | Bundle ID |\n\n资料来源：[src/robot.ts:1-120]()\n\n### IosRobot 实现\n\n`IosRobot` 是 iOS 平台的 Robot 接口实现，负责具体的 iOS 设备操作。该类封装了与 iOS 设备通信的所有逻辑，包括：\n\n- 元素查询与遍历\n- 坐标点击和手势操作\n- 文本输入\n- 应用管理\n- 截图获取\n\n### IosManager\n\n`IosManager` 负责管理 iOS 设备的发现和状态监控：\n\n- `listDevices()` - 列出所有已连接的 iOS 真机\n- 设备健康状态检查\n\n### iPhone Simulator\n\niOS 模拟器通过 `mobilecli` 工具进行管理，提供与真机类似的交互能力。模拟器支持完整的功能测试，无需真实硬件即可进行 UI 自动化测试。\n\n## 工作原理\n\n### 设备连接流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Server as MCP Server\n participant IosManager as IosManager\n participant Device as iOS 设备\n participant WDA as WebDriverAgent/iOS Device Kit\n\n User->>Server: mobile_list_available_devices\n Server->>IosManager: listDevices()\n IosManager->>Device: 查询设备\n Device-->>IosManager: 设备列表\n IosManager-->>Server: 返回设备\n Server-->>User: 可用设备列表\n\n User->>Server: 选择设备并执行操作\n Server->>IosRobot: 创建实例\n IosRobot->>WDA: 初始化连接\n WDA->>Device: 建立通信\n```\n\n### 模拟器 Agent 验证\n\n对于 iOS 模拟器，系统会自动验证并安装必要的 Agent：\n\n```typescript\nif (!agentVerifiedSimulators.has(deviceId)) {\n const agentStatus = mobilecli.agentStatus(deviceId);\n if (agentStatus.status === \"fail\") {\n mobilecli.agentInstall(deviceId);\n }\n agentVerifiedSimulators.add(deviceId);\n}\n```\n\n资料来源：[src/server.ts:50-80]()\n\n## 依赖组件\n\n### mobilecli\n\n`mobilecli` 是项目的基础依赖工具，提供跨平台的移动设备管理能力：\n\n```json\n{\n \"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n }\n}\n```\n\n版本历史记录显示 mobilecli 版本持续更新以支持新功能和修复问题：\n\n| 版本 | 主要更新 |\n|------|----------|\n| 0.3.70 | 当前使用版本，支持最新 iOS Device Kit |\n| 0.3.68 | 引入 iOS Device Kit |\n| 0.2.0 | 早期版本 |\n\n资料来源：[package.json:25-30]()\n\n### iOS Device Kit vs WebDriverAgent\n\n从 v0.0.53 版本开始，项目从 WebDriverAgent 迁移到开源的 iOS Device Kit（Apache 许可证），主要优势包括：\n\n- 开源许可证（WebDriverAgent 使用自定义许可证）\n- 更稳定的设备连接管理\n- 更好的黑屏问题处理\n\n```mermaid\ngraph LR\n A[v0.0.52 及之前] -->|WebDriverAgent| B[闭源实现]\n C[v0.0.53 及之后] -->|iOS Device Kit| D[Apache 许可证]\n```\n\n资料来源：[CHANGELOG.md]()\n\n## iOS 工具集\n\nMobile MCP 为 iOS 平台提供以下 MCP 工具：\n\n### 设备管理\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_list_available_devices` | 列出所有可用设备（包含 iOS 模拟器和真机） |\n| `mobile_get_screen_size` | 获取 iOS 设备屏幕尺寸 |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向 |\n\n### 应用管理\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_list_apps` | 列出 iOS 设备上安装的所有应用 |\n| `mobile_launch_app` | 通过 Bundle ID 启动应用 |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 安装 .ipa 或 .app 文件 |\n| `mobile_uninstall_app` | 卸载应用 |\n\n### 屏幕交互\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_take_screenshot` | 截取当前屏幕 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 获取屏幕元素及属性 |\n| `mobile_click_on_screen_at_coordinates` | 点击指定坐标 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 滑动操作 |\n\n### 输入与导航\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_type_keys` | 输入文本 |\n| `mobile_press_button` | 按下物理按钮（HOME、BACK、VOLUME 等） |\n| `mobile_open_url` | 在浏览器中打开 URL |\n\n## 使用示例\n\n### 配置 Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 使用 Claude Code 连接 iOS 模拟器\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n\n### 列出可用设备\n\n在 Claude Code 或其他 MCP 客户端中执行：\n\n```\n使用 mobile_list_available_devices 工具列出所有可用的 iOS 设备和模拟器\n```\n\n### 在 iOS 模拟器上测试应用\n\n```bash\n# 查看可用模拟器\nxcrun simctl list\n\n# 启动特定模拟器\nxcrun simctl boot \"iPhone 16\"\n\n# 使用 mobile_list_available_devices 获取设备 ID\n# 然后使用 mobile_launch_app 启动测试应用\n```\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 设备未识别 | 运行 `xcrun simctl list` 检查模拟器状态 |\n| WebDriverAgent 连接失败 | 更新 mobilecli 到最新版本 |\n| 模拟器黑屏 | 使用 iOS Device Kit（v0.0.53+）或重启模拟器 |\n| Agent 未安装 | 调用 `mobilecli.agentInstall(deviceId)` |\n\n### 验证 mobilecli 安装\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly. \n Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`);\n }\n};\n```\n\n资料来源：[src/server.ts:15-25]()\n\n## 版本历史\n\n| 版本 | iOS 相关更新 |\n|------|--------------|\n| 0.0.54 | 更新 mobilecli 至 0.3.70；修复导致 iOS Device Kit 黑屏死机的问题 |\n| 0.0.53 | 引入 iOS Device Kit 替代 WebDriverAgent；添加崩溃报告工具 |\n| 0.0.38 | 迁移 iPhone Simulator 调用至 mobilecli；自动下载安装 WebDriverAgent |\n| 0.0.22 | 修复 go-ios 安装检测问题 |\n| 0.0.21 | 模拟器上自动启动 WebDriverAgent |\n\n资料来源：[CHANGELOG.md]()\n\n## 扩展阅读\n\n- [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) - 详细配置和调试指南\n- [Roadmap](https://github.com/orgs/mobile-next/projects/3) - 项目路线图\n- [mobilecli 文档](https://github.com/mobile-next/mobilecli) - 底层工具文档\n\n---\n\n\n\n## Android 实现\n\n### 相关页面\n\n相关主题：[设备管理](#device-management), [iOS 实现](#ios-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# Android 实现\n\n## 概述\n\nAndroid 实现是 mobile-mcp 项目的核心模块之一，负责与 Android 设备（真机、模拟器）进行交互。该模块通过 ADB（Android Debug Bridge）协议与设备通信，实现了设备管理、UI 元素检测、屏幕交互、应用管理等一系列移动端自动化能力。\n\nAndroid 模块的主要职责包括：\n\n- 通过 `adb devices` 命令发现和验证已连接的 Android 设备\n- 使用 `uiautomator dump` 获取界面层次结构并解析 UI 元素\n- 执行点击、双击、长按、滑动等手势操作\n- 管理应用生命周期（安装、卸载、启动、终止）\n- 截取屏幕截图和屏幕录制\n- 获取设备信息（屏幕尺寸、方向、系统版本等）\n\n资料来源：[src/android.ts:1-100]()\n\n## 系统架构\n\n### 整体架构\n\nMobile MCP 采用跨平台统一抽象的设计理念，通过 Robot 模式为 iOS 和 Android 提供统一的操作接口。Android 实现位于这一架构的核心层。\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Manager]\n B --> C[Android Device Manager]\n B --> D[iOS Device Manager]\n C --> E[AndroidRobot]\n D --> F[IosRobot]\n E --> G[ADB Communication]\n G --> H[Android Device/Emulator]\n F --> I[WebDriverAgent/go-ios]\n I --> J[iOS Device/Simulator]\n```\n\n### Android 通信流程\n\nAndroid 设备通过 ADB 与服务端通信，每条命令的执行都遵循以下流程：\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant AR as AndroidRobot\n participant ADB as ADB Command\n participant DEV as Android Device\n\n MCP->>AR: 调用 Android 方法\n AR->>ADB: 构建 adb 命令\n ADB->>DEV: 执行 shell 命令\n DEV-->>ADB: 返回执行结果\n ADB-->>AR: 解析响应数据\n AR-->>MCP: 返回结构化结果\n```\n\n资料来源：[src/android.ts:50-150]()\n\n## 核心组件\n\n### AndroidDeviceManager\n\n`AndroidDeviceManager` 类负责设备发现和枚举，是 Android 模块的入口点。\n\n| 方法 | 说明 | 返回类型 |\n|------|------|----------|\n| `getConnectedDevices()` | 获取已连接的真机和模拟器列表 | `Array<{deviceId, deviceType}>` |\n| `getConnectedDevicesWithDetails()` | 获取包含详细信息的设备列表 | `Array<{deviceId, deviceType, version, name}>` |\n\n**设备发现机制**\n\n```typescript\n// 从 android.ts 提取的关键实现逻辑\nconst names = execFileSync(getAdbPath(), [\"devices\"])\n .toString()\n .split(\"\\n\")\n .map(line => line.trim())\n .filter(line => line !== \"\")\n .filter(line => !line.startsWith(\"List of devices attached\"))\n .filter(line => line.split(\"\\t\")[1]?.trim() === \"device\") // 仅包含在线设备\n .map(line => line.split(\"\\t\")[0]);\n```\n\n设备必须满足两个条件才会被返回：\n1. 出现在 `adb devices` 命令输出中\n2. 状态为 `device`（而非 `offline` 或 `unauthorized`）\n\n资料来源：[src/android.ts:180-220]()\n\n### AndroidRobot\n\n`AndroidRobot` 是与单个 Android 设备交互的核心类，封装了所有设备操作。\n\n| 属性/方法 | 说明 |\n|-----------|------|\n| `deviceId` | 设备标识符 |\n| `getScreenSize()` | 获取屏幕分辨率 |\n| `getOrientation()` | 获取屏幕方向 |\n| `setOrientation()` | 设置屏幕方向 |\n| `listElementsOnScreen()` | 获取屏幕元素列表 |\n| `click()` | 点击指定坐标 |\n| `doubleTap()` | 双击指定坐标 |\n| `longPress()` | 长按指定坐标 |\n| `swipe()` | 滑动操作 |\n| `typeKeys()` | 输入文本 |\n| `pressButton()` | 按压物理按钮 |\n| `takeScreenshot()` | 截取屏幕截图 |\n| `startScreenRecording()` | 开始屏幕录制 |\n| `stopScreenRecording()` | 停止屏幕录制 |\n| `launchApp()` | 启动应用 |\n| `terminateApp()` | 终止应用 |\n| `installApp()` | 安装应用 |\n| `uninstallApp()` | 卸载应用 |\n| `listRunningProcesses()` | 列出运行中的进程 |\n\n资料来源：[src/android.ts:100-350]()\n\n## 设备发现机制\n\n### 设备类型检测\n\nAndroid 模块通过读取系统属性来判断设备类型：\n\n```typescript\nprivate getDeviceType(deviceId: string): string {\n const output = this.adb(deviceId, \"getprop\", \"ro.build.characteristics\");\n if (output.toString().includes(\"emulator\")) {\n return \"emulator\";\n }\n return \"device\";\n}\n```\n\n支持的设备类型：\n- **emulator**: Android 模拟器\n- **device**: Android 真机\n\n### 系统信息获取\n\n| 属性 | 获取方式 | 说明 |\n|------|----------|------|\n| `version` | `getprop ro.build.version.release` | Android 系统版本 |\n| `name` | `getprop ro.product.model` | 设备型号名称 |\n\n资料来源：[src/android.ts:200-250]()\n\n## UI 元素检测\n\n### 界面层次结构获取\n\nAndroid 使用 `uiautomator dump` 命令获取当前界面的 UI 层次结构（Accessibility Tree）：\n\n```typescript\npublic async listElementsOnScreen(): Promise {\n const output = this.uiautomatorDump();\n const parsed = this.parseUIAutomatorXML(output);\n return parsed;\n}\n```\n\n**XML 解析流程**\n\n```mermaid\ngraph LR\n A[Raw XML Output] --> B[fast-xml-parser]\n B --> C[解析后对象]\n C --> D[提取 node 属性]\n D --> E[构建元素数组]\n E --> F[ScreenElements]\n```\n\n### 元素属性提取\n\n解析后的 UI 元素包含以下关键属性：\n\n| 属性 | XML 路径 | 说明 |\n|------|----------|------|\n| `text` | `@text` | 元素文本内容 |\n| `resourceId` | `@resource-id` | 资源 ID |\n| `className` | `@class` | 类名 |\n| `bounds` | `@bounds` | 坐标边界 |\n| `contentDesc` | `@content-desc` | 内容描述 |\n| `clickable` | `@clickable` | 是否可点击 |\n| `enabled` | `@enabled` | 是否启用 |\n\n**元素选择器优先级**\n\n系统使用以下属性按优先级查找元素：\n\n1. `content-desc` (Accessibility Hint)\n2. `text` (显示文本)\n3. `resource-id` (资源 ID)\n4. `class-name` + `text` 组合\n\n资料来源：[src/android.ts:250-350]()\n\n### 坐标计算\n\n元素的点击坐标基于 `bounds` 属性计算：\n\n```typescript\n// bounds 格式: [x1,y1][x2,y2]\nconst match = bounds.match(/\\[(\\d+),(\\d+)\\]\\[(\\d+),(\\d+)\\]/);\nif (match) {\n const x = Math.floor((parseInt(match[1]) + parseInt(match[3])) / 2);\n const y = Math.floor((parseInt(match[2]) + parseInt(match[4])) / 2);\n // 返回中心点坐标\n}\n```\n\n资料来源：[src/android.ts:300-330]()\n\n## 屏幕交互\n\n### 点击操作\n\n| 方法 | 命令 | 参数 |\n|------|------|------|\n| `click(x, y)` | `input tap` | x, y 坐标 |\n| `doubleTap(x, y)` | `input swipe` + 时间控制 | x, y 坐标 |\n| `longPress(x, y)` | `input swipe` + 长间隔 | x, y 坐标, 时长 |\n\n**双击实现原理**\n\n```typescript\npublic async doubleTap(x: number, y: number): Promise {\n const duration = 50; // 50ms 内完成两次点击\n this.adb(deviceId, \"shell\", \"input\", \"swipe\", \n `${x} ${y} ${x} ${y} ${duration}`);\n}\n```\n\n### 滑动操作\n\n滑动方向基于屏幕尺寸百分比计算起始和终止坐标：\n\n```typescript\npublic async swipe(direction: SwipeDirection): Promise {\n const screenSize = await this.getScreenSize();\n const centerX = screenSize.width >> 1; // 屏幕宽度一半\n\n switch (direction) {\n case \"up\":\n // 从底部 80% 位置滑到顶部 20% 位置\n y0 = Math.floor(screenSize.height * 0.80);\n y1 = Math.floor(screenSize.height * 0.20);\n break;\n case \"down\":\n // 从顶部 20% 位置滑到底部 80% 位置\n y0 = Math.floor(screenSize.height * 0.20);\n y1 = Math.floor(screenSize.height * 0.80);\n break;\n // left/right 方向类似\n }\n \n this.adb(deviceId, \"shell\", \"input\", \"swipe\", \n `${x0} ${y0} ${x1} ${y1} ${duration}`);\n}\n```\n\n**滑动参数表**\n\n| 方向 | 起始位置 | 终止位置 | 默认时长 |\n|------|----------|----------|----------|\n| up | y = 80% 屏幕高度 | y = 20% 屏幕高度 | 300ms |\n| down | y = 20% 屏幕高度 | y = 80% 屏幕高度 | 300ms |\n| left | x = 80% 屏幕宽度 | x = 20% 屏幕宽度 | 300ms |\n| right | x = 20% 屏幕宽度 | x = 80% 屏幕宽度 | 300ms |\n\n资料来源：[src/android.ts:350-420]()\n\n### 物理按钮\n\n支持的物理按钮：\n\n| 按钮名称 | ADB 命令 |\n|----------|----------|\n| HOME | `input keyevent KEYCODE_HOME` |\n| BACK | `input keyevent KEYCODE_BACK` |\n| ENTER | `input keyevent KEYCODE_ENTER` |\n| VOLUME_UP | `input keyevent KEYCODE_VOLUME_UP` |\n| VOLUME_DOWN | `input keyevent KEYCODE_VOLUME_DOWN` |\n| POWER | `input keyevent KEYCODE_POWER` |\n\n资料来源：[src/android.ts:420-480]()\n\n## 应用管理\n\n### 应用安装与卸载\n\n**安装流程**\n\n```typescript\npublic async installApp(filePath: string): Promise {\n this.adb(deviceId, \"install\", \"-r\", filePath);\n}\n```\n\n- `-r` 标志表示覆盖安装（允许降级）\n- 支持的文件格式：`.apk`\n\n**卸载流程**\n\n```typescript\npublic async uninstallApp(packageName: string): Promise {\n this.adb(deviceId, \"uninstall\", packageName);\n}\n```\n\n### 应用启动\n\n启动应用使用 `monkey` 命令触发 LAUNCHER Intent：\n\n```typescript\npublic async launchApp(packageName: string, locale?: string): Promise {\n validatePackageName(packageName);\n\n if (locale) {\n validateLocale(locale);\n try {\n // Android 13+ 支持设置应用语言\n this.silentAdb(\"shell\", \"cmd\", \"locale\", \"set-app-locales\", \n packageName, \"--locales\", locale);\n } catch (error) {\n // 静默忽略旧版本 Android 的语言设置失败\n }\n }\n\n this.adb(\"shell\", \"monkey\", \"-p\", packageName, \n \"-c\", \"android.intent.category.LAUNCHER\", \"1\");\n}\n```\n\n**包名验证规则**\n\n```typescript\nfunction validatePackageName(packageName: string): void {\n // 包名必须至少包含一个点\n // 例如: com.example.app\n if (!packageName.includes(\".\")) {\n throw new Error(\"Invalid package name format\");\n }\n}\n```\n\n资料来源：[src/android.ts:100-180]()\n\n### 运行进程查询\n\n```typescript\npublic async listRunningProcesses(): Promise {\n return this.adb(\"shell\", \"ps\", \"-e\")\n .toString()\n .split(\"\\n\")\n .map(line => line.trim())\n .filter(line => line.startsWith(\"u\")) // 非系统进程\n .map(line => line.split(/\\s+/)[8]); // 获取进程名\n}\n```\n\n## 屏幕截图与录制\n\n### 截图\n\n截图功能使用 `screencap` 命令：\n\n```typescript\npublic async takeScreenshot(): Promise {\n const output = this.adb(deviceId, \"exec-out\", \"screencap\", \"-p\");\n return output;\n}\n```\n\n- 使用 `exec-out` 而非 `shell` 避免 CR/LF 换行符问题\n- 返回 PNG 格式的二进制数据\n\n**Windows 兼容性修复**\n\n版本 0.0.15 修复了 Windows 上的换行符问题：\n\n> Android: Fixed broken Android screenshots on Windows because of crlf ([#53](https://github.com/mobile-next/mobile-mcp/pull/53))\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n### 屏幕录制\n\nAndroid 10+ 支持原生屏幕录制功能：\n\n```typescript\npublic async startScreenRecording(\n filePath: string, \n options?: ScreenRecordingOptions\n): Promise {\n const { width, height, bitRate, timeLimit } = options || {};\n \n const args = [\n \"shell\", \"screenrecord\",\n \"--output-format\", \"h264\",\n \"--time-limit\", String(timeLimit || 180),\n filePath\n ];\n \n if (width && height) {\n args.push(\"--size\", `${width}x${height}`);\n }\n \n this.adb(deviceId, ...args);\n}\n```\n\n**录制参数表**\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| timeLimit | 180秒 | 最长录制时间 |\n| width | 设备宽度 | 视频宽度 |\n| height | 设备高度 | 视频高度 |\n| bitRate | 系统默认 | 视频比特率 |\n\n版本 0.0.46 新增了对 Android 模拟器和真机的屏幕录制支持。\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## ADB 命令封装\n\n### 核心执行方法\n\n```typescript\nprivate adb(...args: string[]): Buffer {\n return execFileSync(getAdbPath(), args);\n}\n\nprivate silentAdb(...args: string[]): void {\n try {\n execFileSync(getAdbPath(), args);\n } catch {\n // 静默忽略错误\n }\n}\n```\n\n### ADB 路径解析\n\nADB 路径通过环境变量 `ANDROID_HOME` 配置：\n\n```typescript\nimport { execFileSync } from \"child_process\";\nimport { join } from \"path\";\n\nfunction getAdbPath(): string {\n const androidHome = process.env.ANDROID_HOME;\n if (androidHome) {\n return join(androidHome, \"platform-tools\", \"adb\");\n }\n return \"adb\"; // 使用系统 PATH 中的 adb\n}\n```\n\n版本 0.0.12 引入了对 `ANDROID_HOME` 路径下 adb 的支持。\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## 与服务端集成\n\n### 设备类型检测\n\n在 `server.ts` 中，服务端通过 `AndroidDeviceManager` 判断设备类型：\n\n```typescript\n// src/server.ts 中的设备检测逻辑\nconst androidManager = new AndroidDeviceManager();\nconst androidDevices = androidManager.getConnectedDevices();\nconst androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n\nif (androidDevice) {\n return new AndroidRobot(deviceId);\n}\n```\n\n### 设备不可用错误处理\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(\n `mobilecli is not available or not working properly. ` +\n `Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`\n );\n }\n};\n```\n\n资料来源：[src/server.ts:30-60]()\n\n## 依赖项\n\n### 生产依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| fast-xml-parser | 5.5.7 | 解析 uiautomator XML 输出 |\n| zod | ^4.1.13 | 参数验证和类型定义 |\n\n### 可选依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| mobilecli | 0.3.70 | 辅助 CLI 工具 |\n\n### 系统要求\n\n- Node.js >= 18\n- Android SDK (含 platform-tools)\n- 已连接的 Android 设备或模拟器\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要变更 |\n|------|----------|----------|\n| 0.0.46 | 2026-03-03 | 新增屏幕录制支持 |\n| 0.0.45 | 2026-03-02 | 修复 shell 转义问题 |\n| 0.0.32 | 2025-10-08 | 新增双击支持，减少 stdout 污染 |\n| 0.0.31 | 2025-10-07 | 修复 libc 兼容性问题 |\n| 0.0.30 | 2025-10-06 | 支持应用语言设置 |\n| 0.0.23 | 2025-07-31 | 修复折叠屏设备截图问题 |\n| 0.0.15 | 2025-05-04 | 修复 Windows 截图 CRLF 问题 |\n| 0.0.14 | 2025-05-02 | 优化 UI 元素检测，尝试多次 uiautomator dump |\n| 0.0.13 | 2025-04-20 | 使用 accessibility hints 和 class names 查找元素 |\n| 0.0.12 | 2025-04-12 | 支持 ANDROID_HOME 环境变量 |\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## 常见问题排查\n\n### 设备未被发现\n\n1. 确认设备已通过 USB 连接且授权调试\n2. 运行 `adb devices` 确认设备状态为 `device`\n3. 检查 `ANDROID_HOME` 环境变量是否正确设置\n\n### 截图失败\n\n1. 确认设备屏幕未锁定\n2. 检查设备是否支持 `screencap` 命令（Android 4.0+）\n3. 验证磁盘空间充足\n\n### 元素定位不准确\n\n1. 使用 `listElementsOnScreen` 工具获取最新界面状态\n2. 优先使用 `content-desc` 或 `text` 属性定位\n3. 考虑使用坐标点击作为备选方案\n\n### uiautomator dump 超时\n\n版本 0.0.14 实现了多次重试机制，自动重试 UI 层次结构获取。\n\n## 总结\n\nAndroid 实现为 mobile-mcp 提供了完整的 Android 设备自动化能力。通过 ADB 协议与设备通信，该模块实现了设备发现、UI 元素检测、屏幕交互、应用管理等核心功能。统一的接口设计使得 Android 和 iOS 平台可以无缝切换，为跨平台移动端自动化提供了坚实基础。\n\n---\n\n\n\n## 故障排除\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [安全配置](#security)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 故障排除\n\n本文档提供 Mobile MCP 常见问题的诊断和解决方案。\n\n## 前提条件检查\n\n### 必需组件\n\n确保系统已安装所有必需组件：\n\n| 组件 | 说明 | 最低版本 |\n|------|------|----------|\n| Node.js | 运行环境 | >=18 |\n| mobilecli | 命令行工具 | 0.3.70 |\n| Xcode (iOS) | iOS 开发环境 | - |\n| Xcode Command Line Tools | Xcode 命令行工具 | - |\n| go-ios | iOS 设备通信 | - |\n| Android SDK (Android) | Android 开发环境 | - |\n| ADB | Android 调试桥接器 | - |\n\n### mobilecli 可用性检查\n\nMobile MCP 启动时会自动检查 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly. Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki for installation instructions`);\n }\n};\n```\n\n**资料来源**：[src/server.ts]()\n\n如果遇到 mobilecli 相关错误，请参考 [官方 Wiki 安装指南](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n## iOS 设备问题排查\n\n### 架构概览\n\n```mermaid\ngraph TD\n A[Mobile MCP] --> B[iOS Manager]\n B --> C{iOS Tunnel Required?}\n C -->|Yes| D[iOS Tunnel Status]\n C -->|No| E[WebDriverAgent Check]\n D --> F{Tunnel Running?}\n F -->|Yes| E\n F -->|No| G[Error: iOS tunnel not running]\n E --> H{WDA Forward Running?}\n H -->|Yes| I[Create WebDriverAgent]\n H -->|No| J[Error: Port forwarding not running]\n I --> K[Return WebDriverAgent]\n```\n\n### iOS Tunnel 未运行\n\n当检测到 iOS Tunnel 未运行时，会抛出以下错误：\n\n```\niOS tunnel is not running, please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**解决方案**：\n\n1. 确保已启动 iOS Tunnel 服务\n2. 检查 Xcode Command Line Tools 已正确安装\n3. 验证设备已通过 USB 连接\n4. 参考 [官方 Wiki iOS 隧道配置指南](https://github.com/mobile-next/mobile-mcp/wiki/)\n\n### WebDriverAgent 问题\n\n#### 端口转发未运行\n\n```\nPort forwarding to WebDriverAgent is not running (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**排查步骤**：\n\n1. 确认 iOS Tunnel 已正常运行\n2. 检查端口 `8100` 是否被占用\n3. 重启 WebDriverAgent 服务\n\n#### WebDriverAgent 服务未运行\n\n```\nWebDriverAgent is not running on device (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**解决方案**：\n\n1. 在 iOS 设备上手动启动 WebDriverAgent\n2. 确保设备已通过 Xcode 授权用于开发\n3. 检查设备是否信任计算机\n\n### iOS Tunnel 健康检查\n\n系统通过以下方式检查 iOS Tunnel 状态：\n\n| 检查项 | 方法 | 失败时的错误信息 |\n|--------|------|------------------|\n| Tunnel 端口监听 | `isListeningOnPort(IOS_TUNNEL_PORT)` | iOS tunnel is not running |\n| WDA 端口转发 | `isListeningOnPort(WDA_PORT)` | Port forwarding to WebDriverAgent is not running |\n| WDA 服务状态 | `wda.isRunning()` | WebDriverAgent is not running on device |\n\n**资料来源**：[src/ios.ts]()\n\n## Android 设备问题排查\n\n### 设备连接检查\n\n```mermaid\ngraph LR\n A[Android Device] --> B[ADB Daemon]\n B --> C{Device Connected?}\n C -->|Yes| D[AndroidRobot Ready]\n C -->|No| E[Error: Device not found]\n D --> F[Execute Commands]\n```\n\n### ADB 设备未找到\n\n**排查步骤**：\n\n1. 确认设备已通过 USB 连接并启用 USB 调试\n2. 运行 `adb devices` 检查设备列表\n3. 如果设备未列出，尝试：\n - 重启 ADB 服务：`adb kill-server && adb start-server`\n - 检查设备授权状态\n - 更换 USB 数据线\n\n### Android 命令执行\n\nAndroid 设备通过 `adb shell` 执行命令：\n\n```typescript\npublic runCommand(args: string[]): string {\n return execFileSync(\"adb\", [\"-s\", this.deviceId, \"shell\", ...args], {\n encoding: \"utf-8\",\n }).toString();\n}\n```\n\n**资料来源**：[src/mobile-device.ts]()\n\n**常见错误处理**：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 设备离线 | USB 连接不稳定 | 重新连接或更换数据线 |\n| 未授权 | 设备未授权调试 | 在设备上点击\"允许调试\" |\n| 无响应 | 设备系统无响应 | 重启设备 |\n\n## iOS 模拟器问题排查\n\n### 应用安装失败\n\n#### ZIP 文件处理错误\n\n```mermaid\ngraph TD\n A[Install App Request] --> B{File Extension?}\n B -->|.zip| C[Extract ZIP File]\n B -->|.app| D[Direct Install]\n C --> E{Path Validation}\n E -->|Valid| F[Find .app Bundle]\n E -->|Invalid| G[Error: Zip Slip]\n F --> H{App Bundle Found?}\n H -->|Yes| I[Install .app]\n H -->|No| J[Error: No .app bundle found]\n```\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n#### 常见安装错误\n\n| 错误信息 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `No .app bundle found in the .zip file` | ZIP 内不含 .app 包 | 确保 ZIP 包含正确的 iOS 应用包 |\n| `Failed to unzip file` | ZIP 文件损坏或密码保护 | 验证 ZIP 文件完整性 |\n| Zip Slip 漏洞检测失败 | ZIP 包含路径遍历攻击 | 使用安全的 ZIP 文件 |\n| `simctl install failed` | 模拟器未运行或不支持 | 启动目标模拟器 |\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n### ZIP 安全验证\n\n系统会验证 ZIP 文件路径，防止 Zip Slip 攻击：\n\n```typescript\nprivate validateZipPaths(path: string): void {\n // 确保 ZIP 文件不包含恶意路径\n trace(`Detected .zip file, validating contents`);\n}\n```\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n## 通用设备管理问题\n\n### 设备识别流程\n\n```mermaid\ngraph TD\n A[Get Robot Request] --> B[Ensure mobilecli Available]\n B --> C{Check iOS Devices}\n C -->|Found| D[Create IosRobot]\n C -->|Not Found| E{Check Android Devices}\n E -->|Found| F[Create AndroidRobot]\n E -->|Not Found| G{Check iOS Simulators}\n G -->|Found| H[Create IosRobot]\n G -->|Not Found| I[Return Error]\n```\n\n**资料来源**：[src/server.ts]()\n\n### 设备类型检测优先级\n\n1. **iOS 物理设备** - 通过 IosManager.listDevices() 检测\n2. **Android 物理设备** - 通过 AndroidDeviceManager.getConnectedDevices() 检测\n3. **iOS 模拟器** - 通过 mobilecli.getDevices() 检测\n\n**资料来源**：[src/server.ts]()\n\n## 录制功能问题\n\n### 录制超时处理\n\n录制功能设置了 5 分钟超时限制：\n\n```typescript\nconst timeout = setTimeout(() => {\n child.kill(\"SIGKILL\");\n resolve();\n}, 5 * 60 * 1000);\n```\n\n**资料来源**：[src/server.ts]()\n\n**常见问题**：\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 录制被强制终止 | 超过 5 分钟限制 | 缩短录制时长 |\n| 输出文件未找到 | 录制异常终止 | 检查设备存储空间 |\n| 文件大小为 0 | 录制未成功启动 | 检查设备屏幕状态 |\n\n### 录制输出检查\n\n录制完成后，系统会验证输出文件：\n\n```typescript\nif (!fs.existsSync(outputPath)) {\n return `Recording stopped after ~${durationSeconds}s but the output file was not found at: ${outputPath}`;\n}\n\nconst stats = fs.statSync(outputPath);\nconst fileSizeMB = (stats.size / (1024 * 1024)).toFixed(2);\n```\n\n**资料来源**：[src/server.ts]()\n\n## 崩溃报告问题\n\n### 获取崩溃列表\n\n使用 `mobile_list_crashes` 工具获取设备上的崩溃报告：\n\n```typescript\ntool(\n \"mobile_list_crashes\",\n \"List Crash Reports\",\n \"List crash reports available on the device\",\n {\n device: z.string().describe(\"The device identifier to use...\"),\n },\n { readOnlyHint: true },\n async ({ device }) => {\n ensureMobilecliAvailable();\n const response = mobilecli.crashesList(device);\n return JSON.stringify(response.data);\n }\n);\n```\n\n**资料来源**：[src/server.ts]()\n\n**排查步骤**：\n\n1. 确认 mobilecli 可用\n2. 检查设备是否有足够的存储空间\n3. 验证崩溃报告未被清理\n\n## 环境变量配置\n\n### SSE 服务器认证\n\n使用 `MOBILEMCP_AUTH` 环境变量配置 Bearer Token 认证：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含 `Authorization: Bearer my-secret-token` 头。\n\n## 日志和调试\n\n### 启用调试日志\n\n在运行时设置日志级别以获取详细输出：\n\n参考 [src/logger.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/logger.ts) 获取日志配置详情。\n\n### 常见错误类型\n\n| 错误类型 | 来源 | 说明 |\n|----------|------|------|\n| `ActionableError` | Mobile MCP | 包含可操作建议的错误 |\n| 系统错误 | Node.js/adb | 底层系统级错误 |\n| 网络错误 | 端口转发/Tunnel | 连接问题 |\n\n## 获取帮助\n\n如果以上方案无法解决您的问题：\n\n1. 访问 [官方 Wiki 文档](https://github.com/mobile-next/mobile-mcp/wiki)\n2. 加入 [Slack 社区](https://mobilenexthq.com/join-slack)\n3. 查看 [已知问题](https://github.com/mobile-next/mobile-mcp/issues)\n4. 查看 [路线图](https://github.com/orgs/mobile-next/projects/3) 了解即将修复的功能\n\n---\n\n\n\n## 安全配置\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [故障排除](#troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# 安全配置\n\nMobile MCP 提供了多层安全机制来保护服务器通信和文件系统操作。本文档详细介绍各项安全配置的使用方法和最佳实践。\n\n## 认证机制\n\n### Bearer Token 认证\n\n当 Mobile MCP 以 SSE 服务器模式运行时，可通过设置 `MOBILEMCP_AUTH` 环境变量启用 Bearer Token 认证。\n\n#### 配置方式\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n#### 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as Mobile MCP Server\n \n Client->>Server: 请求 /mcp 端点\n Server->>Server: 检查 Authorization Header\n alt 未设置 MOBILEMCP_AUTH\n Server->>Server: 允许无认证访问\n else 设置了 MOBILEMCP_AUTH\n alt 缺少 Authorization Header\n Server-->>Client: 401 Unauthorized\n else Token 不匹配\n Server-->>Client: 401 Unauthorized\n else Token 正确\n Server-->>Client: 200 OK + MCP 响应\n end\n end\n```\n\n#### 请求格式要求\n\n所有请求必须包含以下 HTTP Header：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n| 配置项 | 环境变量 | 说明 | 必需 |\n|--------|----------|------|------|\n| 认证令牌 | `MOBILEMCP_AUTH` | 设置 Bearer Token 值 | SSE 模式下必需 |\n\n### 认证错误处理\n\n当认证失败时，服务器返回标准的 HTTP 401 状态码。客户端需要确保在配置中正确设置认证令牌，避免连接失败。\n\n## 文件系统安全\n\n### 路径遍历防护\n\nMobile MCP 在保存截图和录制视频功能中实现了路径遍历防护机制，防止恶意请求访问预期目录之外的文件。\n\n#### 安全修复历史\n\n| 版本 | 日期 | 修复内容 | PR |\n|------|------|----------|-----|\n| 0.0.49 | 2026-03-24 | 修复截图和视频保存中的路径遍历漏洞 | [#296](https://github.com/mobile-next/mobile-mcp/pull/296) |\n\n#### 受保护的文件操作\n\n```mermaid\ngraph TD\n A[文件保存请求] --> B{验证路径}\n B -->|包含 ../ 或绝对路径 | C[拒绝访问]\n B -->|合法相对路径 | D[执行保存操作]\n C --> E[返回安全错误]\n D --> F[保存到 lib/screenshots 或 lib/videos 目录]\n```\n\n## 依赖安全\n\n### 安全更新机制\n\nMobile MCP 定期更新依赖包以修复已知安全漏洞。\n\n#### 安全更新历史\n\n| 版本 | 日期 | 更新内容 | PR |\n|------|------|----------|-----|\n| 0.0.48 | 2026-03-20 | fast-xml-parser 安全更新 | [#292](https://github.com/mobile-next/mobile-mcp/pull/292) |\n| 0.0.47 | 2026-03-09 | 更新依赖包以提升安全性 | [#285](https://github.com/mobile-next/mobile-mcp/pull/285) |\n\n#### 关键依赖安全状态\n\n| 依赖包 | 版本 | 用途 | 安全状态 |\n|--------|------|------|----------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP 协议实现 | 已审核 |\n| fast-xml-parser | 5.5.7 | XML 解析 | 已更新 |\n| express | 5.1.0 | SSE 服务器框架 | 已审核 |\n| zod | 4.1.13 | 参数验证 | 已审核 |\n\n## 运行时安全检查\n\n### mobilecli 可用性验证\n\n服务器启动时执行 mobilecli 可用性检查，确保底层工具正常工作：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly...`);\n }\n};\n```\n\n如果 mobilecli 不可用或工作异常，服务器将抛出可操作的错误提示，指导用户访问文档进行排查。\n\n### 设备类型验证\n\n`getRobotFromDevice` 函数通过设备 ID 确定设备类型，并创建对应的 Robot 实例：\n\n```mermaid\ngraph TD\n A[接收 deviceId] --> B{检查 iOS 设备}\n B -->|找到 | C[返回 IosRobot]\n B -->|未找到 | D{检查 Android 设备}\n D -->|找到 | E[返回 AndroidRobot]\n D -->|未找到 | F{检查 iOS 模拟器}\n F -->|找到 | G[返回 IosRobot]\n F -->|未找到 | H[抛出 ActionableError]\n```\n\n## 安全配置最佳实践\n\n### 开发环境\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 生产环境（启用认证）\n\n```bash\n# 设置强认证令牌\nexport MOBILEMCP_AUTH=\"$(openssl rand -hex 32)\"\n\n# 启动 SSE 服务器\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n### 配置参数表\n\n| 参数 | 命令行 | 环境变量 | 说明 | 默认值 |\n|------|--------|----------|------|--------|\n| 监听地址 | `--listen ` | - | SSE 服务器监听端口 | 无（stdio 模式） |\n| 绑定接口 | `--listen ` | - | 指定绑定地址 | localhost |\n| 认证令牌 | - | `MOBILEMCP_AUTH` | Bearer Token | 无 |\n\n## 报告安全漏洞\n\n如发现安全漏洞，请通过以下方式报告：\n\n- GitHub Issues: [https://github.com/mobile-next/mobile-mcp/issues](https://github.com/mobile-next/mobile-mcp/issues)\n- 详细安全策略请参阅 [SECURITY.md](https://github.com/mobile-next/mobile-mcp/blob/main/SECURITY.md)\n\n## 安全版本对照表\n\n| 功能 | 支持版本 | 说明 |\n|------|----------|------|\n| Bearer Token 认证 | 全部版本 | SSE 模式下通过 MOBILEMCP_AUTH 配置 |\n| 路径遍历防护 | ≥ 0.0.49 | 保护截图和视频文件操作 |\n| fast-xml-parser 更新 | ≥ 0.0.48 | XML 解析安全修复 |\n| mobilecli 检查 | 全部版本 | 启动时验证工具可用性 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mobile-next/mobile-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback。\n\n## 1. 配置坑 · 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：mobile_type_keys not support Chinese words\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Default-on telemetry creates security and compliance risk for enterprise users\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：mobile fleet documentation link broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 来源证据：Version 0.0.49\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Version 0.0.54\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：Version 0.0.45\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.45\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5939588c2f74a4f8e7ae874c9fee9f2 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：Version 0.0.47\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.47\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6f22eab42c4140bf9692e3ff9f80dc62 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Version 0.0.48\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.48\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e414a95529d4f27bb06648558502daa | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Version 0.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.51\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eca0ad1c1f574a52897db27953196b98 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：Version 0.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c0b172807554ff4b1969c4fff8abf4b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Version 0.0.53\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.53\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0fb42201cf24850bcd4fa91470e2042 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | release_recency=unknown\n\n\n",
"markdown_key": "mobile-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:956657893",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mobile-next/mobile-mcp"
},
{
"evidence_id": "art_65834296da1e45c082ff541d368d219e",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/mobile-next/mobile-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mobile-mcp 说明书",
"toc": [
"https://github.com/mobile-next/mobile-mcp 项目说明书",
"目录",
"项目概述",
"简介",
"核心特性",
"架构设计",
"主要功能",
"通信模式",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "227e961d131be76b036bab91c5da6e6d0a0347e1",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/logger.ts",
"src/ios.ts",
"src/webdriver-agent.ts",
"src/utils.ts",
"src/png.ts",
"src/index.ts",
"src/robot.ts",
"src/server.ts",
"src/mobile-device.ts",
"src/image-utils.ts",
"src/mobilecli.ts",
"src/iphone-simulator.ts",
"src/android.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @mobilenext/mobile-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @mobilenext/mobile-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx @mobilenext/mobile-mcp@latest` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0006` supported 0.86\n- `npx @mobilenext/mobile-mcp@latest --listen 3000` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：33\n- 重要文件覆盖：32/33\n- 证据索引条目：32\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @mobilenext/mobile-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @mobilenext/mobile-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @mobilenext/mobile-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **Mobile Next - MCP server for Mobile Development and Automation iOS, Android, Simulator, Emulator, and Real Devices**（project_doc）：Mobile Next - MCP server for Mobile Development and Automation iOS, Android, Simulator, Emulator, and Real Devices 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **0.0.54 https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 2026-05-04**（project_doc）：0.0.54 https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 2026-05-04 Server: Update mobilecli to 0.3.70 iOS: Fixed cases where testmanagerd would get Device Kit stuck in a black screen of death iOS: Added 'placeholder' to view tree response 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Security Policy**（project_doc）：All versions of this project are currently being supported with security updates. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Bug report**（project_doc）：Describe the bug A clear and concise description of what the bug is. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n\n## 证据索引\n\n- 共索引 32 条证据。\n\n- **Mobile Next - MCP server for Mobile Development and Automation iOS, Android, Simulator, Emulator, and Real Devices**（documentation）：Mobile Next - MCP server for Mobile Development and Automation iOS, Android, Simulator, Emulator, and Real Devices 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@mobilenext/mobile-mcp\", \"mcpName\": \"io.github.mobile-next/mobile-mcp\", \"version\": \"0.0.1\", \"description\": \"Mobile MCP\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/mobile-next/mobile-mcp.git\" }, \"engines\": { \"node\": \" =18\" }, \"license\": \"Apache-2.0\", \"scripts\": { \"build\": \"tsc && chmod +x lib/index.js\", \"lint\": \"eslint .\", \"fixlint\": \"eslint . --fix\", \"test\": \"nyc mocha --require ts-node/register test/ .ts\", \"watch\": \"tsc --watch\", \"clean\": \"rm -rf lib\", \"prepare\": \"husky\" }, \"files\": \"lib\" , \"dependencies\": { \"@modelcontextprotocol/sdk\": \"1.26.0\", \"ajv\": \"^8.18.0\", \"commander\": \"14.0.0\", \"express\": \"5.1.0\", \"fast-xml-parser\": \"5.5.7\", \"qs\": \"^6.15.0\", \"zod\": \"… 证据：`package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **0.0.54 https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 2026-05-04**（documentation）：0.0.54 https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 2026-05-04 Server: Update mobilecli to 0.3.70 iOS: Fixed cases where testmanagerd would get Device Kit stuck in a black screen of death iOS: Added 'placeholder' to view tree response 证据：`CHANGELOG.md`\n- **Security Policy**（documentation）：All versions of this project are currently being supported with security updates. 证据：`SECURITY.md`\n- **Bug Report**（documentation）：Describe the bug A clear and concise description of what the bug is. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.mobile-next/mobile-mcp\", \"description\": \"MCP server for iOS and Android Mobile Development, Automation and Testing\", \"repository\": { \"url\": \"https://github.com/mobile-next/mobile-mcp\", \"source\": \"github\" }, \"version\": \"{{VERSION}}\", \"packages\": { \"registryType\": \"npm\", \"registryBaseUrl\": \"https://registry.npmjs.org\", \"identifier\": \"@mobilenext/mobile-mcp\", \"version\": \"{{VERSION}}\", \"transport\": { \"type\": \"stdio\" } } } 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ESNext\", \"skipLibCheck\": true, \"esModuleInterop\": true, \"moduleResolution\": \"node\", \"strict\": true, \"module\": \"CommonJS\", \"outDir\": \"./lib\" }, \"include\": \"src\", , } 证据：`tsconfig.json`\n- **.editorconfig**（source_file）：indent style = tab indent size = 8 tab width = 8 end of line = lf charset = utf-8 trim trailing whitespace = true insert final newline = true max line length = 150 证据：`.editorconfig`\n- **.gitignore**（source_file）：/.DS Store node modules lib .nyc output .vscode 证据：`.gitignore`\n- **Pre Commit**（source_file）：npm run lint 证据：`.husky/pre-commit`\n- **.Mocharc**（source_file）：timeout: 60s 证据：`.mocharc.yml`\n- **.npmignore**（source_file）：/ README.md LICENSE !index. !lib/ / .js 证据：`.npmignore`\n- **Eslint.Config**（source_file）：import typescriptEslint from \"@typescript-eslint/eslint-plugin\"; import tsParser from \"@typescript-eslint/parser\"; import stylistic from \"@stylistic/eslint-plugin\"; import importRules from \"eslint-plugin-import\"; 证据：`eslint.config.mjs`\n- **Android**（source_file）：import path from \"node:path\"; import { execFileSync } from \"node:child process\"; import { existsSync } from \"node:fs\"; 证据：`src/android.ts`\n- **Image Utils**（source_file）：import { execFileSync, spawnSync } from \"child process\"; import os from \"node:os\"; import fs from \"node:fs\"; import path from \"node:path\"; import { trace } from \"./logger\"; 证据：`src/image-utils.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node import { SSEServerTransport } from \"@modelcontextprotocol/sdk/server/sse.js\"; import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"; import { createMcpServer, getAgentVersion } from \"./server\"; import { error } from \"./logger\"; import express from \"express\"; import { program } from \"commander\"; 证据：`src/index.ts`\n- **Ios**（source_file）：import { Socket } from \"node:net\"; import { execFileSync } from \"node:child process\"; 证据：`src/ios.ts`\n- **Iphone Simulator**（source_file）：import { execFileSync } from \"node:child process\"; import { mkdtempSync, readdirSync, rmSync } from \"node:fs\"; import { tmpdir } from \"node:os\"; import { join, basename, extname } from \"node:path\"; 证据：`src/iphone-simulator.ts`\n- **Logger**（source_file）：import { appendFileSync } from \"node:fs\"; 证据：`src/logger.ts`\n- **Mobile Device**（source_file）：import { Mobilecli } from \"./mobilecli\"; import { Button, InstalledApp, Orientation, Robot, ScreenElement, ScreenSize, SwipeDirection } from \"./robot\"; 证据：`src/mobile-device.ts`\n- **Mobilecli**（source_file）：import { existsSync } from \"node:fs\"; import { dirname, join, sep } from \"node:path\"; import { execFileSync, spawn, ChildProcess } from \"node:child process\"; 证据：`src/mobilecli.ts`\n- **Png**（source_file）：export interface PngDimensions { width: number; height: number; } 证据：`src/png.ts`\n- **Robot**（source_file）：export interface Dimensions { width: number; height: number; } 证据：`src/robot.ts`\n- **Server**（source_file）：import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"; import { z } from \"zod\"; import fs from \"node:fs\"; import os from \"node:os\"; import path from \"node:path\"; import crypto from \"node:crypto\"; import { ChildProcess } from \"node:child process\"; 证据：`src/server.ts`\n- **Utils**（source_file）：import path from \"node:path\"; import os from \"node:os\"; import fs from \"node:fs\"; import { ActionableError } from \"./robot\"; 证据：`src/utils.ts`\n- **Webdriver Agent**（source_file）：import { ActionableError, SwipeDirection, ScreenSize, ScreenElement, Orientation } from \"./robot\"; 证据：`src/webdriver-agent.ts`\n- **Android**（source_file）：import { PNG } from \"../src/png\"; import { AndroidRobot, AndroidDeviceManager } from \"../src/android\"; 证据：`test/android.ts`\n- **Ios**（source_file）：import { IosManager, IosRobot } from \"../src/ios\"; import { PNG } from \"../src/png\"; 证据：`test/ios.ts`\n- **Iphone Simulator**（source_file）：import assert from \"node:assert\"; import { randomBytes } from \"node:crypto\"; 证据：`test/iphone-simulator.ts`\n- **Mobilecli.Test**（source_file）：import assert from \"node:assert\"; import { Mobilecli } from \"../src/mobilecli\"; 证据：`test/mobilecli.test.ts`\n- **Png**（source_file）：import assert from \"node:assert\"; import { PNG } from \"../src/png\"; 证据：`test/png.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `LICENSE`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json\n- **安装与配置**：importance `high`\n - source_paths: package.json, src/index.ts\n- **客户端配置指南**：importance `high`\n - source_paths: README.md\n- **系统架构**：importance `high`\n - source_paths: src/server.ts, src/robot.ts, src/mobilecli.ts, src/mobile-device.ts\n- **设备管理**：importance `high`\n - source_paths: src/mobile-device.ts, src/mobilecli.ts, src/android.ts, src/ios.ts\n- **MCP 工具详解**：importance `high`\n - source_paths: src/server.ts\n- **iOS 实现**：importance `high`\n - source_paths: src/ios.ts, src/webdriver-agent.ts, src/iphone-simulator.ts\n- **Android 实现**：importance `high`\n - source_paths: src/android.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `227e961d131be76b036bab91c5da6e6d0a0347e1`\n- inspected_files: `package.json`, `README.md`, `src/logger.ts`, `src/ios.ts`, `src/webdriver-agent.ts`, `src/utils.ts`, `src/png.ts`, `src/index.ts`, `src/robot.ts`, `src/server.ts`, `src/mobile-device.ts`, `src/image-utils.ts`, `src/mobilecli.ts`, `src/iphone-simulator.ts`, `src/android.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：mobile_type_keys not support Chinese words\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Default-on telemetry creates security and compliance risk for enterprise users\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：mobile fleet documentation link broken\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Version 0.0.49\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Version 0.0.54\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：mobile-next/mobile-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：mobile_type_keys not support Chinese words（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Default-on telemetry creates security and compliance risk for enterprise users（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/mobile-next/mobile-mcp 项目说明书\n\n生成时间：2026-05-13 17:52:49 UTC\n\n## 目录\n\n- [项目概述](#overview)\n- [安装与配置](#installation)\n- [客户端配置指南](#client-configuration)\n- [系统架构](#system-architecture)\n- [设备管理](#device-management)\n- [MCP 工具详解](#mcp-tools)\n- [iOS 实现](#ios-implementation)\n- [Android 实现](#android-implementation)\n- [故障排除](#troubleshooting)\n- [安全配置](#security)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [安装与配置](#installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n \n\n# 项目概述\n\n## 简介\n\nMobile MCP（Mobile Model Context Protocol）是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 标准的移动设备自动化框架。它使 AI 代理能够通过标准化的接口与 iOS、Android 设备进行交互，支持真机、模拟器和仿真器。资料来源：[README.md:1-10]()\n\n该项目的核心目标是通过 MCP 协议为 AI 助手提供移动设备控制能力，实现自动化测试、数据采集、UI 交互等多种场景。开发者无需编写原生代码，即可通过自然语言指令驱动移动设备完成复杂任务。资料来源：[README.md:35-50]()\n\n## 核心特性\n\nMobile MCP 具有以下核心特性：\n\n| 特性 | 描述 |\n|------|------|\n| 快速轻量 | 利用原生无障碍树（Accessibility Tree）进行大多数交互，在无 a11y 标签时使用截图坐标方案 |\n| LLM 友好 | 无需计算机视觉模型即可进行屏幕分析 |\n| 视觉感知 | 可评估和分析屏幕实际渲染内容 |\n| 跨平台 | 同时支持 iOS 和 Android 设备 |\n| 灵活部署 | 支持 stdio 和 SSE 两种服务器模式 |\n| 安全认证 | SSE 模式支持 Bearer Token 授权验证 |\n\n资料来源：[README.md:50-60]()\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n subgraph MCP客户端 [\"MCP 客户端 (IDE/Agent)\"]\n A[Claude Desktop]\n B[Cursor]\n C[VS Code]\n D[其他 MCP 兼容客户端]\n end\n \n subgraph MCP协议层 [\"MCP 协议层\"]\n E[stdio 模式]\n F[SSE Server 模式]\n end\n \n subgraph Mobile MCP 核心 [\"Mobile MCP 核心\"]\n G[src/server.ts
MCP 服务器入口]\n H[设备管理器层]\n I[机器人抽象层]\n end\n \n subgraph 设备抽象层 [\"设备抽象层\"]\n J[Robot 接口]\n K[WebDriverAgent
iOS WDA]\n L[MobileDevice
Android ADB]\n M[iPhone Simulator
模拟器支持]\n end\n \n subgraph 物理设备 [\"物理/虚拟设备\"]\n N[iOS 真机/模拟器]\n O[Android 真机/仿真器]\n end\n \n A --> E\n B --> E\n C --> F\n D --> F\n E --> G\n F --> G\n G --> H\n H --> I\n I --> J\n J --> K\n J --> L\n J --> M\n K --> N\n L --> O\n M --> N\n```\n\n### 核心模块说明\n\n#### 1. MCP 服务器层 (`src/server.ts`)\n\nMCP 服务器是整个系统的入口点，负责：\n- 注册和暴露所有 MCP 工具\n- 管理设备连接和会话\n- 处理工具调用请求\n- 提供 SSE 服务器模式支持\n\n服务器通过 `mobilecli` 工具进行设备管理，并在启动时验证 `mobilecli` 的可用性。资料来源：[src/server.ts:1-50]()\n\n#### 2. 设备管理器层\n\n设备管理器负责设备的发现、连接和管理：\n\n| 管理器 | 职责 | 源码文件 |\n|--------|------|----------|\n| IosManager | iOS 设备发现和管理 | src/ios.ts |\n| AndroidDeviceManager | Android 设备管理 | src/android.ts |\n| IPhoneSimulator | iPhone 模拟器支持 | src/iphone-simulator.ts |\n\n资料来源：[src/ios.ts:1-80]()\n\n#### 3. 机器人抽象层 (`src/robot.ts`)\n\nRobot 接口定义了所有设备交互的统一抽象：\n\n```typescript\ninterface Robot {\n // 设备信息\n getScreenSize(): Promise;\n getOrientation(): Promise;\n setOrientation(orientation: Orientation): Promise;\n \n // 应用管理\n listApps(): Promise;\n launchApp(packageName: string, locale?: string): Promise;\n terminateApp(packageName: string): Promise;\n installApp(path: string): Promise;\n uninstallApp(bundleId: string): Promise;\n \n // 屏幕交互\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipe(direction: SwipeDirection): Promise;\n \n // 输入操作\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n openUrl(url: string): Promise;\n}\n```\n\n资料来源：[src/robot.ts:1-150]()\n\n#### 4. 平台特定实现\n\n##### iOS 实现 (`src/webdriver-agent.ts`)\n\niOS 设备通过 WebDriverAgent (WDA) 进行控制：\n- 通过 HTTP API 与 WDA 通信\n- 使用 `/source/?format=json` 获取页面元素\n- 使用 `/screenshot` 获取屏幕截图\n- 通过 `/actions` 端点执行手势操作\n\n元素筛选支持以下类型：`TextField`, `Button`, `Switch`, `Icon`, `SearchField`, `StaticText`, `Image`\n\n资料来源：[src/webdriver-agent.ts:1-100]()\n\n##### Android 实现 (`src/mobile-device.ts`)\n\nAndroid 设备通过 `mobilecli` 工具进行控制：\n- 使用 `dump ui` 命令获取界面元素\n- 使用 `io tap` 执行点击操作\n- 使用 `io text` 输入文本\n- 使用 `io button` 模拟按键\n- 使用 `device orientation` 管理屏幕方向\n\n资料来源：[src/mobile-device.ts:1-100]()\n\n## 主要功能\n\n### MCP 工具分类\n\nMobile MCP 提供了丰富的 MCP 工具，主要分为以下几类：\n\n#### 设备信息类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_available_devices` | 列出所有可用设备（模拟器、仿真器、真机） |\n| `mobile_get_screen_size` | 获取设备屏幕尺寸（像素） |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向（竖屏/横屏） |\n\n#### 应用管理类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_apps` | 列出设备上所有已安装应用 |\n| `mobile_launch_app` | 启动指定应用（通过包名） |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 安装应用（支持 .apk, .ipa, .app, .zip） |\n| `mobile_uninstall_app` | 卸载应用 |\n\n#### 屏幕交互类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_take_screenshot` | 截图以了解屏幕内容 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 列出屏幕元素及其坐标和属性 |\n| `mobile_click_on_screen_at_coordinates` | 在指定坐标点击 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 在屏幕上滑动（支持四个方向） |\n\n#### 输入与导航类\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_type_keys` | 向焦点元素输入文本 |\n| `mobile_press_button` | 按下设备物理按钮 |\n\n资料来源：[README.md:100-130]()\n\n## 通信模式\n\nMobile MCP 支持两种通信模式：\n\n### stdio 模式（默认）\n\n默认模式，Mobile MCP 通过标准输入输出与客户端通信。适用于大多数本地场景。\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### SSE Server 模式\n\n当需要远程访问或多人协作时，可启用 SSE 服务器模式：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n可绑定到特定接口：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n连接地址：`http://:3000/mcp`\n\n#### 认证配置\n\nSSE 模式支持 Bearer Token 认证：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含：`Authorization: Bearer my-secret-token`\n\n资料来源：[README.md:180-210]()\n\n## 应用场景\n\n### 主要用例\n\n| 场景 | 描述 |\n|------|------|\n| 原生应用自动化 | iOS 和 Android 应用的测试或数据录入场景 |\n| 脚本化流程 | 无需手动控制模拟器/仿真器或真机即可完成表单交互 |\n| 多步骤用户旅程 | 由 LLM 驱动的自动化用户流程 |\n| 通用应用交互 | 基于代理框架的移动应用交互 |\n| 代理间通信 | 支持移动自动化的代理间通信和数据提取 |\n\n资料来源：[README.md:30-40]()\n\n### 典型工作流示例\n\n#### 示例 1：应用测试与截图\n\n```\n打开指定应用，截取当前屏幕截图，\n列出所有可见的 UI 元素，\n然后点击\"登录\"按钮\n```\n\n#### 示例 2：多步骤表单填写\n\n```\n打开 Settings 应用，\n导航到 \"General\" > \"About\"，\n滚动到页面底部，\n记录设备的序列号和型号\n```\n\n#### 示例 3：内容搜索与保存\n\n```\n打开 Substack 网站，\n搜索 \"Latest trends in AI automation 2025\"，\n打开第一篇文章，\n高亮标题为 \"Emerging AI trends\" 的章节，\n保存文章到阅读列表待稍后查看，\n评论一段随机的段落摘要\n```\n\n#### 示例 4：活动预约\n\n```\n打开 Eventbrite，\n搜索 \"Austin, TX\" 本周末的 AI 创业公司meetup 活动，\n选择最热门的一个，\n注册并确认参加，\n设置日历提醒\n```\n\n资料来源：[README.md:60-100]()\n\n## 环境要求\n\n### 前置条件\n\n使用 Mobile MCP 前，需要准备以下环境：\n\n| 平台 | 要求 |\n|------|------|\n| iOS | macOS + Xcode + WebDriverAgent |\n| Android | Android SDK + ADB |\n| 通用 | Node.js 环境用于运行 mobilecli |\n\n详细安装说明请参阅 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n资料来源：[README.md:105-110]()\n\n## 客户端集成\n\nMobile MCP 可与多种 MCP 兼容客户端集成：\n\n| 客户端 | 集成方式 |\n|--------|----------|\n| Claude Desktop | JSON 配置文件 |\n| Cursor | 手动配置或一键安装 |\n| VS Code | VS Code MCP 扩展 |\n| Claude Code | CLI 命令添加 |\n| Codex | TOML 配置文件 |\n| Copilot | MCP 配置 |\n| Gemini CLI | CLI 命令添加 |\n| Goose | 自定义扩展 |\n| Windsurf | MCP 服务器设置 |\n| Cline | MCP 设置文件 |\n| Amp | VS Code 扩展或 CLI |\n\n详细配置请参考各客户端的 MCP 文档或 [项目 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n## 技术栈\n\n| 层级 | 技术/工具 |\n|------|-----------|\n| 协议层 | Model Context Protocol (MCP) |\n| 运行时 | Node.js |\n| iOS 控制 | WebDriverAgent (WDA) |\n| Android 控制 | mobilecli / ADB |\n| iOS 连接 | go-ios 工具 |\n\n## 路线图\n\n项目团队持续优化 Mobile MCP，详细的路线图可在 [GitHub Projects](https://github.com/orgs/mobile-next/projects/3) 中查看。\n\n路线图涵盖的领域包括：\n- 新功能开发\n- 性能优化\n- 平台扩展\n- 文档完善\n- 社区反馈集成\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| 项目首页 | https://github.com/mobile-next/mobile-mcp |\n| 官方文档 | https://github.com/mobile-next/mobile-mcp/wiki |\n| 问题反馈 | GitHub Issues |\n| Slack 社区 | https://mobilenexthq.com/join-slack |\n| 路线图 | https://github.com/orgs/mobile-next/projects/3 |\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [客户端配置指南](#client-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n \n\n# 安装与配置\n\n## 概述\n\nMobile MCP (Model Context Protocol) 是一个用于移动端自动化和控制的服务端工具，支持 iOS 和 Android 平台的原生应用自动化、模拟器/真机控制、以及脚本化流程交互。该工具通过 MCP 协议与 AI 助手集成，使 LLM 能够操控移动设备完成各类自动化任务。\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 规格 |\n|--------|------|\n| Node.js 版本 | >= 18 |\n| 包管理器 | npm / npx |\n| 许可证 | Apache-2.0 |\n| 发布格式 | npm 包 (`@mobilenext/mobile-mcp`) |\n\n资料来源：[package.json:6-9](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n### 设备支持\n\n系统支持以下类型的移动设备连接：\n\n- **iOS 真机**：通过 WebDriverAgent (WDA) 进行控制\n- **iOS 模拟器**：通过 simctl 命令控制\n- **Android 真机**：通过 Android Debug Bridge (ADB) 命令控制\n- **Android 模拟器**：通过 ADB 连接\n\n设备发现和类型识别逻辑位于 `src/server.ts` 中的 `getRobotFromDevice` 函数：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n // 检查 iOS 真机\n const iosManager = new IosManager();\n const iosDevice = iosManager.listDevices().find(d => d.deviceId === deviceId);\n if (iosDevice) return new IosRobot(deviceId);\n\n // 检查 Android 设备\n const androidManager = new AndroidDeviceManager();\n const androidDevice = androidManager.getConnectedDevices().find(d => d.deviceId === deviceId);\n if (androidDevice) return new AndroidRobot(deviceId);\n\n // 检查 iOS 模拟器\n const response = mobilecli.getDevices({ platform: \"ios\", type: \"simulator\", includeOffline: false });\n // ...\n};\n```\n\n资料来源：[src/server.ts:31-52](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 安装方式\n\n### 方式一：npx 直接运行\n\n最简安装方式，通过 npx 直接启动服务：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n### 方式二：本地安装\n\n```bash\nnpm install -g @mobilenext/mobile-mcp\n```\n\n### 方式三：项目依赖安装\n\n```bash\nnpm install @mobilenext/mobile-mcp\n```\n\n## MCP 客户端配置\n\n### 标准配置模板\n\n大多数 MCP 客户端支持以下标准配置格式：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n资料来源：[README.md:1-10](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### 各客户端配置详情\n\n#### VS Code (Copilot)\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": \"npx\",\n \"tools\": [\"*\"],\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Claude Desktop\n\n配置文件路径：`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Cursor\n\n在 Cursor 设置中添加新的 MCP Server，使用命令类型：\n\n```\n命令: npx -y @mobilenext/mobile-mcp@latest\n```\n\n#### Cline\n\n将标准配置添加到 MCP 设置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Windsurf\n\n在 MCP servers 设置中添加新服务器，使用命令类型：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n#### Codeium (Windsurf)\n\n配置路径：`~/.codex/config.toml`\n\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n\n#### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n\n#### Goose\n\n设置类型：`STDIO`\n命令：`npx -y @mobilenext/mobile-mcp@latest`\n\n#### Kiro\n\n配置文件路径：`.kiro/settings/mcp.json`\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n#### Amp (VS Code 扩展)\n\n通过 Amp VS Code 扩展设置或 `settings.json` 添加：\n\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n\n或通过 CLI：\n\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n## SSE 服务器模式\n\n默认情况下，Mobile MCP 通过 stdio 通信运行。如需以 HTTP 服务器模式运行，使用 `--listen` 参数：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n这会将服务绑定到 `localhost:3000`。\n\n### 指定网络接口\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n### MCP 客户端连接配置\n\n配置客户端连接到 SSE 服务器：\n\n```\nhttp://:3000/mcp\n```\n\n资料来源：[README.md:1-20](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### 授权配置\n\nSSE 服务器支持 Bearer Token 授权。设置环境变量：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含头部：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n## 环境变量\n\n| 变量名 | 说明 | 必填 |\n|--------|------|------|\n| `MOBILEMCP_AUTH` | SSE 服务器的 Bearer Token 认证密钥 | 仅 SSE 模式 |\n| `PATH` | 需包含 mobilecli 可执行文件路径 | 是 |\n\n### mobilecli 可用性检查\n\n服务启动时会自动检查 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly...`);\n }\n};\n```\n\n资料来源：[src/server.ts:18-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 通信协议架构\n\n```mermaid\ngraph TD\n A[MCP 客户端
AI 助手] -->|MCP 协议| B[Mobile MCP Server
mobile-mcp]\n B -->|stdio 或 SSE| A\n B --> C[mobilecli]\n C -->|iOS 控制| D[iOS 模拟器
simctl]\n C -->|iOS 真机| E[WebDriverAgent
WDA 隧道]\n C -->|Android| F[ADB]\n D --> G[iOS 模拟器]\n E --> H[iOS 真机]\n F --> I[Android 设备/模拟器]\n```\n\n## 可用工具列表\n\n安装并配置完成后，以下工具将自动注册到 MCP 客户端：\n\n### 设备管理\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_available_devices` | 列出所有可用设备（模拟器、仿真器、真机） |\n| `mobile_get_screen_size` | 获取设备屏幕尺寸（像素） |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向（竖屏/横屏） |\n\n### 应用管理\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_apps` | 列出设备上安装的所有应用 |\n| `mobile_launch_app` | 通过包名启动应用 |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 从文件安装应用（.apk, .ipa, .app, .zip） |\n| `mobile_uninstall_app` | 卸载应用 |\n\n### 屏幕交互\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_take_screenshot` | 截取屏幕截图 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 列出屏幕上的 UI 元素及其坐标和属性 |\n| `mobile_click_on_screen_at_coordinates` | 点击指定坐标 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 在任意方向滑动 |\n\n### 输入与导航\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_type_keys` | 向焦点元素输入文本 |\n| `mobile_press_button` | 按下设备按钮 |\n| `mobile_open_url` | 打开 URL |\n\n### 崩溃日志\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `mobile_list_crashes` | 列出设备上的崩溃报告 |\n| `mobile_get_crash` | 获取指定 ID 的崩溃报告内容 |\n\n资料来源：[README.md:100-130](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 依赖项\n\n### 核心依赖\n\n```json\n{\n \"@modelcontextprotocol/sdk\": \"1.26.0\",\n \"ajv\": \"^8.18.0\",\n \"commander\": \"14.0.0\",\n \"express\": \"5.1.0\",\n \"fast-xml-parser\": \"5.5.7\",\n \"qs\": \"^6.15.0\",\n \"zod\": \"^4.1.13\",\n \"zod-to-json-schema\": \"3.25.0\"\n}\n```\n\n### 可选依赖\n\n```json\n{\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n`mobilecli` 为可选依赖，用于与 iOS/Android 设备通信。\n\n资料来源：[package.json:23-45](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 构建与开发\n\n### 项目构建\n\n```bash\nnpm run build\n```\n\n构建产物输出到 `lib` 目录。\n\n### 开发模式\n\n```bash\nnpm run watch\n```\n\n### 代码检查\n\n```bash\nnpm run lint\n```\n\n## 故障排除\n\n### mobilecli 不可用\n\n错误信息：\n```\nmobilecli is not available or not working properly\n```\n\n解决方案：访问 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) 查看 mobilecli 安装说明。\n\n### iOS 设备连接问题\n\niOS 真机需要以下服务正常运行：\n\n1. **iOS 隧道**：用于网络通信\n2. **WDA 端口转发**：WebDriverAgent 端口转发\n3. **WebDriverAgent**：设备上安装并运行\n\n连接检查逻辑位于 `src/ios.ts`：\n\n```typescript\nprivate async assertTunnelRunning(): Promise {\n if (await this.isTunnelRequired()) {\n if (!(await this.isTunnelRunning())) {\n throw new ActionableError(\"iOS tunnel is not running...\");\n }\n }\n}\n\nprivate async wda(): Promise {\n await this.assertTunnelRunning();\n if (!(await this.isWdaForwardRunning())) {\n throw new ActionableError(\"Port forwarding to WebDriverAgent is not running...\");\n }\n if (!(await wda.isRunning())) {\n throw new ActionableError(\"WebDriverAgent is not running on device...\");\n }\n return wda;\n}\n```\n\n资料来源：[src/ios.ts:60-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### 应用安装失败\n\n安装 .zip 文件时会进行以下验证：\n\n1. 路径安全检查（防止 zip-slip 攻击）\n2. 自动解压到临时目录\n3. 查找 .app bundle 文件\n\n如未找到 .app bundle，抛出错误：\n```\nNo .app bundle found in the .zip file\n```\n\n资料来源：[src/iphone-simulator.ts:80-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n\n## 更多资源\n\n- 完整文档：[官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki)\n- 路线图：[项目路线图](https://github.com/orgs/mobile-next/projects/3)\n- 示例提示词：[Prompt Example 仓库](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- Slack 社区：[加入讨论](https://mobilenexthq.com/join-slack)\n\n---\n\n\n\n## 客户端配置指南\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [MCP 工具详解](#mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 客户端配置指南\n\n本指南详细说明如何在不同 IDE 和 AI 编程助手客户端中配置 Mobile MCP 服务器。Mobile MCP 是一个基于 Model Context Protocol (MCP) 的移动设备自动化框架，支持 iOS、Android、模拟器和真机等平台。\n\n## 标准配置模板\n\n无论使用何种客户端，大多数工具都使用相同的基础配置结构：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `command` | string | 执行命令，固定为 `npx` |\n| `args` | array | 命令参数，`-y` 表示自动确认，`@mobilenext/mobile-mcp@latest` 指定包名和版本 |\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Claude 系列客户端配置\n\n### Claude Desktop\n\n在 Claude Desktop 中配置 Mobile MCP，需要编辑 MCP 安装配置文件。详细步骤请参考 [MCP 快速入门指南](https://modelcontextprotocol.io/quickstart/user)，直接使用上述标准配置即可。\n\n### Claude Code\n\n使用 Claude Code CLI 添加 Mobile MCP 服务器：\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n\n或者手动编辑配置文件 `~/.claude/settings.json`，添加标准配置模板中的 JSON 内容。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Cline\n\nCline 客户端配置最为简单，只需将标准配置 JSON 添加到 MCP 设置文件即可：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n更多详情请参考 [Cline 配置文档](https://github.com/mobile-next/mobile-mcp/wiki/Cline)。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## AI IDE 客户端配置\n\n### Cursor\n\nCursor 提供两种安装方式：\n\n#### 方式一：点击安装按钮\n\n访问 Cursor 安装页面，点击安装按钮自动配置。\n\n#### 方式二：手动安装\n\n1. 进入 `Cursor Settings` → `MCP` → `Add new MCP Server`\n2. 根据喜好命名服务器\n3. 使用 `command` 类型，命令设为 `npx -y @mobilenext/mobile-mcp@latest`\n4. 可通过点击 `Edit` 验证配置或添加命令行参数\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Codex\n\n使用 Codex CLI 添加服务器：\n\n```bash\ncodex mcp add mobile-mcp npx \"@mobilenext/mobile-mcp@latest\"\n```\n\n或者编辑配置文件 `~/.codex/config.toml`：\n\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n\n更多配置信息请参考 Codex MCP 文档。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Copilot\n\n使用 Copilot CLI 交互式添加服务器：\n\n```bash\n/mcp add\n```\n\n或者手动编辑 `~/.copilot/mcp-config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": \"npx\",\n \"tools\": [\"*\"],\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 其他开发工具配置\n\n### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n\n### Goose\n\n#### 点击安装\n\n访问 Goose 安装页面，使用默认配置自动安装。\n\n#### 手动安装\n\n1. 进入 `Advanced settings` → `Extensions` → `Add custom extension`\n2. 自定义命名\n3. 选择类型为 `STDIO`\n4. 设置命令为 `npx -y @mobilenext/mobile-mcp@latest`\n5. 点击 \"Add Extension\"\n\n### Kiro\n\n在 `.kiro/settings/mcp.json` 中添加配置：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n详细文档请参考 [Kiro MCP 文档](https://kiro.dev/docs/mcp/)。\n\n### opencode\n\n在 `~/.config/opencode/opencode.json` 中配置：\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"mobile-mcp\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"@mobilenext/mobile-mcp@latest\"],\n \"enabled\": true\n }\n }\n}\n```\n\n### Qodo Gen\n\n1. 在 VSCode 或 IntelliJ 中打开 Qodo Gen 聊天面板\n2. 进入 `Connect more tools` → `+ Add new MCP`\n3. 粘贴标准配置\n4. 点击 `Save`\n\n### Windsurf\n\n1. 打开 Windsurf 设置\n2. 导航至 MCP servers\n3. 添加新服务器，选择 `command` 类型\n4. 输入命令：`npx @mobilenext/mobile-mcp@latest`\n\n或在设置中的 `mcpServers` 下添加标准配置。\n\n### Amp\n\n#### VS Code 扩展方式\n\n通过 Amp VS Code 扩展设置界面添加，或更新 `settings.json`：\n\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n\n#### Amp CLI 方式\n\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## SSE 服务器模式配置\n\nMobile MCP 默认通过 stdio 通信。如需启动 SSE 服务器，使用 `--listen` 参数：\n\n### 基础配置\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n这将绑定到 `localhost:3000`。\n\n### 绑定特定网络接口\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n配置 MCP 客户端连接到 `http://:3000/mcp`。\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n### Bearer Token 授权配置\n\n为 SSE 服务器启用 Bearer Token 认证，需设置 `MOBILEMCP_AUTH` 环境变量：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n启用后，所有请求必须包含认证头：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n> 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 设备连接架构\n\nMobile MCP 通过 `mobilecli` 工具与移动设备通信，支持多种设备类型：\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端\"\n A[Claude Code] --> B[配置解析]\n C[Cursor] --> B\n D[Copilot] --> B\n end\n \n subgraph \"Mobile MCP 服务器\"\n B --> E[服务器初始化]\n E --> F{设备类型检测}\n F -->|iOS| G[IosRobot]\n F -->|Android| H[AndroidRobot]\n F -->|Simulator| I[SimulatorRobot]\n end\n \n subgraph \"设备通信层\"\n G --> J[ios libimobiledevice]\n H --> K[Android Debug Bridge]\n I --> J\n end\n \n subgraph \"移动设备\"\n J --> L[iOS 设备]\n K --> M[Android 设备]\n end\n```\n\n### 设备类型检测流程\n\n1. 获取设备标识符\n2. 检查是否为 iOS 真机（通过 `IosManager.listDevices()`）\n3. 检查是否为 Android 设备（通过 `AndroidDeviceManager.getConnectedDevices()`）\n4. 检查是否为模拟器（通过 `mobilecli.getDevices()`）\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n> 资料来源：[src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## 环境要求\n\n### Node.js 版本\n\n要求 Node.js 版本 >= 18\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\n> 资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n### mobilecli 依赖\n\n`mobilecli` 是可选依赖项，用于底层设备通信：\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n服务器启动时会验证 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly.`);\n }\n};\n```\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 配置问题排查\n\n### 常见配置错误\n\n| 错误信息 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| `mobilecli is not available` | mobilecli 未安装或路径错误 | 参考 [Wiki 安装文档](https://github.com/mobile-next/mobile-mcp/wiki) |\n| `iOS tunnel is not running` | iOS 设备隧道未建立 | 确保 WebDriverAgent 和端口转发正常运行 |\n| `Port forwarding to WebDriverAgent is not running` | WDA 端口未转发 | 检查端口 8100 是否正常转发 |\n| `WebDriverAgent is not running on device` | WDA 应用未启动 | 重启设备上的 WDA 应用 |\n\n### 调试步骤\n\n1. **验证 mobilecli**：运行 `npx mobilecli --version` 确认安装\n2. **检查设备连接**：`mobilecli list-devices` 查看可用设备\n3. **查看服务端日志**：启用详细日志以诊断问题\n4. **参考 Wiki 文档**：访问 [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) 获取详细故障排除指南\n\n> 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n> 资料来源：[src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n## 完整配置示例\n\n### 开发环境完整配置\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"],\n \"env\": {\n \"MOBILEMCP_AUTH\": \"dev-token\"\n }\n }\n }\n}\n```\n\n### 生产环境 SSE 模式配置\n\n```bash\n# 启动带认证的 SSE 服务器\nMOBILEMCP_AUTH=secure-token npx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n对应的客户端配置：\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"],\n \"url\": \"http://localhost:3000/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer secure-token\"\n }\n }\n }\n}\n```\n\n## 进阶配置\n\n### iOS 设备专用配置\n\niOS 设备需要额外的 WebDriverAgent (WDA) 配置。服务器会自动处理：\n\n1. 隧道连接验证\n2. WDA 端口转发检查（默认端口 8100）\n3. WebDriverAgent 运行状态检测\n\n```typescript\nprivate async assertTunnelRunning(): Promise {\n if (await this.isTunnelRequired()) {\n if (!(await this.isTunnelRunning())) {\n throw new ActionableError(\"iOS tunnel is not running\");\n }\n }\n}\n\nprivate async wda(): Promise {\n await this.assertTunnelRunning();\n \n if (!(await this.isWdaForwardRunning())) {\n throw new ActionableError(\"Port forwarding to WebDriverAgent is not running\");\n }\n \n const wda = new WebDriverAgent(\"localhost\", WDA_PORT);\n \n if (!(await wda.isRunning())) {\n throw new ActionableError(\"WebDriverAgent is not running on device\");\n }\n \n return wda;\n}\n```\n\n> 资料来源：[src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android 设备专用配置\n\nAndroid 设备通过 ADB 通信，支持以下功能：\n\n- 应用安装（`.apk` 文件）\n- 应用卸载（通过 bundle ID）\n- 应用启动（支持设置 locale）\n- Shell 命令执行\n\n```typescript\npublic async launchApp(packageName: string, locale?: string): Promise {\n validatePackageName(packageName);\n \n if (locale) {\n validateLocale(locale);\n try {\n this.silentAdb(\"shell\", \"cmd\", \"locale\", \"set-app-locales\", packageName, \"--locales\", locale);\n } catch (error) {\n // set-app-locales requires Android 13+ (API 33)\n }\n }\n \n try {\n this.silentAdb(\"shell\", \"monkey\", \"-p\", packageName, \"-c\", \"android.intent.category.LAUNCHER\", \"1\");\n } catch (error) {\n throw new ActionableError(`Failed launching app with package name \"${packageName}\"`);\n }\n}\n```\n\n> 资料来源：[src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n\n## 相关资源\n\n- [官方 Wiki 文档](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Mobile MCP Roadmap](https://github.com/orgs/mobile-next/projects/3)\n- [Prompt 示例库](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- [Slack 社区](https://mobilenexthq.com/join-slack)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#overview), [设备管理](#device-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 系统架构\n\n## 概述\n\nMobile MCP 是一个基于 Model Context Protocol (MCP) 的移动端自动化服务框架，旨在为 AI Agent 提供统一的移动设备交互能力。该项目支持 iOS 和 Android 平台，能够控制真机、模拟器和模拟器，核心设计理念是通过原生无障碍树（Accessibility Tree）实现 UI 元素识别和交互，无需依赖计算机视觉模型。 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 整体架构\n\nMobile MCP 采用分层架构设计，从上到下依次为：MCP 协议层、工具调度层、机器人抽象层和设备适配层。这种设计确保了上层与具体设备实现的解耦，使得框架能够灵活支持多种移动设备类型。\n\n```mermaid\ngraph TD\n A[MCP Client
Claude/Cursor等] --> B[MCP SDK
协议通信]\n B --> C[Server
工具注册与调度]\n C --> D[Robot Interface
抽象接口层]\n D --> E1[iOS Robot
WebDriverAgent]\n D --> E2[Android Robot
mobilecli]\n D --> E3[Simulator Robot]\n E1 --> F1[iOS Device
真机/模拟器]\n E2 --> F2[Android Device
真机/模拟器]\n E3 --> F1\n```\n\n## 核心组件\n\n### MCP 服务层\n\n**src/server.ts** 是整个系统的核心入口，负责 MCP 协议的初始化、工具定义和执行调度。\n\n| 组件 | 职责 |\n|------|------|\n| tool() | 工具定义函数，使用 Zod 进行参数校验 |\n| getRobotFromDevice() | 根据设备 ID 返回对应的 Robot 实例 |\n| ensureMobilecliAvailable() | 验证 mobilecli 依赖是否可用 |\n\n服务层初始化时首先调用 `ensureMobilecliAvailable()` 验证 mobilecli 可用性，通过 `posthog(\"launch\", {})` 记录启动事件。随后通过 `getRobotFromDevice()` 方法实现设备类型的自动识别。 资料来源：[src/server.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n### 设备管理机制\n\n#### 设备识别流程\n\n```mermaid\ngraph TD\n A[设备ID] --> B{检查iOS设备列表}\n B -->|匹配| C[返回IosRobot]\n B -->|不匹配| D{检查Android设备列表}\n D -->|匹配| E[返回AndroidRobot]\n D -->|不匹配| F{检查iOS模拟器}\n F -->|匹配| G[返回IosRobot]\n F -->|不匹配| H[抛出异常]\n```\n\n设备识别按照 iOS 真机 → Android 真机 → iOS 模拟器的优先级顺序进行检测。每个设备类型都有对应的 Manager 类负责设备列表管理：\n\n- **IosManager**: 通过 `iosManager.listDevices()` 获取 iOS 设备列表\n- **AndroidDeviceManager**: 通过 `androidManager.getConnectedDevices()` 获取 Android 设备列表\n- **mobilecli**: 通过 `mobilecli.getDevices()` 获取模拟器列表\n\n资料来源：[src/server.ts:20-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n#### 设备列表工具\n\n系统提供 `mobile_list_available_devices` 工具用于列举所有可用设备，返回设备 ID、平台类型、设备名称和连接状态信息。\n\n## 机器人抽象层\n\n### Robot 接口定义\n\n**src/robot.ts** 定义了 Robot 抽象接口，规定了所有设备类型必须实现的核心方法：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| getScreenSize() | 获取屏幕尺寸 | 无 |\n| getOrientation() | 获取屏幕方向 | 无 |\n| setOrientation() | 设置屏幕方向 | orientation |\n| swipe() | 滑动操作 | direction, distance |\n| swipeFromCoordinate() | 从坐标滑动 | x, y, direction, distance |\n| tap() | 点击操作 | x, y |\n| doubleTap() | 双击操作 | x, y |\n| longPress() | 长按操作 | x, y, duration |\n| getScreenshot() | 获取截图 | 无 |\n| getElementsOnScreen() | 获取屏幕元素 | 无 |\n| listApps() | 列出已安装应用 | 无 |\n| launchApp() | 启动应用 | packageName, locale |\n| terminateApp() | 终止应用 | packageName |\n| installApp() | 安装应用 | path |\n| uninstallApp() | 卸载应用 | bundleId |\n| openUrl() | 打开 URL | url |\n| sendKeys() | 发送按键 | text |\n| pressButton() | 按压按钮 | button |\n\n资料来源：[src/robot.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n### 屏幕元素数据模型\n\n```typescript\ninterface ScreenElement {\n type: string; // 元素类型：TextField, Button, Switch 等\n label: string; // 无障碍标签\n name: string; // 元素名称\n value: string; // 元素值\n identifier: string; // 元素标识符\n rect: {\n x: number; // 左上角 X 坐标\n y: number; // 左上角 Y 坐标\n width: number; // 元素宽度\n height: number; // 元素高度\n };\n}\n```\n\n## iOS 实现\n\n### 架构特点\n\niOS 设备控制采用 WebDriverAgent (WDA) 作为底层交互协议，通过 `go-ios` 工具建立设备隧道和端口转发。\n\n```mermaid\ngraph LR\n A[MCP Server] -->|localhost:PORT| B[Port Forwarding]\n B --> C[WebDriverAgent]\n C --> D[iOS Device]\n \n E[go-ios tunnel] -->|WDA_PORT| B\n E -->|IOS_TUNNEL_PORT| F[iOS Device Network]\n```\n\n### 关键组件\n\n**src/ios.ts** 包含以下核心功能：\n\n| 组件 | 功能 |\n|------|------|\n| isTunnelRunning() | 检查 iOS 隧道是否运行 |\n| isWdaForwardRunning() | 检查 WDA 端口转发是否建立 |\n| assertTunnelRunning() | 确保隧道可用 |\n| wda() | 获取 WebDriverAgent 实例 |\n\niOS 实现层包含严格的状态检查机制，在执行任何设备操作前必须确保隧道和端口转发正常运行。 资料来源：[src/ios.ts:1-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### WebDriverAgent 交互\n\n**src/webdriver-agent.ts** 实现了 WebDriverAgent 协议，支持以下操作：\n\n| 操作 | 端点 | 方法 |\n|------|------|------|\n| 按压按钮 | /wda/pressButton | POST |\n| 指针动作 | /actions | POST |\n| 获取页面源码 | /source/?format=json | GET |\n| 打开 URL | /url | POST |\n\n元素识别通过 Accessibility Tree 实现，系统只返回特定类型的元素：TextField、Button、Switch、Icon、SearchField、StaticText、Image，并对元素可见性进行过滤。 资料来源：[src/webdriver-agent.ts:1-120](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n## Android 实现\n\n### mobilecli 集成\n\nAndroid 设备通过 mobilecli 命令行工具实现控制。**src/mobile-device.ts** 封装了所有 Android 特有的交互逻辑。\n\n| 命令 | 功能 |\n|------|------|\n| io tap x,y | 点击坐标 |\n| io longpress x,y --duration ms | 长按操作 |\n| io text \"text\" | 输入文本 |\n| io button BACK/HOME | 按压虚拟按键 |\n| dump ui | 获取 UI 层次结构 |\n| device orientation set/get | 屏幕方向控制 |\n\n资料来源：[src/mobile-device.ts:1-60](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n### UI 层级获取\n\nAndroid 设备通过 `dump ui` 命令获取屏幕元素，响应结构为 DumpUIResponse，包含 data.elements 数组，每个元素包含 type、label、text、name、value、identifier、rect 和 focused 属性。\n\n## 通信协议\n\n### STDIO 模式\n\n默认配置下，Mobile MCP 通过标准输入输出（STDIO）与 MCP Client 通信，适用于本地集成场景。启动命令：\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\n### SSE 服务器模式\n\n当需要远程连接时，可启用 SSE（Server-Sent Events）服务器模式：\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n可通过环境变量配置认证令牌：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nSSE 模式下，所有请求需要携带 `Authorization: Bearer ` 头部。 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## 工具系统\n\n### 工具注册机制\n\n所有工具通过 `tool()` 函数注册到 MCP 服务器，每个工具包含：\n\n| 属性 | 说明 |\n|------|------|\n| name | 工具名称，如 mobile_tap_on_screen |\n| description | 工具功能描述 |\n| inputSchema | Zod schema 定义参数 |\n| annotations | 工具标注，如 destructiveHint |\n| handler | 异步处理函数 |\n\n### 核心工具列表\n\n| 工具名 | 功能 | 破坏性提示 |\n|--------|------|------------|\n| mobile_list_available_devices | 列出可用设备 | 否 |\n| mobile_get_screen_size | 获取屏幕尺寸 | 否 |\n| mobile_get_orientation | 获取屏幕方向 | 否 |\n| mobile_set_orientation | 设置屏幕方向 | 是 |\n| mobile_list_apps | 列出已安装应用 | 否 |\n| mobile_launch_app | 启动应用 | 是 |\n| mobile_terminate_app | 终止应用 | 是 |\n| mobile_install_app | 安装应用 | 是 |\n| mobile_uninstall_app | 卸载应用 | 是 |\n| mobile_take_screenshot | 截图 | 否 |\n| mobile_list_elements_on_screen | 获取屏幕元素 | 否 |\n| mobile_click_on_screen_at_coordinates | 点击坐标 | 是 |\n| mobile_double_tap_on_screen | 双击坐标 | 是 |\n| mobile_long_press_on_screen_at_coordinates | 长按坐标 | 是 |\n| mobile_swipe_on_screen | 滑动屏幕 | 是 |\n| mobile_type_keys | 输入文本 | 是 |\n| mobile_press_button | 按压按钮 | 是 |\n| mobile_open_url | 打开 URL | 是 |\n\n资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP 协议实现 |\n| zod | ^4.1.13 | 参数校验 |\n| express | 5.1.0 | SSE 服务器 |\n| commander | 14.0.0 | CLI 参数解析 |\n| fast-xml-parser | 5.5.7 | XML 解析 |\n| qs | ^6.15.0 | 查询字符串处理 |\n| ajv | ^8.18.0 | JSON Schema 验证 |\n\n### 可选依赖\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| mobilecli | 0.3.70 | Android 设备控制 |\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 安全机制\n\n### URL 安全限制\n\n系统默认只允许 http:// 和 https:// 协议 URL，unsafe URL schemes 需要显式设置环境变量：\n\n```bash\nMOBILEMCP_ALLOW_UNSAFE_URLS=1\n```\n\n此检查在 `mobile_open_url` 工具中实现。 资料来源：[src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## 启动流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Client\n participant Server as Server\n participant Mobilecli as mobilecli\n participant Device as Device Manager\n \n MCP->>Server: 连接请求\n Server->>Mobilecli: 检查版本\n alt mobilecli 不可用\n Server-->>MCP: 抛出错误\n end\n Server->>Device: 获取设备列表\n Device-->>Server: 设备信息\n Server->>MCP: 注册工具\n MCP->>Server: 工具调用请求\n Server->>Device: 获取 Robot 实例\n Device-->>Server: Robot 对象\n Server->>Robot: 执行操作\n Robot-->>Server: 操作结果\n Server-->>MCP: 返回结果\n```\n\n## 扩展性设计\n\n系统通过 Robot 接口抽象层支持多种设备类型的扩展，新增设备类型只需：\n\n1. 实现 Robot 接口的所有方法\n2. 在 `getRobotFromDevice()` 中添加设备识别逻辑\n3. 注册对应的 Manager 类\n\n这种设计模式使得框架具有良好的可扩展性，能够适应新平台或新设备类型的集成需求。\n\n---\n\n\n\n## 设备管理\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [iOS 实现](#ios-implementation), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 设备管理\n\n## 概述\n\n设备管理是 Mobile MCP 的核心子系统，负责统一管理 iOS、Android 模拟器、 Android 模拟器以及物理真机等各类移动设备。该模块通过抽象层将不同平台的设备操作统一为一致的接口，使上层工具能够以平台无关的方式与设备进行交互。\n\n设备管理的核心职责包括：\n\n- 设备发现与枚举\n- 设备类型自动识别\n- 设备连接状态管理\n- 设备 Robot 实例化\n- Agent 状态维护与自动安装\n\n资料来源：[src/server.ts:16-18]()\n\n## 架构设计\n\n### 整体架构\n\nMobile MCP 采用分层架构设计，设备管理层位于服务层与平台实现层之间：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[Server.ts 工具层]\n B --> C[设备管理模块]\n C --> D[Robot 抽象接口]\n D --> E[iOS Robot 实现]\n D --> F[Android Robot 实现]\n D --> G[MobileDevice Robot 实现]\n C --> H[mobilecli 工具层]\n H --> I[iOS 平台层]\n H --> J[Android 平台层]\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `getRobotFromDevice()` | src/server.ts | 设备类型检测与 Robot 实例化工厂 |\n| `Robot` | src/robot.ts | 设备操作抽象接口定义 |\n| `IosRobot` | src/ios.ts | iOS 设备操作实现 |\n| `AndroidRobot` | src/android.ts | Android 设备操作实现 |\n| `MobileDevice` | src/mobile-device.ts | 模拟器设备操作实现 |\n| `IosManager` | src/ios.ts | iOS 设备枚举与管理 |\n| `AndroidDeviceManager` | src/android.ts | Android 设备枚举与管理 |\n\n资料来源：[src/server.ts:16-66]()\n\n## 设备发现流程\n\n### 设备列表获取\n\n当调用 `mobile_list_available_devices` 工具时，系统按以下顺序扫描各平台设备：\n\n```mermaid\ngraph TD\n A[开始] --> B[初始化 IosManager]\n B --> C[初始化 AndroidDeviceManager]\n C --> D[获取 Android 设备列表]\n D --> E[遍历 Android 设备详情]\n E --> F[获取 iOS 设备列表]\n F --> G[遍历 iOS 设备详情]\n G --> H[通过 mobilecli 获取模拟器]\n H --> I[合并去重]\n I --> J[返回设备列表]\n```\n\n设备发现函数实现：\n\n```typescript\nasync ({}) => {\n ensureMobilecliAvailable();\n const iosManager = new IosManager();\n const androidManager = new AndroidDeviceManager();\n const devices: MobilecliDevice[] = [];\n // 获取 Android 设备\n const androidDevices = androidManager.getConnectedDevices();\n // ... 合并各平台设备\n}\n```\n\n资料来源：[src/server.ts:100-130]()\n\n### 设备类型识别\n\n`getRobotFromDevice()` 函数负责将设备 ID 映射到对应的 Robot 实现：\n\n```mermaid\ngraph TD\n A[传入 deviceId] --> B{检查是否为 iOS 真机}\n B -->|是| C[返回 IosRobot]\n B -->|否| D{检查是否为 Android 真机}\n D -->|是| E[返回 AndroidRobot]\n D -->|否| F{检查是否为 iOS 模拟器}\n F -->|是| G[检查 agentVerifiedSimulators]\n G -->|未验证| H[调用 agentStatus]\n H -->|失败| I[调用 agentInstall]\n I --> J[添加到已验证集合]\n J --> K[返回 MobileDevice]\n F -->|是| L[返回 MobileDevice]\n```\n\n核心实现逻辑：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n ensureMobilecliAvailable();\n \n // 检查 iOS 真机\n const iosManager = new IosManager();\n const iosDevices = iosManager.listDevices();\n const iosDevice = iosDevices.find(d => d.deviceId === deviceId);\n if (iosDevice) {\n return new IosRobot(deviceId);\n }\n \n // 检查 Android 真机\n const androidManager = new AndroidDeviceManager();\n const androidDevices = androidManager.getConnectedDevices();\n const androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n if (androidDevice) {\n return new AndroidRobot(deviceId);\n }\n \n // 检查 iOS 模拟器\n const response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n });\n // ... 模拟器处理逻辑\n}\n```\n\n资料来源：[src/server.ts:16-66]()\n\n## Robot 抽象接口\n\n`Robot` 接口定义了所有设备类型的通用操作方法：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| `tap(x, y)` | 点击屏幕指定坐标 | x: number, y: number |\n| `doubleTap(x, y)` | 双击屏幕指定坐标 | x: number, y: number |\n| `longPress(x, y, duration)` | 长按屏幕指定坐标 | x, y, duration(ms) |\n| `swipeFromCoordinate(x, y, direction, distance?)` | 从坐标处滑动 | 方向、距离 |\n| `getScreenshot()` | 获取屏幕截图 | 无 |\n| `getElementsOnScreen()` | 获取屏幕元素列表 | 无 |\n| `listApps()` | 列出已安装应用 | 无 |\n| `launchApp(packageName, locale?)` | 启动应用 | 包名、区域 |\n| `terminateApp(packageName)` | 终止应用 | 包名 |\n| `installApp(path)` | 安装应用 | 文件路径 |\n| `uninstallApp(bundleId)` | 卸载应用 | 标识符 |\n| `openUrl(url)` | 打开 URL | 网址 |\n| `sendKeys(text)` | 发送文本输入 | 文本内容 |\n| `pressButton(button)` | 按下物理按钮 | 按钮类型 |\n| `setOrientation(orientation)` | 设置屏幕方向 | portrait/landscape |\n| `getOrientation()` | 获取屏幕方向 | 无 |\n\n资料来源：[src/robot.ts:1-80]()\n\n## 平台实现\n\n### iOS 设备管理\n\niOS 平台使用 `IosManager` 类进行设备管理，通过 WebDriverAgent 或 iOS Device Kit 实现与设备的通信：\n\n- 支持物理真机连接\n- 支持 iOS 模拟器\n- 自动检测 WebDriverAgent 安装状态\n- 支持应用启动时指定区域设置\n\n```typescript\nexport class IosManager {\n listDevices(): IosDevice[] {\n // 列出所有 iOS 设备\n }\n}\n\nexport class IosRobot implements Robot {\n constructor(deviceId: string) {\n // 初始化 iOS Robot 实例\n }\n}\n```\n\n资料来源：[src/ios.ts:1-50]()\n\n### Android 设备管理\n\nAndroid 平台使用 `AndroidDeviceManager` 类进行设备管理，通过 ADB 和 UI Automator 实现与设备的通信：\n\n- 支持物理真机连接\n- 支持 Android 模拟器\n- 支持折叠屏等多屏幕设备\n- 支持应用启动时指定区域设置\n\n```typescript\nexport class AndroidDeviceManager {\n getConnectedDevices(): AndroidDevice[] {\n // 获取已连接的 Android 设备\n }\n}\n\nexport class AndroidRobot implements Robot {\n constructor(deviceId: string) {\n // 初始化 Android Robot 实例\n }\n}\n```\n\n资料来源：[src/android.ts:1-50]()\n\n## mobilecli 集成\n\n### mobilecli 依赖\n\nmobilecli 是 Mobile MCP 的核心底层工具，提供跨平台的设备管理能力：\n\n| 属性 | 值 |\n|------|-----|\n| 包名 | mobilecli |\n| 版本 | 0.3.70 |\n| 类型 | 可选依赖 (optionalDependencies) |\n| Node 版本要求 | >=18 |\n\n资料来源：[package.json:28-29]()\n\n### 依赖检查\n\n在执行任何设备操作前，系统会通过 `ensureMobilecliAvailable()` 函数验证 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(\n `mobilecli is not available or not working properly. ` +\n `Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`\n );\n }\n};\n```\n\n资料来源：[src/server.ts:9-17]()\n\n### mobilecli API\n\n| API 方法 | 功能 | 返回类型 |\n|----------|------|----------|\n| `mobilecli.getVersion()` | 获取 mobilecli 版本 | string |\n| `mobilecli.getDevices(options)` | 获取设备列表 | DeviceResponse |\n| `mobilecli.agentStatus(deviceId)` | 检查设备 Agent 状态 | AgentStatus |\n| `mobilecli.agentInstall(deviceId)` | 在设备上安装 Agent | void |\n\n```typescript\ninterface DeviceResponse {\n status: \"ok\" | \"fail\";\n data?: {\n devices: MobilecliDevice[];\n };\n}\n\ninterface MobilecliDevice {\n id: string;\n name: string;\n platform: string;\n type: string;\n}\n```\n\n资料来源：[src/mobilecli.ts:1-30]()\n\n## 模拟器特殊处理\n\n### Agent 验证机制\n\n对于 iOS 模拟器，系统维护一个 `agentVerifiedSimulators` 集合来追踪已验证的模拟器：\n\n```typescript\nconst agentVerifiedSimulators = new Set();\n```\n\n首次使用模拟器时，系统自动执行 Agent 状态检查：\n\n```mermaid\ngraph TD\n A[模拟器 deviceId] --> B{agentVerifiedSimulators.has}\n B -->|未验证| C[调用 agentStatus]\n C -->|状态失败| D[调用 agentInstall]\n D --> E[添加到已验证集合]\n B -->|已验证| F[跳过验证]\n E --> G[返回 MobileDevice]\n F --> G\n```\n\n资料来源：[src/server.ts:50-60]()\n\n### 模拟器设备类型\n\n通过 mobilecli 获取的模拟器使用 `MobileDevice` 类进行管理，该类提供统一的设备操作接口。\n\n资料来源：[src/mobile-device.ts:1-30]()\n\n## 错误处理\n\n### ActionableError\n\n系统定义 `ActionableError` 类用于提供可操作的错误信息：\n\n```typescript\nclass ActionableError extends Error {\n constructor(message: string) {\n super(message);\n }\n}\n```\n\n### 常见错误场景\n\n| 错误场景 | 错误消息 | 解决方案 |\n|----------|----------|----------|\n| mobilecli 不可用 | \"mobilecli is not available or not working properly\" | 检查安装并参考 Wiki 文档 |\n| 设备未找到 | \"Device \\\"{deviceId}\\\" not found\" | 使用 mobile_list_available_devices 查看可用设备 |\n| Agent 安装失败 | \"agentInstall failed\" | 手动检查 WebDriverAgent/iOS Device Kit 安装状态 |\n\n资料来源：[src/server.ts:9-17, 64-66]()\n\n## 使用示例\n\n### 列出可用设备\n\n```bash\n# 使用 Claude Code\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n\n# 调用 mobile_list_available_devices 工具\n```\n\n### 选择设备并执行操作\n\n```typescript\n// 1. 获取设备列表\nconst devices = await server.tools.mobile_list_available_devices();\n\n// 2. 根据设备 ID 创建 Robot 实例\nconst robot = getRobotFromDevice(deviceId);\n\n// 3. 执行设备操作\nawait robot.tap(100, 200);\nawait robot.getScreenshot();\nawait robot.launchApp(\"com.example.app\");\n```\n\n## 相关工具\n\n设备管理模块提供以下 MCP 工具：\n\n| 工具名称 | 功能 | 只读 |\n|----------|------|------|\n| `mobile_list_available_devices` | 列出所有可用设备 | 是 |\n| `mobile_get_screen_size` | 获取屏幕尺寸 | 是 |\n| `mobile_get_orientation` | 获取屏幕方向 | 是 |\n| `mobile_set_orientation` | 设置屏幕方向 | 否 |\n| `mobile_list_apps` | 列出已安装应用 | 是 |\n| `mobile_launch_app` | 启动应用 | 否 |\n| `mobile_terminate_app` | 终止应用 | 否 |\n| `mobile_install_app` | 安装应用 | 否 |\n| `mobile_uninstall_app` | 卸载应用 | 否 |\n\n资料来源：[src/server.ts:100-200]()\n\n## 总结\n\n设备管理模块是 Mobile MCP 连接 MCP 协议与实际移动设备的桥梁。通过统一的 Robot 抽象接口，系统支持 iOS 物理设备、iOS 模拟器、Android 物理设备和 Android 模拟器四种设备类型。该模块利用 mobilecli 工具进行跨平台设备发现和通信，并针对不同平台特性（如 iOS 的 Agent 验证机制）进行了专门优化。\n\n---\n\n\n\n## MCP 工具详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [iOS 实现](#ios-implementation), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# MCP 工具详解\n\nMobile MCP 是一个基于 Model Context Protocol (MCP) 的移动设备自动化框架，通过标准化的工具接口实现对 iOS、Android、模拟器和真机的远程控制。本文详细介绍该项目中所有可用的 MCP 工具，包括其功能、参数定义和底层实现机制。\n\n## 工具系统架构\n\nMobile MCP 的工具系统采用注册式架构，所有工具通过统一的 `tool()` 函数注册到 MCP 服务器。每个工具包含名称、标题、描述、参数模式和回调函数四个核心组件。\n\n```mermaid\ngraph TD\n A[MCP Client] -->|tool request| B[McpServer]\n B --> C[tool registry]\n C --> D[回调函数执行]\n D --> E[device manager]\n E --> F[iOS Robot]\n E --> G[Android Robot]\n F --> H[WebDriverAgent/iOS]\n G --> I[ADB/Android]\n D --> J[返回结果]\n```\n\n### 工具注册机制\n\n工具注册函数定义于 `src/server.ts`，其签名如下：\n\n```typescript\nconst tool = (\n name: string, // 工具唯一标识符\n title: string, // 人类可读标题\n description: string, // 功能描述\n paramsSchema: ZodSchemaShape, // 参数模式\n annotations: ToolAnnotations, // 注解信息\n cb: (args: any) => Promise // 回调函数\n) => { ... }\n```\n\n`ToolAnnotations` 接口定义了工具的语义注解：\n\n| 注解字段 | 类型 | 说明 |\n|---------|------|------|\n| `readOnlyHint` | boolean | 指示工具是否只读操作 |\n| `destructiveHint` | boolean | 指示工具是否可能造成数据损坏 |\n\n资料来源：[src/server.ts:52-57]()\n\n## 设备管理工具\n\n### 列出可用设备\n\n**工具名称**: `mobile_list_available_devices`\n\n**功能描述**: 返回所有可用的移动设备列表，包括 iOS 模拟器、iOS 真机、Android 模拟器、Android 真机以及离线设备（可选）。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `includeOffline` | boolean | 否 | 是否包含离线设备 |\n\n**返回值**: JSON 格式的设备列表，包含每个设备的标识符、平台类型、设备类型和可用状态。\n\n资料来源：[src/server.ts:103-112]()\n\n### 获取设备类型\n\n**工具名称**: `mobile_get_device_type`\n\n**功能描述**: 获取指定设备的类型信息。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**实现逻辑**: 通过遍历 iOS 设备列表、Android 设备列表和模拟器列表来确定设备类型。\n\n```mermaid\ngraph TD\n A[输入 deviceId] --> B{查找 iOS 设备}\n B -->|找到| C[返回 ios]\n B -->|未找到| D{查找 Android 设备}\n D -->|找到| E[返回 android]\n D -->|未找到| F{查找模拟器}\n F -->|找到| G[返回 simulator]\n F -->|未找到| H[抛出异常]\n```\n\n资料来源：[src/server.ts:85-102]()\n\n## 屏幕与显示工具\n\n### 获取屏幕尺寸\n\n**工具名称**: `mobile_get_screen_size`\n\n**功能描述**: 获取移动设备的屏幕尺寸（像素单位）。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含 `width` 和 `height` 的屏幕尺寸对象。\n\n资料来源：[README.md]()\n\n### 获取屏幕方向\n\n**工具名称**: `mobile_get_orientation`\n\n**功能描述**: 获取当前设备的屏幕方向。\n\n**返回值**: `\"portrait\"` 或 `\"landscape\"`。\n\n资料来源：[src/robot.ts:67-70]()\n\n### 设置屏幕方向\n\n**工具名称**: `mobile_set_orientation`\n\n**功能描述**: 更改设备的屏幕方向。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `orientation` | string | 是 | 目标方向：`portrait` 或 `landscape` |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nsetOrientation(orientation: Orientation): Promise;\n```\n\n资料来源：[src/robot.ts:60-65]()\n\n## 应用管理工具\n\n### 列出已安装应用\n\n**工具名称**: `mobile_list_apps`\n\n**功能描述**: 列出目标设备上所有已安装的应用程序。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含应用名称、包名/Bundle ID 等信息的 JSON 数组。\n\n资料来源：[README.md]()\n\n### 启动应用\n\n**工具名称**: `mobile_launch_app`\n\n**功能描述**: 通过包名称（Android）或 Bundle ID（iOS）启动指定应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 应用标识符 |\n| `locale` | string | 否 | 启动时使用的语言环境（仅 iOS） |\n\n资料来源：[src/server.ts](), [CHANGELOG.md]()\n\n### 终止应用\n\n**工具名称**: `mobile_terminate_app`\n\n**功能描述**: 强制停止并终止正在运行的应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 要终止的应用标识符 |\n\n**Android 实现**: 使用 `adb shell am force-stop ` 命令。\n\n资料来源：[src/android.ts:126-128]()\n\n### 安装应用\n\n**工具名称**: `mobile_install_app`\n\n**功能描述**: 从本地文件安装应用。\n\n**支持格式**: `.apk`（Android）、`.ipa`（iOS）、`.app`、`.zip`\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appPath` | string | 是 | 应用文件路径 |\n\n### 卸载应用\n\n**工具名称**: `mobile_uninstall_app`\n\n**功能描述**: 卸载指定应用。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `appId` | string | 是 | 应用标识符 |\n\n## 屏幕交互工具\n\n### 截图\n\n**工具名称**: `mobile_take_screenshot`\n\n**功能描述**: 拍摄当前屏幕截图，用于了解屏幕内容。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n### 保存截图\n\n**工具名称**: `mobile_save_screenshot`\n\n**功能描述**: 将截图保存到指定文件路径。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `outputPath` | string | 是 | 输出文件路径 |\n\n**安全修复**: 0.0.49 版本修复了路径遍历漏洞，防止通过 `../` 访问目录外文件。\n\n资料来源：[CHANGELOG.md]()\n\n### 点击坐标\n\n**工具名称**: `mobile_click_on_screen_at_coordinates`\n\n**功能描述**: 在指定屏幕坐标处执行点击操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n\n### 双击\n\n**工具名称**: `mobile_double_tap_on_screen`\n\n**功能描述**: 在指定坐标执行双击操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n\n### 长按\n\n**工具名称**: `mobile_long_press_on_screen_at_coordinates`\n\n**功能描述**: 在指定坐标执行长按操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `x` | number | 是 | X 坐标 |\n| `y` | number | 是 | Y 坐标 |\n| `duration` | number | 是 | 长按持续时间（毫秒） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nlongPress(x: number, y: number, duration: number): Promise;\n```\n\n资料来源：[src/robot.ts:41-49]()\n\n### 滑动\n\n**工具名称**: `mobile_swipe_on_screen`\n\n**功能描述**: 在屏幕上执行滑动操作，支持任意方向。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `direction` | string | 是 | 滑动方向：`up`、`down`、`left`、`right` |\n\n## 输入工具\n\n### 输入文本\n\n**工具名称**: `mobile_type_keys`\n\n**功能描述**: 向当前焦点元素输入文本，支持可选的提交操作。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `text` | string | 是 | 要输入的文本 |\n| `submit` | boolean | 否 | 是否在输入后提交 |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nsendKeys(text: string): Promise;\n```\n\n资料来源：[src/robot.ts:29-33]()\n\n### 按键\n\n**工具名称**: `mobile_press_button`\n\n**功能描述**: 模拟物理按键按压。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `button` | string | 是 | 按键名称（如 `ENTER`、`HOME`、`BACK`） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\npressButton(button: Button): Promise;\n```\n\n**iOS 实现**（WebDriverAgent）:\n\n```typescript\nawait this.withinSession(async sessionUrl => {\n const url = `${sessionUrl}/wda/pressButton`;\n const response = await fetch(url, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ name: button }),\n });\n return response.json();\n});\n```\n\n资料来源：[src/webdriver-agent.ts](), [src/robot.ts:35-38]()\n\n## 元素检测工具\n\n### 列出屏幕元素\n\n**工具名称**: `mobile_list_elements_on_screen`\n\n**功能描述**: 列出屏幕上所有 UI 元素及其坐标和属性信息。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 包含元素类型、标签、名称、值、标识符和矩形区域的数组。\n\n**ScreenElement 数据结构**:\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `type` | string | 元素类型（如 `TextField`、`Button`、`Switch`） |\n| `label` | string | 元素标签 |\n| `name` | string | 元素名称 |\n| `value` | string | 元素值 |\n| `identifier` | string | 元素标识符（resource-id 或 rawIdentifier） |\n| `rect` | object | 元素矩形区域 `{x, y, width, height}` |\n\n**Android 元素收集逻辑**:\n\n```mermaid\ngraph TD\n A[获取 UI Automator XML] --> B[遍历 XML 节点]\n B --> C{节点是否包含可交互属性?}\n C -->|text/content-desc/hint/resource-id| D[创建 ScreenElement]\n C -->|无| E[跳过]\n D --> F{rect width > 0 && height > 0?}\n F -->|是| G[添加到元素列表]\n F -->|否| E\n G --> H{是否有子节点?}\n H -->|是| B\n H -->|否| I[返回元素列表]\n```\n\n**iOS 元素过滤逻辑**:\n\n```typescript\nconst acceptedTypes = [\"TextField\", \"Button\", \"Switch\", \"Icon\", \"SearchField\", \"StaticText\", \"Image\"];\n\nif (acceptedTypes.includes(source.type)) {\n if (source.isVisible === \"1\" && this.isVisible(source.rect)) {\n if (source.label !== null || source.name !== null || source.rawIdentifier !== null) {\n output.push({ ... });\n }\n }\n}\n```\n\n资料来源：[src/android.ts](), [src/webdriver-agent.ts:1-35]()\n\n## 崩溃日志工具\n\n### 列出崩溃报告\n\n**工具名称**: `mobile_list_crashes`\n\n**功能描述**: 列出设备上可用的崩溃报告。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n\n**返回值**: 崩溃报告 ID 列表。\n\n**实现**:\n\n```typescript\nasync ({ device }) => {\n ensureMobilecliAvailable();\n const response = mobilecli.crashesList(device);\n return JSON.stringify(response.data);\n}\n```\n\n资料来源：[src/server.ts:201-211]()\n\n### 获取崩溃详情\n\n**工具名称**: `mobile_get_crash`\n\n**功能描述**: 根据崩溃 ID 获取完整崩溃报告内容。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `crashId` | string | 是 | 崩溃报告 ID |\n\n## 录制工具\n\n### 开始录制\n\n**工具名称**: `mobile_start_recording`\n\n**功能描述**: 开始录制屏幕操作视频。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `outputPath` | string | 是 | 输出文件路径 |\n\n**实现细节**:\n\n- 使用子进程启动录制命令\n- 设置 5 分钟超时保护\n- 返回 `ActiveRecording` 对象包含进程和开始时间\n\n### 停止录制\n\n**工具名称**: `mobile_stop_recording`\n\n**功能描述**: 停止正在进行的屏幕录制。\n\n**返回值**: 包含文件路径、大小（MB）和持续时间的信息字符串。\n\n**超时机制**:\n\n```typescript\nconst timeout = setTimeout(() => {\n child.kill(\"SIGKILL\");\n resolve();\n}, 5 * 60 * 1000);\n```\n\n资料来源：[src/server.ts:145-200]()\n\n## URL 导航工具\n\n### 打开 URL\n\n**工具名称**: `mobile_open_url`\n\n**功能描述**: 在设备浏览器或应用内打开指定 URL。\n\n**参数定义**:\n\n| 参数名 | 类型 | 必填 | 说明 |\n|-------|------|------|------|\n| `device` | string | 是 | 设备标识符 |\n| `url` | string | 是 | 目标 URL（支持 http://, https:// 或自定义 scheme） |\n\n**接口定义**（Robot 抽象类）:\n\n```typescript\nopenUrl(url: string): Promise;\n```\n\n**iOS 实现**（WebDriverAgent）:\n\n```typescript\npublic async openUrl(url: string): Promise {\n await this.withinSession(async sessionUrl => {\n await fetch(`${sessionUrl}/url`, {\n method: \"POST\",\n body: JSON.stringify({ url }),\n });\n });\n}\n```\n\n资料来源：[src/webdriver-agent.ts](), [src/robot.ts:25-28]()\n\n## 工具分类总览\n\n| 分类 | 工具数量 | 核心功能 |\n|------|---------|---------|\n| 设备管理 | 2 | 列表查询、类型获取 |\n| 屏幕显示 | 3 | 尺寸、方向管理 |\n| 应用管理 | 4 | 安装、卸载、启动、终止 |\n| 屏幕交互 | 5 | 点击、双击、长按、滑动、截图 |\n| 输入 | 2 | 文本输入、按键 |\n| 元素检测 | 1 | UI 元素枚举 |\n| 崩溃日志 | 2 | 列表查询、详情获取 |\n| 录制 | 2 | 开始/停止屏幕录制 |\n| 导航 | 1 | URL 打开 |\n\n## 技术依赖\n\nMobile MCP 工具系统的核心依赖：\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP 协议实现 |\n| `zod` | ^4.1.13 | 参数验证 |\n| `zod-to-json-schema` | 3.25.0 | Zod 转 JSON Schema |\n| `mobilecli` | 0.3.70 | 移动设备 CLI 接口 |\n\n资料来源：[package.json:23-34]()\n\n## 总结\n\nMobile MCP 通过统一的工具注册机制，封装了针对 iOS 和 Android 平台的大量自动化操作。所有工具遵循相同的接口规范，通过设备管理器自动路由到对应的平台实现（`IosRobot` 或 `AndroidRobot`）。这种设计使得 AI Agent 能够通过简单的工具调用完成复杂的移动端自动化任务，包括应用管理、UI 交互、数据采集和端到端工作流执行。\n\n---\n\n\n\n## iOS 实现\n\n### 相关页面\n\n相关主题：[设备管理](#device-management), [Android 实现](#android-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/android-robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android-robot.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# iOS 实现\n\n## 概述\n\nMobile MCP 的 iOS 实现模块负责与 iOS 设备（真机和模拟器）进行交互。该模块通过统一的抽象接口 `Robot` 提供跨平台自动化能力，同时针对 iOS 平台特性实现了特定的设备管理、元素获取和交互操作。\n\niOS 实现的核心目标包括：\n\n- 支持 iOS 模拟器（iPhone Simulator）和真机设备\n- 通过原生无障碍树（Accessibility Tree）获取 UI 元素信息\n- 提供截图、点击、滑动、文本输入等基础交互能力\n- 自动管理 WebDriverAgent 或 iOS Device Kit 生命周期\n\n资料来源：[src/robot.ts:1-50]()\n\n## 架构设计\n\n### 整体架构\n\nMobile MCP 采用分层架构设计，iOS 实现位于设备交互层：\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Server Layer]\n B --> C[Tool Handlers]\n C --> D[Robot Interface]\n D --> E[iOS Robot]\n D --> F[Android Robot]\n E --> G[IosManager]\n E --> H[Mobilecli]\n G --> I[WebDriverAgent]\n G --> J[iOS Device Kit]\n H --> K[iPhone Simulator]\n```\n\n### 设备类型识别\n\n服务器启动时通过 `getRobotFromDevice` 函数识别设备类型并返回对应的 Robot 实例：\n\n```typescript\nconst getRobotFromDevice = (deviceId: string): Robot => {\n ensureMobilecliAvailable();\n \n // 检查是否为 iOS 真机\n const iosManager = new IosManager();\n const iosDevices = iosManager.listDevices();\n const iosDevice = iosDevices.find(d => d.deviceId === deviceId);\n if (iosDevice) {\n return new IosRobot(deviceId);\n }\n \n // 检查是否为 Android 设备\n const androidManager = new AndroidDeviceManager();\n const androidDevices = androidManager.getConnectedDevices();\n const androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n if (androidDevice) {\n return new AndroidRobot(deviceId);\n }\n \n // 检查是否为 iOS 模拟器\n const response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n });\n // ...\n};\n```\n\n资料来源：[src/server.ts:1-100]()\n\n## 核心组件\n\n### Robot 接口定义\n\n`Robot` 接口是所有设备交互的抽象基类，定义了统一的操作契约：\n\n| 方法 | 功能描述 | 参数 |\n|------|----------|------|\n| `getScreenSize()` | 获取屏幕尺寸 | 无 |\n| `getOrientation()` | 获取屏幕方向 | 无 |\n| `setOrientation(orientation)` | 设置屏幕方向 | `portrait` 或 `landscape` |\n| `getScreenshot()` | 获取屏幕截图 | 无 |\n| `getElementsOnScreen()` | 获取屏幕元素列表 | 无 |\n| `tap(x, y)` | 点击指定坐标 | x, y 坐标 |\n| `doubleTap(x, y)` | 双击指定坐标 | x, y 坐标 |\n| `longPress(x, y, duration)` | 长按指定坐标 | x, y, duration(ms) |\n| `swipeFromCoordinate(x, y, direction, distance)` | 滑动操作 | 起点坐标、方向、距离 |\n| `sendKeys(text)` | 输入文本 | 文本内容 |\n| `pressButton(button)` | 按下物理按钮 | HOME, BACK, VOLUME_UP 等 |\n| `openUrl(url)` | 打开 URL | URL 字符串 |\n| `listApps()` | 列出已安装应用 | 无 |\n| `launchApp(packageName, locale?)` | 启动应用 | 包名，可选语言 |\n| `terminateApp(packageName)` | 终止应用 | 包名 |\n| `installApp(path)` | 安装应用 | 文件路径 |\n| `uninstallApp(bundleId)` | 卸载应用 | Bundle ID |\n\n资料来源：[src/robot.ts:1-120]()\n\n### IosRobot 实现\n\n`IosRobot` 是 iOS 平台的 Robot 接口实现，负责具体的 iOS 设备操作。该类封装了与 iOS 设备通信的所有逻辑，包括：\n\n- 元素查询与遍历\n- 坐标点击和手势操作\n- 文本输入\n- 应用管理\n- 截图获取\n\n### IosManager\n\n`IosManager` 负责管理 iOS 设备的发现和状态监控：\n\n- `listDevices()` - 列出所有已连接的 iOS 真机\n- 设备健康状态检查\n\n### iPhone Simulator\n\niOS 模拟器通过 `mobilecli` 工具进行管理，提供与真机类似的交互能力。模拟器支持完整的功能测试，无需真实硬件即可进行 UI 自动化测试。\n\n## 工作原理\n\n### 设备连接流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Server as MCP Server\n participant IosManager as IosManager\n participant Device as iOS 设备\n participant WDA as WebDriverAgent/iOS Device Kit\n\n User->>Server: mobile_list_available_devices\n Server->>IosManager: listDevices()\n IosManager->>Device: 查询设备\n Device-->>IosManager: 设备列表\n IosManager-->>Server: 返回设备\n Server-->>User: 可用设备列表\n\n User->>Server: 选择设备并执行操作\n Server->>IosRobot: 创建实例\n IosRobot->>WDA: 初始化连接\n WDA->>Device: 建立通信\n```\n\n### 模拟器 Agent 验证\n\n对于 iOS 模拟器，系统会自动验证并安装必要的 Agent：\n\n```typescript\nif (!agentVerifiedSimulators.has(deviceId)) {\n const agentStatus = mobilecli.agentStatus(deviceId);\n if (agentStatus.status === \"fail\") {\n mobilecli.agentInstall(deviceId);\n }\n agentVerifiedSimulators.add(deviceId);\n}\n```\n\n资料来源：[src/server.ts:50-80]()\n\n## 依赖组件\n\n### mobilecli\n\n`mobilecli` 是项目的基础依赖工具，提供跨平台的移动设备管理能力：\n\n```json\n{\n \"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n }\n}\n```\n\n版本历史记录显示 mobilecli 版本持续更新以支持新功能和修复问题：\n\n| 版本 | 主要更新 |\n|------|----------|\n| 0.3.70 | 当前使用版本，支持最新 iOS Device Kit |\n| 0.3.68 | 引入 iOS Device Kit |\n| 0.2.0 | 早期版本 |\n\n资料来源：[package.json:25-30]()\n\n### iOS Device Kit vs WebDriverAgent\n\n从 v0.0.53 版本开始，项目从 WebDriverAgent 迁移到开源的 iOS Device Kit（Apache 许可证），主要优势包括：\n\n- 开源许可证（WebDriverAgent 使用自定义许可证）\n- 更稳定的设备连接管理\n- 更好的黑屏问题处理\n\n```mermaid\ngraph LR\n A[v0.0.52 及之前] -->|WebDriverAgent| B[闭源实现]\n C[v0.0.53 及之后] -->|iOS Device Kit| D[Apache 许可证]\n```\n\n资料来源：[CHANGELOG.md]()\n\n## iOS 工具集\n\nMobile MCP 为 iOS 平台提供以下 MCP 工具：\n\n### 设备管理\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_list_available_devices` | 列出所有可用设备（包含 iOS 模拟器和真机） |\n| `mobile_get_screen_size` | 获取 iOS 设备屏幕尺寸 |\n| `mobile_get_orientation` | 获取当前屏幕方向 |\n| `mobile_set_orientation` | 设置屏幕方向 |\n\n### 应用管理\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_list_apps` | 列出 iOS 设备上安装的所有应用 |\n| `mobile_launch_app` | 通过 Bundle ID 启动应用 |\n| `mobile_terminate_app` | 终止运行中的应用 |\n| `mobile_install_app` | 安装 .ipa 或 .app 文件 |\n| `mobile_uninstall_app` | 卸载应用 |\n\n### 屏幕交互\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_take_screenshot` | 截取当前屏幕 |\n| `mobile_save_screenshot` | 保存截图到文件 |\n| `mobile_list_elements_on_screen` | 获取屏幕元素及属性 |\n| `mobile_click_on_screen_at_coordinates` | 点击指定坐标 |\n| `mobile_double_tap_on_screen` | 双击指定坐标 |\n| `mobile_long_press_on_screen_at_coordinates` | 长按指定坐标 |\n| `mobile_swipe_on_screen` | 滑动操作 |\n\n### 输入与导航\n\n| 工具名称 | 功能 |\n|----------|------|\n| `mobile_type_keys` | 输入文本 |\n| `mobile_press_button` | 按下物理按钮（HOME、BACK、VOLUME 等） |\n| `mobile_open_url` | 在浏览器中打开 URL |\n\n## 使用示例\n\n### 配置 Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 使用 Claude Code 连接 iOS 模拟器\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n\n### 列出可用设备\n\n在 Claude Code 或其他 MCP 客户端中执行：\n\n```\n使用 mobile_list_available_devices 工具列出所有可用的 iOS 设备和模拟器\n```\n\n### 在 iOS 模拟器上测试应用\n\n```bash\n# 查看可用模拟器\nxcrun simctl list\n\n# 启动特定模拟器\nxcrun simctl boot \"iPhone 16\"\n\n# 使用 mobile_list_available_devices 获取设备 ID\n# 然后使用 mobile_launch_app 启动测试应用\n```\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 设备未识别 | 运行 `xcrun simctl list` 检查模拟器状态 |\n| WebDriverAgent 连接失败 | 更新 mobilecli 到最新版本 |\n| 模拟器黑屏 | 使用 iOS Device Kit（v0.0.53+）或重启模拟器 |\n| Agent 未安装 | 调用 `mobilecli.agentInstall(deviceId)` |\n\n### 验证 mobilecli 安装\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly. \n Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`);\n }\n};\n```\n\n资料来源：[src/server.ts:15-25]()\n\n## 版本历史\n\n| 版本 | iOS 相关更新 |\n|------|--------------|\n| 0.0.54 | 更新 mobilecli 至 0.3.70；修复导致 iOS Device Kit 黑屏死机的问题 |\n| 0.0.53 | 引入 iOS Device Kit 替代 WebDriverAgent；添加崩溃报告工具 |\n| 0.0.38 | 迁移 iPhone Simulator 调用至 mobilecli；自动下载安装 WebDriverAgent |\n| 0.0.22 | 修复 go-ios 安装检测问题 |\n| 0.0.21 | 模拟器上自动启动 WebDriverAgent |\n\n资料来源：[CHANGELOG.md]()\n\n## 扩展阅读\n\n- [官方 Wiki](https://github.com/mobile-next/mobile-mcp/wiki) - 详细配置和调试指南\n- [Roadmap](https://github.com/orgs/mobile-next/projects/3) - 项目路线图\n- [mobilecli 文档](https://github.com/mobile-next/mobilecli) - 底层工具文档\n\n---\n\n\n\n## Android 实现\n\n### 相关页面\n\n相关主题：[设备管理](#device-management), [iOS 实现](#ios-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/android.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/android.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# Android 实现\n\n## 概述\n\nAndroid 实现是 mobile-mcp 项目的核心模块之一，负责与 Android 设备（真机、模拟器）进行交互。该模块通过 ADB（Android Debug Bridge）协议与设备通信，实现了设备管理、UI 元素检测、屏幕交互、应用管理等一系列移动端自动化能力。\n\nAndroid 模块的主要职责包括：\n\n- 通过 `adb devices` 命令发现和验证已连接的 Android 设备\n- 使用 `uiautomator dump` 获取界面层次结构并解析 UI 元素\n- 执行点击、双击、长按、滑动等手势操作\n- 管理应用生命周期（安装、卸载、启动、终止）\n- 截取屏幕截图和屏幕录制\n- 获取设备信息（屏幕尺寸、方向、系统版本等）\n\n资料来源：[src/android.ts:1-100]()\n\n## 系统架构\n\n### 整体架构\n\nMobile MCP 采用跨平台统一抽象的设计理念，通过 Robot 模式为 iOS 和 Android 提供统一的操作接口。Android 实现位于这一架构的核心层。\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Manager]\n B --> C[Android Device Manager]\n B --> D[iOS Device Manager]\n C --> E[AndroidRobot]\n D --> F[IosRobot]\n E --> G[ADB Communication]\n G --> H[Android Device/Emulator]\n F --> I[WebDriverAgent/go-ios]\n I --> J[iOS Device/Simulator]\n```\n\n### Android 通信流程\n\nAndroid 设备通过 ADB 与服务端通信，每条命令的执行都遵循以下流程：\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant AR as AndroidRobot\n participant ADB as ADB Command\n participant DEV as Android Device\n\n MCP->>AR: 调用 Android 方法\n AR->>ADB: 构建 adb 命令\n ADB->>DEV: 执行 shell 命令\n DEV-->>ADB: 返回执行结果\n ADB-->>AR: 解析响应数据\n AR-->>MCP: 返回结构化结果\n```\n\n资料来源：[src/android.ts:50-150]()\n\n## 核心组件\n\n### AndroidDeviceManager\n\n`AndroidDeviceManager` 类负责设备发现和枚举，是 Android 模块的入口点。\n\n| 方法 | 说明 | 返回类型 |\n|------|------|----------|\n| `getConnectedDevices()` | 获取已连接的真机和模拟器列表 | `Array<{deviceId, deviceType}>` |\n| `getConnectedDevicesWithDetails()` | 获取包含详细信息的设备列表 | `Array<{deviceId, deviceType, version, name}>` |\n\n**设备发现机制**\n\n```typescript\n// 从 android.ts 提取的关键实现逻辑\nconst names = execFileSync(getAdbPath(), [\"devices\"])\n .toString()\n .split(\"\\n\")\n .map(line => line.trim())\n .filter(line => line !== \"\")\n .filter(line => !line.startsWith(\"List of devices attached\"))\n .filter(line => line.split(\"\\t\")[1]?.trim() === \"device\") // 仅包含在线设备\n .map(line => line.split(\"\\t\")[0]);\n```\n\n设备必须满足两个条件才会被返回：\n1. 出现在 `adb devices` 命令输出中\n2. 状态为 `device`（而非 `offline` 或 `unauthorized`）\n\n资料来源：[src/android.ts:180-220]()\n\n### AndroidRobot\n\n`AndroidRobot` 是与单个 Android 设备交互的核心类，封装了所有设备操作。\n\n| 属性/方法 | 说明 |\n|-----------|------|\n| `deviceId` | 设备标识符 |\n| `getScreenSize()` | 获取屏幕分辨率 |\n| `getOrientation()` | 获取屏幕方向 |\n| `setOrientation()` | 设置屏幕方向 |\n| `listElementsOnScreen()` | 获取屏幕元素列表 |\n| `click()` | 点击指定坐标 |\n| `doubleTap()` | 双击指定坐标 |\n| `longPress()` | 长按指定坐标 |\n| `swipe()` | 滑动操作 |\n| `typeKeys()` | 输入文本 |\n| `pressButton()` | 按压物理按钮 |\n| `takeScreenshot()` | 截取屏幕截图 |\n| `startScreenRecording()` | 开始屏幕录制 |\n| `stopScreenRecording()` | 停止屏幕录制 |\n| `launchApp()` | 启动应用 |\n| `terminateApp()` | 终止应用 |\n| `installApp()` | 安装应用 |\n| `uninstallApp()` | 卸载应用 |\n| `listRunningProcesses()` | 列出运行中的进程 |\n\n资料来源：[src/android.ts:100-350]()\n\n## 设备发现机制\n\n### 设备类型检测\n\nAndroid 模块通过读取系统属性来判断设备类型：\n\n```typescript\nprivate getDeviceType(deviceId: string): string {\n const output = this.adb(deviceId, \"getprop\", \"ro.build.characteristics\");\n if (output.toString().includes(\"emulator\")) {\n return \"emulator\";\n }\n return \"device\";\n}\n```\n\n支持的设备类型：\n- **emulator**: Android 模拟器\n- **device**: Android 真机\n\n### 系统信息获取\n\n| 属性 | 获取方式 | 说明 |\n|------|----------|------|\n| `version` | `getprop ro.build.version.release` | Android 系统版本 |\n| `name` | `getprop ro.product.model` | 设备型号名称 |\n\n资料来源：[src/android.ts:200-250]()\n\n## UI 元素检测\n\n### 界面层次结构获取\n\nAndroid 使用 `uiautomator dump` 命令获取当前界面的 UI 层次结构（Accessibility Tree）：\n\n```typescript\npublic async listElementsOnScreen(): Promise {\n const output = this.uiautomatorDump();\n const parsed = this.parseUIAutomatorXML(output);\n return parsed;\n}\n```\n\n**XML 解析流程**\n\n```mermaid\ngraph LR\n A[Raw XML Output] --> B[fast-xml-parser]\n B --> C[解析后对象]\n C --> D[提取 node 属性]\n D --> E[构建元素数组]\n E --> F[ScreenElements]\n```\n\n### 元素属性提取\n\n解析后的 UI 元素包含以下关键属性：\n\n| 属性 | XML 路径 | 说明 |\n|------|----------|------|\n| `text` | `@text` | 元素文本内容 |\n| `resourceId` | `@resource-id` | 资源 ID |\n| `className` | `@class` | 类名 |\n| `bounds` | `@bounds` | 坐标边界 |\n| `contentDesc` | `@content-desc` | 内容描述 |\n| `clickable` | `@clickable` | 是否可点击 |\n| `enabled` | `@enabled` | 是否启用 |\n\n**元素选择器优先级**\n\n系统使用以下属性按优先级查找元素：\n\n1. `content-desc` (Accessibility Hint)\n2. `text` (显示文本)\n3. `resource-id` (资源 ID)\n4. `class-name` + `text` 组合\n\n资料来源：[src/android.ts:250-350]()\n\n### 坐标计算\n\n元素的点击坐标基于 `bounds` 属性计算：\n\n```typescript\n// bounds 格式: [x1,y1][x2,y2]\nconst match = bounds.match(/\\[(\\d+),(\\d+)\\]\\[(\\d+),(\\d+)\\]/);\nif (match) {\n const x = Math.floor((parseInt(match[1]) + parseInt(match[3])) / 2);\n const y = Math.floor((parseInt(match[2]) + parseInt(match[4])) / 2);\n // 返回中心点坐标\n}\n```\n\n资料来源：[src/android.ts:300-330]()\n\n## 屏幕交互\n\n### 点击操作\n\n| 方法 | 命令 | 参数 |\n|------|------|------|\n| `click(x, y)` | `input tap` | x, y 坐标 |\n| `doubleTap(x, y)` | `input swipe` + 时间控制 | x, y 坐标 |\n| `longPress(x, y)` | `input swipe` + 长间隔 | x, y 坐标, 时长 |\n\n**双击实现原理**\n\n```typescript\npublic async doubleTap(x: number, y: number): Promise {\n const duration = 50; // 50ms 内完成两次点击\n this.adb(deviceId, \"shell\", \"input\", \"swipe\", \n `${x} ${y} ${x} ${y} ${duration}`);\n}\n```\n\n### 滑动操作\n\n滑动方向基于屏幕尺寸百分比计算起始和终止坐标：\n\n```typescript\npublic async swipe(direction: SwipeDirection): Promise {\n const screenSize = await this.getScreenSize();\n const centerX = screenSize.width >> 1; // 屏幕宽度一半\n\n switch (direction) {\n case \"up\":\n // 从底部 80% 位置滑到顶部 20% 位置\n y0 = Math.floor(screenSize.height * 0.80);\n y1 = Math.floor(screenSize.height * 0.20);\n break;\n case \"down\":\n // 从顶部 20% 位置滑到底部 80% 位置\n y0 = Math.floor(screenSize.height * 0.20);\n y1 = Math.floor(screenSize.height * 0.80);\n break;\n // left/right 方向类似\n }\n \n this.adb(deviceId, \"shell\", \"input\", \"swipe\", \n `${x0} ${y0} ${x1} ${y1} ${duration}`);\n}\n```\n\n**滑动参数表**\n\n| 方向 | 起始位置 | 终止位置 | 默认时长 |\n|------|----------|----------|----------|\n| up | y = 80% 屏幕高度 | y = 20% 屏幕高度 | 300ms |\n| down | y = 20% 屏幕高度 | y = 80% 屏幕高度 | 300ms |\n| left | x = 80% 屏幕宽度 | x = 20% 屏幕宽度 | 300ms |\n| right | x = 20% 屏幕宽度 | x = 80% 屏幕宽度 | 300ms |\n\n资料来源：[src/android.ts:350-420]()\n\n### 物理按钮\n\n支持的物理按钮：\n\n| 按钮名称 | ADB 命令 |\n|----------|----------|\n| HOME | `input keyevent KEYCODE_HOME` |\n| BACK | `input keyevent KEYCODE_BACK` |\n| ENTER | `input keyevent KEYCODE_ENTER` |\n| VOLUME_UP | `input keyevent KEYCODE_VOLUME_UP` |\n| VOLUME_DOWN | `input keyevent KEYCODE_VOLUME_DOWN` |\n| POWER | `input keyevent KEYCODE_POWER` |\n\n资料来源：[src/android.ts:420-480]()\n\n## 应用管理\n\n### 应用安装与卸载\n\n**安装流程**\n\n```typescript\npublic async installApp(filePath: string): Promise {\n this.adb(deviceId, \"install\", \"-r\", filePath);\n}\n```\n\n- `-r` 标志表示覆盖安装（允许降级）\n- 支持的文件格式：`.apk`\n\n**卸载流程**\n\n```typescript\npublic async uninstallApp(packageName: string): Promise {\n this.adb(deviceId, \"uninstall\", packageName);\n}\n```\n\n### 应用启动\n\n启动应用使用 `monkey` 命令触发 LAUNCHER Intent：\n\n```typescript\npublic async launchApp(packageName: string, locale?: string): Promise {\n validatePackageName(packageName);\n\n if (locale) {\n validateLocale(locale);\n try {\n // Android 13+ 支持设置应用语言\n this.silentAdb(\"shell\", \"cmd\", \"locale\", \"set-app-locales\", \n packageName, \"--locales\", locale);\n } catch (error) {\n // 静默忽略旧版本 Android 的语言设置失败\n }\n }\n\n this.adb(\"shell\", \"monkey\", \"-p\", packageName, \n \"-c\", \"android.intent.category.LAUNCHER\", \"1\");\n}\n```\n\n**包名验证规则**\n\n```typescript\nfunction validatePackageName(packageName: string): void {\n // 包名必须至少包含一个点\n // 例如: com.example.app\n if (!packageName.includes(\".\")) {\n throw new Error(\"Invalid package name format\");\n }\n}\n```\n\n资料来源：[src/android.ts:100-180]()\n\n### 运行进程查询\n\n```typescript\npublic async listRunningProcesses(): Promise {\n return this.adb(\"shell\", \"ps\", \"-e\")\n .toString()\n .split(\"\\n\")\n .map(line => line.trim())\n .filter(line => line.startsWith(\"u\")) // 非系统进程\n .map(line => line.split(/\\s+/)[8]); // 获取进程名\n}\n```\n\n## 屏幕截图与录制\n\n### 截图\n\n截图功能使用 `screencap` 命令：\n\n```typescript\npublic async takeScreenshot(): Promise {\n const output = this.adb(deviceId, \"exec-out\", \"screencap\", \"-p\");\n return output;\n}\n```\n\n- 使用 `exec-out` 而非 `shell` 避免 CR/LF 换行符问题\n- 返回 PNG 格式的二进制数据\n\n**Windows 兼容性修复**\n\n版本 0.0.15 修复了 Windows 上的换行符问题：\n\n> Android: Fixed broken Android screenshots on Windows because of crlf ([#53](https://github.com/mobile-next/mobile-mcp/pull/53))\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n### 屏幕录制\n\nAndroid 10+ 支持原生屏幕录制功能：\n\n```typescript\npublic async startScreenRecording(\n filePath: string, \n options?: ScreenRecordingOptions\n): Promise {\n const { width, height, bitRate, timeLimit } = options || {};\n \n const args = [\n \"shell\", \"screenrecord\",\n \"--output-format\", \"h264\",\n \"--time-limit\", String(timeLimit || 180),\n filePath\n ];\n \n if (width && height) {\n args.push(\"--size\", `${width}x${height}`);\n }\n \n this.adb(deviceId, ...args);\n}\n```\n\n**录制参数表**\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| timeLimit | 180秒 | 最长录制时间 |\n| width | 设备宽度 | 视频宽度 |\n| height | 设备高度 | 视频高度 |\n| bitRate | 系统默认 | 视频比特率 |\n\n版本 0.0.46 新增了对 Android 模拟器和真机的屏幕录制支持。\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## ADB 命令封装\n\n### 核心执行方法\n\n```typescript\nprivate adb(...args: string[]): Buffer {\n return execFileSync(getAdbPath(), args);\n}\n\nprivate silentAdb(...args: string[]): void {\n try {\n execFileSync(getAdbPath(), args);\n } catch {\n // 静默忽略错误\n }\n}\n```\n\n### ADB 路径解析\n\nADB 路径通过环境变量 `ANDROID_HOME` 配置：\n\n```typescript\nimport { execFileSync } from \"child_process\";\nimport { join } from \"path\";\n\nfunction getAdbPath(): string {\n const androidHome = process.env.ANDROID_HOME;\n if (androidHome) {\n return join(androidHome, \"platform-tools\", \"adb\");\n }\n return \"adb\"; // 使用系统 PATH 中的 adb\n}\n```\n\n版本 0.0.12 引入了对 `ANDROID_HOME` 路径下 adb 的支持。\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## 与服务端集成\n\n### 设备类型检测\n\n在 `server.ts` 中，服务端通过 `AndroidDeviceManager` 判断设备类型：\n\n```typescript\n// src/server.ts 中的设备检测逻辑\nconst androidManager = new AndroidDeviceManager();\nconst androidDevices = androidManager.getConnectedDevices();\nconst androidDevice = androidDevices.find(d => d.deviceId === deviceId);\n\nif (androidDevice) {\n return new AndroidRobot(deviceId);\n}\n```\n\n### 设备不可用错误处理\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(\n `mobilecli is not available or not working properly. ` +\n `Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki`\n );\n }\n};\n```\n\n资料来源：[src/server.ts:30-60]()\n\n## 依赖项\n\n### 生产依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| fast-xml-parser | 5.5.7 | 解析 uiautomator XML 输出 |\n| zod | ^4.1.13 | 参数验证和类型定义 |\n\n### 可选依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| mobilecli | 0.3.70 | 辅助 CLI 工具 |\n\n### 系统要求\n\n- Node.js >= 18\n- Android SDK (含 platform-tools)\n- 已连接的 Android 设备或模拟器\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## 版本历史\n\n| 版本 | 发布日期 | 主要变更 |\n|------|----------|----------|\n| 0.0.46 | 2026-03-03 | 新增屏幕录制支持 |\n| 0.0.45 | 2026-03-02 | 修复 shell 转义问题 |\n| 0.0.32 | 2025-10-08 | 新增双击支持，减少 stdout 污染 |\n| 0.0.31 | 2025-10-07 | 修复 libc 兼容性问题 |\n| 0.0.30 | 2025-10-06 | 支持应用语言设置 |\n| 0.0.23 | 2025-07-31 | 修复折叠屏设备截图问题 |\n| 0.0.15 | 2025-05-04 | 修复 Windows 截图 CRLF 问题 |\n| 0.0.14 | 2025-05-02 | 优化 UI 元素检测，尝试多次 uiautomator dump |\n| 0.0.13 | 2025-04-20 | 使用 accessibility hints 和 class names 查找元素 |\n| 0.0.12 | 2025-04-12 | 支持 ANDROID_HOME 环境变量 |\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## 常见问题排查\n\n### 设备未被发现\n\n1. 确认设备已通过 USB 连接且授权调试\n2. 运行 `adb devices` 确认设备状态为 `device`\n3. 检查 `ANDROID_HOME` 环境变量是否正确设置\n\n### 截图失败\n\n1. 确认设备屏幕未锁定\n2. 检查设备是否支持 `screencap` 命令（Android 4.0+）\n3. 验证磁盘空间充足\n\n### 元素定位不准确\n\n1. 使用 `listElementsOnScreen` 工具获取最新界面状态\n2. 优先使用 `content-desc` 或 `text` 属性定位\n3. 考虑使用坐标点击作为备选方案\n\n### uiautomator dump 超时\n\n版本 0.0.14 实现了多次重试机制，自动重试 UI 层次结构获取。\n\n## 总结\n\nAndroid 实现为 mobile-mcp 提供了完整的 Android 设备自动化能力。通过 ADB 协议与设备通信，该模块实现了设备发现、UI 元素检测、屏幕交互、应用管理等核心功能。统一的接口设计使得 Android 和 iOS 平台可以无缝切换，为跨平台移动端自动化提供了坚实基础。\n\n---\n\n\n\n## 故障排除\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [安全配置](#security)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/ios.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n- [src/iphone-simulator.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# 故障排除\n\n本文档提供 Mobile MCP 常见问题的诊断和解决方案。\n\n## 前提条件检查\n\n### 必需组件\n\n确保系统已安装所有必需组件：\n\n| 组件 | 说明 | 最低版本 |\n|------|------|----------|\n| Node.js | 运行环境 | >=18 |\n| mobilecli | 命令行工具 | 0.3.70 |\n| Xcode (iOS) | iOS 开发环境 | - |\n| Xcode Command Line Tools | Xcode 命令行工具 | - |\n| go-ios | iOS 设备通信 | - |\n| Android SDK (Android) | Android 开发环境 | - |\n| ADB | Android 调试桥接器 | - |\n\n### mobilecli 可用性检查\n\nMobile MCP 启动时会自动检查 mobilecli 是否可用：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly. Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki for installation instructions`);\n }\n};\n```\n\n**资料来源**：[src/server.ts]()\n\n如果遇到 mobilecli 相关错误，请参考 [官方 Wiki 安装指南](https://github.com/mobile-next/mobile-mcp/wiki)。\n\n## iOS 设备问题排查\n\n### 架构概览\n\n```mermaid\ngraph TD\n A[Mobile MCP] --> B[iOS Manager]\n B --> C{iOS Tunnel Required?}\n C -->|Yes| D[iOS Tunnel Status]\n C -->|No| E[WebDriverAgent Check]\n D --> F{Tunnel Running?}\n F -->|Yes| E\n F -->|No| G[Error: iOS tunnel not running]\n E --> H{WDA Forward Running?}\n H -->|Yes| I[Create WebDriverAgent]\n H -->|No| J[Error: Port forwarding not running]\n I --> K[Return WebDriverAgent]\n```\n\n### iOS Tunnel 未运行\n\n当检测到 iOS Tunnel 未运行时，会抛出以下错误：\n\n```\niOS tunnel is not running, please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**解决方案**：\n\n1. 确保已启动 iOS Tunnel 服务\n2. 检查 Xcode Command Line Tools 已正确安装\n3. 验证设备已通过 USB 连接\n4. 参考 [官方 Wiki iOS 隧道配置指南](https://github.com/mobile-next/mobile-mcp/wiki/)\n\n### WebDriverAgent 问题\n\n#### 端口转发未运行\n\n```\nPort forwarding to WebDriverAgent is not running (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**排查步骤**：\n\n1. 确认 iOS Tunnel 已正常运行\n2. 检查端口 `8100` 是否被占用\n3. 重启 WebDriverAgent 服务\n\n#### WebDriverAgent 服务未运行\n\n```\nWebDriverAgent is not running on device (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\n```\n\n**资料来源**：[src/ios.ts]()\n\n**解决方案**：\n\n1. 在 iOS 设备上手动启动 WebDriverAgent\n2. 确保设备已通过 Xcode 授权用于开发\n3. 检查设备是否信任计算机\n\n### iOS Tunnel 健康检查\n\n系统通过以下方式检查 iOS Tunnel 状态：\n\n| 检查项 | 方法 | 失败时的错误信息 |\n|--------|------|------------------|\n| Tunnel 端口监听 | `isListeningOnPort(IOS_TUNNEL_PORT)` | iOS tunnel is not running |\n| WDA 端口转发 | `isListeningOnPort(WDA_PORT)` | Port forwarding to WebDriverAgent is not running |\n| WDA 服务状态 | `wda.isRunning()` | WebDriverAgent is not running on device |\n\n**资料来源**：[src/ios.ts]()\n\n## Android 设备问题排查\n\n### 设备连接检查\n\n```mermaid\ngraph LR\n A[Android Device] --> B[ADB Daemon]\n B --> C{Device Connected?}\n C -->|Yes| D[AndroidRobot Ready]\n C -->|No| E[Error: Device not found]\n D --> F[Execute Commands]\n```\n\n### ADB 设备未找到\n\n**排查步骤**：\n\n1. 确认设备已通过 USB 连接并启用 USB 调试\n2. 运行 `adb devices` 检查设备列表\n3. 如果设备未列出，尝试：\n - 重启 ADB 服务：`adb kill-server && adb start-server`\n - 检查设备授权状态\n - 更换 USB 数据线\n\n### Android 命令执行\n\nAndroid 设备通过 `adb shell` 执行命令：\n\n```typescript\npublic runCommand(args: string[]): string {\n return execFileSync(\"adb\", [\"-s\", this.deviceId, \"shell\", ...args], {\n encoding: \"utf-8\",\n }).toString();\n}\n```\n\n**资料来源**：[src/mobile-device.ts]()\n\n**常见错误处理**：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| 设备离线 | USB 连接不稳定 | 重新连接或更换数据线 |\n| 未授权 | 设备未授权调试 | 在设备上点击\"允许调试\" |\n| 无响应 | 设备系统无响应 | 重启设备 |\n\n## iOS 模拟器问题排查\n\n### 应用安装失败\n\n#### ZIP 文件处理错误\n\n```mermaid\ngraph TD\n A[Install App Request] --> B{File Extension?}\n B -->|.zip| C[Extract ZIP File]\n B -->|.app| D[Direct Install]\n C --> E{Path Validation}\n E -->|Valid| F[Find .app Bundle]\n E -->|Invalid| G[Error: Zip Slip]\n F --> H{App Bundle Found?}\n H -->|Yes| I[Install .app]\n H -->|No| J[Error: No .app bundle found]\n```\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n#### 常见安装错误\n\n| 错误信息 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| `No .app bundle found in the .zip file` | ZIP 内不含 .app 包 | 确保 ZIP 包含正确的 iOS 应用包 |\n| `Failed to unzip file` | ZIP 文件损坏或密码保护 | 验证 ZIP 文件完整性 |\n| Zip Slip 漏洞检测失败 | ZIP 包含路径遍历攻击 | 使用安全的 ZIP 文件 |\n| `simctl install failed` | 模拟器未运行或不支持 | 启动目标模拟器 |\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n### ZIP 安全验证\n\n系统会验证 ZIP 文件路径，防止 Zip Slip 攻击：\n\n```typescript\nprivate validateZipPaths(path: string): void {\n // 确保 ZIP 文件不包含恶意路径\n trace(`Detected .zip file, validating contents`);\n}\n```\n\n**资料来源**：[src/iphone-simulator.ts]()\n\n## 通用设备管理问题\n\n### 设备识别流程\n\n```mermaid\ngraph TD\n A[Get Robot Request] --> B[Ensure mobilecli Available]\n B --> C{Check iOS Devices}\n C -->|Found| D[Create IosRobot]\n C -->|Not Found| E{Check Android Devices}\n E -->|Found| F[Create AndroidRobot]\n E -->|Not Found| G{Check iOS Simulators}\n G -->|Found| H[Create IosRobot]\n G -->|Not Found| I[Return Error]\n```\n\n**资料来源**：[src/server.ts]()\n\n### 设备类型检测优先级\n\n1. **iOS 物理设备** - 通过 IosManager.listDevices() 检测\n2. **Android 物理设备** - 通过 AndroidDeviceManager.getConnectedDevices() 检测\n3. **iOS 模拟器** - 通过 mobilecli.getDevices() 检测\n\n**资料来源**：[src/server.ts]()\n\n## 录制功能问题\n\n### 录制超时处理\n\n录制功能设置了 5 分钟超时限制：\n\n```typescript\nconst timeout = setTimeout(() => {\n child.kill(\"SIGKILL\");\n resolve();\n}, 5 * 60 * 1000);\n```\n\n**资料来源**：[src/server.ts]()\n\n**常见问题**：\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 录制被强制终止 | 超过 5 分钟限制 | 缩短录制时长 |\n| 输出文件未找到 | 录制异常终止 | 检查设备存储空间 |\n| 文件大小为 0 | 录制未成功启动 | 检查设备屏幕状态 |\n\n### 录制输出检查\n\n录制完成后，系统会验证输出文件：\n\n```typescript\nif (!fs.existsSync(outputPath)) {\n return `Recording stopped after ~${durationSeconds}s but the output file was not found at: ${outputPath}`;\n}\n\nconst stats = fs.statSync(outputPath);\nconst fileSizeMB = (stats.size / (1024 * 1024)).toFixed(2);\n```\n\n**资料来源**：[src/server.ts]()\n\n## 崩溃报告问题\n\n### 获取崩溃列表\n\n使用 `mobile_list_crashes` 工具获取设备上的崩溃报告：\n\n```typescript\ntool(\n \"mobile_list_crashes\",\n \"List Crash Reports\",\n \"List crash reports available on the device\",\n {\n device: z.string().describe(\"The device identifier to use...\"),\n },\n { readOnlyHint: true },\n async ({ device }) => {\n ensureMobilecliAvailable();\n const response = mobilecli.crashesList(device);\n return JSON.stringify(response.data);\n }\n);\n```\n\n**资料来源**：[src/server.ts]()\n\n**排查步骤**：\n\n1. 确认 mobilecli 可用\n2. 检查设备是否有足够的存储空间\n3. 验证崩溃报告未被清理\n\n## 环境变量配置\n\n### SSE 服务器认证\n\n使用 `MOBILEMCP_AUTH` 环境变量配置 Bearer Token 认证：\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n所有请求必须包含 `Authorization: Bearer my-secret-token` 头。\n\n## 日志和调试\n\n### 启用调试日志\n\n在运行时设置日志级别以获取详细输出：\n\n参考 [src/logger.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/logger.ts) 获取日志配置详情。\n\n### 常见错误类型\n\n| 错误类型 | 来源 | 说明 |\n|----------|------|------|\n| `ActionableError` | Mobile MCP | 包含可操作建议的错误 |\n| 系统错误 | Node.js/adb | 底层系统级错误 |\n| 网络错误 | 端口转发/Tunnel | 连接问题 |\n\n## 获取帮助\n\n如果以上方案无法解决您的问题：\n\n1. 访问 [官方 Wiki 文档](https://github.com/mobile-next/mobile-mcp/wiki)\n2. 加入 [Slack 社区](https://mobilenexthq.com/join-slack)\n3. 查看 [已知问题](https://github.com/mobile-next/mobile-mcp/issues)\n4. 查看 [路线图](https://github.com/orgs/mobile-next/projects/3) 了解即将修复的功能\n\n---\n\n\n\n## 安全配置\n\n### 相关页面\n\n相关主题：[安装与配置](#installation), [故障排除](#troubleshooting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# 安全配置\n\nMobile MCP 提供了多层安全机制来保护服务器通信和文件系统操作。本文档详细介绍各项安全配置的使用方法和最佳实践。\n\n## 认证机制\n\n### Bearer Token 认证\n\n当 Mobile MCP 以 SSE 服务器模式运行时，可通过设置 `MOBILEMCP_AUTH` 环境变量启用 Bearer Token 认证。\n\n#### 配置方式\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n#### 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as Mobile MCP Server\n \n Client->>Server: 请求 /mcp 端点\n Server->>Server: 检查 Authorization Header\n alt 未设置 MOBILEMCP_AUTH\n Server->>Server: 允许无认证访问\n else 设置了 MOBILEMCP_AUTH\n alt 缺少 Authorization Header\n Server-->>Client: 401 Unauthorized\n else Token 不匹配\n Server-->>Client: 401 Unauthorized\n else Token 正确\n Server-->>Client: 200 OK + MCP 响应\n end\n end\n```\n\n#### 请求格式要求\n\n所有请求必须包含以下 HTTP Header：\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n| 配置项 | 环境变量 | 说明 | 必需 |\n|--------|----------|------|------|\n| 认证令牌 | `MOBILEMCP_AUTH` | 设置 Bearer Token 值 | SSE 模式下必需 |\n\n### 认证错误处理\n\n当认证失败时，服务器返回标准的 HTTP 401 状态码。客户端需要确保在配置中正确设置认证令牌，避免连接失败。\n\n## 文件系统安全\n\n### 路径遍历防护\n\nMobile MCP 在保存截图和录制视频功能中实现了路径遍历防护机制，防止恶意请求访问预期目录之外的文件。\n\n#### 安全修复历史\n\n| 版本 | 日期 | 修复内容 | PR |\n|------|------|----------|-----|\n| 0.0.49 | 2026-03-24 | 修复截图和视频保存中的路径遍历漏洞 | [#296](https://github.com/mobile-next/mobile-mcp/pull/296) |\n\n#### 受保护的文件操作\n\n```mermaid\ngraph TD\n A[文件保存请求] --> B{验证路径}\n B -->|包含 ../ 或绝对路径 | C[拒绝访问]\n B -->|合法相对路径 | D[执行保存操作]\n C --> E[返回安全错误]\n D --> F[保存到 lib/screenshots 或 lib/videos 目录]\n```\n\n## 依赖安全\n\n### 安全更新机制\n\nMobile MCP 定期更新依赖包以修复已知安全漏洞。\n\n#### 安全更新历史\n\n| 版本 | 日期 | 更新内容 | PR |\n|------|------|----------|-----|\n| 0.0.48 | 2026-03-20 | fast-xml-parser 安全更新 | [#292](https://github.com/mobile-next/mobile-mcp/pull/292) |\n| 0.0.47 | 2026-03-09 | 更新依赖包以提升安全性 | [#285](https://github.com/mobile-next/mobile-mcp/pull/285) |\n\n#### 关键依赖安全状态\n\n| 依赖包 | 版本 | 用途 | 安全状态 |\n|--------|------|------|----------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP 协议实现 | 已审核 |\n| fast-xml-parser | 5.5.7 | XML 解析 | 已更新 |\n| express | 5.1.0 | SSE 服务器框架 | 已审核 |\n| zod | 4.1.13 | 参数验证 | 已审核 |\n\n## 运行时安全检查\n\n### mobilecli 可用性验证\n\n服务器启动时执行 mobilecli 可用性检查，确保底层工具正常工作：\n\n```typescript\nconst ensureMobilecliAvailable = (): void => {\n try {\n const version = mobilecli.getVersion();\n if (version.startsWith(\"failed\")) {\n throw new Error(\"mobilecli version check failed\");\n }\n } catch (error: any) {\n throw new ActionableError(`mobilecli is not available or not working properly...`);\n }\n};\n```\n\n如果 mobilecli 不可用或工作异常，服务器将抛出可操作的错误提示，指导用户访问文档进行排查。\n\n### 设备类型验证\n\n`getRobotFromDevice` 函数通过设备 ID 确定设备类型，并创建对应的 Robot 实例：\n\n```mermaid\ngraph TD\n A[接收 deviceId] --> B{检查 iOS 设备}\n B -->|找到 | C[返回 IosRobot]\n B -->|未找到 | D{检查 Android 设备}\n D -->|找到 | E[返回 AndroidRobot]\n D -->|未找到 | F{检查 iOS 模拟器}\n F -->|找到 | G[返回 IosRobot]\n F -->|未找到 | H[抛出 ActionableError]\n```\n\n## 安全配置最佳实践\n\n### 开发环境\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n\n### 生产环境（启用认证）\n\n```bash\n# 设置强认证令牌\nexport MOBILEMCP_AUTH=\"$(openssl rand -hex 32)\"\n\n# 启动 SSE 服务器\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\n### 配置参数表\n\n| 参数 | 命令行 | 环境变量 | 说明 | 默认值 |\n|------|--------|----------|------|--------|\n| 监听地址 | `--listen ` | - | SSE 服务器监听端口 | 无（stdio 模式） |\n| 绑定接口 | `--listen ` | - | 指定绑定地址 | localhost |\n| 认证令牌 | - | `MOBILEMCP_AUTH` | Bearer Token | 无 |\n\n## 报告安全漏洞\n\n如发现安全漏洞，请通过以下方式报告：\n\n- GitHub Issues: [https://github.com/mobile-next/mobile-mcp/issues](https://github.com/mobile-next/mobile-mcp/issues)\n- 详细安全策略请参阅 [SECURITY.md](https://github.com/mobile-next/mobile-mcp/blob/main/SECURITY.md)\n\n## 安全版本对照表\n\n| 功能 | 支持版本 | 说明 |\n|------|----------|------|\n| Bearer Token 认证 | 全部版本 | SSE 模式下通过 MOBILEMCP_AUTH 配置 |\n| 路径遍历防护 | ≥ 0.0.49 | 保护截图和视频文件操作 |\n| fast-xml-parser 更新 | ≥ 0.0.48 | XML 解析安全修复 |\n| mobilecli 检查 | 全部版本 | 启动时验证工具可用性 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mobile-next/mobile-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback。\n\n## 1. 配置坑 · 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：mobile_type_keys not support Chinese words\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Default-on telemetry creates security and compliance risk for enterprise users\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：mobile fleet documentation link broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 来源证据：Version 0.0.49\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Version 0.0.54\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：Version 0.0.45\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.45\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5939588c2f74a4f8e7ae874c9fee9f2 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：Version 0.0.47\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.47\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6f22eab42c4140bf9692e3ff9f80dc62 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Version 0.0.48\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.48\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e414a95529d4f27bb06648558502daa | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Version 0.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.51\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eca0ad1c1f574a52897db27953196b98 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：Version 0.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c0b172807554ff4b1969c4fff8abf4b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Version 0.0.53\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.53\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0fb42201cf24850bcd4fa91470e2042 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：mobile-next/mobile-mcp\n\n摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback。\n\n## 1. 配置坑 · 来源证据：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(iOS): add Unix Domain Socket support for usbmuxd (/var/run/usbmuxd) with TCP fallback\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dbf2449bab944bc99876270f1ec05c62 | https://github.com/mobile-next/mobile-mcp/issues/322 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：mobile_type_keys not support Chinese words\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：mobile_type_keys not support Chinese words\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2dc233de12994981b510eaee492c2389 | https://github.com/mobile-next/mobile-mcp/issues/238 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Default-on telemetry creates security and compliance risk for enterprise users\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Default-on telemetry creates security and compliance risk for enterprise users\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5f969914c2b845edae80052061f7b4c3 | https://github.com/mobile-next/mobile-mcp/issues/330 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：iOS physical-device support blocked on macOS 26 (Tahoe) — go-ios can't read /var/db/lockdown/RemotePairing/\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a003bada38d4c7b85ace117a1057fba | https://github.com/mobile-next/mobile-mcp/issues/323 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：start/stop_screen_recording produces corrupt files on Android and silently fails on iOS physical devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0cfa3373dd3042f885f3bfc06594d58b | https://github.com/mobile-next/mobile-mcp/issues/321 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：mobile fleet documentation link broken\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：mobile fleet documentation link broken\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b92402a79ce24b41b5f9ca2351e56e81 | https://github.com/mobile-next/mobile-mcp/issues/328 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 来源证据：Version 0.0.49\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.49\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_885b7e8395a34cc8aaa7ce492d0b5d31 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.49 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：Version 0.0.54\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Version 0.0.54\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02193405127b48d2a7d25148f61b2e9b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.54 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：Version 0.0.45\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.45\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5939588c2f74a4f8e7ae874c9fee9f2 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.45 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：Version 0.0.47\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.47\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6f22eab42c4140bf9692e3ff9f80dc62 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.47 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Version 0.0.48\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.48\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e414a95529d4f27bb06648558502daa | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.48 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Version 0.0.51\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.51\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eca0ad1c1f574a52897db27953196b98 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：Version 0.0.52\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.52\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c0b172807554ff4b1969c4fff8abf4b | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.52 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Version 0.0.53\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.53\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0fb42201cf24850bcd4fa91470e2042 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.53 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mobile-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mobile-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. client-configuration：客户端配置指南。围绕“客户端配置指南”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. device-management：设备管理。围绕“设备管理”模拟一次用户任务，不展示安装或运行结果。\n5. mcp-tools：MCP 工具详解。围绕“MCP 工具详解”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. client-configuration\n输入：用户提供的“客户端配置指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. device-management\n输入：用户提供的“设备管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. mcp-tools\n输入：用户提供的“MCP 工具详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / client-configuration：Step 2 必须围绕“客户端配置指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / device-management：Step 4 必须围绕“设备管理”形成一个小中间产物，并等待用户确认。\n- Step 5 / mcp-tools：Step 5 必须围绕“MCP 工具详解”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/mobile-next/mobile-mcp\n- https://github.com/mobile-next/mobile-mcp#readme\n- README.md\n- package.json\n- src/server.ts\n- src/robot.ts\n- src/mobilecli.ts\n- src/mobile-device.ts\n- src/android.ts\n- src/ios.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mobile-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：mobile-next/mobile-mcp\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n来源：https://github.com/mobile-next/mobile-mcp#readme\n\n## 来源\n\n- repo: https://github.com/mobile-next/mobile-mcp\n- docs: https://github.com/mobile-next/mobile-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_3293fbe150c74840ad45c6c4749acf6a"
}