{
"canonical_name": "mobile-next/mobile-mcp",
"compilation_id": "pack_c8bd9fc449a24505aae687670f167d3e",
"created_at": "2026-05-19T05:03:10.819965+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": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-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": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"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": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"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_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": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Version 0.0.51",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_eca0ad1c1f574a52897db27953196b98 | https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.51 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Version 0.0.51",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 20 个潜在踩坑项，其中 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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for mobile-next/mobile-mcp.\n\nProject:\n- Name: mobile-mcp\n- Repository: https://github.com/mobile-next/mobile-mcp\n- Summary: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. prerequisites: Prerequisites. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-tools-reference: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n5. screen-interaction: Screen Interaction and Input. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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/mobile-device.ts\n- src/mobilecli.ts\n- src/png.ts\n- src/image-utils.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。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_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.55（https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.55）；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）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"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_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.55",
"url": "https://github.com/mobile-next/mobile-mcp/releases/tag/0.0.55"
},
{
"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"
}
],
"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": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/mobile-next/mobile-mcp 项目说明书\n\n生成时间：2026-05-15 10:52:12 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [Installation and Configuration](#installation)\n- [Prerequisites](#prerequisites)\n- [System Architecture](#system-architecture)\n- [Device Abstraction Layer](#device-abstraction)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Device Management](#device-management)\n- [App Management](#app-management)\n- [Screen Interaction and Input](#screen-interaction)\n- [iOS Implementation](#ios-implementation)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[Installation and Configuration](#installation), [System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)\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/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n \n\n# Overview\n\nMobile MCP (Model Context Protocol) is an open-source project that enables AI assistants to interact with mobile devices through the MCP protocol. It provides a bridge between AI agents and mobile device automation, supporting both iOS and Android platforms including simulators, emulators, and physical devices.\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Project Purpose\n\nThe project serves as an MCP server implementation that allows AI assistants to:\n\n- Automate native iOS and Android applications for testing or data entry scenarios\n- Execute scripted flows and form interactions without manual device control\n- Automate multi-step user journeys driven by large language models\n- Enable general-purpose mobile application interaction for agent-based frameworks\n- Facilitate agent-to-agent communication for mobile automation use cases and data extraction\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Core Architecture\n\nMobile MCP follows a modular architecture that separates platform-specific implementations from the core server logic.\n\n```mermaid\ngraph TD\n subgraph \"MCP Clients\"\n C1[Claude Desktop]\n C2[Cursor]\n C3[VS Code]\n C4[Codex]\n C5[Other MCP Clients]\n end\n \n subgraph \"Mobile MCP Server\"\n Server[Core Server
src/server.ts]\n Tools[MCP Tools Layer]\n Robot[Robot Interface
src/robot.ts]\n end\n \n subgraph \"Platform Implementations\"\n iOS_WDA[WebDriver Agent
src/webdriver-agent.ts]\n iOS_Sim[iOS Simulator
src/iphone-simulator.ts]\n Android[Android Device Manager]\n end\n \n subgraph \"Target Devices\"\n iOS_Real[iOS Physical Device]\n Android_Real[Android Physical Device]\n Simulators[iOS Simulators]\n Emulators[Android Emulators]\n end\n \n C1 & C2 & C3 & C4 & C5 --> Server\n Server --> Tools\n Tools --> Robot\n Robot --> iOS_WDA & iOS_Sim & Android\n iOS_WDA --> iOS_Real & Simulators\n iOS_Sim --> Simulators\n Android --> Android_Real & Emulators\n```\n\n### Key Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Core Server | `src/server.ts` | MCP protocol implementation, device management, tool routing |\n| Robot Interface | `src/robot.ts` | Abstract interface defining device interaction methods |\n| WebDriver Agent | `src/webdriver-agent.ts` | iOS real device and simulator automation via WebDriverAgent |\n| iOS Simulator | `src/iphone-simulator.ts` | Direct iOS simulator control using simctl |\n| Android Manager | (platform-specific) | Android device automation |\n\n资料来源：[src/server.ts:1-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Device Detection Flow\n\nThe server implements a device detection mechanism that identifies the platform type when a device ID is provided.\n\n```mermaid\ngraph TD\n Start[Get Device ID] --> Check_iOS{iOS Device?}\n Check_iOS -->|Yes| Return_iOS[Return IosRobot]\n Check_iOS -->|No| Check_Android{Android Device?}\n Check_Android -->|Yes| Return_Android[Return AndroidRobot]\n Check_Android -->|No| Check_Simulator{iOS Simulator?}\n Check_Simulator -->|Yes| Return_Simulator[Return Simulator Robot]\n Check_Simulator -->|No| Error[Throw Error]\n \n style Return_iOS fill:#90EE90\n style Return_Android fill:#90EE90\n style Return_Simulator fill:#90EE90\n style Error fill:#FFB6C1\n```\n\n资料来源：[src/server.ts:20-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Available Tools\n\nMobile MCP exposes the following tool categories through the MCP protocol:\n\n### Device Management\n\n| Tool | Description |\n|------|-------------|\n| `mobile_list_available_devices` | List all available devices (simulators, emulators, and real devices) |\n| `mobile_get_screen_size` | Get screen dimensions in pixels |\n| `mobile_get_orientation` | Get current screen orientation |\n| `mobile_set_orientation` | Change screen orientation (portrait/landscape) |\n\n### App Management\n\n| Tool | Description |\n|------|-------------|\n| `mobile_list_apps` | List all installed apps on the device |\n| `mobile_launch_app` | Launch an app using package name |\n| `mobile_terminate_app` | Stop and terminate a running app |\n| `mobile_install_app` | Install an app from file (.apk, .ipa, .app, .zip) |\n| `mobile_uninstall_app` | Uninstall an app using bundle ID or package name |\n\n### Screen Interaction\n\n| Tool | Description |\n|------|-------------|\n| `mobile_take_screenshot` | Capture screenshot to understand screen content |\n| `mobile_save_screenshot` | Save screenshot to a file |\n| `mobile_list_elements_on_screen` | List UI elements with coordinates and properties |\n| `mobile_click_on_screen_at_coordinates` | Click at specific x,y coordinates |\n| `mobile_double_tap_on_screen` | Double-tap at specific coordinates |\n| `mobile_long_press_on_screen_at_coordinates` | Long press at specific coordinates |\n| `mobile_swipe_on_screen` | Swipe in any direction (up, down, left, right) |\n\n### Input & Navigation\n\n| Tool | Description |\n|------|-------------|\n| `mobile_type_keys` | Type text into focused elements with optional submit |\n| `mobile_press_button` | Press device buttons (home, back, etc.) |\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Robot Interface\n\nThe `Robot` interface defines the contract for all platform implementations:\n\n```typescript\ninterface Robot {\n // Screen operations\n getScreenshot(): Promise;\n getScreenSize(): Promise;\n getOrientation(): Promise;\n setOrientation(orientation: Orientation): Promise;\n \n // Element operations\n getElementsOnScreen(): Promise;\n \n // Touch operations\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n \n // Text and keys\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n \n // App management\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 // URL handling\n openUrl(url: string): Promise;\n}\n```\n\n资料来源：[src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Platform Support\n\n### iOS Platform\n\niOS automation is handled through two mechanisms:\n\n1. **WebDriverAgent** (`src/webdriver-agent.ts`): Used for real iOS devices and Xcode-managed simulators\n - Communicates via HTTP with WDA session\n - Filters elements by accepted types: `TextField`, `Button`, `Switch`, `Icon`, `SearchField`, `StaticText`, `Image`\n - Uses element visibility and accessibility properties for filtering\n\n2. **iOS Simulator** (`src/iphone-simulator.ts`): Direct simctl control for booted simulators\n - Handles `.app` bundle installation\n - Supports `.zip` file extraction with zip-slip vulnerability protection\n - Uses simctl command-line tool\n\n资料来源：[src/webdriver-agent.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n### Android Platform\n\nAndroid automation uses platform-specific managers to:\n- List connected devices\n- Query UI elements via accessibility tree\n- Execute touch and input operations\n- Manage app lifecycle\n\n## Communication Modes\n\n### STDIO Mode (Default)\n\nThe server communicates over standard input/output:\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\n### SSE Server Mode\n\nFor HTTP-based connections, the server can listen on a specified port:\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nOptional Bearer token authentication can be enabled:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Technology Stack\n\n| Component | Technology | Version |\n|-----------|------------|---------|\n| Runtime | Node.js | >=18 |\n| MCP SDK | @modelcontextprotocol/sdk | 1.26.0 |\n| HTTP Framework | express | 5.1.0 |\n| CLI Framework | commander | 14.0.0 |\n| Validation | zod | 4.1.13 |\n| XML Parsing | fast-xml-parser | 5.5.7 |\n| Native CLI | mobilecli | 0.3.70 (optional) |\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## Key Features\n\n- **Fast and lightweight**: Uses native accessibility trees for most interactions, or screenshot-based coordinates where accessibility labels are not available\n- **LLM-friendly**: No computer vision model required in Accessibility (Snapshot)\n- **Visual Sense**: Evaluates and analyses what's actually rendered on screen\n- **Cross-platform**: Supports iOS, Android, simulators, emulators, and real devices\n- **Standard protocol**: Built on Model Context Protocol for seamless AI assistant integration\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Version History\n\nThe project follows semantic versioning with active development:\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.0.49 | 2026-03-24 | Path traversal fix in save screenshot and record video |\n| 0.0.48 | 2026-03-20 | fast-xml-parser security updates, error handling fixes |\n| 0.0.47 | 2026-03-09 | Zod coerce for number parameter parsing, locale support for iOS |\n| 0.0.42 | 2026-02-03 | mobilecli upgrade, fast-xml-parser security update |\n| 0.0.41 | 2026-01-27 | Android element filtering improvements |\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## Getting Started\n\n### Installation\n\nAdd to your MCP client configuration:\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### Prerequisites\n\n- Node.js >= 18\n- For iOS: Xcode Command Line Tools, WebDriverAgent (for real devices)\n- For Android: Android SDK, ADB configured\n\n### Client Support\n\nMobile MCP is compatible with multiple AI coding assistants:\n\n- Claude Desktop\n- Claude Code\n- Cursor\n- VS Code\n- Codex\n- Copilot\n- Gemini CLI\n- Goose\n- Cline\n- Windsurf\n- Qodo Gen\n- Amp\n- Kiro\n- opencode\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n---\n\n\n\n## Installation and Configuration\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Prerequisites](#prerequisites)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [server.json](https://github.com/mobile-next/mobile-mcp/blob/main/server.json)\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/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n \n\n# Installation and Configuration\n\n## Overview\n\nMobile MCP is a Model Context Protocol (MCP) server that enables mobile automation for iOS and Android devices. The server provides a standardized interface for AI assistants to interact with mobile devices through simulators, emulators, and real hardware.\n\nThis page covers the complete installation process, configuration options, and server deployment modes.\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Specification |\n|-------------|---------------|\n| Node.js | Version 18 or higher |\n| Package Manager | npm, yarn, or pnpm |\n| Mobile CLI Tools | `mobilecli` (auto-installed as optional dependency) |\n| Platform Tools | Xcode Command Line Tools (iOS) / Android SDK (Android) |\n\nThe server requires Node.js 18+ as specified in `package.json`:\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n资料来源：[package.json:12]()\n\n### Required Mobile Tools\n\nMobile MCP depends on `mobilecli` for device communication. The SDK checks for mobilecli availability at server startup:\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资料来源：[src/server.ts:1-20]()\n\n## Installation Methods\n\n### Standard NPM Installation\n\nThe recommended installation method uses npx to run the package directly:\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\nThis command downloads and executes the latest version without requiring local installation.\n\n### Local Installation\n\nFor development or customization, install locally:\n\n```bash\nnpm install @mobilenext/mobile-mcp\n```\n\nThe package provides a binary entry point:\n\n```json\n\"bin\": {\n \"mcp-server-mobile\": \"lib/index.js\"\n}\n```\n资料来源：[package.json:62-65]()\n\n### Building from Source\n\nTo build from source:\n\n```bash\ngit clone https://github.com/mobile-next/mobile-mcp.git\ncd mobile-mcp\nnpm install\nnpm run build\n```\n\nBuild artifacts are output to the `lib/` directory:\n\n```bash\nnpm run build # Compiles TypeScript and sets executable permissions\nnpm run watch # Watch mode for development\n```\n资料来源：[package.json:22-30]()\n\n## Server Configuration\n\n### Standard MCP Configuration\n\nThe following JSON configuration works across most MCP clients:\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Configuration Schema\n\nThe server adheres to the MCP protocol schema:\n\n```json\n{\n \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n \"name\": \"io.github.mobile-next/mobile-mcp\",\n \"description\": \"MCP server for iOS and Android Mobile Development, Automation and Testing\",\n \"version\": \"{{VERSION}}\",\n \"packages\": [\n {\n \"registryType\": \"npm\",\n \"registryBaseUrl\": \"https://registry.npmjs.org\",\n \"identifier\": \"@mobilenext/mobile-mcp\",\n \"transport\": {\n \"type\": \"stdio\"\n }\n }\n ]\n}\n```\n资料来源：[server.json:1-20]()\n\n## Client-Specific Configuration\n\n### Claude Code\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Claude Desktop\n\nFollow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user) and use the standard JSON configuration above.\n\n### Codex\n\n**CLI Installation:**\n```bash\ncodex mcp add mobile-mcp npx \"@mobilenext/mobile-mcp@latest\"\n```\n\n**Manual Configuration** (`~/.codex/config.toml`):\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n资料来源：[README.md:1]()\n\n### Copilot\n\nConfiguration file (`~/.copilot/mcp-config.json`):\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资料来源：[README.md:1]()\n\n### Cursor\n\n**Installation Button:**\nClick the provided deeplink or navigate to `Cursor Settings` → `MCP` → `Add new MCP Server`.\n\n**Manual Configuration:**\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Goose\n\n**UI Installation:**\nUse the extension install button or navigate to `Advanced settings` → `Extensions` → `Add custom extension`.\n\n**Manual Configuration:**\n- Type: `STDIO`\n- Command: `npx -y @mobilenext/mobile-mcp@latest`\n资料来源：[README.md:1]()\n\n### Windsurf\n\nNavigate to Windsurf settings → `MCP servers` → Add new server:\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Amp\n\n**CLI Installation:**\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n**VS Code Extension:**\nAdd via settings.json:\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Cline\n\nAdd the standard JSON configuration to your MCP settings file.\n资料来源：[README.md:1]()\n\n### Kiro\n\nConfiguration file (`~/.kiro/settings/mcp.json`):\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### opencode\n\nConfiguration file (`~/.config/opencode/opencode.json`):\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资料来源：[README.md:1]()\n\n### Qodo Gen\n\nOpen Qodo Gen chat panel → `Connect more tools` → `+ Add new MCP` → Paste the standard configuration.\n资料来源：[README.md:1]()\n\n## SSE Server Mode\n\nBy default, Mobile MCP communicates over stdio. For remote or web-based deployments, enable SSE (Server-Sent Events) mode.\n\n### Starting the SSE Server\n\n**Basic Usage:**\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n**Binding to Specific Interface:**\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\nThis binds the server to all network interfaces on port 3000.\n\n### Client Configuration for SSE\n\nConfigure your MCP client to connect to the SSE endpoint:\n\n```\nhttp://:3000/mcp\n```\n\n### Architecture Diagram\n\n```mermaid\ngraph TD\n A[MCP Client] -->|HTTP/MCP Protocol| B[SSE Server]\n B --> C{Mobile MCP Server}\n C -->|iOS Devices| D[IosRobot]\n C -->|Android Devices| E[AndroidRobot]\n D --> F[mobilecli]\n E --> F\n F --> G[iOS Simulator/Device]\n F --> H[Android Emulator/Device]\n```\n\n## Authorization\n\nWhen running in SSE mode, secure the server with Bearer token authentication.\n\n### Configuration\n\nSet the `MOBILEMCP_AUTH` environment variable:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n### Client Request Format\n\nAll requests must include the authorization header:\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n## Dependencies\n\n### Production Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP protocol implementation |\n| ajv | ^8.18.0 | JSON schema validation |\n| commander | 14.0.0 | CLI argument parsing |\n| express | 5.1.0 | SSE server framework |\n| fast-xml-parser | 5.5.7 | XML parsing for mobile protocols |\n| qs | ^6.15.0 | Query string parsing |\n| zod | ^4.1.13 | Schema validation |\n| zod-to-json-schema | 3.25.0 | Zod to JSON Schema conversion |\n| mobilecli | 0.3.70 | Mobile device communication (optional) |\n资料来源：[package.json:31-48]()\n\n### Dev Dependencies\n\nKey development dependencies include:\n- TypeScript 5.8.2\n- ESLint 9.19.0\n- Mocha 11.1.0 (testing)\n- ts-node 10.9.2\n- husky 9.1.7 (git hooks)\n资料来源：[package.json:49-60]()\n\n## Troubleshooting\n\n### mobilecli Not Available\n\nIf the server fails to start with \"mobilecli is not available\":\n\n1. Ensure the optional dependency is installed:\n ```bash\n npm install mobilecli\n ```\n\n2. Verify installation:\n ```bash\n mobilecli --version\n ```\n\n3. Check platform compatibility using the binary resolution logic in `src/mobilecli.ts`.\n\n### Binary Resolution Path\n\nThe server searches for mobilecli in this order:\n\n```mermaid\ngraph TD\n A[Start] --> B{Current path contains node_modules?}\n B -->|Yes| C[Find last node_modules directory]\n C --> D[Check mobilecli/bin/]\n D --> E{Binary exists?}\n E -->|Yes| F[Return path]\n E -->|No| G[Check parentDir/node_modules/mobilecli/bin/...]\n B -->|No| G\n G --> H{Binary exists?}\n H -->|Yes| F\n H -->|No| I[Throw error]\n```\n资料来源：[src/mobilecli.ts:1-35]()\n\n### Node.js Version\n\nEnsure Node.js 18+ is installed:\n```bash\nnode --version\n```\n\n### iOS Simulator Issues\n\nFor iOS simulators, ensure Xcode Command Line Tools are installed:\n```bash\nxcode-select --install\n```\n\nList available simulators:\n```bash\nxcrun simctl list\n```\n\nBoot a simulator before use:\n```bash\nxcrun simctl boot \"iPhone 16\"\n```\n\n## Next Steps\n\nAfter successful installation:\n\n1. **Connect a Device**: Use physical devices, simulators (iOS), or emulators (Android)\n2. **Verify Connection**: Run `mobile_list_devices` tool\n3. **Take a Screenshot**: Use `mobile_take_screenshot` to verify communication\n4. **Explore Tools**: Review available tools in the [main documentation](https://github.com/mobile-next/mobile-mcp/wiki)\n\n---\n\n\n\n## Prerequisites\n\n### 相关页面\n\n相关主题：[Installation and Configuration](#installation), [iOS Implementation](#ios-implementation)\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# Prerequisites\n\nMobile MCP (Model Context Protocol) enables AI agents to interact with mobile devices for automation, testing, and mobile application manipulation. Before using Mobile MCP, you must ensure your environment meets the necessary requirements for both the MCP server and the target mobile devices.\n\n## System Requirements\n\n### Node.js Environment\n\nMobile MCP requires **Node.js version 18 or higher**. This requirement is enforced through the `package.json` engine specification:\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\n资料来源：[package.json:11]()\n\nThe MCP SDK version 1.26.0 is used as the core protocol implementation, which also requires a modern Node.js environment with support for ES modules and async/await patterns.\n\n### Supported Platforms\n\nMobile MCP supports automation across multiple platform types:\n\n| Platform Type | Examples | Access Method |\n|---------------|----------|---------------|\n| iOS Simulators | iPhone Simulator, iPad Simulator | Local Xcode tools |\n| iOS Real Devices | Physical iPhones, iPads | WebDriverAgent via tunnel |\n| Android Emulators | Android Studio Emulator, Genymotion | ADB |\n| Android Real Devices | Samsung, Google Pixel, etc. | ADB |\n\n资料来源：[src/server.ts:32-55]()\n\nThe server automatically detects which platform type a device belongs to by checking against iOS devices, Android devices, and iOS simulators in sequence.\n\n## Required Software Components\n\n### mobilecli\n\nThe `mobilecli` package is the core CLI tool that Mobile MCP relies on for device communication. It is listed as an **optional dependency** in `package.json`:\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n资料来源：[package.json:31-33]()\n\nThe server performs a version check on startup to ensure `mobilecli` is available:\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-28]()\n\n### Installation Methods\n\n#### Via npm (Recommended)\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n#### Via mobilecli package\n\n```bash\nnpm install -g mobilecli\n```\n\n## iOS-Specific Prerequisites\n\n### WebDriverAgent (Real Devices)\n\nFor physical iOS devices, **WebDriverAgent (WDA)** must be installed and running. WDA is Facebook's WebDriver protocol implementation for iOS used for device control and element inspection.\n\nThe `IosManager` class manages WDA connections:\n\n```typescript\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:82-97]()\n\n#### WebDriverAgent Port Configuration\n\n| Setting | Default Value | Purpose |\n|---------|---------------|---------|\n| WDA_PORT | 8100 | WebDriverAgent local port |\n| IOS_TUNNEL_PORT | 9222 | iOS tunnel port |\n\n### iOS Tunnel Requirements\n\nWhen connecting to remote iOS devices, an **iOS tunnel** must be established. The tunnel allows the MCP server to communicate with devices over a network connection.\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```\n\n资料来源：[src/ios.ts:68-74]()\n\n#### Tunnel Setup Requirements\n\n1. **Port forwarding must be active** - The tunnel forwards WDA traffic to the local MCP server\n2. **Firewall configuration** - Port 9222 must be accessible for tunnel connections\n3. **Network connectivity** - Both server and device must have network access\n\n### iOS Simulator Requirements\n\nFor iOS simulators, the system uses `simctl` commands through the Xcode toolchain:\n\n```typescript\nthis.simctl(\"install\", this.simulatorUuid, installPath);\n```\n\n资料来源：[src/iphone-simulator.ts:89]()\n\n**Required tools for simulators:**\n- Xcode Command Line Tools\n- `simctl` utility\n- Bootable simulator instances\n\n### App Installation on iOS\n\nThe iOS manager handles `.zip` and `.app` bundle installations:\n\n```typescript\nif (extname(path).toLowerCase() === \".zip\") {\n this.validateZipPaths(path);\n // Extract and install .app bundle\n}\n```\n\n资料来源：[src/iphone-simulator.ts:58-65]()\n\nSupported formats: `.zip`, `.app`\n\n## Android-Specific Prerequisites\n\n### Android Debug Bridge (ADB)\n\nAndroid devices communicate through **ADB (Android Debug Bridge)**. The `MobileDevice` class executes ADB commands for device interaction:\n\n```typescript\nprivate runCommand(args: string[]): string {\n const result = execFileSync(\"adb\", [\"-s\", this.deviceId, ...args]);\n return result.toString();\n}\n```\n\n资料来源：[src/mobile-device.ts:17-20]()\n\n#### Common ADB Operations\n\n| Command | Purpose |\n|---------|---------|\n| `adb shell` | Execute shell commands on device |\n| `adb install` | Install APK packages |\n| `adb uninstall` | Remove applications |\n| `adb screencap` | Capture screen screenshots |\n| `adb input` | Send touch/keyboard input |\n\n### Android Device Requirements\n\n1. **USB Debugging enabled** - Required for ADB communication\n2. **Device authorization** - Device must approve computer for debugging\n3. **Proper USB drivers** - Especially on Windows systems\n\n### Android UI Automation Commands\n\nThe Android implementation uses `uiautomator2` commands through ADB shell:\n\n```typescript\npublic async getElementsOnScreen(): Promise {\n const response = JSON.parse(this.runCommand([\"dump\", \"ui\"])) as DumpUIResponse;\n return response.data.elements.map(element => ({\n type: element.type,\n label: element.label,\n text: element.text,\n // ... other properties\n }));\n}\n```\n\n资料来源：[src/mobile-device.ts:52-61]()\n\n### Supported Android Input Operations\n\n| Operation | ADB Command |\n|-----------|-------------|\n| Tap | `input tap x,y` |\n| Swipe | `input swipe x1 y1 x2 y2` |\n| Text input | `input text ` |\n| Button press | `input keyevent ` |\n| Long press | Custom implementation with duration |\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n subgraph \"MCP Client\" \n A[\"AI Agent / IDE\"]\n end\n \n subgraph \"Mobile MCP Server\"\n B[\"server.ts
MCP Protocol Handler\"]\n C[\"Robot Interface
Abstract Layer\"]\n end\n \n subgraph \"Device Abstraction Layer\"\n D[\"IosRobot
iOS Implementation\"]\n E[\"AndroidRobot
Android Implementation\"]\n F[\"IosSimulatorRobot
Simulator Implementation\"]\n end\n \n subgraph \"Device Communication\"\n G[\"mobilecli\"]\n H[\"WebDriverAgent
iOS Real Devices\"]\n I[\"ADB
Android Devices\"]\n J[\"simctl
iOS Simulators\"]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n D --> H\n E --> G\n E --> I\n F --> G\n F --> J\n```\n\n## Prerequisites Checklist\n\nBefore running Mobile MCP, verify the following:\n\n### Environment Checklist\n\n- [ ] Node.js >= 18 installed\n- [ ] `mobilecli` package accessible\n- [ ] Network connectivity for remote devices\n\n### iOS Device Checklist (Real Devices)\n\n- [ ] WebDriverAgent installed on device\n- [ ] iOS tunnel established (for remote access)\n- [ ] Port forwarding active (port 8100)\n- [ ] Device connected via USB or network\n\n### iOS Simulator Checklist\n\n- [ ] Xcode installed\n- [ ] Simulator booted and available\n- [ ] `simctl` command accessible\n\n### Android Device Checklist\n\n- [ ] ADB installed and in PATH\n- [ ] USB debugging enabled on device\n- [ ] Device authorized for debugging\n- [ ] Device connected (USB or network)\n\n## Troubleshooting Prerequisites Issues\n\n### mobilecli Not Found\n\n```\nError: mobilecli is not available or not working properly\n```\n\n**Solution:** Install mobilecli globally:\n```bash\nnpm install -g mobilecli\n```\n\n### iOS Tunnel Not Running\n\n```\nError: iOS tunnel is not running\n```\n\n**Solution:** Establish tunnel using `go-ios`:\n```bash\nios tunnel start\n```\n\n### WebDriverAgent Not Running\n\n```\nError: WebDriverAgent is not running on device\n```\n\n**Solution:** \n1. Ensure WDA is installed on the device\n2. Verify port forwarding: `iproxy 8100 8100`\n3. Restart WebDriverAgent if needed\n\n### Android Device Not Detected\n\n```\nError: No Android devices found\n```\n\n**Solution:**\n1. Verify ADB is running: `adb devices`\n2. Enable USB debugging on device\n3. Reconnect device or restart ADB: `adb kill-server && adb start-server`\n\n## Related Documentation\n\n- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)\n- [iOS Setup](https://github.com/mobile-next/mobile-mcp/wiki/iOS-Setup)\n- [Android Setup](https://github.com/mobile-next/mobile-mcp/wiki/Android-Setup)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Troubleshooting)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Device Abstraction Layer](#device-abstraction), [iOS Implementation](#ios-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/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.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- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n \n\n# System Architecture\n\n## Overview\n\nMobile MCP is a Model Context Protocol (MCP) server that enables AI agents to interact with mobile devices (iOS and Android) through a standardized interface. The system acts as a bridge between LLM-powered agents and mobile device automation, supporting physical devices, simulators, and emulators.\n\n资料来源：[README.md:1-50]()\n\n## High-Level Architecture\n\nThe architecture follows a layered design pattern with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[\"MCP Client
(Cursor, Claude, etc.)\"]\n end\n \n subgraph \"MCP Server Layer\"\n B[\"server.ts
(MCP Protocol Handler)\"]\n C[\"Tool Definitions\"]\n D[\"Device Manager\"]\n end\n \n subgraph \"Abstraction Layer\"\n E[\"Robot Interface
(robot.ts)\"]\n end\n \n subgraph \"Device Implementation Layer\"\n F[\"IosRobot
(ios.ts)\"]\n G[\"AndroidRobot
(android.ts)\"]\n H[\"MobileDevice
(mobile-device.ts)\"]\n end\n \n subgraph \"External Dependencies\"\n I[\"mobilecli\"]\n J[\"WebDriverAgent\"]\n K[\"ADB\"]\n end\n \n A --> B\n B --> C\n B --> D\n D --> E\n E --> F\n E --> G\n E --> H\n F --> J\n G --> K\n H --> I\n```\n\n## Core Components\n\n### 1. MCP Server (`server.ts`)\n\nThe main entry point that implements the MCP protocol. It handles:\n\n- Tool registration and discovery\n- Device listing and selection\n- Request routing to appropriate robot implementations\n- Authentication handling (SSE mode)\n\nKey responsibilities:\n- Initializes the MCP SDK and registers all tools 资料来源：[src/server.ts:1-50]()\n- Validates mobilecli availability at startup 资料来源：[src/server.ts:20-30]()\n- Routes requests based on device type 资料来源：[src/server.ts:40-70]()\n\n### 2. Robot Interface (`robot.ts`)\n\nDefines the abstract interface that all device implementations must follow:\n\n```typescript\ninterface Robot {\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): 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 swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\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 setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n}\n```\n\n资料来源：[src/robot.ts:1-100]()\n\n### 3. Device Implementations\n\n#### IosRobot (`ios.ts`)\n\nManages iOS device interactions through WebDriverAgent:\n\n- Establishes tunnel connections for remote device access\n- Manages WebDriverAgent port forwarding\n- Provides iOS-specific automation commands\n\nKey features:\n- Port forwarding management (WDA_PORT = 8100, IOS_TUNNEL_PORT = 20021) 资料来源：[src/ios.ts:30-50]()\n- WebDriverAgent lifecycle management 资料来源：[src/ios.ts:60-80]()\n- Tunnel status validation 资料来源：[src/ios.ts:55-70]()\n\n#### AndroidRobot (`android.ts`)\n\nManages Android device interactions through ADB:\n\n- Direct ADB command execution\n- Device discovery and listing\n- APK installation and management\n\n#### MobileDevice (`mobile-device.ts`)\n\nUses mobilecli for unified device control:\n\n- Works across both platforms through mobilecli abstraction\n- UI element dumping and interaction\n- Device orientation management\n\n资料来源：[src/mobile-device.ts:1-80]()\n\n## Device Selection Flow\n\n```mermaid\ngraph TD\n A[\"mobile_list_available_devices\"] --> B[\"Check iOS Devices\"]\n B --> C[\"Check Android Devices\"]\n C --> D[\"Check iOS Simulators\"]\n D --> E[\"Return Combined List\"]\n \n F[\"getRobotFromDevice
(deviceId)\"] --> G{\"Is iOS Device?\"}\n G -->|Yes| H[\"Return IosRobot\"]\n G -->|No| I{\"Is Android Device?\"}\n I -->|Yes| J[\"Return AndroidRobot\"]\n I -->|No| K{\"Is iOS Simulator?\"}\n K -->|Yes| L[\"Check Agent Status\"]\n L -->|Install if needed| M[\"Return MobileDevice\"]\n K -->|No| N[\"Throw Error\"]\n```\n\n资料来源：[src/server.ts:60-100]()\n\n## Tool Architecture\n\nAll MCP tools follow a consistent pattern defined in `server.ts`:\n\n| Category | Tool Name | Purpose |\n|----------|-----------|---------|\n| Device Info | `mobile_list_available_devices` | List all connected devices |\n| Device Info | `mobile_get_screen_size` | Get device screen dimensions |\n| Device Info | `mobile_get_orientation` | Get current screen orientation |\n| Device Info | `mobile_set_orientation` | Set screen orientation |\n| App Management | `mobile_list_apps` | List installed apps |\n| App Management | `mobile_launch_app` | Launch an app |\n| App Management | `mobile_terminate_app` | Stop an app |\n| App Management | `mobile_install_app` | Install from file |\n| App Management | `mobile_uninstall_app` | Uninstall app |\n| Screen Interaction | `mobile_take_screenshot` | Capture screen |\n| Screen Interaction | `mobile_click_on_screen_at_coordinates` | Tap at coordinates |\n| Screen Interaction | `mobile_double_tap_on_screen` | Double tap |\n| Screen Interaction | `mobile_long_press_on_screen_at_coordinates` | Long press |\n| Screen Interaction | `mobile_swipe_on_screen` | Swipe gesture |\n| Input | `mobile_type_keys` | Send text input |\n\n## Communication Protocols\n\n### Stdio Mode (Default)\n\nThe default communication mode uses standard input/output:\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 Mode\n\nOptional HTTP server mode for remote access:\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nSupports optional Bearer token authentication:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n## WebDriverAgent Integration (iOS)\n\nFor iOS devices, the architecture leverages WebDriverAgent:\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant IosRobot\n participant WDA as WebDriverAgent\n participant Tunnel\n \n MCP->>IosRobot: tap(x, y)\n IosRobot->>Tunnel: Ensure tunnel running\n Tunnel-->>IosRobot: OK\n IosRobot->>WDA: POST /wda/tap/0\n WDA-->>IosRobot: Response\n IosRobot-->>MCP: Success\n```\n\n资料来源：[src/webdriver-agent.ts:50-100]()\n\n## Dependency Architecture\n\n```mermaid\ngraph LR\n A[\"@modelcontextprotocol/sdk\"] --> B[\"MCP Server\"]\n C[\"mobilecli\"] --> D[\"MobileDevice\"]\n E[\"express\"] --> F[\"SSE Server\"]\n G[\"zod\"] --> H[\"Schema Validation\"]\n```\n\n### Key Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |\n| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile control |\n| `express` | 5.1.0 | HTTP server for SSE mode |\n| `zod` | ^4.1.13 | Runtime type validation |\n| `commander` | 14.0.0 | CLI argument parsing |\n\n资料来源：[package.json:1-50]()\n\n## Error Handling\n\nThe system uses `ActionableError` for user-friendly error messages:\n\n```typescript\nthrow new ActionableError(\n `Device \"${deviceId}\" not found. Use the mobile_list_available_devices tool to see available devices.`\n);\n```\n\n资料来源：[src/server.ts:90-95]()\n\n## Platform Detection Logic\n\n```mermaid\ngraph TD\n A[\"getRobotFromDevice\"] --> B[\"Check IosManager\"]\n B --> C{\"Found in iOS devices?\"}\n C -->|Yes| D[\"Return IosRobot\"]\n C -->|No| E[\"Check AndroidManager\"]\n E --> F{\"Found in Android devices?\"}\n F -->|Yes| G[\"Return AndroidRobot\"]\n F -->|No| H[\"Check iOS Simulators\"]\n H --> I{\"Found?\"}\n I -->|Yes| J[\"Return MobileDevice\"]\n I -->|No| K[\"Throw ActionableError\"]\n```\n\n## Security Considerations\n\n- URL scheme validation: Only `http://` and `https://` allowed by default 资料来源：[src/server.ts:150-160]()\n- Optional unsafe URL access via `MOBILEMCP_ALLOW_UNSAFE_URLS=1`\n- Bearer token authentication for SSE mode\n- No arbitrary command execution on host system\n\n## Extensibility\n\nThe Robot interface design allows for additional platform implementations:\n\n1. Implement the `Robot` interface\n2. Add device detection in `getRobotFromDevice()`\n3. Register new tools in `server.ts`\n\n```typescript\n// Example: Adding a new platform\nconst newPlatformDevice = new NewPlatformRobot(deviceId);\nreturn newPlatformRobot;\n```\n\nThis modular architecture enables easy addition of new device types or automation backends without modifying existing implementations.\n\n---\n\n\n\n## Device Abstraction Layer\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [iOS Implementation](#ios-implementation)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.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 \n\n# Device Abstraction Layer\n\n## Overview\n\nThe Device Abstraction Layer (DAL) is the core architectural component of mobile-mcp that provides a unified interface for interacting with mobile devices across different platforms. It abstracts platform-specific implementations (iOS and Android) behind a common Robot interface, enabling AI agents and automated workflows to control mobile devices without knowledge of the underlying platform details.\n\nThe DAL serves as the bridge between the Model Context Protocol (MCP) server and the physical mobile devices, handling device detection, robot instantiation, and operation delegation.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Abstraction Layer]\n B --> C[Robot Factory]\n C --> D{IOS Device?}\n C --> E{Android Device?}\n C --> F{Simulator?}\n D --> G[IosRobot]\n E --> H[AndroidRobot]\n F --> I[MobileDevice]\n G --> J[mobilecli / iOS Device Kit]\n H --> K[ADB / UI Automator]\n I --> J\n```\n\n## Core Components\n\n### Robot Interface\n\nThe Robot interface (`src/robot.ts`) defines the contract that all platform-specific implementations must follow. This ensures consistent behavior regardless of the target device.\n\n**File:** `src/robot.ts:1-80`\n\n| Method | Description | Parameters | Return Type |\n|--------|-------------|------------|-------------|\n| `openUrl` | Open a URL in the device browser | `url: string` | `Promise` |\n| `sendKeys` | Send keyboard input to device | `text: string` | `Promise` |\n| `pressButton` | Simulate physical button press | `button: Button` | `Promise` |\n| `tap` | Tap at screen coordinates | `x: number, y: number` | `Promise` |\n| `doubleTap` | Double-tap at coordinates | `x: number, y: number` | `Promise` |\n| `longPress` | Long press at coordinates | `x: number, y: number, duration: number` | `Promise` |\n| `getElementsOnScreen` | Get interactive UI elements | - | `Promise` |\n| `setOrientation` | Change screen orientation | `orientation: Orientation` | `Promise` |\n| `getOrientation` | Get current orientation | - | `Promise` |\n\n### Platform Implementations\n\n#### IosRobot\n\nHandles iOS device interactions using WebDriverAgent or iOS Device Kit as the underlying protocol.\n\n**File:** `src/ios.ts`\n\n| Capability | Description |\n|------------|-------------|\n| Simulator Support | Full support for iOS simulators |\n| Real Device Support | Uses iOS Device Kit for physical devices |\n| WebDriverAgent | Legacy support via go-ios |\n\n#### AndroidRobot\n\nManages Android device interactions through ADB (Android Debug Bridge) and UI Automator.\n\n**File:** `src/android.ts`\n\n| Capability | Description |\n|------------|-------------|\n| Emulator Support | Full support for Android emulators |\n| Real Device Support | Direct ADB communication |\n| Foldable Support | Multi-screen device handling (v0.0.23+) |\n\n#### MobileDevice\n\nUnified device class for modern simulator/emulator management. Used as the primary interface for iOS simulators.\n\n**File:** `src/mobile-device.ts`\n\n| Feature | Description |\n|---------|-------------|\n| Agent Status Check | Verifies device readiness |\n| Agent Install | Automatically installs required agents |\n| Platform Abstraction | Works across iOS and Android platforms |\n\n## Device Detection Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant DAL as Device Abstraction Layer\n participant IosMgr as IosManager\n participant AndroidMgr as AndroidDeviceManager\n participant mobilecli\n\n Client->>Server: Tool Request (deviceId)\n Server->>DAL: getRobotFromDevice(deviceId)\n DAL->>IosMgr: listDevices()\n DAL->>AndroidMgr: getConnectedDevices()\n \n alt iOS Device Found\n DAL->>DAL: Create IosRobot(deviceId)\n else Android Device Found\n DAL->>DAL: Create AndroidRobot(deviceId)\n else Simulator Check\n DAL->>mobilecli: getDevices(platform: \"ios\", type: \"simulator\")\n alt Simulator Found\n DAL->>DAL: Check agentVerifiedSimulators\n DAL->>mobilecli: agentStatus(deviceId)\n alt Agent Not Installed\n DAL->>mobilecli: agentInstall(deviceId)\n end\n DAL->>DAL: Create MobileDevice(deviceId)\n else Not Found\n DAL-->>Client: Error: Device not found\n end\n end\n DAL-->>Server: Robot Instance\n Server-->>Client: Execute Tool\n```\n\n## Device Manager Classes\n\n### IosManager\n\nManages iOS device discovery and listing.\n\n**File:** `src/ios.ts`\n\n```typescript\nclass IosManager {\n listDevices(): IosDevice[];\n}\n```\n\n### AndroidDeviceManager\n\nManages Android device discovery via ADB.\n\n**File:** `src/android.ts`\n\n```typescript\nclass AndroidDeviceManager {\n getConnectedDevices(): AndroidDevice[];\n}\n```\n\n## mobilecli Integration\n\nThe mobilecli tool (`src/mobilecli.ts`) is the underlying CLI that provides cross-platform device management. It is a required dependency for the Device Abstraction Layer to function.\n\n**File:** `src/server.ts:8-16`\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### Key mobilecli Functions\n\n| Function | Purpose |\n|----------|---------|\n| `getVersion()` | Verify mobilecli installation |\n| `getDevices()` | List available devices by platform and type |\n| `agentStatus()` | Check if agent is installed on device |\n| `agentInstall()` | Install required agent on device |\n| `agentUninstall()` | Remove agent from device |\n\n## Simulator Agent Management\n\nFor iOS simulators, the DAL implements an agent verification and auto-installation system.\n\n**File:** `src/server.ts:45-58`\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\nThis ensures that:\n1. Each simulator is checked at most once per server session\n2. Missing agents are automatically installed\n3. The `agentVerifiedSimulators` Set prevents redundant installations\n\n## Error Handling\n\nThe DAL provides actionable error messages when device operations fail.\n\n| Error Condition | Response |\n|-----------------|----------|\n| mobilecli not available | Links to installation wiki |\n| Device not found | Lists available devices tool |\n| iOS Device Kit failure | Fallback mechanisms |\n\n**File:** `src/server.ts:15-16`\n\n```typescript\nthrow new ActionableError(`Device \"${deviceId}\" not found. \nUse the mobile_list_available_devices tool to see available devices.`);\n```\n\n## Usage in MCP Tools\n\nThe Device Abstraction Layer is invoked by all device interaction tools defined in the MCP server:\n\n**File:** `src/server.ts:63-90`\n\n| Tool | Operation |\n|------|-----------|\n| `mobile_list_available_devices` | Lists all connected devices |\n| `mobile_get_screen_size` | Delegates to active Robot |\n| `mobile_take_screenshot` | Delegates to active Robot |\n| `mobile_click_on_screen_at_coordinates` | Delegates to active Robot |\n| `mobile_type_keys` | Delegates to active Robot |\n| `mobile_press_button` | Delegates to active Robot |\n\n## Configuration\n\nThe DAL requires mobilecli as an optional dependency:\n\n**File:** `package.json:22-23`\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n## Summary\n\nThe Device Abstraction Layer provides:\n\n- **Unified Interface**: A single `Robot` interface for all platform operations\n- **Platform Detection**: Automatic identification of iOS, Android, and simulator devices\n- **Factory Pattern**: Dynamic robot instantiation based on device type\n- **Agent Management**: Automatic verification and installation of required agents\n- **Error Context**: Actionable error messages with documentation links\n\nThis architecture enables mobile-mcp to provide a consistent automation experience across the diverse mobile device ecosystem while maintaining platform-specific optimizations.\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Device Management](#device-management), [App Management](#app-management), [Screen Interaction and Input](#screen-interaction)\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/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- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe Mobile MCP server exposes a comprehensive set of tools that enable AI assistants to interact with mobile devices (iOS and Android) through the Model Context Protocol. These tools provide capabilities for device management, screen interaction, app lifecycle management, and UI automation. 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\nThe tools are implemented in TypeScript and follow a consistent pattern where each tool accepts a `device` parameter to specify the target device identifier. 资料来源：[src/server.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Architecture\n\n### Tool Layer Hierarchy\n\n```mermaid\ngraph TD\n A[MCP Client
Claude, Cursor, Codex] --> B[Mobile MCP Server]\n B --> C[Robot Interface]\n C --> D[iOS Robot]\n C --> E[Android Robot]\n D --> F[WebDriverAgent]\n D --> G[iPhone Simulator]\n E --> H[Android ADB]\n F --> I[Real iOS Device]\n G --> J[iOS Simulator]\n H --> K[Android Emulator]\n H --> L[Android Device]\n```\n\n### Device Detection Flow\n\n```mermaid\ngraph TD\n A[getRobotFromDevice
deviceId: string] --> B{Is iOS Device?}\n B -->|Yes| C[Return IosRobot]\n B -->|No| D{Is Android Device?}\n D -->|Yes| E[Return AndroidRobot]\n D -->|No| F{Check iOS
Simulators?}\n F -->|Found| G[Return IosRobot]\n F -->|Not Found| H[Return Error]\n```\n\nThe `getRobotFromDevice` function determines the appropriate robot implementation based on the device type by querying device managers and checking against known device identifiers. 资料来源：[src/server.ts:15-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Tool Categories\n\n### Device Management Tools\n\n#### mobile_list_available_devices\n\nLists all available mobile devices including simulators, emulators, and connected physical devices.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | No | Optional device filter |\n\n**Response:** JSON array of device objects with `deviceId`, `name`, `platform`, and `status`.\n\n#### mobile_get_screen_size\n\nRetrieves the screen dimensions of the connected device in pixels.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** `{ \"width\": number, \"height\": number }`\n\n#### mobile_get_orientation\n\nReturns the current screen orientation of the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** `\"portrait\"` or `\"landscape\"` 资料来源：[src/mobile-device.ts:80-90](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n#### mobile_set_orientation\n\nChanges the screen orientation of the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `orientation` | string | Yes | `\"portrait\"` or `\"landscape\"` |\n\n```typescript\npublic async setOrientation(orientation: Orientation): Promise {\n this.runCommand([\"device\", \"orientation\", \"set\", orientation]);\n}\n```\n\n资料来源：[src/mobile-device.ts:75-79](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n---\n\n### App Management Tools\n\n#### mobile_list_apps\n\nLists all installed applications on the target device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Array of installed app objects containing `bundleId`, `name`, and `version`.\n\n#### mobile_launch_app\n\nLaunches an application by its package name (Android) or bundle identifier (iOS).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID (iOS) or package name (Android) |\n| `locale` | string | No | Optional locale to set before launching |\n\n```typescript\nlaunchApp(packageName: string, locale?: string): Promise;\n```\n\n#### mobile_terminate_app\n\nStops and terminates a running application. This is a no-op if the app is not running.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID or package name |\n\n#### mobile_install_app\n\nInstalls an application from a local file path. Supports `.apk`, `.ipa`, `.app`, and `.zip` formats.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_path` | string | Yes | Absolute path to the app file |\n\n**Implementation Note:** For iOS simulators, ZIP files are automatically extracted and the `.app` bundle is identified for installation. 资料来源：[src/iphone-simulator.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n\n#### mobile_uninstall_app\n\nRemoves an installed application from the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID or package name |\n\n---\n\n### Screen Interaction Tools\n\n#### mobile_take_screenshot\n\nCaptures the current screen and returns it as a PNG buffer for visual analysis.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Base64-encoded PNG image data.\n\n#### mobile_save_screenshot\n\nCaptures and saves a screenshot to a specified file path.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `path` | string | Yes | Destination file path |\n\n#### mobile_list_elements_on_screen\n\nRetrieves all interactive UI elements visible on the screen with their properties.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Array of screen elements with the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `type` | string | Element type (TextField, Button, Switch, etc.) |\n| `label` | string | Accessibility label |\n| `text` | string | Display text content |\n| `name` | string | Element name |\n| `value` | string | Current value |\n| `identifier` | string | Unique element identifier |\n| `rect` | object | Position and dimensions `{x, y, width, height}` |\n| `focused` | boolean | Whether the element has focus |\n\n**Implementation Note:** For iOS, this uses WebDriverAgent's page source API. For Android, it uses the accessibility tree via `dump ui` command. 资料来源：[src/webdriver-agent.ts:50-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n#### mobile_click_on_screen_at_coordinates\n\nPerforms a tap action at specific screen coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n\n#### mobile_double_tap_on_screen\n\nPerforms a double-tap action at specific screen coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n\n**Implementation:** On iOS WebDriverAgent, this uses pointer actions with pause between taps. On Android, it may execute two sequential taps. 资料来源：[src/webdriver-agent.ts:120-150](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n#### mobile_long_press_on_screen_at_coordinates\n\nPerforms a long press gesture at specified coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n| `duration` | number | No | Press duration in milliseconds (default: 1000) |\n\n#### mobile_swipe_on_screen\n\nPerforms a swipe gesture in a specified direction.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `direction` | string | Yes | `up`, `down`, `left`, or `right` |\n| `start_x` | number | No | Starting X coordinate |\n| `start_y` | number | No | Starting Y coordinate |\n| `distance` | number | No | Swipe distance in pixels |\n\n---\n\n### Input & Navigation Tools\n\n#### mobile_type_keys\n\nTypes text into the currently focused element with optional submit action.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `text` | string | Yes | Text to type |\n| `submit` | boolean | No | Whether to press Enter after typing |\n\n```typescript\npublic async sendKeys(text: string): Promise {\n this.runCommand([\"io\", \"text\", text]);\n}\n```\n\n资料来源：[src/mobile-device.ts:50-52](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n#### mobile_press_button\n\nSimulates a physical button press on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `button` | string | Yes | Button name (see supported buttons) |\n\n**Supported Buttons:**\n\n| Platform | Buttons |\n|----------|---------|\n| Android | `home`, `back`, `up`, `down`, `left`, `right`, `enter`, `delete` |\n| iOS | `home`, `volumeUp`, `volumeDown` |\n\n#### mobile_open_url\n\nOpens a URL in the device's web browser or launches an app via custom URL scheme.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `url` | string | Yes | URL to open (https:// or custom scheme like `myapp://`) |\n\n---\n\n### Recording & Diagnostics Tools\n\n#### mobile_start_recording\n\nStarts screen recording on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `output_path` | string | No | Output file path |\n\n#### mobile_stop_recording\n\nStops the active screen recording and returns the output file information.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** File path, size in MB, and duration in seconds.\n\n#### mobile_list_crashes\n\nLists all crash reports available on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** JSON array of crash report objects with IDs and timestamps.\n\n#### mobile_get_crash\n\nRetrieves the full content of a specific crash report.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `crash_id` | string | Yes | Crash report identifier |\n\n---\n\n## Robot Interface\n\nThe `Robot` interface defines the contract for all mobile device implementations:\n\n```typescript\ninterface Robot {\n // URL and Input\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n \n // Touch Gestures\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n \n // Screen\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\n setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n \n // App Management\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\n资料来源：[src/robot.ts:1-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Platform-Specific Implementations\n\n### iOS Implementation\n\nThe iOS robot uses WebDriverAgent (WDA) for real devices and simctl for simulators:\n\n```mermaid\ngraph TD\n A[IosRobot] --> B{Device Type?}\n B -->|Real Device| C[WebDriverAgent]\n C --> D[WDA REST API]\n D --> E[WDA Port Forwarding]\n E --> F[iOS Device]\n B -->|Simulator| G[iPhone Simulator]\n G --> H[simctl CLI]\n H --> I[Xcode Simulator]\n```\n\n**Port Requirements for Real iOS Devices:**\n\n| Service | Port |\n|---------|------|\n| iOS Tunnel | 28000 |\n| WDA Forward | 8100 |\n\nThe tunnel must be running and port forwarding established before WDA operations can proceed. 资料来源：[src/ios.ts:30-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Implementation\n\nThe Android robot uses ADB (Android Debug Bridge) for all device interactions:\n\n```mermaid\ngraph TD\n A[AndroidRobot] --> B[ADB Commands]\n B --> C[UI Interaction: tap, swipe, text input]\n B --> D[App Management: install, uninstall, launch]\n B --> E[Device Info: orientation, screen size]\n B --> F[Accessibility: dump ui tree]\n```\n\n**Android Element Discovery:**\n\nThe `dump ui` command returns a JSON response containing the accessibility tree:\n\n```typescript\npublic async getElementsOnScreen(): Promise {\n const response = JSON.parse(this.runCommand([\"dump\", \"ui\"])) as DumpUIResponse;\n return response.data.elements.map(element => ({\n type: element.type,\n label: element.label,\n text: element.text,\n name: element.name,\n value: element.value,\n identifier: element.identifier,\n rect: element.rect,\n focused: element.focused,\n }));\n}\n```\n\n资料来源：[src/mobile-device.ts:55-70](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n## Tool Configuration\n\n### Standard Configuration\n\nMost MCP clients use the following standard configuration:\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 Mode\n\nFor network-based connections, enable SSE mode with optional authentication:\n\n```bash\n# Basic SSE server\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n\n# With authentication\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `--listen` | Port to bind the SSE server |\n| `MOBILEMCP_AUTH` | Bearer token for authorization |\n\n---\n\n## Error Handling\n\nAll tools validate device availability and return structured errors. Common error scenarios:\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| `Device not found` | Invalid device identifier | Use `mobile_list_available_devices` |\n| `iOS tunnel not running` | Missing port forwarding | See [wiki](https://github.com/mobile-next/mobile-mcp/wiki/) |\n| `WDA not running` | WebDriverAgent crashed | Restart WDA on device |\n| `App not installed` | Invalid bundle ID | Verify with `mobile_list_apps` |\n\nThe `ActionableError` class provides user-friendly messages with links to troubleshooting documentation. 资料来源：[src/server.ts:20-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n---\n\n## Quick Reference\n\n### Essential Tools for UI Automation\n\n| Task | Primary Tool | Secondary Tool |\n|------|--------------|----------------|\n| View screen | `mobile_take_screenshot` | `mobile_list_elements_on_screen` |\n| Tap element | `mobile_click_on_screen_at_coordinates` | - |\n| Type text | `mobile_type_keys` | - |\n| Scroll | `mobile_swipe_on_screen` | - |\n| Navigate back | `mobile_press_button` (back) | - |\n\n### Device-Specific Tools\n\n| Capability | iOS | Android |\n|------------|-----|---------|\n| Real device | Yes | Yes |\n| Simulator | Yes | No |\n| Emulator | No | Yes |\n| WebDriverAgent | Yes (real) | N/A |\n| ADB | N/A | Yes |\n\n---\n\n\n\n## Device Management\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Device Abstraction Layer](#device-abstraction)\n\n\nRelevant Source Files
\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/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n- [src/utils.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/utils.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# Device Management\n\n## Overview\n\nDevice Management in Mobile MCP provides a unified abstraction layer for controlling mobile devices across iOS and Android platforms. It enables AI agents to interact with physical devices, simulators, and emulators through a consistent set of tools and APIs, abstracting platform-specific implementation details.\n\n资料来源：[src/server.ts:1-50]()\n\n## Architecture\n\nThe Device Management system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Manager]\n B --> C[iOS Manager]\n B --> D[Android Manager]\n B --> E[Mobile CLI]\n C --> F[iOS Robot]\n D --> G[Android Robot]\n E --> H[Mobile Device]\n F --> I[Physical Device / Simulator]\n G --> J[Emulator / Physical Device]\n H --> K[iOS Simulator]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `Robot` interface | `src/robot.ts` | Defines unified device interaction contract |\n| `IosRobot` | Platform-specific | Handles iOS device communication |\n| `AndroidRobot` | Platform-specific | Handles Android device communication |\n| `MobileDevice` | Platform-specific | Handles iOS simulators via mobilecli |\n| `IosManager` | Internal | iOS device discovery and management |\n| `AndroidDeviceManager` | Internal | Android device discovery and management |\n\n资料来源：[src/robot.ts:1-50]()\n\n## Device Discovery\n\nDevice discovery is performed through the `getRobotFromDevice()` function, which identifies the device type and returns the appropriate robot implementation.\n\n```mermaid\ngraph TD\n A[Start] --> B{Check iOS Devices}\n B -->|Found| C[Return IosRobot]\n B -->|Not Found| D{Check Android Devices}\n D -->|Found| E[Return AndroidRobot]\n D -->|Not Found| F{Check Simulators via mobilecli}\n F -->|Simulator Found| G[Verify Agent Status]\n G -->|Status Failed| H[Install Agent]\n G -->|Status OK| I[Return MobileDevice]\n F -->|Not Found| J[Throw Error]\n```\n\n### Device Detection Flow\n\nThe detection sequence in `src/server.ts`:\n\n1. **iOS Physical Devices**: Uses `IosManager.listDevices()` to enumerate iOS devices\n2. **Android Physical Devices**: Uses `AndroidDeviceManager.getConnectedDevices()` to enumerate Android devices\n3. **iOS Simulators**: Uses `mobilecli.getDevices()` with `platform: \"ios\"` and `type: \"simulator\"`\n\n资料来源：[src/server.ts:50-100]()\n\n## Device Types Supported\n\n### Platform Matrix\n\n| Platform | Physical Devices | Simulators/Emulators | Key Technologies |\n|----------|------------------|---------------------|------------------|\n| iOS | iPhone, iPad | iOS Simulator | WebDriverAgent, iOS Device Kit |\n| Android | Samsung, Pixel, etc. | Android Emulator | ADB, UI Automator |\n\n### Simulator Agent Verification\n\nWhen connecting to iOS simulators, Mobile MCP performs agent verification:\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:75-85]()\n\n## Robot Interface\n\nThe `Robot` interface in `src/robot.ts` defines all device interaction methods:\n\n### Screen Operations\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `getScreenshot()` | Capture screen as PNG | `Promise` |\n| `getScreenSize()` | Get screen dimensions | `Promise<{width, height}>` |\n| `getOrientation()` | Get current orientation | `Promise` |\n| `setOrientation()` | Set portrait/landscape | `Promise` |\n\n### Touch Interactions\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `tap(x, y)` | Single tap | x, y coordinates |\n| `doubleTap(x, y)` | Double tap | x, y coordinates |\n| `longPress(x, y, duration)` | Long press | x, y, duration (ms) |\n| `swipeFromCoordinate(x, y, direction, distance?)` | Swipe gesture | x, y, direction, optional distance |\n\n### App Management\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `listApps()` | List installed apps | None |\n| `launchApp(packageName, locale?)` | Launch app | package name, optional locale |\n| `terminateApp(packageName)` | Stop app | package name |\n| `installApp(path)` | Install from file | file path (.apk, .ipa, .app, .zip) |\n| `uninstallApp(bundleId)` | Uninstall app | bundle ID/package name |\n\n### Navigation & Input\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `sendKeys(text)` | Type text | string |\n| `pressButton(button)` | Press button | Button enum (HOME, BACK, etc.) |\n| `openUrl(url)` | Open URL/browser | URL string |\n\n资料来源：[src/robot.ts:50-120]()\n\n## Available Tools\n\nMobile MCP exposes the following device management tools to MCP clients:\n\n### Device Information\n\n- `mobile_list_available_devices` - List all connected devices (physical and simulators)\n- `mobile_get_screen_size` - Get screen dimensions in pixels\n- `mobile_get_orientation` - Get current screen orientation\n- `mobile_set_orientation` - Change screen orientation (portrait/landscape)\n- `mobile_list_crashes` - List crash reports on device\n- `mobile_get_crash` - Retrieve full crash report content\n\n### Screen Interaction\n\n- `mobile_take_screenshot` - Capture screenshot\n- `mobile_save_screenshot` - Save screenshot to file\n- `mobile_list_elements_on_screen` - Get UI elements with coordinates\n- `mobile_click_on_screen_at_coordinates` - Click at x,y\n- `mobile_double_tap_on_screen` - Double tap at x,y\n- `mobile_long_press_on_screen_at_coordinates` - Long press at x,y\n- `mobile_swipe_on_screen` - Swipe in direction\n\n### Input & Navigation\n\n- `mobile_type_keys` - Type text into focused elements\n- `mobile_press_button` - Press device buttons\n- `mobile_open_url` - Open URL in browser\n\n### App Management\n\n- `mobile_list_apps` - List installed apps\n- `mobile_launch_app` - Launch app by package name\n- `mobile_terminate_app` - Stop running app\n- `mobile_install_app` - Install from file\n- `mobile_uninstall_app` - Uninstall app\n\n## Prerequisites\n\nDevice management requires the `mobilecli` tool to be available on the system. The server validates this on startup:\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...`);\n }\n};\n```\n\n资料来源：[src/server.ts:20-35]()\n\n## Configuration\n\n### MCP Server Configuration\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 Mode with Authentication\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nWhen `MOBILEMCP_AUTH` is set, all requests require the header:\n```\nAuthorization: Bearer my-secret-token\n```\n\n资料来源：[package.json:1-30]()\n\n## Error Handling\n\nThe device management system uses `ActionableError` to provide users with actionable error messages:\n\n```typescript\nthrow new ActionableError(\n `Device \"${deviceId}\" not found. Use the mobile_list_available_devices tool to see available devices.`\n);\n```\n\nThis pattern ensures users receive guidance on how to resolve issues, not just failure messages.\n\n资料来源：[src/server.ts:95-100]()\n\n## Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |\n| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile CLI |\n| `express` | 5.1.0 | SSE server transport |\n| `zod` | ^4.1.13 | Schema validation |\n\n资料来源：[package.json:25-50]()\n\n## See Also\n\n- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki)\n\n---\n\n\n\n## App Management\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-implementation)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation:\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- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# App Management\n\nApp Management in Mobile MCP enables AI agents to interact with mobile applications on connected devices through a unified interface. This system provides capabilities for listing, launching, terminating, installing, and uninstalling applications across both iOS and Android platforms.\n\n## Overview\n\nThe App Management feature abstracts platform-specific implementation details behind a consistent Robot interface. This allows AI agents to manage applications without understanding the underlying differences between iOS and Android platforms.\n\n```mermaid\ngraph TD\n A[MCP Client / AI Agent] --> B[Mobile MCP Server]\n B --> C[Robot Interface]\n C --> D[iOS Robot]\n C --> E[Android Robot]\n D --> F[WebDriverAgent / go-ios]\n E --> G[ADB / Android Manager]\n```\n\n**资料来源：** [src/robot.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Available Tools\n\nMobile MCP exposes five primary tools for application management:\n\n| Tool | Description | Platform |\n|------|-------------|----------|\n| `mobile_list_apps` | List all installed applications | iOS, Android |\n| `mobile_launch_app` | Launch an app by package/bundle name | iOS, Android |\n| `mobile_terminate_app` | Stop a running application | iOS, Android |\n| `mobile_install_app` | Install app from file (.apk, .ipa, .app, .zip) | iOS, Android |\n| `mobile_uninstall_app` | Uninstall app by bundle ID or package name | iOS, Android |\n\n**资料来源：** [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Robot Interface\n\nThe core App Management functionality is defined in the `Robot` interface. This interface declares abstract methods that platform-specific implementations must provide.\n\n```typescript\ninterface Robot {\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 openUrl(url: string): Promise;\n}\n```\n\n**资料来源：** [src/robot.ts:40-75](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n### Method Specifications\n\n#### listApps()\n\nReturns all installed applications on the device.\n\n```typescript\nlistApps(): Promise;\n```\n\n**Return Type:** `InstalledApp[]` - Array of objects containing package names (Android) or bundle identifiers (iOS).\n\n#### launchApp()\n\nLaunches an application with optional locale specification.\n\n```typescript\nlaunchApp(packageName: string, locale?: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `packageName` | `string` | The package name (Android) or bundle ID (iOS) of the app |\n| `locale` | `string` (optional) | Locale to launch the app with (e.g., \"en_US\") |\n\n**资料来源：** [src/robot.ts:47-49](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n#### terminateApp()\n\nTerminates a running application. If the app is not running or doesn't exist, this operation is a no-op.\n\n```typescript\nterminateApp(packageName: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `packageName` | `string` | The package name (Android) or bundle ID (iOS) |\n\n#### installApp()\n\nInstalls an application from a local file path. Supports multiple formats across platforms.\n\n```typescript\ninstallApp(path: string): Promise;\n```\n\n**Supported Formats:**\n| Platform | Formats |\n|----------|---------|\n| Android | `.apk`, `.zip` |\n| iOS | `.ipa`, `.app`, `.zip` |\n\n#### uninstallApp()\n\nUninstalls an application from the device.\n\n```typescript\nuninstallApp(bundleId: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `bundleId` | `string` | The app's bundle identifier (iOS) or package name (Android) |\n\n#### openUrl()\n\nOpens a URL in the device's web browser.\n\n```typescript\nopenUrl(url: string): Promise;\n```\n\n**Supported URL Schemes:**\n| Type | Example |\n|------|---------|\n| HTTP/HTTPS | `https://example.com` |\n| Custom Schemes | `myapp://action` |\n\n**资料来源：** [src/robot.ts:59-63](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Architecture\n\n### Device Selection Flow\n\nWhen a tool requires device-specific implementation, the server determines the appropriate Robot based on the device type:\n\n```mermaid\ngraph TD\n A[Device ID Provided] --> B{Is iOS Device?}\n B -->|Yes| C[Return IosRobot]\n B -->|No| D{Is Android Device?}\n D -->|Yes| E[Return AndroidRobot]\n D -->|No| F{Is Simulator?}\n F -->|Yes| G[Return MobileDevice]\n F -->|No| H[Throw ActionableError]\n```\n\n**资料来源：** [src/server.ts:30-60](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n### iOS Implementation\n\nThe iOS implementation leverages `go-ios` (via `mobilecli`) for device communication. The `IosManager` handles device detection and the `WebDriverAgent` protocol manages application lifecycle.\n\nKey components in iOS app management:\n\n1. **WebDriverAgent (WDA)** - Apple's testing framework for iOS\n2. **go-ios** - Command-line interface for iOS device control\n3. **Tunnel Service** - Required for real device communication\n\n**资料来源：** [src/ios.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Implementation\n\nAndroid implementation uses the Android Debug Bridge (ADB) through the Android Manager:\n\n1. **ADB** - Primary communication protocol with Android devices\n2. **Android Manager** - Handles device enumeration and app operations\n3. **Package Manager** - Manages app installation and uninstallation\n\n## Tool Registration\n\nApp Management tools are registered in the server with descriptive schemas:\n\n```typescript\ntool(\n \"mobile_list_apps\",\n \"List Apps\",\n \"List all installed apps on the device\",\n {},\n { readOnlyHint: true },\n async ({}) => { /* implementation */ }\n);\n```\n\n**资料来源：** [src/server.ts:80-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Prerequisites\n\n### iOS Requirements\n- WebDriverAgent must be running on the device\n- For real devices: iOS tunnel must be established\n- go-ios must be installed and functional\n\n**资料来源：** [src/ios.ts:35-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Requirements\n- ADB must be enabled on the device\n- Device must be connected and authorized\n- USB debugging must be enabled\n\n## Usage Examples\n\n### List All Installed Apps\n\n```json\n{\n \"tool\": \"mobile_list_apps\",\n \"arguments\": {}\n}\n```\n\n### Launch an App with Locale\n\n```json\n{\n \"tool\": \"mobile_launch_app\",\n \"arguments\": {\n \"packageName\": \"com.example.app\",\n \"locale\": \"en_US\"\n }\n}\n```\n\n### Install an App\n\n```json\n{\n \"tool\": \"mobile_install_app\",\n \"arguments\": {\n \"path\": \"/path/to/application.apk\"\n }\n}\n```\n\n### Uninstall an App\n\n```json\n{\n \"tool\": \"mobile_uninstall_app\",\n \"arguments\": {\n \"bundleId\": \"com.example.app\"\n }\n}\n```\n\n### Open URL in Browser\n\n```json\n{\n \"tool\": \"mobile_open_url\",\n \"arguments\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n## Error Handling\n\nThe system provides actionable error messages when operations fail. Common error scenarios include:\n\n| Error Condition | Cause | Resolution |\n|-----------------|-------|------------|\n| Device not found | Invalid device ID or disconnected device | Check device connection |\n| App not installed | Attempting to launch non-existent app | Install app first |\n| Installation failed | Invalid file format or corrupted package | Verify file integrity |\n| Permission denied | Insufficient device permissions | Grant required permissions |\n\n**资料来源：** [src/server.ts:45-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Dependencies\n\nApp Management relies on the following package:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mobilecli` | 0.3.70 | Cross-platform mobile device CLI |\n\n**资料来源：** [package.json:25-30](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n---\n\n\n\n## Screen Interaction and Input\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-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/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 \n\n# Screen Interaction and Input\n\n## Overview\n\nThe Screen Interaction and Input system in Mobile MCP provides a comprehensive abstraction layer for controlling mobile devices (iOS, Android, simulators, and emulators) through a unified Robot interface. This system enables AI agents to interact with mobile applications by simulating user input events, capturing screen content, and managing device orientation.\n\nThe architecture is designed to work with multiple device platforms while presenting a consistent API to MCP clients. The system leverages native accessibility trees for most interactions, falling back to screenshot-based coordinate operations when accessibility labels are unavailable. 资料来源：[src/robot.ts:1-30]()\n\n## Architecture\n\n### Core Components\n\nThe system consists of three primary device abstraction layers:\n\n| Component | Platform | Protocol | File |\n|-----------|----------|----------|------|\n| `IosRobot` | iOS | WebDriverAgent (WDA) | [src/webdriver-agent.ts:1-50]() |\n| `AndroidRobot` | Android | mobilecli | [src/mobile-device.ts:1-30]() |\n| `Robot` (interface) | All | Abstract | [src/robot.ts:1-50]() |\n\n### Robot Interface Contract\n\nThe `Robot` interface defines the contract that all platform-specific implementations must fulfill:\n\n```typescript\ninterface Robot {\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): 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 getElementsOnScreen(): Promise;\n setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n getScreenshot(): Promise;\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\n资料来源：[src/robot.ts:30-100]()\n\n### Device Selection Flow\n\nThe server determines which Robot implementation to use based on the device identifier:\n\n```mermaid\ngraph TD\n A[MCP Request with device ID] --> B{Device Type Check}\n B -->|iOS Device| C[IosRobot]\n B -->|Android Device| D[AndroidRobot]\n B -->|Simulator| E[IosRobot]\n C --> F[WebDriverAgent Connection]\n D --> G[mobilecli Commands]\n E --> F\n```\n\n资料来源：[src/server.ts:50-80]()\n\n## Touch Interactions\n\n### Tap Operations\n\n#### Single Tap\n\nSingle tap is implemented using pointer actions sent through the WebDriverAgent protocol for iOS:\n\n```typescript\npublic async tap(x: number, y: number) {\n await this.withinSession(async sessionUrl => {\n const url = `${sessionUrl}/actions`;\n await fetch(url, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n actions: [{\n type: \"pointer\",\n id: \"finger1\",\n parameters: { pointerType: \"touch\" },\n actions: [\n { type: \"pointerMove\", duration: 0, x, y },\n { type: \"pointerDown\", button: 0 },\n { type: \"pause\", duration: 100 },\n { type: \"pointerUp\", button: 0 }\n ]\n }]\n }),\n });\n });\n}\n```\n\n资料来源：[src/webdriver-agent.ts:180-210]()\n\nFor Android, the tap operation uses the mobilecli command:\n\n```typescript\npublic async tap(x: number, y: number): Promise {\n this.runCommand([\"io\", \"tap\", `${x},${y}`]);\n}\n```\n\n资料来源：[src/mobile-device.ts:50-52]()\n\n#### Double Tap\n\nDouble tap is implemented by executing two consecutive tap operations:\n\n```typescript\npublic async doubleTap(x: number, y: number): Promise {\n await this.tap(x, y);\n await this.tap(x, y);\n}\n```\n\n资料来源：[src/mobile-device.ts:56-60]()\n\nIn iOS WebDriverAgent, the double tap uses the W3C Actions API with multiple pointer sequences.\n\n#### Long Press\n\nLong press requires specifying the duration in milliseconds:\n\n```typescript\npublic async longPress(x: number, y: number, duration: number): Promise {\n this.runCommand([\"io\", \"longpress\", `${x},${y}`, \"--duration\", `${duration}`]);\n}\n```\n\n资料来源：[src/mobile-device.ts:62-64]()\n\nThe iOS implementation uses the Actions API with extended pointerDown duration:\n\n```typescript\n{ type: \"pointerDown\", button: 0 },\n{ type: \"pause\", duration: duration },\n{ type: \"pointerUp\", button: 0 }\n```\n\n### Swipe Gestures\n\nSwipe gestures calculate coordinates based on screen dimensions, using 60% of the screen width or height as the swipe distance:\n\n```typescript\nconst verticalDistance = Math.floor(screenSize.height * 0.6);\nconst horizontalDistance = Math.floor(screenSize.width * 0.6);\nconst centerX = Math.floor(screenSize.width / 2);\nconst centerY = Math.floor(screenSize.height / 2);\n```\n\n资料来源：[src/webdriver-agent.ts:130-135]()\n\nThe swipe direction determines the start and end coordinates:\n\n| Direction | X Movement | Y Movement |\n|-----------|------------|------------|\n| up | centerX | centerY ± verticalDistance/2 |\n| down | centerX | centerY ± verticalDistance/2 |\n| left | centerX ± horizontalDistance/2 | centerY |\n| right | centerX ± horizontalDistance/2 | centerY |\n\n## Text Input\n\n### Keyboard Input\n\nText input is handled through different mechanisms per platform:\n\n**iOS (via WebDriverAgent):**\n```typescript\npublic async sendKeys(text: string): Promise {\n await this.withinSession(async sessionUrl => {\n await fetch(`${sessionUrl}/wda/keys`, {\n method: \"POST\",\n body: JSON.stringify({ value: text.split(\"\") }),\n });\n });\n}\n```\n\n**Android (via mobilecli):**\n```typescript\npublic async typeText(text: string): Promise {\n this.runCommand([\"io\", \"text\", text]);\n}\n```\n\n资料来源：[src/mobile-device.ts:42-44]()\n\n### Button Presses\n\nPhysical device buttons are mapped to platform-specific commands:\n\n| Button | iOS Action | Android Command |\n|--------|------------|-----------------|\n| HOME | `wda/pressButton` | `io button home` |\n| BACK | N/A | `io button back` |\n| POWER | N/A | `io button power` |\n| ENTER | sendKeys \"\\n\" | `io button enter` |\n| VOLUME_UP | `wda/pressButton` | `io button volume_up` |\n| VOLUME_DOWN | `wda/pressButton\" | `io button volume_down` |\n\n资料来源：[src/webdriver-agent.ts:150-175]()\n\n## Screen Capture\n\n### Screenshot Retrieval\n\nScreenshots are retrieved as PNG buffers through platform-specific protocols:\n\n**iOS WebDriverAgent:**\n```typescript\npublic async getScreenshot(): Promise {\n const url = `http://${this.host}:${this.port}/screenshot`;\n const response = await fetch(url);\n const json = await response.json();\n return Buffer.from(json.value, \"base64\");\n}\n```\n\n资料来源：[src/webdriver-agent.ts:100-106]()\n\n**Android (via mobilecli):** Screenshots are captured using the platform's native screenshot mechanism through the `dump` command.\n\n## UI Element Discovery\n\n### Element Filtering\n\nThe system filters accessibility elements to return only actionable UI components:\n\n```typescript\nconst acceptedTypes = [\n \"TextField\", \n \"Button\", \n \"Switch\", \n \"Icon\", \n \"SearchField\", \n \"StaticText\", \n \"Image\"\n];\n```\n\n资料来源：[src/webdriver-agent.ts:30-32]()\n\nElement visibility is determined by checking both the `isVisible` flag and bounds:\n\n```typescript\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({ /* element data */ });\n }\n }\n}\n```\n\n### Element Data Structure\n\nEach screen element contains:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| type | string | Element type (Button, TextField, etc.) |\n| label | string | Accessibility label |\n| name | string | Element name |\n| value | string | Current value (for text fields) |\n| identifier | string | Platform-specific identifier |\n| rect | {x, y, width, height} | Bounding rectangle |\n| focused | boolean | Focus state |\n\n资料来源：[src/mobile-device.ts:66-76]()\n\n## Orientation Management\n\nDevice orientation can be queried and changed:\n\n```typescript\npublic async setOrientation(orientation: Orientation): Promise {\n this.runCommand([\"device\", \"orientation\", \"set\", orientation]);\n}\n\npublic async getOrientation(): Promise {\n const response = JSON.parse(this.runCommand([\"device\", \"orientation\", \"get\"])) as OrientationResponse;\n return response.data.orientation;\n}\n```\n\n资料来源：[src/mobile-device.ts:78-85]()\n\nSupported orientations: `\"portrait\"` | `\"landscape\"`\n\n## Connection Prerequisites\n\n### iOS Requirements\n\niOS devices require several connection layers to be operational:\n\n```mermaid\ngraph LR\n A[MCP Server] --> B[iOS Tunnel]\n B --> C[WDA Port Forward]\n C --> D[WebDriverAgent]\n D --> E[iOS Device]\n \n F[Check: Tunnel Running] --> B\n G[Check: WDA Forward Running] --> C\n H[Check: WDA isRunning] --> D\n```\n\n资料来源：[src/ios.ts:30-60]()\n\nThe system verifies:\n\n1. **Tunnel Running** - Required for remote iOS devices\n2. **WDA Port Forward** - TCP port forwarding to WebDriverAgent\n3. **WebDriverAgent Status** - Actual running state of WDA on device\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```\n\n## MCP Tools Interface\n\nThe server exposes the following screen interaction tools:\n\n| Tool Name | Description | Parameters |\n|-----------|-------------|------------|\n| `mobile_take_screenshot` | Capture current screen | device |\n| `mobile_list_elements_on_screen` | Get UI elements | device |\n| `mobile_click_on_screen_at_coordinates` | Tap at coordinates | device, x, y |\n| `mobile_double_tap_on_screen` | Double tap | device, x, y |\n| `mobile_long_press_on_screen_at_coordinates` | Long press | device, x, y, duration |\n| `mobile_swipe_on_screen` | Swipe gesture | device, direction |\n| `mobile_type_keys` | Text input | device, text, submit |\n| `mobile_get_orientation` | Query orientation | device |\n| `mobile_set_orientation` | Set orientation | device, orientation |\n\n## Usage Examples\n\n### Basic Screen Interaction Workflow\n\n```typescript\n// 1. List available devices\nconst devices = await listAvailableDevices();\n\n// 2. Get screen elements\nconst elements = await getElementsOnScreen(deviceId);\n\n// 3. Tap on a button by coordinates\nawait tap(deviceId, 150, 300);\n\n// 4. Type text into a field\nawait typeKeys(deviceId, \"Hello World\", false);\n\n// 5. Swipe up to scroll\nawait swipe(deviceId, \"up\");\n\n// 6. Take screenshot to verify\nconst screenshot = await getScreenshot(deviceId);\n```\n\n### Complete User Journey Automation\n\n```typescript\n// Open app and perform multi-step interaction\nawait launchApp(deviceId, \"com.example.app\");\nawait swipe(deviceId, \"up\");\nconst elements = await getElementsOnScreen(deviceId);\nconst loginButton = elements.find(e => e.name === \"Login\");\nawait tap(deviceId, loginButton.rect.x + 10, loginButton.rect.y + 10);\nawait typeKeys(deviceId, \"user@example.com\", false);\nawait pressButton(deviceId, \"ENTER\");\n```\n\n## Error Handling\n\nThe system provides actionable error messages with troubleshooting links:\n\n```typescript\nthrow new ActionableError(\n `mobilecli is not available or not working properly. \n Please review the documentation at \n https://github.com/mobile-next/mobile-mcp/wiki`\n);\n```\n\n资料来源：[src/server.ts:20-25]()\n\nCommon error scenarios:\n\n| Error Condition | Cause | Resolution |\n|----------------|-------|------------|\n| \"iOS tunnel is not running\" | Remote device connection issue | Start tunnel per wiki instructions |\n| \"Port forwarding not running\" | WDA port not forwarded | Configure port forwarding |\n| \"WebDriverAgent not running\" | WDA crashed on device | Restart WDA on iOS device |\n\n## Performance Considerations\n\n- **Element queries** use native accessibility trees for speed\n- **Screenshots** are transferred as base64-encoded PNG\n- **Gestures** are calculated as percentages of screen dimensions\n- **Timeouts** for recording operations default to 5 minutes (300 seconds)\n\n---\n\n\n\n## iOS Implementation\n\n### 相关页面\n\n相关主题：[Device Abstraction Layer](#device-abstraction), [Screen Interaction and Input](#screen-interaction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n \n\n# iOS Implementation\n\n## Overview\n\nThe iOS Implementation module provides comprehensive automation capabilities for iOS devices, including physical devices, simulators, and emulators. This module serves as a bridge between the Mobile MCP server and iOS testing infrastructure, enabling AI agents to interact with iOS applications through accessibility trees and coordinate-based input.\n\n**Purpose:** The iOS Implementation enables native app automation for iOS testing, scripted flows, and multi-step user journeys driven by LLMs.\n\n**Scope:** The module handles device detection, connection management, WebDriverAgent communication, tunnel port forwarding, and command execution via the go-ios library.\n\n资料来源：[src/ios.ts:1-50]()\n\n## Architecture\n\nThe iOS implementation follows a layered architecture that separates device management, robot control, and protocol communication.\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[IosManager]\n A --> C[IosRobot]\n B --> D[go-ios / mobilecli]\n C --> E[WebDriverAgent]\n C --> F[iOS Device Kit]\n E --> G[Physical iOS Device]\n F --> G\n D --> H[iOS Simulator]\n I[iPhone Simulator] --> H\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|-----------------|\n| IosManager | src/server.ts | Device discovery and listing |\n| IosRobot | src/server.ts | Device interaction via Robot interface |\n| IosDeviceConnection | src/ios.ts | Connection and tunnel management |\n| WebDriverAgent | src/webdriver-agent.ts | UI automation protocol |\n| iPhone Simulator | src/iphone-simulator.ts | Simulator-specific operations |\n\n资料来源：[src/server.ts:30-80]()\n\n## Device Detection\n\nThe system uses a multi-step detection process to identify iOS device types and establish appropriate communication channels.\n\n### Device Type Resolution\n\n```mermaid\ngraph TD\n A[Device ID] --> B{IosManager listDevices?}\n B -->|Found| C[IosRobot]\n B -->|Not Found| D{AndroidDeviceManager?}\n D -->|Found| E[AndroidRobot]\n D -->|Not Found| F{mobilecli getDevices?}\n F -->|Simulator Found| G{MobileDevice}\n F -->|Not Found| H[Error: Device not found]\n```\n\nThe `getRobotFromDevice` function performs the following checks in order:\n\n1. **iOS Physical Devices:** Queries IosManager for connected iOS devices 资料来源：[src/server.ts:45-50]()\n2. **Android Devices:** Checks AndroidDeviceManager for matching device ID 资料来源：[src/server.ts:52-56]()\n3. **iOS Simulators:** Uses mobilecli with platform filter for simulators 资料来源：[src/server.ts:58-75]()\n\n### Simulator Agent Verification\n\nFor iOS simulators, the system automatically verifies and installs the agent if needed:\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:65-71]()\n\n## Connection Management\n\n### Port-Based Connection State\n\nThe iOS implementation uses port checking to verify connection states:\n\n```mermaid\ngraph LR\n A[Device] -->|USB Tunnel| B[localhost:PORT]\n B --> C{WDA Port Check}\n C -->|Listening| D[WebDriverAgent Ready]\n C -->|Not Listening| E[Error: Port forwarding not running]\n```\n\n#### Tunnel Requirements\n\nThe `isTunnelRequired` method determines when tunnel port forwarding is necessary based on connection type. When a tunnel is required but not running, the system throws an `ActionableError`:\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, please see https://github.com/mobile-next/mobile-mcp/wiki/\");\n }\n }\n}\n```\n\n资料来源：[src/ios.ts:45-50]()\n\n#### WebDriverAgent Port Forwarding\n\nConnection to WebDriverAgent requires both tunnel and port forwarding verification:\n\n```typescript\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 (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\");\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 (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\");\n }\n\n return wda;\n}\n```\n\n资料来源：[src/ios.ts:55-70]()\n\n## Robot Interface Implementation\n\nThe IosRobot class implements the Robot interface, providing unified access to iOS device capabilities.\n\n### Supported Operations\n\n| Category | Operations |\n|----------|------------|\n| **Screen** | getScreenshot, getScreenSize, getOrientation, setOrientation |\n| **Touch** | tap, doubleTap, longPress, swipeFromCoordinate |\n| **Input** | sendKeys, pressButton |\n| **Navigation** | home, back, openUrl |\n| **Apps** | listApps, launchApp, terminateApp, installApp, uninstallApp |\n| **Elements** | getElementsOnScreen |\n\n资料来源：[src/robot.ts:1-80]()\n\n### iOS-Specific Considerations\n\n#### Accessibility Tree\n\nThe implementation uses native accessibility trees for element detection rather than computer vision, making it LLM-friendly and fast.\n\n> **Note:** The `getElementsOnScreen` method works only on native apps and will not function within webviews.\n\n资料来源：[src/robot.ts:40-45]()\n\n#### Long Press Duration\n\nThe long press operation accepts a custom duration parameter:\n\n```typescript\nlongPress(x: number, y: number, duration: number): Promise;\n```\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| x | number | X coordinate on screen |\n| y | number | Y coordinate on screen |\n| duration | number | Duration in milliseconds |\n\n资料来源：[src/robot.ts:35-38]()\n\n## WebDriverAgent Integration\n\nThe WebDriverAgent (WDA) serves as the primary automation protocol for iOS physical devices.\n\n### Connection Flow\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Ios as IosDeviceConnection\n participant WDA as WebDriverAgent\n participant Device as iOS Device\n\n MCP->>Ios: wda()\n Ios->>Ios: assertTunnelRunning()\n Ios->>Ios: isWdaForwardRunning()\n Ios->>WDA: new WebDriverAgent(localhost, PORT)\n WDA->>Device: isRunning()\n Device-->>WDA: status\n WDA-->>Ios: WebDriverAgent instance\n Ios-->>MCP: Ready for commands\n```\n\n### Port Configuration\n\n| Port | Purpose | Configuration |\n|------|---------|---------------|\n| WDA_PORT | WebDriverAgent communication | localhost:PORT |\n| IOS_TUNNEL_PORT | USB tunnel forwarding | localhost:PORT |\n\n资料来源：[src/webdriver-agent.ts:1-30]()\n\n## iOS Simulator Support\n\nThe iPhone Simulator module provides specialized handling for iOS Simulator instances.\n\n### Simulator Detection\n\nSimulators are detected through mobilecli with the following parameters:\n\n```typescript\nconst response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n});\n```\n\n资料来源：[src/server.ts:58-62]()\n\n### Simulator vs Physical Device\n\n| Aspect | Simulator | Physical Device |\n|--------|-----------|------------------|\n| **Connection** | Direct via mobilecli | USB tunnel + WDA |\n| **Agent** | Auto-installed on demand | Manual setup required |\n| **Port Forwarding** | Not required | Required (WDA_PORT) |\n| **WebDriverAgent** | Optional auto-start | Required |\n\n资料来源：[src/iphone-simulator.ts:1-40]()\n\n## go-ios Integration\n\nThe implementation uses the go-ios binary for low-level iOS device communication.\n\n### Command Execution\n\n```typescript\nprivate async ios(...args: string[]): Promise {\n return execFileSync(getGoIosPath(), [\"--udid\", this.deviceId, ...args], {}).toString();\n}\n```\n\n资料来源：[src/ios.ts:75-77]()\n\n### Utility Functions\n\nThe system checks for mobilecli availability on startup:\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:22-32]()\n\n## Error Handling\n\n### Actionable Errors\n\nThe system throws `ActionableError` with user-friendly messages and documentation links:\n\n| Error Scenario | Message | Resolution Link |\n|----------------|---------|-----------------|\n| mobilecli unavailable | Installation instructions | [Wiki Installation](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Tunnel not running | Setup guide | [Wiki Tunnel Setup](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Port forwarding failed | Troubleshooting | [Wiki Debugging](https://github.com/mobile-next/mobile-mcp/wiki) |\n| WDA not running | Configuration guide | [Wiki WDA Setup](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Device not found | Device list | mobile_list_available_devices tool |\n\n资料来源：[src/ios.ts:48-70]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| MOBILEMCP_AUTH | Bearer token for SSE authorization | None |\n\n### Port Constants\n\nThe system uses standard port configurations for iOS tunnel and WDA communication. Refer to the source code for current port values.\n\n## Platform Support Matrix\n\n| Platform | Version | Automation Method |\n|----------|---------|-------------------|\n| iOS Simulator | All versions | mobilecli + iOS Device Kit |\n| Physical iOS | iOS 13+ | WebDriverAgent via go-ios |\n| Real Device (debug) | iOS 13+ | USB tunnel + WDA |\n\n资料来源：[src/webdriver-agent.ts:20-30]()\n\n## Related Documentation\n\n- [Main README](https://github.com/mobile-next/mobile-mcp)\n- [Wiki Home](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Setup Guide](https://github.com/mobile-next/mobile-mcp/wiki/Setup)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Debugging)\n- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mobile-next/mobile-mcp\n\n摘要：发现 20 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 维护坑 · 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## 20. 维护坑 · 发布节奏不明确\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 项目说明书",
"目录",
"Overview",
"Project Purpose",
"Core Architecture",
"Device Detection Flow",
"Available Tools",
"Robot Interface",
"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": "f9486673dd3732990d65753ac2ae6b16a57a5594",
"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- **Overview**：importance `high`\n - source_paths: README.md, package.json, src/server.ts\n- **Installation and Configuration**：importance `high`\n - source_paths: README.md, server.json, package.json\n- **Prerequisites**：importance `high`\n - source_paths: README.md, package.json\n- **System Architecture**：importance `high`\n - source_paths: src/server.ts, src/robot.ts, src/mobile-device.ts, src/mobilecli.ts\n- **Device Abstraction Layer**：importance `medium`\n - source_paths: src/mobile-device.ts, src/mobilecli.ts, src/android.ts, src/ios.ts\n- **MCP Tools Reference**：importance `high`\n - source_paths: src/server.ts, README.md\n- **Device Management**：importance `medium`\n - source_paths: src/server.ts, src/mobilecli.ts, src/utils.ts\n- **App Management**：importance `medium`\n - source_paths: src/server.ts, src/android.ts, src/ios.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `f9486673dd3732990d65753ac2ae6b16a57a5594`\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-15 10:52:12 UTC\n\n## 目录\n\n- [Overview](#overview)\n- [Installation and Configuration](#installation)\n- [Prerequisites](#prerequisites)\n- [System Architecture](#system-architecture)\n- [Device Abstraction Layer](#device-abstraction)\n- [MCP Tools Reference](#mcp-tools-reference)\n- [Device Management](#device-management)\n- [App Management](#app-management)\n- [Screen Interaction and Input](#screen-interaction)\n- [iOS Implementation](#ios-implementation)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[Installation and Configuration](#installation), [System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)\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/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n- [CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n \n\n# Overview\n\nMobile MCP (Model Context Protocol) is an open-source project that enables AI assistants to interact with mobile devices through the MCP protocol. It provides a bridge between AI agents and mobile device automation, supporting both iOS and Android platforms including simulators, emulators, and physical devices.\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Project Purpose\n\nThe project serves as an MCP server implementation that allows AI assistants to:\n\n- Automate native iOS and Android applications for testing or data entry scenarios\n- Execute scripted flows and form interactions without manual device control\n- Automate multi-step user journeys driven by large language models\n- Enable general-purpose mobile application interaction for agent-based frameworks\n- Facilitate agent-to-agent communication for mobile automation use cases and data extraction\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Core Architecture\n\nMobile MCP follows a modular architecture that separates platform-specific implementations from the core server logic.\n\n```mermaid\ngraph TD\n subgraph \"MCP Clients\"\n C1[Claude Desktop]\n C2[Cursor]\n C3[VS Code]\n C4[Codex]\n C5[Other MCP Clients]\n end\n \n subgraph \"Mobile MCP Server\"\n Server[Core Server
src/server.ts]\n Tools[MCP Tools Layer]\n Robot[Robot Interface
src/robot.ts]\n end\n \n subgraph \"Platform Implementations\"\n iOS_WDA[WebDriver Agent
src/webdriver-agent.ts]\n iOS_Sim[iOS Simulator
src/iphone-simulator.ts]\n Android[Android Device Manager]\n end\n \n subgraph \"Target Devices\"\n iOS_Real[iOS Physical Device]\n Android_Real[Android Physical Device]\n Simulators[iOS Simulators]\n Emulators[Android Emulators]\n end\n \n C1 & C2 & C3 & C4 & C5 --> Server\n Server --> Tools\n Tools --> Robot\n Robot --> iOS_WDA & iOS_Sim & Android\n iOS_WDA --> iOS_Real & Simulators\n iOS_Sim --> Simulators\n Android --> Android_Real & Emulators\n```\n\n### Key Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Core Server | `src/server.ts` | MCP protocol implementation, device management, tool routing |\n| Robot Interface | `src/robot.ts` | Abstract interface defining device interaction methods |\n| WebDriver Agent | `src/webdriver-agent.ts` | iOS real device and simulator automation via WebDriverAgent |\n| iOS Simulator | `src/iphone-simulator.ts` | Direct iOS simulator control using simctl |\n| Android Manager | (platform-specific) | Android device automation |\n\n资料来源：[src/server.ts:1-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Device Detection Flow\n\nThe server implements a device detection mechanism that identifies the platform type when a device ID is provided.\n\n```mermaid\ngraph TD\n Start[Get Device ID] --> Check_iOS{iOS Device?}\n Check_iOS -->|Yes| Return_iOS[Return IosRobot]\n Check_iOS -->|No| Check_Android{Android Device?}\n Check_Android -->|Yes| Return_Android[Return AndroidRobot]\n Check_Android -->|No| Check_Simulator{iOS Simulator?}\n Check_Simulator -->|Yes| Return_Simulator[Return Simulator Robot]\n Check_Simulator -->|No| Error[Throw Error]\n \n style Return_iOS fill:#90EE90\n style Return_Android fill:#90EE90\n style Return_Simulator fill:#90EE90\n style Error fill:#FFB6C1\n```\n\n资料来源：[src/server.ts:20-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Available Tools\n\nMobile MCP exposes the following tool categories through the MCP protocol:\n\n### Device Management\n\n| Tool | Description |\n|------|-------------|\n| `mobile_list_available_devices` | List all available devices (simulators, emulators, and real devices) |\n| `mobile_get_screen_size` | Get screen dimensions in pixels |\n| `mobile_get_orientation` | Get current screen orientation |\n| `mobile_set_orientation` | Change screen orientation (portrait/landscape) |\n\n### App Management\n\n| Tool | Description |\n|------|-------------|\n| `mobile_list_apps` | List all installed apps on the device |\n| `mobile_launch_app` | Launch an app using package name |\n| `mobile_terminate_app` | Stop and terminate a running app |\n| `mobile_install_app` | Install an app from file (.apk, .ipa, .app, .zip) |\n| `mobile_uninstall_app` | Uninstall an app using bundle ID or package name |\n\n### Screen Interaction\n\n| Tool | Description |\n|------|-------------|\n| `mobile_take_screenshot` | Capture screenshot to understand screen content |\n| `mobile_save_screenshot` | Save screenshot to a file |\n| `mobile_list_elements_on_screen` | List UI elements with coordinates and properties |\n| `mobile_click_on_screen_at_coordinates` | Click at specific x,y coordinates |\n| `mobile_double_tap_on_screen` | Double-tap at specific coordinates |\n| `mobile_long_press_on_screen_at_coordinates` | Long press at specific coordinates |\n| `mobile_swipe_on_screen` | Swipe in any direction (up, down, left, right) |\n\n### Input & Navigation\n\n| Tool | Description |\n|------|-------------|\n| `mobile_type_keys` | Type text into focused elements with optional submit |\n| `mobile_press_button` | Press device buttons (home, back, etc.) |\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Robot Interface\n\nThe `Robot` interface defines the contract for all platform implementations:\n\n```typescript\ninterface Robot {\n // Screen operations\n getScreenshot(): Promise;\n getScreenSize(): Promise;\n getOrientation(): Promise;\n setOrientation(orientation: Orientation): Promise;\n \n // Element operations\n getElementsOnScreen(): Promise;\n \n // Touch operations\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n \n // Text and keys\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n \n // App management\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 // URL handling\n openUrl(url: string): Promise;\n}\n```\n\n资料来源：[src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Platform Support\n\n### iOS Platform\n\niOS automation is handled through two mechanisms:\n\n1. **WebDriverAgent** (`src/webdriver-agent.ts`): Used for real iOS devices and Xcode-managed simulators\n - Communicates via HTTP with WDA session\n - Filters elements by accepted types: `TextField`, `Button`, `Switch`, `Icon`, `SearchField`, `StaticText`, `Image`\n - Uses element visibility and accessibility properties for filtering\n\n2. **iOS Simulator** (`src/iphone-simulator.ts`): Direct simctl control for booted simulators\n - Handles `.app` bundle installation\n - Supports `.zip` file extraction with zip-slip vulnerability protection\n - Uses simctl command-line tool\n\n资料来源：[src/webdriver-agent.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n### Android Platform\n\nAndroid automation uses platform-specific managers to:\n- List connected devices\n- Query UI elements via accessibility tree\n- Execute touch and input operations\n- Manage app lifecycle\n\n## Communication Modes\n\n### STDIO Mode (Default)\n\nThe server communicates over standard input/output:\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\n### SSE Server Mode\n\nFor HTTP-based connections, the server can listen on a specified port:\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nOptional Bearer token authentication can be enabled:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Technology Stack\n\n| Component | Technology | Version |\n|-----------|------------|---------|\n| Runtime | Node.js | >=18 |\n| MCP SDK | @modelcontextprotocol/sdk | 1.26.0 |\n| HTTP Framework | express | 5.1.0 |\n| CLI Framework | commander | 14.0.0 |\n| Validation | zod | 4.1.13 |\n| XML Parsing | fast-xml-parser | 5.5.7 |\n| Native CLI | mobilecli | 0.3.70 (optional) |\n\n资料来源：[package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n## Key Features\n\n- **Fast and lightweight**: Uses native accessibility trees for most interactions, or screenshot-based coordinates where accessibility labels are not available\n- **LLM-friendly**: No computer vision model required in Accessibility (Snapshot)\n- **Visual Sense**: Evaluates and analyses what's actually rendered on screen\n- **Cross-platform**: Supports iOS, Android, simulators, emulators, and real devices\n- **Standard protocol**: Built on Model Context Protocol for seamless AI assistant integration\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Version History\n\nThe project follows semantic versioning with active development:\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.0.49 | 2026-03-24 | Path traversal fix in save screenshot and record video |\n| 0.0.48 | 2026-03-20 | fast-xml-parser security updates, error handling fixes |\n| 0.0.47 | 2026-03-09 | Zod coerce for number parameter parsing, locale support for iOS |\n| 0.0.42 | 2026-02-03 | mobilecli upgrade, fast-xml-parser security update |\n| 0.0.41 | 2026-01-27 | Android element filtering improvements |\n\n资料来源：[CHANGELOG.md](https://github.com/mobile-next/mobile-mcp/blob/main/CHANGELOG.md)\n\n## Getting Started\n\n### Installation\n\nAdd to your MCP client configuration:\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### Prerequisites\n\n- Node.js >= 18\n- For iOS: Xcode Command Line Tools, WebDriverAgent (for real devices)\n- For Android: Android SDK, ADB configured\n\n### Client Support\n\nMobile MCP is compatible with multiple AI coding assistants:\n\n- Claude Desktop\n- Claude Code\n- Cursor\n- VS Code\n- Codex\n- Copilot\n- Gemini CLI\n- Goose\n- Cline\n- Windsurf\n- Qodo Gen\n- Amp\n- Kiro\n- opencode\n\n资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n---\n\n\n\n## Installation and Configuration\n\n### 相关页面\n\n相关主题：[Overview](#overview), [Prerequisites](#prerequisites)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n- [server.json](https://github.com/mobile-next/mobile-mcp/blob/main/server.json)\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/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n \n\n# Installation and Configuration\n\n## Overview\n\nMobile MCP is a Model Context Protocol (MCP) server that enables mobile automation for iOS and Android devices. The server provides a standardized interface for AI assistants to interact with mobile devices through simulators, emulators, and real hardware.\n\nThis page covers the complete installation process, configuration options, and server deployment modes.\n\n## Prerequisites\n\n### System Requirements\n\n| Requirement | Specification |\n|-------------|---------------|\n| Node.js | Version 18 or higher |\n| Package Manager | npm, yarn, or pnpm |\n| Mobile CLI Tools | `mobilecli` (auto-installed as optional dependency) |\n| Platform Tools | Xcode Command Line Tools (iOS) / Android SDK (Android) |\n\nThe server requires Node.js 18+ as specified in `package.json`:\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n资料来源：[package.json:12]()\n\n### Required Mobile Tools\n\nMobile MCP depends on `mobilecli` for device communication. The SDK checks for mobilecli availability at server startup:\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资料来源：[src/server.ts:1-20]()\n\n## Installation Methods\n\n### Standard NPM Installation\n\nThe recommended installation method uses npx to run the package directly:\n\n```bash\nnpx -y @mobilenext/mobile-mcp@latest\n```\n\nThis command downloads and executes the latest version without requiring local installation.\n\n### Local Installation\n\nFor development or customization, install locally:\n\n```bash\nnpm install @mobilenext/mobile-mcp\n```\n\nThe package provides a binary entry point:\n\n```json\n\"bin\": {\n \"mcp-server-mobile\": \"lib/index.js\"\n}\n```\n资料来源：[package.json:62-65]()\n\n### Building from Source\n\nTo build from source:\n\n```bash\ngit clone https://github.com/mobile-next/mobile-mcp.git\ncd mobile-mcp\nnpm install\nnpm run build\n```\n\nBuild artifacts are output to the `lib/` directory:\n\n```bash\nnpm run build # Compiles TypeScript and sets executable permissions\nnpm run watch # Watch mode for development\n```\n资料来源：[package.json:22-30]()\n\n## Server Configuration\n\n### Standard MCP Configuration\n\nThe following JSON configuration works across most MCP clients:\n\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Configuration Schema\n\nThe server adheres to the MCP protocol schema:\n\n```json\n{\n \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n \"name\": \"io.github.mobile-next/mobile-mcp\",\n \"description\": \"MCP server for iOS and Android Mobile Development, Automation and Testing\",\n \"version\": \"{{VERSION}}\",\n \"packages\": [\n {\n \"registryType\": \"npm\",\n \"registryBaseUrl\": \"https://registry.npmjs.org\",\n \"identifier\": \"@mobilenext/mobile-mcp\",\n \"transport\": {\n \"type\": \"stdio\"\n }\n }\n ]\n}\n```\n资料来源：[server.json:1-20]()\n\n## Client-Specific Configuration\n\n### Claude Code\n\n```bash\nclaude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Claude Desktop\n\nFollow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user) and use the standard JSON configuration above.\n\n### Codex\n\n**CLI Installation:**\n```bash\ncodex mcp add mobile-mcp npx \"@mobilenext/mobile-mcp@latest\"\n```\n\n**Manual Configuration** (`~/.codex/config.toml`):\n```toml\n[mcp_servers.mobile-mcp]\ncommand = \"npx\"\nargs = [\"@mobilenext/mobile-mcp@latest\"]\n```\n资料来源：[README.md:1]()\n\n### Copilot\n\nConfiguration file (`~/.copilot/mcp-config.json`):\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资料来源：[README.md:1]()\n\n### Cursor\n\n**Installation Button:**\nClick the provided deeplink or navigate to `Cursor Settings` → `MCP` → `Add new MCP Server`.\n\n**Manual Configuration:**\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Gemini CLI\n\n```bash\ngemini mcp add mobile-mcp npx -y @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Goose\n\n**UI Installation:**\nUse the extension install button or navigate to `Advanced settings` → `Extensions` → `Add custom extension`.\n\n**Manual Configuration:**\n- Type: `STDIO`\n- Command: `npx -y @mobilenext/mobile-mcp@latest`\n资料来源：[README.md:1]()\n\n### Windsurf\n\nNavigate to Windsurf settings → `MCP servers` → Add new server:\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n资料来源：[README.md:1]()\n\n### Amp\n\n**CLI Installation:**\n```bash\namp mcp add mobile-mcp -- npx @mobilenext/mobile-mcp@latest\n```\n\n**VS Code Extension:**\nAdd via settings.json:\n```json\n\"amp.mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n}\n```\n资料来源：[README.md:1]()\n\n### Cline\n\nAdd the standard JSON configuration to your MCP settings file.\n资料来源：[README.md:1]()\n\n### Kiro\n\nConfiguration file (`~/.kiro/settings/mcp.json`):\n```json\n{\n \"mcpServers\": {\n \"mobile-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@mobilenext/mobile-mcp@latest\"]\n }\n }\n}\n```\n资料来源：[README.md:1]()\n\n### opencode\n\nConfiguration file (`~/.config/opencode/opencode.json`):\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资料来源：[README.md:1]()\n\n### Qodo Gen\n\nOpen Qodo Gen chat panel → `Connect more tools` → `+ Add new MCP` → Paste the standard configuration.\n资料来源：[README.md:1]()\n\n## SSE Server Mode\n\nBy default, Mobile MCP communicates over stdio. For remote or web-based deployments, enable SSE (Server-Sent Events) mode.\n\n### Starting the SSE Server\n\n**Basic Usage:**\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n**Binding to Specific Interface:**\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 0.0.0.0:3000\n```\n\nThis binds the server to all network interfaces on port 3000.\n\n### Client Configuration for SSE\n\nConfigure your MCP client to connect to the SSE endpoint:\n\n```\nhttp://:3000/mcp\n```\n\n### Architecture Diagram\n\n```mermaid\ngraph TD\n A[MCP Client] -->|HTTP/MCP Protocol| B[SSE Server]\n B --> C{Mobile MCP Server}\n C -->|iOS Devices| D[IosRobot]\n C -->|Android Devices| E[AndroidRobot]\n D --> F[mobilecli]\n E --> F\n F --> G[iOS Simulator/Device]\n F --> H[Android Emulator/Device]\n```\n\n## Authorization\n\nWhen running in SSE mode, secure the server with Bearer token authentication.\n\n### Configuration\n\nSet the `MOBILEMCP_AUTH` environment variable:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n### Client Request Format\n\nAll requests must include the authorization header:\n\n```\nAuthorization: Bearer my-secret-token\n```\n\n## Dependencies\n\n### Production Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| @modelcontextprotocol/sdk | 1.26.0 | MCP protocol implementation |\n| ajv | ^8.18.0 | JSON schema validation |\n| commander | 14.0.0 | CLI argument parsing |\n| express | 5.1.0 | SSE server framework |\n| fast-xml-parser | 5.5.7 | XML parsing for mobile protocols |\n| qs | ^6.15.0 | Query string parsing |\n| zod | ^4.1.13 | Schema validation |\n| zod-to-json-schema | 3.25.0 | Zod to JSON Schema conversion |\n| mobilecli | 0.3.70 | Mobile device communication (optional) |\n资料来源：[package.json:31-48]()\n\n### Dev Dependencies\n\nKey development dependencies include:\n- TypeScript 5.8.2\n- ESLint 9.19.0\n- Mocha 11.1.0 (testing)\n- ts-node 10.9.2\n- husky 9.1.7 (git hooks)\n资料来源：[package.json:49-60]()\n\n## Troubleshooting\n\n### mobilecli Not Available\n\nIf the server fails to start with \"mobilecli is not available\":\n\n1. Ensure the optional dependency is installed:\n ```bash\n npm install mobilecli\n ```\n\n2. Verify installation:\n ```bash\n mobilecli --version\n ```\n\n3. Check platform compatibility using the binary resolution logic in `src/mobilecli.ts`.\n\n### Binary Resolution Path\n\nThe server searches for mobilecli in this order:\n\n```mermaid\ngraph TD\n A[Start] --> B{Current path contains node_modules?}\n B -->|Yes| C[Find last node_modules directory]\n C --> D[Check mobilecli/bin/]\n D --> E{Binary exists?}\n E -->|Yes| F[Return path]\n E -->|No| G[Check parentDir/node_modules/mobilecli/bin/...]\n B -->|No| G\n G --> H{Binary exists?}\n H -->|Yes| F\n H -->|No| I[Throw error]\n```\n资料来源：[src/mobilecli.ts:1-35]()\n\n### Node.js Version\n\nEnsure Node.js 18+ is installed:\n```bash\nnode --version\n```\n\n### iOS Simulator Issues\n\nFor iOS simulators, ensure Xcode Command Line Tools are installed:\n```bash\nxcode-select --install\n```\n\nList available simulators:\n```bash\nxcrun simctl list\n```\n\nBoot a simulator before use:\n```bash\nxcrun simctl boot \"iPhone 16\"\n```\n\n## Next Steps\n\nAfter successful installation:\n\n1. **Connect a Device**: Use physical devices, simulators (iOS), or emulators (Android)\n2. **Verify Connection**: Run `mobile_list_devices` tool\n3. **Take a Screenshot**: Use `mobile_take_screenshot` to verify communication\n4. **Explore Tools**: Review available tools in the [main documentation](https://github.com/mobile-next/mobile-mcp/wiki)\n\n---\n\n\n\n## Prerequisites\n\n### 相关页面\n\n相关主题：[Installation and Configuration](#installation), [iOS Implementation](#ios-implementation)\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# Prerequisites\n\nMobile MCP (Model Context Protocol) enables AI agents to interact with mobile devices for automation, testing, and mobile application manipulation. Before using Mobile MCP, you must ensure your environment meets the necessary requirements for both the MCP server and the target mobile devices.\n\n## System Requirements\n\n### Node.js Environment\n\nMobile MCP requires **Node.js version 18 or higher**. This requirement is enforced through the `package.json` engine specification:\n\n```json\n\"engines\": {\n \"node\": \">=18\"\n}\n```\n\n资料来源：[package.json:11]()\n\nThe MCP SDK version 1.26.0 is used as the core protocol implementation, which also requires a modern Node.js environment with support for ES modules and async/await patterns.\n\n### Supported Platforms\n\nMobile MCP supports automation across multiple platform types:\n\n| Platform Type | Examples | Access Method |\n|---------------|----------|---------------|\n| iOS Simulators | iPhone Simulator, iPad Simulator | Local Xcode tools |\n| iOS Real Devices | Physical iPhones, iPads | WebDriverAgent via tunnel |\n| Android Emulators | Android Studio Emulator, Genymotion | ADB |\n| Android Real Devices | Samsung, Google Pixel, etc. | ADB |\n\n资料来源：[src/server.ts:32-55]()\n\nThe server automatically detects which platform type a device belongs to by checking against iOS devices, Android devices, and iOS simulators in sequence.\n\n## Required Software Components\n\n### mobilecli\n\nThe `mobilecli` package is the core CLI tool that Mobile MCP relies on for device communication. It is listed as an **optional dependency** in `package.json`:\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n资料来源：[package.json:31-33]()\n\nThe server performs a version check on startup to ensure `mobilecli` is available:\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-28]()\n\n### Installation Methods\n\n#### Via npm (Recommended)\n\n```bash\nnpx @mobilenext/mobile-mcp@latest\n```\n\n#### Via mobilecli package\n\n```bash\nnpm install -g mobilecli\n```\n\n## iOS-Specific Prerequisites\n\n### WebDriverAgent (Real Devices)\n\nFor physical iOS devices, **WebDriverAgent (WDA)** must be installed and running. WDA is Facebook's WebDriver protocol implementation for iOS used for device control and element inspection.\n\nThe `IosManager` class manages WDA connections:\n\n```typescript\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:82-97]()\n\n#### WebDriverAgent Port Configuration\n\n| Setting | Default Value | Purpose |\n|---------|---------------|---------|\n| WDA_PORT | 8100 | WebDriverAgent local port |\n| IOS_TUNNEL_PORT | 9222 | iOS tunnel port |\n\n### iOS Tunnel Requirements\n\nWhen connecting to remote iOS devices, an **iOS tunnel** must be established. The tunnel allows the MCP server to communicate with devices over a network connection.\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```\n\n资料来源：[src/ios.ts:68-74]()\n\n#### Tunnel Setup Requirements\n\n1. **Port forwarding must be active** - The tunnel forwards WDA traffic to the local MCP server\n2. **Firewall configuration** - Port 9222 must be accessible for tunnel connections\n3. **Network connectivity** - Both server and device must have network access\n\n### iOS Simulator Requirements\n\nFor iOS simulators, the system uses `simctl` commands through the Xcode toolchain:\n\n```typescript\nthis.simctl(\"install\", this.simulatorUuid, installPath);\n```\n\n资料来源：[src/iphone-simulator.ts:89]()\n\n**Required tools for simulators:**\n- Xcode Command Line Tools\n- `simctl` utility\n- Bootable simulator instances\n\n### App Installation on iOS\n\nThe iOS manager handles `.zip` and `.app` bundle installations:\n\n```typescript\nif (extname(path).toLowerCase() === \".zip\") {\n this.validateZipPaths(path);\n // Extract and install .app bundle\n}\n```\n\n资料来源：[src/iphone-simulator.ts:58-65]()\n\nSupported formats: `.zip`, `.app`\n\n## Android-Specific Prerequisites\n\n### Android Debug Bridge (ADB)\n\nAndroid devices communicate through **ADB (Android Debug Bridge)**. The `MobileDevice` class executes ADB commands for device interaction:\n\n```typescript\nprivate runCommand(args: string[]): string {\n const result = execFileSync(\"adb\", [\"-s\", this.deviceId, ...args]);\n return result.toString();\n}\n```\n\n资料来源：[src/mobile-device.ts:17-20]()\n\n#### Common ADB Operations\n\n| Command | Purpose |\n|---------|---------|\n| `adb shell` | Execute shell commands on device |\n| `adb install` | Install APK packages |\n| `adb uninstall` | Remove applications |\n| `adb screencap` | Capture screen screenshots |\n| `adb input` | Send touch/keyboard input |\n\n### Android Device Requirements\n\n1. **USB Debugging enabled** - Required for ADB communication\n2. **Device authorization** - Device must approve computer for debugging\n3. **Proper USB drivers** - Especially on Windows systems\n\n### Android UI Automation Commands\n\nThe Android implementation uses `uiautomator2` commands through ADB shell:\n\n```typescript\npublic async getElementsOnScreen(): Promise {\n const response = JSON.parse(this.runCommand([\"dump\", \"ui\"])) as DumpUIResponse;\n return response.data.elements.map(element => ({\n type: element.type,\n label: element.label,\n text: element.text,\n // ... other properties\n }));\n}\n```\n\n资料来源：[src/mobile-device.ts:52-61]()\n\n### Supported Android Input Operations\n\n| Operation | ADB Command |\n|-----------|-------------|\n| Tap | `input tap x,y` |\n| Swipe | `input swipe x1 y1 x2 y2` |\n| Text input | `input text ` |\n| Button press | `input keyevent ` |\n| Long press | Custom implementation with duration |\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n subgraph \"MCP Client\" \n A[\"AI Agent / IDE\"]\n end\n \n subgraph \"Mobile MCP Server\"\n B[\"server.ts
MCP Protocol Handler\"]\n C[\"Robot Interface
Abstract Layer\"]\n end\n \n subgraph \"Device Abstraction Layer\"\n D[\"IosRobot
iOS Implementation\"]\n E[\"AndroidRobot
Android Implementation\"]\n F[\"IosSimulatorRobot
Simulator Implementation\"]\n end\n \n subgraph \"Device Communication\"\n G[\"mobilecli\"]\n H[\"WebDriverAgent
iOS Real Devices\"]\n I[\"ADB
Android Devices\"]\n J[\"simctl
iOS Simulators\"]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n D --> G\n D --> H\n E --> G\n E --> I\n F --> G\n F --> J\n```\n\n## Prerequisites Checklist\n\nBefore running Mobile MCP, verify the following:\n\n### Environment Checklist\n\n- [ ] Node.js >= 18 installed\n- [ ] `mobilecli` package accessible\n- [ ] Network connectivity for remote devices\n\n### iOS Device Checklist (Real Devices)\n\n- [ ] WebDriverAgent installed on device\n- [ ] iOS tunnel established (for remote access)\n- [ ] Port forwarding active (port 8100)\n- [ ] Device connected via USB or network\n\n### iOS Simulator Checklist\n\n- [ ] Xcode installed\n- [ ] Simulator booted and available\n- [ ] `simctl` command accessible\n\n### Android Device Checklist\n\n- [ ] ADB installed and in PATH\n- [ ] USB debugging enabled on device\n- [ ] Device authorized for debugging\n- [ ] Device connected (USB or network)\n\n## Troubleshooting Prerequisites Issues\n\n### mobilecli Not Found\n\n```\nError: mobilecli is not available or not working properly\n```\n\n**Solution:** Install mobilecli globally:\n```bash\nnpm install -g mobilecli\n```\n\n### iOS Tunnel Not Running\n\n```\nError: iOS tunnel is not running\n```\n\n**Solution:** Establish tunnel using `go-ios`:\n```bash\nios tunnel start\n```\n\n### WebDriverAgent Not Running\n\n```\nError: WebDriverAgent is not running on device\n```\n\n**Solution:** \n1. Ensure WDA is installed on the device\n2. Verify port forwarding: `iproxy 8100 8100`\n3. Restart WebDriverAgent if needed\n\n### Android Device Not Detected\n\n```\nError: No Android devices found\n```\n\n**Solution:**\n1. Verify ADB is running: `adb devices`\n2. Enable USB debugging on device\n3. Reconnect device or restart ADB: `adb kill-server && adb start-server`\n\n## Related Documentation\n\n- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)\n- [iOS Setup](https://github.com/mobile-next/mobile-mcp/wiki/iOS-Setup)\n- [Android Setup](https://github.com/mobile-next/mobile-mcp/wiki/Android-Setup)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Troubleshooting)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Device Abstraction Layer](#device-abstraction), [iOS Implementation](#ios-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/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.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- [src/webdriver-agent.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n \n\n# System Architecture\n\n## Overview\n\nMobile MCP is a Model Context Protocol (MCP) server that enables AI agents to interact with mobile devices (iOS and Android) through a standardized interface. The system acts as a bridge between LLM-powered agents and mobile device automation, supporting physical devices, simulators, and emulators.\n\n资料来源：[README.md:1-50]()\n\n## High-Level Architecture\n\nThe architecture follows a layered design pattern with clear separation of concerns:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n A[\"MCP Client
(Cursor, Claude, etc.)\"]\n end\n \n subgraph \"MCP Server Layer\"\n B[\"server.ts
(MCP Protocol Handler)\"]\n C[\"Tool Definitions\"]\n D[\"Device Manager\"]\n end\n \n subgraph \"Abstraction Layer\"\n E[\"Robot Interface
(robot.ts)\"]\n end\n \n subgraph \"Device Implementation Layer\"\n F[\"IosRobot
(ios.ts)\"]\n G[\"AndroidRobot
(android.ts)\"]\n H[\"MobileDevice
(mobile-device.ts)\"]\n end\n \n subgraph \"External Dependencies\"\n I[\"mobilecli\"]\n J[\"WebDriverAgent\"]\n K[\"ADB\"]\n end\n \n A --> B\n B --> C\n B --> D\n D --> E\n E --> F\n E --> G\n E --> H\n F --> J\n G --> K\n H --> I\n```\n\n## Core Components\n\n### 1. MCP Server (`server.ts`)\n\nThe main entry point that implements the MCP protocol. It handles:\n\n- Tool registration and discovery\n- Device listing and selection\n- Request routing to appropriate robot implementations\n- Authentication handling (SSE mode)\n\nKey responsibilities:\n- Initializes the MCP SDK and registers all tools 资料来源：[src/server.ts:1-50]()\n- Validates mobilecli availability at startup 资料来源：[src/server.ts:20-30]()\n- Routes requests based on device type 资料来源：[src/server.ts:40-70]()\n\n### 2. Robot Interface (`robot.ts`)\n\nDefines the abstract interface that all device implementations must follow:\n\n```typescript\ninterface Robot {\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): 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 swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\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 setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n}\n```\n\n资料来源：[src/robot.ts:1-100]()\n\n### 3. Device Implementations\n\n#### IosRobot (`ios.ts`)\n\nManages iOS device interactions through WebDriverAgent:\n\n- Establishes tunnel connections for remote device access\n- Manages WebDriverAgent port forwarding\n- Provides iOS-specific automation commands\n\nKey features:\n- Port forwarding management (WDA_PORT = 8100, IOS_TUNNEL_PORT = 20021) 资料来源：[src/ios.ts:30-50]()\n- WebDriverAgent lifecycle management 资料来源：[src/ios.ts:60-80]()\n- Tunnel status validation 资料来源：[src/ios.ts:55-70]()\n\n#### AndroidRobot (`android.ts`)\n\nManages Android device interactions through ADB:\n\n- Direct ADB command execution\n- Device discovery and listing\n- APK installation and management\n\n#### MobileDevice (`mobile-device.ts`)\n\nUses mobilecli for unified device control:\n\n- Works across both platforms through mobilecli abstraction\n- UI element dumping and interaction\n- Device orientation management\n\n资料来源：[src/mobile-device.ts:1-80]()\n\n## Device Selection Flow\n\n```mermaid\ngraph TD\n A[\"mobile_list_available_devices\"] --> B[\"Check iOS Devices\"]\n B --> C[\"Check Android Devices\"]\n C --> D[\"Check iOS Simulators\"]\n D --> E[\"Return Combined List\"]\n \n F[\"getRobotFromDevice
(deviceId)\"] --> G{\"Is iOS Device?\"}\n G -->|Yes| H[\"Return IosRobot\"]\n G -->|No| I{\"Is Android Device?\"}\n I -->|Yes| J[\"Return AndroidRobot\"]\n I -->|No| K{\"Is iOS Simulator?\"}\n K -->|Yes| L[\"Check Agent Status\"]\n L -->|Install if needed| M[\"Return MobileDevice\"]\n K -->|No| N[\"Throw Error\"]\n```\n\n资料来源：[src/server.ts:60-100]()\n\n## Tool Architecture\n\nAll MCP tools follow a consistent pattern defined in `server.ts`:\n\n| Category | Tool Name | Purpose |\n|----------|-----------|---------|\n| Device Info | `mobile_list_available_devices` | List all connected devices |\n| Device Info | `mobile_get_screen_size` | Get device screen dimensions |\n| Device Info | `mobile_get_orientation` | Get current screen orientation |\n| Device Info | `mobile_set_orientation` | Set screen orientation |\n| App Management | `mobile_list_apps` | List installed apps |\n| App Management | `mobile_launch_app` | Launch an app |\n| App Management | `mobile_terminate_app` | Stop an app |\n| App Management | `mobile_install_app` | Install from file |\n| App Management | `mobile_uninstall_app` | Uninstall app |\n| Screen Interaction | `mobile_take_screenshot` | Capture screen |\n| Screen Interaction | `mobile_click_on_screen_at_coordinates` | Tap at coordinates |\n| Screen Interaction | `mobile_double_tap_on_screen` | Double tap |\n| Screen Interaction | `mobile_long_press_on_screen_at_coordinates` | Long press |\n| Screen Interaction | `mobile_swipe_on_screen` | Swipe gesture |\n| Input | `mobile_type_keys` | Send text input |\n\n## Communication Protocols\n\n### Stdio Mode (Default)\n\nThe default communication mode uses standard input/output:\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 Mode\n\nOptional HTTP server mode for remote access:\n\n```bash\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nSupports optional Bearer token authentication:\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n## WebDriverAgent Integration (iOS)\n\nFor iOS devices, the architecture leverages WebDriverAgent:\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant IosRobot\n participant WDA as WebDriverAgent\n participant Tunnel\n \n MCP->>IosRobot: tap(x, y)\n IosRobot->>Tunnel: Ensure tunnel running\n Tunnel-->>IosRobot: OK\n IosRobot->>WDA: POST /wda/tap/0\n WDA-->>IosRobot: Response\n IosRobot-->>MCP: Success\n```\n\n资料来源：[src/webdriver-agent.ts:50-100]()\n\n## Dependency Architecture\n\n```mermaid\ngraph LR\n A[\"@modelcontextprotocol/sdk\"] --> B[\"MCP Server\"]\n C[\"mobilecli\"] --> D[\"MobileDevice\"]\n E[\"express\"] --> F[\"SSE Server\"]\n G[\"zod\"] --> H[\"Schema Validation\"]\n```\n\n### Key Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |\n| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile control |\n| `express` | 5.1.0 | HTTP server for SSE mode |\n| `zod` | ^4.1.13 | Runtime type validation |\n| `commander` | 14.0.0 | CLI argument parsing |\n\n资料来源：[package.json:1-50]()\n\n## Error Handling\n\nThe system uses `ActionableError` for user-friendly error messages:\n\n```typescript\nthrow new ActionableError(\n `Device \"${deviceId}\" not found. Use the mobile_list_available_devices tool to see available devices.`\n);\n```\n\n资料来源：[src/server.ts:90-95]()\n\n## Platform Detection Logic\n\n```mermaid\ngraph TD\n A[\"getRobotFromDevice\"] --> B[\"Check IosManager\"]\n B --> C{\"Found in iOS devices?\"}\n C -->|Yes| D[\"Return IosRobot\"]\n C -->|No| E[\"Check AndroidManager\"]\n E --> F{\"Found in Android devices?\"}\n F -->|Yes| G[\"Return AndroidRobot\"]\n F -->|No| H[\"Check iOS Simulators\"]\n H --> I{\"Found?\"}\n I -->|Yes| J[\"Return MobileDevice\"]\n I -->|No| K[\"Throw ActionableError\"]\n```\n\n## Security Considerations\n\n- URL scheme validation: Only `http://` and `https://` allowed by default 资料来源：[src/server.ts:150-160]()\n- Optional unsafe URL access via `MOBILEMCP_ALLOW_UNSAFE_URLS=1`\n- Bearer token authentication for SSE mode\n- No arbitrary command execution on host system\n\n## Extensibility\n\nThe Robot interface design allows for additional platform implementations:\n\n1. Implement the `Robot` interface\n2. Add device detection in `getRobotFromDevice()`\n3. Register new tools in `server.ts`\n\n```typescript\n// Example: Adding a new platform\nconst newPlatformDevice = new NewPlatformRobot(deviceId);\nreturn newPlatformRobot;\n```\n\nThis modular architecture enables easy addition of new device types or automation backends without modifying existing implementations.\n\n---\n\n\n\n## Device Abstraction Layer\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [iOS Implementation](#ios-implementation)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [src/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.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 \n\n# Device Abstraction Layer\n\n## Overview\n\nThe Device Abstraction Layer (DAL) is the core architectural component of mobile-mcp that provides a unified interface for interacting with mobile devices across different platforms. It abstracts platform-specific implementations (iOS and Android) behind a common Robot interface, enabling AI agents and automated workflows to control mobile devices without knowledge of the underlying platform details.\n\nThe DAL serves as the bridge between the Model Context Protocol (MCP) server and the physical mobile devices, handling device detection, robot instantiation, and operation delegation.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Abstraction Layer]\n B --> C[Robot Factory]\n C --> D{IOS Device?}\n C --> E{Android Device?}\n C --> F{Simulator?}\n D --> G[IosRobot]\n E --> H[AndroidRobot]\n F --> I[MobileDevice]\n G --> J[mobilecli / iOS Device Kit]\n H --> K[ADB / UI Automator]\n I --> J\n```\n\n## Core Components\n\n### Robot Interface\n\nThe Robot interface (`src/robot.ts`) defines the contract that all platform-specific implementations must follow. This ensures consistent behavior regardless of the target device.\n\n**File:** `src/robot.ts:1-80`\n\n| Method | Description | Parameters | Return Type |\n|--------|-------------|------------|-------------|\n| `openUrl` | Open a URL in the device browser | `url: string` | `Promise` |\n| `sendKeys` | Send keyboard input to device | `text: string` | `Promise` |\n| `pressButton` | Simulate physical button press | `button: Button` | `Promise` |\n| `tap` | Tap at screen coordinates | `x: number, y: number` | `Promise` |\n| `doubleTap` | Double-tap at coordinates | `x: number, y: number` | `Promise` |\n| `longPress` | Long press at coordinates | `x: number, y: number, duration: number` | `Promise` |\n| `getElementsOnScreen` | Get interactive UI elements | - | `Promise` |\n| `setOrientation` | Change screen orientation | `orientation: Orientation` | `Promise` |\n| `getOrientation` | Get current orientation | - | `Promise` |\n\n### Platform Implementations\n\n#### IosRobot\n\nHandles iOS device interactions using WebDriverAgent or iOS Device Kit as the underlying protocol.\n\n**File:** `src/ios.ts`\n\n| Capability | Description |\n|------------|-------------|\n| Simulator Support | Full support for iOS simulators |\n| Real Device Support | Uses iOS Device Kit for physical devices |\n| WebDriverAgent | Legacy support via go-ios |\n\n#### AndroidRobot\n\nManages Android device interactions through ADB (Android Debug Bridge) and UI Automator.\n\n**File:** `src/android.ts`\n\n| Capability | Description |\n|------------|-------------|\n| Emulator Support | Full support for Android emulators |\n| Real Device Support | Direct ADB communication |\n| Foldable Support | Multi-screen device handling (v0.0.23+) |\n\n#### MobileDevice\n\nUnified device class for modern simulator/emulator management. Used as the primary interface for iOS simulators.\n\n**File:** `src/mobile-device.ts`\n\n| Feature | Description |\n|---------|-------------|\n| Agent Status Check | Verifies device readiness |\n| Agent Install | Automatically installs required agents |\n| Platform Abstraction | Works across iOS and Android platforms |\n\n## Device Detection Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant DAL as Device Abstraction Layer\n participant IosMgr as IosManager\n participant AndroidMgr as AndroidDeviceManager\n participant mobilecli\n\n Client->>Server: Tool Request (deviceId)\n Server->>DAL: getRobotFromDevice(deviceId)\n DAL->>IosMgr: listDevices()\n DAL->>AndroidMgr: getConnectedDevices()\n \n alt iOS Device Found\n DAL->>DAL: Create IosRobot(deviceId)\n else Android Device Found\n DAL->>DAL: Create AndroidRobot(deviceId)\n else Simulator Check\n DAL->>mobilecli: getDevices(platform: \"ios\", type: \"simulator\")\n alt Simulator Found\n DAL->>DAL: Check agentVerifiedSimulators\n DAL->>mobilecli: agentStatus(deviceId)\n alt Agent Not Installed\n DAL->>mobilecli: agentInstall(deviceId)\n end\n DAL->>DAL: Create MobileDevice(deviceId)\n else Not Found\n DAL-->>Client: Error: Device not found\n end\n end\n DAL-->>Server: Robot Instance\n Server-->>Client: Execute Tool\n```\n\n## Device Manager Classes\n\n### IosManager\n\nManages iOS device discovery and listing.\n\n**File:** `src/ios.ts`\n\n```typescript\nclass IosManager {\n listDevices(): IosDevice[];\n}\n```\n\n### AndroidDeviceManager\n\nManages Android device discovery via ADB.\n\n**File:** `src/android.ts`\n\n```typescript\nclass AndroidDeviceManager {\n getConnectedDevices(): AndroidDevice[];\n}\n```\n\n## mobilecli Integration\n\nThe mobilecli tool (`src/mobilecli.ts`) is the underlying CLI that provides cross-platform device management. It is a required dependency for the Device Abstraction Layer to function.\n\n**File:** `src/server.ts:8-16`\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### Key mobilecli Functions\n\n| Function | Purpose |\n|----------|---------|\n| `getVersion()` | Verify mobilecli installation |\n| `getDevices()` | List available devices by platform and type |\n| `agentStatus()` | Check if agent is installed on device |\n| `agentInstall()` | Install required agent on device |\n| `agentUninstall()` | Remove agent from device |\n\n## Simulator Agent Management\n\nFor iOS simulators, the DAL implements an agent verification and auto-installation system.\n\n**File:** `src/server.ts:45-58`\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\nThis ensures that:\n1. Each simulator is checked at most once per server session\n2. Missing agents are automatically installed\n3. The `agentVerifiedSimulators` Set prevents redundant installations\n\n## Error Handling\n\nThe DAL provides actionable error messages when device operations fail.\n\n| Error Condition | Response |\n|-----------------|----------|\n| mobilecli not available | Links to installation wiki |\n| Device not found | Lists available devices tool |\n| iOS Device Kit failure | Fallback mechanisms |\n\n**File:** `src/server.ts:15-16`\n\n```typescript\nthrow new ActionableError(`Device \"${deviceId}\" not found. \nUse the mobile_list_available_devices tool to see available devices.`);\n```\n\n## Usage in MCP Tools\n\nThe Device Abstraction Layer is invoked by all device interaction tools defined in the MCP server:\n\n**File:** `src/server.ts:63-90`\n\n| Tool | Operation |\n|------|-----------|\n| `mobile_list_available_devices` | Lists all connected devices |\n| `mobile_get_screen_size` | Delegates to active Robot |\n| `mobile_take_screenshot` | Delegates to active Robot |\n| `mobile_click_on_screen_at_coordinates` | Delegates to active Robot |\n| `mobile_type_keys` | Delegates to active Robot |\n| `mobile_press_button` | Delegates to active Robot |\n\n## Configuration\n\nThe DAL requires mobilecli as an optional dependency:\n\n**File:** `package.json:22-23`\n\n```json\n\"optionalDependencies\": {\n \"mobilecli\": \"0.3.70\"\n}\n```\n\n## Summary\n\nThe Device Abstraction Layer provides:\n\n- **Unified Interface**: A single `Robot` interface for all platform operations\n- **Platform Detection**: Automatic identification of iOS, Android, and simulator devices\n- **Factory Pattern**: Dynamic robot instantiation based on device type\n- **Agent Management**: Automatic verification and installation of required agents\n- **Error Context**: Actionable error messages with documentation links\n\nThis architecture enables mobile-mcp to provide a consistent automation experience across the diverse mobile device ecosystem while maintaining platform-specific optimizations.\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Device Management](#device-management), [App Management](#app-management), [Screen Interaction and Input](#screen-interaction)\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/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- [src/mobile-device.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n- [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe Mobile MCP server exposes a comprehensive set of tools that enable AI assistants to interact with mobile devices (iOS and Android) through the Model Context Protocol. These tools provide capabilities for device management, screen interaction, app lifecycle management, and UI automation. 资料来源：[README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\nThe tools are implemented in TypeScript and follow a consistent pattern where each tool accepts a `device` parameter to specify the target device identifier. 资料来源：[src/server.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Architecture\n\n### Tool Layer Hierarchy\n\n```mermaid\ngraph TD\n A[MCP Client
Claude, Cursor, Codex] --> B[Mobile MCP Server]\n B --> C[Robot Interface]\n C --> D[iOS Robot]\n C --> E[Android Robot]\n D --> F[WebDriverAgent]\n D --> G[iPhone Simulator]\n E --> H[Android ADB]\n F --> I[Real iOS Device]\n G --> J[iOS Simulator]\n H --> K[Android Emulator]\n H --> L[Android Device]\n```\n\n### Device Detection Flow\n\n```mermaid\ngraph TD\n A[getRobotFromDevice
deviceId: string] --> B{Is iOS Device?}\n B -->|Yes| C[Return IosRobot]\n B -->|No| D{Is Android Device?}\n D -->|Yes| E[Return AndroidRobot]\n D -->|No| F{Check iOS
Simulators?}\n F -->|Found| G[Return IosRobot]\n F -->|Not Found| H[Return Error]\n```\n\nThe `getRobotFromDevice` function determines the appropriate robot implementation based on the device type by querying device managers and checking against known device identifiers. 资料来源：[src/server.ts:15-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Tool Categories\n\n### Device Management Tools\n\n#### mobile_list_available_devices\n\nLists all available mobile devices including simulators, emulators, and connected physical devices.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | No | Optional device filter |\n\n**Response:** JSON array of device objects with `deviceId`, `name`, `platform`, and `status`.\n\n#### mobile_get_screen_size\n\nRetrieves the screen dimensions of the connected device in pixels.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** `{ \"width\": number, \"height\": number }`\n\n#### mobile_get_orientation\n\nReturns the current screen orientation of the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** `\"portrait\"` or `\"landscape\"` 资料来源：[src/mobile-device.ts:80-90](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n#### mobile_set_orientation\n\nChanges the screen orientation of the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `orientation` | string | Yes | `\"portrait\"` or `\"landscape\"` |\n\n```typescript\npublic async setOrientation(orientation: Orientation): Promise {\n this.runCommand([\"device\", \"orientation\", \"set\", orientation]);\n}\n```\n\n资料来源：[src/mobile-device.ts:75-79](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n---\n\n### App Management Tools\n\n#### mobile_list_apps\n\nLists all installed applications on the target device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Array of installed app objects containing `bundleId`, `name`, and `version`.\n\n#### mobile_launch_app\n\nLaunches an application by its package name (Android) or bundle identifier (iOS).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID (iOS) or package name (Android) |\n| `locale` | string | No | Optional locale to set before launching |\n\n```typescript\nlaunchApp(packageName: string, locale?: string): Promise;\n```\n\n#### mobile_terminate_app\n\nStops and terminates a running application. This is a no-op if the app is not running.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID or package name |\n\n#### mobile_install_app\n\nInstalls an application from a local file path. Supports `.apk`, `.ipa`, `.app`, and `.zip` formats.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_path` | string | Yes | Absolute path to the app file |\n\n**Implementation Note:** For iOS simulators, ZIP files are automatically extracted and the `.app` bundle is identified for installation. 资料来源：[src/iphone-simulator.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/iphone-simulator.ts)\n\n#### mobile_uninstall_app\n\nRemoves an installed application from the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `app_id` | string | Yes | Bundle ID or package name |\n\n---\n\n### Screen Interaction Tools\n\n#### mobile_take_screenshot\n\nCaptures the current screen and returns it as a PNG buffer for visual analysis.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Base64-encoded PNG image data.\n\n#### mobile_save_screenshot\n\nCaptures and saves a screenshot to a specified file path.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `path` | string | Yes | Destination file path |\n\n#### mobile_list_elements_on_screen\n\nRetrieves all interactive UI elements visible on the screen with their properties.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** Array of screen elements with the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `type` | string | Element type (TextField, Button, Switch, etc.) |\n| `label` | string | Accessibility label |\n| `text` | string | Display text content |\n| `name` | string | Element name |\n| `value` | string | Current value |\n| `identifier` | string | Unique element identifier |\n| `rect` | object | Position and dimensions `{x, y, width, height}` |\n| `focused` | boolean | Whether the element has focus |\n\n**Implementation Note:** For iOS, this uses WebDriverAgent's page source API. For Android, it uses the accessibility tree via `dump ui` command. 资料来源：[src/webdriver-agent.ts:50-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n#### mobile_click_on_screen_at_coordinates\n\nPerforms a tap action at specific screen coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n\n#### mobile_double_tap_on_screen\n\nPerforms a double-tap action at specific screen coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n\n**Implementation:** On iOS WebDriverAgent, this uses pointer actions with pause between taps. On Android, it may execute two sequential taps. 资料来源：[src/webdriver-agent.ts:120-150](https://github.com/mobile-next/mobile-mcp/blob/main/src/webdriver-agent.ts)\n\n#### mobile_long_press_on_screen_at_coordinates\n\nPerforms a long press gesture at specified coordinates.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n| `duration` | number | No | Press duration in milliseconds (default: 1000) |\n\n#### mobile_swipe_on_screen\n\nPerforms a swipe gesture in a specified direction.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `direction` | string | Yes | `up`, `down`, `left`, or `right` |\n| `start_x` | number | No | Starting X coordinate |\n| `start_y` | number | No | Starting Y coordinate |\n| `distance` | number | No | Swipe distance in pixels |\n\n---\n\n### Input & Navigation Tools\n\n#### mobile_type_keys\n\nTypes text into the currently focused element with optional submit action.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `text` | string | Yes | Text to type |\n| `submit` | boolean | No | Whether to press Enter after typing |\n\n```typescript\npublic async sendKeys(text: string): Promise {\n this.runCommand([\"io\", \"text\", text]);\n}\n```\n\n资料来源：[src/mobile-device.ts:50-52](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n#### mobile_press_button\n\nSimulates a physical button press on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `button` | string | Yes | Button name (see supported buttons) |\n\n**Supported Buttons:**\n\n| Platform | Buttons |\n|----------|---------|\n| Android | `home`, `back`, `up`, `down`, `left`, `right`, `enter`, `delete` |\n| iOS | `home`, `volumeUp`, `volumeDown` |\n\n#### mobile_open_url\n\nOpens a URL in the device's web browser or launches an app via custom URL scheme.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `url` | string | Yes | URL to open (https:// or custom scheme like `myapp://`) |\n\n---\n\n### Recording & Diagnostics Tools\n\n#### mobile_start_recording\n\nStarts screen recording on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `output_path` | string | No | Output file path |\n\n#### mobile_stop_recording\n\nStops the active screen recording and returns the output file information.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** File path, size in MB, and duration in seconds.\n\n#### mobile_list_crashes\n\nLists all crash reports available on the device.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n\n**Response:** JSON array of crash report objects with IDs and timestamps.\n\n#### mobile_get_crash\n\nRetrieves the full content of a specific crash report.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `device` | string | Yes | Target device identifier |\n| `crash_id` | string | Yes | Crash report identifier |\n\n---\n\n## Robot Interface\n\nThe `Robot` interface defines the contract for all mobile device implementations:\n\n```typescript\ninterface Robot {\n // URL and Input\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): Promise;\n \n // Touch Gestures\n tap(x: number, y: number): Promise;\n doubleTap(x: number, y: number): Promise;\n longPress(x: number, y: number, duration: number): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n \n // Screen\n getScreenshot(): Promise;\n getElementsOnScreen(): Promise;\n setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n \n // App Management\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\n资料来源：[src/robot.ts:1-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Platform-Specific Implementations\n\n### iOS Implementation\n\nThe iOS robot uses WebDriverAgent (WDA) for real devices and simctl for simulators:\n\n```mermaid\ngraph TD\n A[IosRobot] --> B{Device Type?}\n B -->|Real Device| C[WebDriverAgent]\n C --> D[WDA REST API]\n D --> E[WDA Port Forwarding]\n E --> F[iOS Device]\n B -->|Simulator| G[iPhone Simulator]\n G --> H[simctl CLI]\n H --> I[Xcode Simulator]\n```\n\n**Port Requirements for Real iOS Devices:**\n\n| Service | Port |\n|---------|------|\n| iOS Tunnel | 28000 |\n| WDA Forward | 8100 |\n\nThe tunnel must be running and port forwarding established before WDA operations can proceed. 资料来源：[src/ios.ts:30-80](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Implementation\n\nThe Android robot uses ADB (Android Debug Bridge) for all device interactions:\n\n```mermaid\ngraph TD\n A[AndroidRobot] --> B[ADB Commands]\n B --> C[UI Interaction: tap, swipe, text input]\n B --> D[App Management: install, uninstall, launch]\n B --> E[Device Info: orientation, screen size]\n B --> F[Accessibility: dump ui tree]\n```\n\n**Android Element Discovery:**\n\nThe `dump ui` command returns a JSON response containing the accessibility tree:\n\n```typescript\npublic async getElementsOnScreen(): Promise {\n const response = JSON.parse(this.runCommand([\"dump\", \"ui\"])) as DumpUIResponse;\n return response.data.elements.map(element => ({\n type: element.type,\n label: element.label,\n text: element.text,\n name: element.name,\n value: element.value,\n identifier: element.identifier,\n rect: element.rect,\n focused: element.focused,\n }));\n}\n```\n\n资料来源：[src/mobile-device.ts:55-70](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobile-device.ts)\n\n## Tool Configuration\n\n### Standard Configuration\n\nMost MCP clients use the following standard configuration:\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 Mode\n\nFor network-based connections, enable SSE mode with optional authentication:\n\n```bash\n# Basic SSE server\nnpx @mobilenext/mobile-mcp@latest --listen 3000\n\n# With authentication\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\n| Parameter | Description |\n|-----------|-------------|\n| `--listen` | Port to bind the SSE server |\n| `MOBILEMCP_AUTH` | Bearer token for authorization |\n\n---\n\n## Error Handling\n\nAll tools validate device availability and return structured errors. Common error scenarios:\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| `Device not found` | Invalid device identifier | Use `mobile_list_available_devices` |\n| `iOS tunnel not running` | Missing port forwarding | See [wiki](https://github.com/mobile-next/mobile-mcp/wiki/) |\n| `WDA not running` | WebDriverAgent crashed | Restart WDA on device |\n| `App not installed` | Invalid bundle ID | Verify with `mobile_list_apps` |\n\nThe `ActionableError` class provides user-friendly messages with links to troubleshooting documentation. 资料来源：[src/server.ts:20-30](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n---\n\n## Quick Reference\n\n### Essential Tools for UI Automation\n\n| Task | Primary Tool | Secondary Tool |\n|------|--------------|----------------|\n| View screen | `mobile_take_screenshot` | `mobile_list_elements_on_screen` |\n| Tap element | `mobile_click_on_screen_at_coordinates` | - |\n| Type text | `mobile_type_keys` | - |\n| Scroll | `mobile_swipe_on_screen` | - |\n| Navigate back | `mobile_press_button` (back) | - |\n\n### Device-Specific Tools\n\n| Capability | iOS | Android |\n|------------|-----|---------|\n| Real device | Yes | Yes |\n| Simulator | Yes | No |\n| Emulator | No | Yes |\n| WebDriverAgent | Yes (real) | N/A |\n| ADB | N/A | Yes |\n\n---\n\n\n\n## Device Management\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [Device Abstraction Layer](#device-abstraction)\n\n\nRelevant Source Files
\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/mobilecli.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/mobilecli.ts)\n- [src/utils.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/utils.ts)\n- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# Device Management\n\n## Overview\n\nDevice Management in Mobile MCP provides a unified abstraction layer for controlling mobile devices across iOS and Android platforms. It enables AI agents to interact with physical devices, simulators, and emulators through a consistent set of tools and APIs, abstracting platform-specific implementation details.\n\n资料来源：[src/server.ts:1-50]()\n\n## Architecture\n\nThe Device Management system follows a layered architecture:\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[Device Manager]\n B --> C[iOS Manager]\n B --> D[Android Manager]\n B --> E[Mobile CLI]\n C --> F[iOS Robot]\n D --> G[Android Robot]\n E --> H[Mobile Device]\n F --> I[Physical Device / Simulator]\n G --> J[Emulator / Physical Device]\n H --> K[iOS Simulator]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `Robot` interface | `src/robot.ts` | Defines unified device interaction contract |\n| `IosRobot` | Platform-specific | Handles iOS device communication |\n| `AndroidRobot` | Platform-specific | Handles Android device communication |\n| `MobileDevice` | Platform-specific | Handles iOS simulators via mobilecli |\n| `IosManager` | Internal | iOS device discovery and management |\n| `AndroidDeviceManager` | Internal | Android device discovery and management |\n\n资料来源：[src/robot.ts:1-50]()\n\n## Device Discovery\n\nDevice discovery is performed through the `getRobotFromDevice()` function, which identifies the device type and returns the appropriate robot implementation.\n\n```mermaid\ngraph TD\n A[Start] --> B{Check iOS Devices}\n B -->|Found| C[Return IosRobot]\n B -->|Not Found| D{Check Android Devices}\n D -->|Found| E[Return AndroidRobot]\n D -->|Not Found| F{Check Simulators via mobilecli}\n F -->|Simulator Found| G[Verify Agent Status]\n G -->|Status Failed| H[Install Agent]\n G -->|Status OK| I[Return MobileDevice]\n F -->|Not Found| J[Throw Error]\n```\n\n### Device Detection Flow\n\nThe detection sequence in `src/server.ts`:\n\n1. **iOS Physical Devices**: Uses `IosManager.listDevices()` to enumerate iOS devices\n2. **Android Physical Devices**: Uses `AndroidDeviceManager.getConnectedDevices()` to enumerate Android devices\n3. **iOS Simulators**: Uses `mobilecli.getDevices()` with `platform: \"ios\"` and `type: \"simulator\"`\n\n资料来源：[src/server.ts:50-100]()\n\n## Device Types Supported\n\n### Platform Matrix\n\n| Platform | Physical Devices | Simulators/Emulators | Key Technologies |\n|----------|------------------|---------------------|------------------|\n| iOS | iPhone, iPad | iOS Simulator | WebDriverAgent, iOS Device Kit |\n| Android | Samsung, Pixel, etc. | Android Emulator | ADB, UI Automator |\n\n### Simulator Agent Verification\n\nWhen connecting to iOS simulators, Mobile MCP performs agent verification:\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:75-85]()\n\n## Robot Interface\n\nThe `Robot` interface in `src/robot.ts` defines all device interaction methods:\n\n### Screen Operations\n\n| Method | Purpose | Return Type |\n|--------|---------|-------------|\n| `getScreenshot()` | Capture screen as PNG | `Promise` |\n| `getScreenSize()` | Get screen dimensions | `Promise<{width, height}>` |\n| `getOrientation()` | Get current orientation | `Promise` |\n| `setOrientation()` | Set portrait/landscape | `Promise` |\n\n### Touch Interactions\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `tap(x, y)` | Single tap | x, y coordinates |\n| `doubleTap(x, y)` | Double tap | x, y coordinates |\n| `longPress(x, y, duration)` | Long press | x, y, duration (ms) |\n| `swipeFromCoordinate(x, y, direction, distance?)` | Swipe gesture | x, y, direction, optional distance |\n\n### App Management\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `listApps()` | List installed apps | None |\n| `launchApp(packageName, locale?)` | Launch app | package name, optional locale |\n| `terminateApp(packageName)` | Stop app | package name |\n| `installApp(path)` | Install from file | file path (.apk, .ipa, .app, .zip) |\n| `uninstallApp(bundleId)` | Uninstall app | bundle ID/package name |\n\n### Navigation & Input\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `sendKeys(text)` | Type text | string |\n| `pressButton(button)` | Press button | Button enum (HOME, BACK, etc.) |\n| `openUrl(url)` | Open URL/browser | URL string |\n\n资料来源：[src/robot.ts:50-120]()\n\n## Available Tools\n\nMobile MCP exposes the following device management tools to MCP clients:\n\n### Device Information\n\n- `mobile_list_available_devices` - List all connected devices (physical and simulators)\n- `mobile_get_screen_size` - Get screen dimensions in pixels\n- `mobile_get_orientation` - Get current screen orientation\n- `mobile_set_orientation` - Change screen orientation (portrait/landscape)\n- `mobile_list_crashes` - List crash reports on device\n- `mobile_get_crash` - Retrieve full crash report content\n\n### Screen Interaction\n\n- `mobile_take_screenshot` - Capture screenshot\n- `mobile_save_screenshot` - Save screenshot to file\n- `mobile_list_elements_on_screen` - Get UI elements with coordinates\n- `mobile_click_on_screen_at_coordinates` - Click at x,y\n- `mobile_double_tap_on_screen` - Double tap at x,y\n- `mobile_long_press_on_screen_at_coordinates` - Long press at x,y\n- `mobile_swipe_on_screen` - Swipe in direction\n\n### Input & Navigation\n\n- `mobile_type_keys` - Type text into focused elements\n- `mobile_press_button` - Press device buttons\n- `mobile_open_url` - Open URL in browser\n\n### App Management\n\n- `mobile_list_apps` - List installed apps\n- `mobile_launch_app` - Launch app by package name\n- `mobile_terminate_app` - Stop running app\n- `mobile_install_app` - Install from file\n- `mobile_uninstall_app` - Uninstall app\n\n## Prerequisites\n\nDevice management requires the `mobilecli` tool to be available on the system. The server validates this on startup:\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...`);\n }\n};\n```\n\n资料来源：[src/server.ts:20-35]()\n\n## Configuration\n\n### MCP Server Configuration\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 Mode with Authentication\n\n```bash\nMOBILEMCP_AUTH=my-secret-token npx @mobilenext/mobile-mcp@latest --listen 3000\n```\n\nWhen `MOBILEMCP_AUTH` is set, all requests require the header:\n```\nAuthorization: Bearer my-secret-token\n```\n\n资料来源：[package.json:1-30]()\n\n## Error Handling\n\nThe device management system uses `ActionableError` to provide users with actionable error messages:\n\n```typescript\nthrow new ActionableError(\n `Device \"${deviceId}\" not found. Use the mobile_list_available_devices tool to see available devices.`\n);\n```\n\nThis pattern ensures users receive guidance on how to resolve issues, not just failure messages.\n\n资料来源：[src/server.ts:95-100]()\n\n## Dependencies\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| `@modelcontextprotocol/sdk` | 1.26.0 | MCP protocol implementation |\n| `mobilecli` | 0.3.70 (optional) | Cross-platform mobile CLI |\n| `express` | 5.1.0 | SSE server transport |\n| `zod` | ^4.1.13 | Schema validation |\n\n资料来源：[package.json:25-50]()\n\n## See Also\n\n- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n- [Installation Guide](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki)\n\n---\n\n\n\n## App Management\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-implementation)\n\n\nRelevant Source Files
\n\nThe following source files were used to generate this documentation:\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- [package.json](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n \n\n# App Management\n\nApp Management in Mobile MCP enables AI agents to interact with mobile applications on connected devices through a unified interface. This system provides capabilities for listing, launching, terminating, installing, and uninstalling applications across both iOS and Android platforms.\n\n## Overview\n\nThe App Management feature abstracts platform-specific implementation details behind a consistent Robot interface. This allows AI agents to manage applications without understanding the underlying differences between iOS and Android platforms.\n\n```mermaid\ngraph TD\n A[MCP Client / AI Agent] --> B[Mobile MCP Server]\n B --> C[Robot Interface]\n C --> D[iOS Robot]\n C --> E[Android Robot]\n D --> F[WebDriverAgent / go-ios]\n E --> G[ADB / Android Manager]\n```\n\n**资料来源：** [src/robot.ts:1-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Available Tools\n\nMobile MCP exposes five primary tools for application management:\n\n| Tool | Description | Platform |\n|------|-------------|----------|\n| `mobile_list_apps` | List all installed applications | iOS, Android |\n| `mobile_launch_app` | Launch an app by package/bundle name | iOS, Android |\n| `mobile_terminate_app` | Stop a running application | iOS, Android |\n| `mobile_install_app` | Install app from file (.apk, .ipa, .app, .zip) | iOS, Android |\n| `mobile_uninstall_app` | Uninstall app by bundle ID or package name | iOS, Android |\n\n**资料来源：** [README.md](https://github.com/mobile-next/mobile-mcp/blob/main/README.md)\n\n## Robot Interface\n\nThe core App Management functionality is defined in the `Robot` interface. This interface declares abstract methods that platform-specific implementations must provide.\n\n```typescript\ninterface Robot {\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 openUrl(url: string): Promise;\n}\n```\n\n**资料来源：** [src/robot.ts:40-75](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n### Method Specifications\n\n#### listApps()\n\nReturns all installed applications on the device.\n\n```typescript\nlistApps(): Promise;\n```\n\n**Return Type:** `InstalledApp[]` - Array of objects containing package names (Android) or bundle identifiers (iOS).\n\n#### launchApp()\n\nLaunches an application with optional locale specification.\n\n```typescript\nlaunchApp(packageName: string, locale?: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `packageName` | `string` | The package name (Android) or bundle ID (iOS) of the app |\n| `locale` | `string` (optional) | Locale to launch the app with (e.g., \"en_US\") |\n\n**资料来源：** [src/robot.ts:47-49](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n#### terminateApp()\n\nTerminates a running application. If the app is not running or doesn't exist, this operation is a no-op.\n\n```typescript\nterminateApp(packageName: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `packageName` | `string` | The package name (Android) or bundle ID (iOS) |\n\n#### installApp()\n\nInstalls an application from a local file path. Supports multiple formats across platforms.\n\n```typescript\ninstallApp(path: string): Promise;\n```\n\n**Supported Formats:**\n| Platform | Formats |\n|----------|---------|\n| Android | `.apk`, `.zip` |\n| iOS | `.ipa`, `.app`, `.zip` |\n\n#### uninstallApp()\n\nUninstalls an application from the device.\n\n```typescript\nuninstallApp(bundleId: string): Promise;\n```\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `bundleId` | `string` | The app's bundle identifier (iOS) or package name (Android) |\n\n#### openUrl()\n\nOpens a URL in the device's web browser.\n\n```typescript\nopenUrl(url: string): Promise;\n```\n\n**Supported URL Schemes:**\n| Type | Example |\n|------|---------|\n| HTTP/HTTPS | `https://example.com` |\n| Custom Schemes | `myapp://action` |\n\n**资料来源：** [src/robot.ts:59-63](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n\n## Architecture\n\n### Device Selection Flow\n\nWhen a tool requires device-specific implementation, the server determines the appropriate Robot based on the device type:\n\n```mermaid\ngraph TD\n A[Device ID Provided] --> B{Is iOS Device?}\n B -->|Yes| C[Return IosRobot]\n B -->|No| D{Is Android Device?}\n D -->|Yes| E[Return AndroidRobot]\n D -->|No| F{Is Simulator?}\n F -->|Yes| G[Return MobileDevice]\n F -->|No| H[Throw ActionableError]\n```\n\n**资料来源：** [src/server.ts:30-60](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n### iOS Implementation\n\nThe iOS implementation leverages `go-ios` (via `mobilecli`) for device communication. The `IosManager` handles device detection and the `WebDriverAgent` protocol manages application lifecycle.\n\nKey components in iOS app management:\n\n1. **WebDriverAgent (WDA)** - Apple's testing framework for iOS\n2. **go-ios** - Command-line interface for iOS device control\n3. **Tunnel Service** - Required for real device communication\n\n**资料来源：** [src/ios.ts:1-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Implementation\n\nAndroid implementation uses the Android Debug Bridge (ADB) through the Android Manager:\n\n1. **ADB** - Primary communication protocol with Android devices\n2. **Android Manager** - Handles device enumeration and app operations\n3. **Package Manager** - Manages app installation and uninstallation\n\n## Tool Registration\n\nApp Management tools are registered in the server with descriptive schemas:\n\n```typescript\ntool(\n \"mobile_list_apps\",\n \"List Apps\",\n \"List all installed apps on the device\",\n {},\n { readOnlyHint: true },\n async ({}) => { /* implementation */ }\n);\n```\n\n**资料来源：** [src/server.ts:80-100](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Prerequisites\n\n### iOS Requirements\n- WebDriverAgent must be running on the device\n- For real devices: iOS tunnel must be established\n- go-ios must be installed and functional\n\n**资料来源：** [src/ios.ts:35-45](https://github.com/mobile-next/mobile-mcp/blob/main/src/ios.ts)\n\n### Android Requirements\n- ADB must be enabled on the device\n- Device must be connected and authorized\n- USB debugging must be enabled\n\n## Usage Examples\n\n### List All Installed Apps\n\n```json\n{\n \"tool\": \"mobile_list_apps\",\n \"arguments\": {}\n}\n```\n\n### Launch an App with Locale\n\n```json\n{\n \"tool\": \"mobile_launch_app\",\n \"arguments\": {\n \"packageName\": \"com.example.app\",\n \"locale\": \"en_US\"\n }\n}\n```\n\n### Install an App\n\n```json\n{\n \"tool\": \"mobile_install_app\",\n \"arguments\": {\n \"path\": \"/path/to/application.apk\"\n }\n}\n```\n\n### Uninstall an App\n\n```json\n{\n \"tool\": \"mobile_uninstall_app\",\n \"arguments\": {\n \"bundleId\": \"com.example.app\"\n }\n}\n```\n\n### Open URL in Browser\n\n```json\n{\n \"tool\": \"mobile_open_url\",\n \"arguments\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n## Error Handling\n\nThe system provides actionable error messages when operations fail. Common error scenarios include:\n\n| Error Condition | Cause | Resolution |\n|-----------------|-------|------------|\n| Device not found | Invalid device ID or disconnected device | Check device connection |\n| App not installed | Attempting to launch non-existent app | Install app first |\n| Installation failed | Invalid file format or corrupted package | Verify file integrity |\n| Permission denied | Insufficient device permissions | Grant required permissions |\n\n**资料来源：** [src/server.ts:45-50](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n\n## Dependencies\n\nApp Management relies on the following package:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mobilecli` | 0.3.70 | Cross-platform mobile device CLI |\n\n**资料来源：** [package.json:25-30](https://github.com/mobile-next/mobile-mcp/blob/main/package.json)\n\n---\n\n\n\n## Screen Interaction and Input\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#mcp-tools-reference), [iOS Implementation](#ios-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/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 \n\n# Screen Interaction and Input\n\n## Overview\n\nThe Screen Interaction and Input system in Mobile MCP provides a comprehensive abstraction layer for controlling mobile devices (iOS, Android, simulators, and emulators) through a unified Robot interface. This system enables AI agents to interact with mobile applications by simulating user input events, capturing screen content, and managing device orientation.\n\nThe architecture is designed to work with multiple device platforms while presenting a consistent API to MCP clients. The system leverages native accessibility trees for most interactions, falling back to screenshot-based coordinate operations when accessibility labels are unavailable. 资料来源：[src/robot.ts:1-30]()\n\n## Architecture\n\n### Core Components\n\nThe system consists of three primary device abstraction layers:\n\n| Component | Platform | Protocol | File |\n|-----------|----------|----------|------|\n| `IosRobot` | iOS | WebDriverAgent (WDA) | [src/webdriver-agent.ts:1-50]() |\n| `AndroidRobot` | Android | mobilecli | [src/mobile-device.ts:1-30]() |\n| `Robot` (interface) | All | Abstract | [src/robot.ts:1-50]() |\n\n### Robot Interface Contract\n\nThe `Robot` interface defines the contract that all platform-specific implementations must fulfill:\n\n```typescript\ninterface Robot {\n openUrl(url: string): Promise;\n sendKeys(text: string): Promise;\n pressButton(button: Button): 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 getElementsOnScreen(): Promise;\n setOrientation(orientation: Orientation): Promise;\n getOrientation(): Promise;\n swipeFromCoordinate(x: number, y: number, direction: SwipeDirection, distance?: number): Promise;\n getScreenshot(): Promise;\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\n资料来源：[src/robot.ts:30-100]()\n\n### Device Selection Flow\n\nThe server determines which Robot implementation to use based on the device identifier:\n\n```mermaid\ngraph TD\n A[MCP Request with device ID] --> B{Device Type Check}\n B -->|iOS Device| C[IosRobot]\n B -->|Android Device| D[AndroidRobot]\n B -->|Simulator| E[IosRobot]\n C --> F[WebDriverAgent Connection]\n D --> G[mobilecli Commands]\n E --> F\n```\n\n资料来源：[src/server.ts:50-80]()\n\n## Touch Interactions\n\n### Tap Operations\n\n#### Single Tap\n\nSingle tap is implemented using pointer actions sent through the WebDriverAgent protocol for iOS:\n\n```typescript\npublic async tap(x: number, y: number) {\n await this.withinSession(async sessionUrl => {\n const url = `${sessionUrl}/actions`;\n await fetch(url, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n actions: [{\n type: \"pointer\",\n id: \"finger1\",\n parameters: { pointerType: \"touch\" },\n actions: [\n { type: \"pointerMove\", duration: 0, x, y },\n { type: \"pointerDown\", button: 0 },\n { type: \"pause\", duration: 100 },\n { type: \"pointerUp\", button: 0 }\n ]\n }]\n }),\n });\n });\n}\n```\n\n资料来源：[src/webdriver-agent.ts:180-210]()\n\nFor Android, the tap operation uses the mobilecli command:\n\n```typescript\npublic async tap(x: number, y: number): Promise {\n this.runCommand([\"io\", \"tap\", `${x},${y}`]);\n}\n```\n\n资料来源：[src/mobile-device.ts:50-52]()\n\n#### Double Tap\n\nDouble tap is implemented by executing two consecutive tap operations:\n\n```typescript\npublic async doubleTap(x: number, y: number): Promise {\n await this.tap(x, y);\n await this.tap(x, y);\n}\n```\n\n资料来源：[src/mobile-device.ts:56-60]()\n\nIn iOS WebDriverAgent, the double tap uses the W3C Actions API with multiple pointer sequences.\n\n#### Long Press\n\nLong press requires specifying the duration in milliseconds:\n\n```typescript\npublic async longPress(x: number, y: number, duration: number): Promise {\n this.runCommand([\"io\", \"longpress\", `${x},${y}`, \"--duration\", `${duration}`]);\n}\n```\n\n资料来源：[src/mobile-device.ts:62-64]()\n\nThe iOS implementation uses the Actions API with extended pointerDown duration:\n\n```typescript\n{ type: \"pointerDown\", button: 0 },\n{ type: \"pause\", duration: duration },\n{ type: \"pointerUp\", button: 0 }\n```\n\n### Swipe Gestures\n\nSwipe gestures calculate coordinates based on screen dimensions, using 60% of the screen width or height as the swipe distance:\n\n```typescript\nconst verticalDistance = Math.floor(screenSize.height * 0.6);\nconst horizontalDistance = Math.floor(screenSize.width * 0.6);\nconst centerX = Math.floor(screenSize.width / 2);\nconst centerY = Math.floor(screenSize.height / 2);\n```\n\n资料来源：[src/webdriver-agent.ts:130-135]()\n\nThe swipe direction determines the start and end coordinates:\n\n| Direction | X Movement | Y Movement |\n|-----------|------------|------------|\n| up | centerX | centerY ± verticalDistance/2 |\n| down | centerX | centerY ± verticalDistance/2 |\n| left | centerX ± horizontalDistance/2 | centerY |\n| right | centerX ± horizontalDistance/2 | centerY |\n\n## Text Input\n\n### Keyboard Input\n\nText input is handled through different mechanisms per platform:\n\n**iOS (via WebDriverAgent):**\n```typescript\npublic async sendKeys(text: string): Promise {\n await this.withinSession(async sessionUrl => {\n await fetch(`${sessionUrl}/wda/keys`, {\n method: \"POST\",\n body: JSON.stringify({ value: text.split(\"\") }),\n });\n });\n}\n```\n\n**Android (via mobilecli):**\n```typescript\npublic async typeText(text: string): Promise {\n this.runCommand([\"io\", \"text\", text]);\n}\n```\n\n资料来源：[src/mobile-device.ts:42-44]()\n\n### Button Presses\n\nPhysical device buttons are mapped to platform-specific commands:\n\n| Button | iOS Action | Android Command |\n|--------|------------|-----------------|\n| HOME | `wda/pressButton` | `io button home` |\n| BACK | N/A | `io button back` |\n| POWER | N/A | `io button power` |\n| ENTER | sendKeys \"\\n\" | `io button enter` |\n| VOLUME_UP | `wda/pressButton` | `io button volume_up` |\n| VOLUME_DOWN | `wda/pressButton\" | `io button volume_down` |\n\n资料来源：[src/webdriver-agent.ts:150-175]()\n\n## Screen Capture\n\n### Screenshot Retrieval\n\nScreenshots are retrieved as PNG buffers through platform-specific protocols:\n\n**iOS WebDriverAgent:**\n```typescript\npublic async getScreenshot(): Promise {\n const url = `http://${this.host}:${this.port}/screenshot`;\n const response = await fetch(url);\n const json = await response.json();\n return Buffer.from(json.value, \"base64\");\n}\n```\n\n资料来源：[src/webdriver-agent.ts:100-106]()\n\n**Android (via mobilecli):** Screenshots are captured using the platform's native screenshot mechanism through the `dump` command.\n\n## UI Element Discovery\n\n### Element Filtering\n\nThe system filters accessibility elements to return only actionable UI components:\n\n```typescript\nconst acceptedTypes = [\n \"TextField\", \n \"Button\", \n \"Switch\", \n \"Icon\", \n \"SearchField\", \n \"StaticText\", \n \"Image\"\n];\n```\n\n资料来源：[src/webdriver-agent.ts:30-32]()\n\nElement visibility is determined by checking both the `isVisible` flag and bounds:\n\n```typescript\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({ /* element data */ });\n }\n }\n}\n```\n\n### Element Data Structure\n\nEach screen element contains:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| type | string | Element type (Button, TextField, etc.) |\n| label | string | Accessibility label |\n| name | string | Element name |\n| value | string | Current value (for text fields) |\n| identifier | string | Platform-specific identifier |\n| rect | {x, y, width, height} | Bounding rectangle |\n| focused | boolean | Focus state |\n\n资料来源：[src/mobile-device.ts:66-76]()\n\n## Orientation Management\n\nDevice orientation can be queried and changed:\n\n```typescript\npublic async setOrientation(orientation: Orientation): Promise {\n this.runCommand([\"device\", \"orientation\", \"set\", orientation]);\n}\n\npublic async getOrientation(): Promise {\n const response = JSON.parse(this.runCommand([\"device\", \"orientation\", \"get\"])) as OrientationResponse;\n return response.data.orientation;\n}\n```\n\n资料来源：[src/mobile-device.ts:78-85]()\n\nSupported orientations: `\"portrait\"` | `\"landscape\"`\n\n## Connection Prerequisites\n\n### iOS Requirements\n\niOS devices require several connection layers to be operational:\n\n```mermaid\ngraph LR\n A[MCP Server] --> B[iOS Tunnel]\n B --> C[WDA Port Forward]\n C --> D[WebDriverAgent]\n D --> E[iOS Device]\n \n F[Check: Tunnel Running] --> B\n G[Check: WDA Forward Running] --> C\n H[Check: WDA isRunning] --> D\n```\n\n资料来源：[src/ios.ts:30-60]()\n\nThe system verifies:\n\n1. **Tunnel Running** - Required for remote iOS devices\n2. **WDA Port Forward** - TCP port forwarding to WebDriverAgent\n3. **WebDriverAgent Status** - Actual running state of WDA on device\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```\n\n## MCP Tools Interface\n\nThe server exposes the following screen interaction tools:\n\n| Tool Name | Description | Parameters |\n|-----------|-------------|------------|\n| `mobile_take_screenshot` | Capture current screen | device |\n| `mobile_list_elements_on_screen` | Get UI elements | device |\n| `mobile_click_on_screen_at_coordinates` | Tap at coordinates | device, x, y |\n| `mobile_double_tap_on_screen` | Double tap | device, x, y |\n| `mobile_long_press_on_screen_at_coordinates` | Long press | device, x, y, duration |\n| `mobile_swipe_on_screen` | Swipe gesture | device, direction |\n| `mobile_type_keys` | Text input | device, text, submit |\n| `mobile_get_orientation` | Query orientation | device |\n| `mobile_set_orientation` | Set orientation | device, orientation |\n\n## Usage Examples\n\n### Basic Screen Interaction Workflow\n\n```typescript\n// 1. List available devices\nconst devices = await listAvailableDevices();\n\n// 2. Get screen elements\nconst elements = await getElementsOnScreen(deviceId);\n\n// 3. Tap on a button by coordinates\nawait tap(deviceId, 150, 300);\n\n// 4. Type text into a field\nawait typeKeys(deviceId, \"Hello World\", false);\n\n// 5. Swipe up to scroll\nawait swipe(deviceId, \"up\");\n\n// 6. Take screenshot to verify\nconst screenshot = await getScreenshot(deviceId);\n```\n\n### Complete User Journey Automation\n\n```typescript\n// Open app and perform multi-step interaction\nawait launchApp(deviceId, \"com.example.app\");\nawait swipe(deviceId, \"up\");\nconst elements = await getElementsOnScreen(deviceId);\nconst loginButton = elements.find(e => e.name === \"Login\");\nawait tap(deviceId, loginButton.rect.x + 10, loginButton.rect.y + 10);\nawait typeKeys(deviceId, \"user@example.com\", false);\nawait pressButton(deviceId, \"ENTER\");\n```\n\n## Error Handling\n\nThe system provides actionable error messages with troubleshooting links:\n\n```typescript\nthrow new ActionableError(\n `mobilecli is not available or not working properly. \n Please review the documentation at \n https://github.com/mobile-next/mobile-mcp/wiki`\n);\n```\n\n资料来源：[src/server.ts:20-25]()\n\nCommon error scenarios:\n\n| Error Condition | Cause | Resolution |\n|----------------|-------|------------|\n| \"iOS tunnel is not running\" | Remote device connection issue | Start tunnel per wiki instructions |\n| \"Port forwarding not running\" | WDA port not forwarded | Configure port forwarding |\n| \"WebDriverAgent not running\" | WDA crashed on device | Restart WDA on iOS device |\n\n## Performance Considerations\n\n- **Element queries** use native accessibility trees for speed\n- **Screenshots** are transferred as base64-encoded PNG\n- **Gestures** are calculated as percentages of screen dimensions\n- **Timeouts** for recording operations default to 5 minutes (300 seconds)\n\n---\n\n\n\n## iOS Implementation\n\n### 相关页面\n\n相关主题：[Device Abstraction Layer](#device-abstraction), [Screen Interaction and Input](#screen-interaction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [src/robot.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/robot.ts)\n- [src/server.ts](https://github.com/mobile-next/mobile-mcp/blob/main/src/server.ts)\n \n\n# iOS Implementation\n\n## Overview\n\nThe iOS Implementation module provides comprehensive automation capabilities for iOS devices, including physical devices, simulators, and emulators. This module serves as a bridge between the Mobile MCP server and iOS testing infrastructure, enabling AI agents to interact with iOS applications through accessibility trees and coordinate-based input.\n\n**Purpose:** The iOS Implementation enables native app automation for iOS testing, scripted flows, and multi-step user journeys driven by LLMs.\n\n**Scope:** The module handles device detection, connection management, WebDriverAgent communication, tunnel port forwarding, and command execution via the go-ios library.\n\n资料来源：[src/ios.ts:1-50]()\n\n## Architecture\n\nThe iOS implementation follows a layered architecture that separates device management, robot control, and protocol communication.\n\n```mermaid\ngraph TD\n A[MCP Server] --> B[IosManager]\n A --> C[IosRobot]\n B --> D[go-ios / mobilecli]\n C --> E[WebDriverAgent]\n C --> F[iOS Device Kit]\n E --> G[Physical iOS Device]\n F --> G\n D --> H[iOS Simulator]\n I[iPhone Simulator] --> H\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|-----------------|\n| IosManager | src/server.ts | Device discovery and listing |\n| IosRobot | src/server.ts | Device interaction via Robot interface |\n| IosDeviceConnection | src/ios.ts | Connection and tunnel management |\n| WebDriverAgent | src/webdriver-agent.ts | UI automation protocol |\n| iPhone Simulator | src/iphone-simulator.ts | Simulator-specific operations |\n\n资料来源：[src/server.ts:30-80]()\n\n## Device Detection\n\nThe system uses a multi-step detection process to identify iOS device types and establish appropriate communication channels.\n\n### Device Type Resolution\n\n```mermaid\ngraph TD\n A[Device ID] --> B{IosManager listDevices?}\n B -->|Found| C[IosRobot]\n B -->|Not Found| D{AndroidDeviceManager?}\n D -->|Found| E[AndroidRobot]\n D -->|Not Found| F{mobilecli getDevices?}\n F -->|Simulator Found| G{MobileDevice}\n F -->|Not Found| H[Error: Device not found]\n```\n\nThe `getRobotFromDevice` function performs the following checks in order:\n\n1. **iOS Physical Devices:** Queries IosManager for connected iOS devices 资料来源：[src/server.ts:45-50]()\n2. **Android Devices:** Checks AndroidDeviceManager for matching device ID 资料来源：[src/server.ts:52-56]()\n3. **iOS Simulators:** Uses mobilecli with platform filter for simulators 资料来源：[src/server.ts:58-75]()\n\n### Simulator Agent Verification\n\nFor iOS simulators, the system automatically verifies and installs the agent if needed:\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:65-71]()\n\n## Connection Management\n\n### Port-Based Connection State\n\nThe iOS implementation uses port checking to verify connection states:\n\n```mermaid\ngraph LR\n A[Device] -->|USB Tunnel| B[localhost:PORT]\n B --> C{WDA Port Check}\n C -->|Listening| D[WebDriverAgent Ready]\n C -->|Not Listening| E[Error: Port forwarding not running]\n```\n\n#### Tunnel Requirements\n\nThe `isTunnelRequired` method determines when tunnel port forwarding is necessary based on connection type. When a tunnel is required but not running, the system throws an `ActionableError`:\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, please see https://github.com/mobile-next/mobile-mcp/wiki/\");\n }\n }\n}\n```\n\n资料来源：[src/ios.ts:45-50]()\n\n#### WebDriverAgent Port Forwarding\n\nConnection to WebDriverAgent requires both tunnel and port forwarding verification:\n\n```typescript\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 (tunnel okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\");\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 (tunnel okay, port forwarding okay), please see https://github.com/mobile-next/mobile-mcp/wiki/\");\n }\n\n return wda;\n}\n```\n\n资料来源：[src/ios.ts:55-70]()\n\n## Robot Interface Implementation\n\nThe IosRobot class implements the Robot interface, providing unified access to iOS device capabilities.\n\n### Supported Operations\n\n| Category | Operations |\n|----------|------------|\n| **Screen** | getScreenshot, getScreenSize, getOrientation, setOrientation |\n| **Touch** | tap, doubleTap, longPress, swipeFromCoordinate |\n| **Input** | sendKeys, pressButton |\n| **Navigation** | home, back, openUrl |\n| **Apps** | listApps, launchApp, terminateApp, installApp, uninstallApp |\n| **Elements** | getElementsOnScreen |\n\n资料来源：[src/robot.ts:1-80]()\n\n### iOS-Specific Considerations\n\n#### Accessibility Tree\n\nThe implementation uses native accessibility trees for element detection rather than computer vision, making it LLM-friendly and fast.\n\n> **Note:** The `getElementsOnScreen` method works only on native apps and will not function within webviews.\n\n资料来源：[src/robot.ts:40-45]()\n\n#### Long Press Duration\n\nThe long press operation accepts a custom duration parameter:\n\n```typescript\nlongPress(x: number, y: number, duration: number): Promise;\n```\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| x | number | X coordinate on screen |\n| y | number | Y coordinate on screen |\n| duration | number | Duration in milliseconds |\n\n资料来源：[src/robot.ts:35-38]()\n\n## WebDriverAgent Integration\n\nThe WebDriverAgent (WDA) serves as the primary automation protocol for iOS physical devices.\n\n### Connection Flow\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP Server\n participant Ios as IosDeviceConnection\n participant WDA as WebDriverAgent\n participant Device as iOS Device\n\n MCP->>Ios: wda()\n Ios->>Ios: assertTunnelRunning()\n Ios->>Ios: isWdaForwardRunning()\n Ios->>WDA: new WebDriverAgent(localhost, PORT)\n WDA->>Device: isRunning()\n Device-->>WDA: status\n WDA-->>Ios: WebDriverAgent instance\n Ios-->>MCP: Ready for commands\n```\n\n### Port Configuration\n\n| Port | Purpose | Configuration |\n|------|---------|---------------|\n| WDA_PORT | WebDriverAgent communication | localhost:PORT |\n| IOS_TUNNEL_PORT | USB tunnel forwarding | localhost:PORT |\n\n资料来源：[src/webdriver-agent.ts:1-30]()\n\n## iOS Simulator Support\n\nThe iPhone Simulator module provides specialized handling for iOS Simulator instances.\n\n### Simulator Detection\n\nSimulators are detected through mobilecli with the following parameters:\n\n```typescript\nconst response = mobilecli.getDevices({\n platform: \"ios\",\n type: \"simulator\",\n includeOffline: false,\n});\n```\n\n资料来源：[src/server.ts:58-62]()\n\n### Simulator vs Physical Device\n\n| Aspect | Simulator | Physical Device |\n|--------|-----------|------------------|\n| **Connection** | Direct via mobilecli | USB tunnel + WDA |\n| **Agent** | Auto-installed on demand | Manual setup required |\n| **Port Forwarding** | Not required | Required (WDA_PORT) |\n| **WebDriverAgent** | Optional auto-start | Required |\n\n资料来源：[src/iphone-simulator.ts:1-40]()\n\n## go-ios Integration\n\nThe implementation uses the go-ios binary for low-level iOS device communication.\n\n### Command Execution\n\n```typescript\nprivate async ios(...args: string[]): Promise {\n return execFileSync(getGoIosPath(), [\"--udid\", this.deviceId, ...args], {}).toString();\n}\n```\n\n资料来源：[src/ios.ts:75-77]()\n\n### Utility Functions\n\nThe system checks for mobilecli availability on startup:\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:22-32]()\n\n## Error Handling\n\n### Actionable Errors\n\nThe system throws `ActionableError` with user-friendly messages and documentation links:\n\n| Error Scenario | Message | Resolution Link |\n|----------------|---------|-----------------|\n| mobilecli unavailable | Installation instructions | [Wiki Installation](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Tunnel not running | Setup guide | [Wiki Tunnel Setup](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Port forwarding failed | Troubleshooting | [Wiki Debugging](https://github.com/mobile-next/mobile-mcp/wiki) |\n| WDA not running | Configuration guide | [Wiki WDA Setup](https://github.com/mobile-next/mobile-mcp/wiki) |\n| Device not found | Device list | mobile_list_available_devices tool |\n\n资料来源：[src/ios.ts:48-70]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| MOBILEMCP_AUTH | Bearer token for SSE authorization | None |\n\n### Port Constants\n\nThe system uses standard port configurations for iOS tunnel and WDA communication. Refer to the source code for current port values.\n\n## Platform Support Matrix\n\n| Platform | Version | Automation Method |\n|----------|---------|-------------------|\n| iOS Simulator | All versions | mobilecli + iOS Device Kit |\n| Physical iOS | iOS 13+ | WebDriverAgent via go-ios |\n| Real Device (debug) | iOS 13+ | USB tunnel + WDA |\n\n资料来源：[src/webdriver-agent.ts:20-30]()\n\n## Related Documentation\n\n- [Main README](https://github.com/mobile-next/mobile-mcp)\n- [Wiki Home](https://github.com/mobile-next/mobile-mcp/wiki)\n- [Setup Guide](https://github.com/mobile-next/mobile-mcp/wiki/Setup)\n- [Troubleshooting](https://github.com/mobile-next/mobile-mcp/wiki/Debugging)\n- [Prompt Examples](https://github.com/mobile-next/mobile-mcp/wiki/Prompt-Example-repo-list)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：mobile-next/mobile-mcp\n\n摘要：发现 20 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 维护坑 · 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## 20. 维护坑 · 发布节奏不明确\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摘要：发现 20 个潜在踩坑项，其中 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_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:956657893 | https://github.com/mobile-next/mobile-mcp | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：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## 14. 安全/权限坑 · 来源证据：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## 15. 安全/权限坑 · 来源证据：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## 16. 安全/权限坑 · 来源证据：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## 17. 安全/权限坑 · 来源证据：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## 18. 安全/权限坑 · 来源证据：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## 19. 维护坑 · 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## 20. 维护坑 · 发布节奏不明确\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for mobile-next/mobile-mcp.\n\nProject:\n- Name: mobile-mcp\n- Repository: https://github.com/mobile-next/mobile-mcp\n- Summary: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. prerequisites: Prerequisites. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-tools-reference: MCP Tools Reference. Produce one small intermediate artifact and wait for confirmation.\n5. screen-interaction: Screen Interaction and Input. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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/mobile-device.ts\n- src/mobilecli.ts\n- src/png.ts\n- src/image-utils.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}