MobiLoop

Name: MobiLoop
Author: enessubass

本地服务

enessubass.github.io开发工具112 周前更新

代码仓库访问官网

关于 MobiLoop

MobiLoop 是面向移动应用开发团队的受控 MCP 工具层，支持 Android 和 iOS 的构建、设备测试与验证。它通过日志、截图和断言收集证据并分类故障，默认不自动执行代码修补与重测。

主要功能

01Android 与 iOS 构建测试
02Appium 界面自动化
03截图、日志与 API 证据
04流程检查点记录与重放
05安全扫描与审批控制

适用场景

01运行移动端端到端测试
02依据设备证据排查失败
03扫描代码并评估安全修复

MCP 相关

提供一体化或按职责拆分的 MCP 服务，供 AI 客户端调用代码、构建、设备、Appium、验证、流程及安全工具。高影响操作可要求审批，并默认对文本中的常见敏感信息脱敏。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "enessubass-mobiloop": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MOBILOOP_WORKSPACE_ROOT",
        "-e",
        "APPIUM_SERVER_URL",
        "ghcr.io/enessubass/mobiloop-mcp:0.1.0-alpha.15"
      ],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "<MOBILOOP_WORKSPACE_ROOT>",
        "APPIUM_SERVER_URL": "<APPIUM_SERVER_URL>"
      }
    }
  }
}

启动命令docker run -i --rm -e MOBILOOP_WORKSPACE_ROOT -e APPIUM_SERVER_URL ghcr.io/enessubass/mobiloop-mcp:0.1.0-alpha.15

需要配置的环境变量

MOBILOOP_WORKSPACE_ROOTWorkspace path mounted into the container.

APPIUM_SERVER_URLAppium server URL reachable from the container.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocighcr.io/enessubass/mobiloop-mcp:0.1.0-alpha.15stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MobiLoop MCP

用于 Agent 移动端构建、测试和修复循环的防护型 MCP 服务。

文档站点 | 安装 | 安全模型 | 工具参考

code change -> build -> install on device -> Appium test -> evidence -> classify -> report

MobiLoop MCP 是 AI 编码 Agent 与真实移动开发环境之间的受控工具层。它允许 MCP 客户端读取和修改移动项目、构建项目、将其安装到 Android 或 iOS 目标设备上、通过 Appium 操控应用、验证日志／屏幕／API 结果、记住已知的应用流程检查点，并生成基于证据的报告。

这个名称体现了其核心约定：移动端工作应通过一个可衡量的循环进行，包括变更、构建、设备执行、验证和基于证据的问题分类。

它面向这样的工作流：Agent 不只是编写代码，还会构建、运行、测试、观察、分类故障，并提供证据。Agent 仍可使用独立的防护型代码工具进行修改和重新测试，但这一步有意排除在默认编排器之外。

目前，MobiLoop 提供防护型构建、测试和验证循环，以及基于证据的故障分类。在启用更严格的审批、回滚和审核控制之前，完全自动化的修改与重新测试有意排除在默认编排器之外。

亮点

证据优先的移动端循环：构建日志、屏幕截图、Appium XML 源码、logcat／模拟器日志、API 响应、屏幕截图差异和迭代记录。
Android 和 iOS 工具分离：Android adb／模拟器工具与 iOS xcrun simctl／xcodebuild 工具分开。
Appium UI 自动化：语义化点击、输入、滑动、返回导航、可见性断言、屏幕截图和无障碍摘要。
流程记忆：记录运行时屏幕检查点、记住最近一次通过的路径，并自动重放通往目标检查点的稳定设置步骤。
场景生成与流程 DSL：扫描源码以查找候选 E2E 场景，然后运行包含等待／点击／输入／断言／证据步骤的高级 JSON 流程。
源码流程分析：扫描 Flutter、React Native、Android 和 iOS 源码，查找屏幕、路由、转换和可见文本候选项。
根因分类：将 logcat 证据分类为应用错误、自动化错误、环境缺失、远程规则和测试数据问题。
服务端审批门控：安全模式要求高影响工具提供有效的审批负载。
内置移动安全循环：扫描源码和平台设置、生成测试计划、比较修复方案，并在不依赖其他扫描器包的情况下对发布决策进行门控。
默认脱敏：从文本构件、命令输出和 MCP／CLI 文本响应中脱敏常见机密、持有者令牌、API 密钥、电子邮件地址和电话号码。
防护型代码工具：仅允许读取／搜索／修改工作区内容，并支持禁止访问机密路径、防护型分支、提交和创建 PR。
可用于 Docker 的 MCP 运行时：将 Node MCP 服务打包到 Docker 中，同时将移动 SDK、模拟器、设备和 Appium 保留在主机或运行器上。
可组合的二进制程序：可将所有功能作为一个服务运行，也可将各项职责拆分到独立的 MCP 服务中。
可移植的移动 QA 技能：采用 MIT 许可证的Agent 技能，用于规划测试、收集证据，并使用现有工具运行有界的修复与重新测试工作流。

项目简介

本项目为以下架构提供 MCP 工具：

AI / MCP client
  |
  v
MobiLoop MCP
  |
  |-- code tools
  |-- environment preflight
  |-- build tools
  |-- Android device tools
  |-- iOS simulator tools
  |-- Appium tools
  |-- verification tools
  |-- flow-memory replay tools
  |-- loop/report tools
  |-- CI publication tools
  |-- Android/iOS orchestrators
  |-- security scan and release gate tools
  |
  v
mobile repo + emulator/device + Appium + build toolchain

服务不会仅凭模型的说法就宣称测试通过。通过结果应有工具输出作为依据：命令退出码、屏幕截图、页面源码、日志检查、API 断言和已记录的循环迭代。

不包括的内容

它不能替代 Android SDK、Xcode、Flutter、Gradle、React Native、Appium 或平台驱动程序。
它不是通用的移动模拟器容器。iOS 模拟器需要 macOS，Android 模拟器的可移植性取决于主机加速和设备访问能力。
它不是不受限制的 Shell 桥接工具。工具采用结构化设计，并受到保护。
它不是生产环境部署工具。发布签名、应用商店上传和生产环境密钥不在默认范围内。

要求

只安装目标应用所需的内容。

工作流	主机	所需工具
MCP 运行时	macOS、Linux、Windows	Node.js 20+
Android 构建/测试	macOS、Linux、Windows	Android SDK、`adb`、模拟器或实体设备、按需安装 Java/Gradle、Appium、兼容的 UiAutomator2 驱动程序
Flutter Android	macOS、Linux、Windows	Flutter SDK、Android SDK、用于 UI 工作流的 Appium
React Native Android	macOS、Linux、Windows	Node/npm、Android Gradle 工具链、Android SDK、Appium
iOS 模拟器	仅限 macOS	Xcode、`xcrun simctl`、iOS Simulator、Appium、兼容的 XCUITest 驱动程序
Docker MCP 运行时	macOS、Linux、Windows	Docker，以及用于控制设备的主机端移动工具

在使用 Appium 或工作流回放工具之前，先启动 Appium：

appium --address 127.0.0.1 --port 4723

本地安装的 Appium 也可以使用：

npx appium --address 127.0.0.1 --port 4723

对于 Android，请确保 Appium 进程能够访问：

export ANDROID_HOME=/absolute/path/to/android/sdk
export ANDROID_SDK_ROOT=/absolute/path/to/android/sdk
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

对于已运行的 Genymotion 设备，将其 Android SDK platform tools 添加到 PATH，然后在启动工作流前验证设备：

export PATH="$HOME/Library/Android/sdk/platform-tools:$PATH"
adb devices -l

从源代码安装

npm ci
npm test

配置项目本地 MCP 和捆绑的技能，然后诊断主机：

node dist/src/cli.js setup --workspace /absolute/path/to/mobile/app --client codex --yes
node dist/src/cli.js doctor --workspace /absolute/path/to/mobile/app --target android

客户端：codex、claude、cursor、vscode、generic。使用 --dry-run 进行预览。设置过程会保留其他服务，为已更改的文件创建备份，且不会安装 SDK 或修改应用数据。Windows、升级和先决条件请参阅安装说明。尚未启用 NPM 注册表发布；这些命令使用已构建的检出版本。

运行一体化 MCP 服务：

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/index.js

开发时：

npm run dev

CLI 后备方案

如果 MCP 客户端无法将服务公开为可调用工具，请使用 CLI 封装程序：

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js list-tools

检查工具策略元数据：

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js list-tools --json

也可以通过 MCP 中的 policy.list_tools 获取相同的元数据。

直接调用任意工具：

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js call flow.generate_test_scenarios '{"goal":"login smoke and validation"}'

生成场景候选项：

MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app \
node dist/src/cli.js generate-scenarios "cover onboarding, login, and validation"

MCP 客户端配置

一体化服务

用于本地开发和更简单的 MCP 客户端。

{
  "mcpServers": {
    "mobiloop": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/index.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    }
  }
}

拆分服务

如果希望按职责划分更严格的策略边界，请使用拆分服务。

{
  "mcpServers": {
    "mobile-code": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/code.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-build": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/build.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-device": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/device.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-appium": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/appium.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    },
    "mobile-flow": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/flow.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app",
        "APPIUM_SERVER_URL": "http://127.0.0.1:4723"
      }
    },
    "mobile-verify": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/verify.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    },
    "mobile-loop": {
      "command": "node",
      "args": ["/absolute/path/to/mobiloop-mcp/dist/src/servers/loop.js"],
      "env": {
        "MOBILOOP_WORKSPACE_ROOT": "/absolute/path/to/mobile/app"
      }
    }
  }
}

以下列出所有二进制文件。

二进制文件	范围
`mobiloop`	用于列出工具、调用工具和生成场景的 CLI 封装器
`mobiloop-mcp`	所有工具
`mobiloop-code-mcp`	代码和 git 工具
`mobiloop-env-mcp`	环境预检和兼容性矩阵
`mobiloop-build-mcp`	依赖项、lint、测试和 APK 构建工具
`mobiloop-device-mcp`	Android `adb` 和模拟器工具
`mobiloop-ios-mcp`	iOS 模拟器和 Xcode 工具
`mobiloop-appium-mcp`	Appium UI 自动化工具
`mobiloop-verify-mcp`	断言和证据收集
`mobiloop-flow-mcp`	源码流程分析和检查点重放
`mobiloop-loop-mcp`	迭代记录和报告
`mobiloop-ci-mcp`	构件清单、GitHub 摘要、PR 评论
`mobiloop-orchestrator-mcp`	Android 和 iOS 构建-安装-测试-验证循环
`mobiloop-security-mcp`	静态移动安全扫描、测试计划、扫描对比、发布门禁

配置

安全模式不会从项目目录读取配置。在宿主环境中设置工作区和 Appium 值：

export MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app
export APPIUM_SERVER_URL=http://127.0.0.1:4723

如需使用由宿主控制的文件配置，请复制示例并显式指定其路径：

cp mobiloop.config.example.json mobiloop.config.json

或者显式指定其路径：

export MOBILOOP_CONFIG=/absolute/path/to/mobiloop.config.json

AGENTIC_MOBILE_MCP_CONFIG 和 AGENTIC_MOBILE_WORKSPACE_ROOT 仍可作为旧版备用配置使用，但新项目应使用 MOBILOOP_* 名称。

常用字段：

字段	默认值	用途
`securityMode`	`secure`	安全模式会忽略项目本地配置；受信任模式允许显式覆盖
`workspaceRoot`	当前工作目录	MCP 服务可访问的移动应用工作区
`artifactsDir`	`.mobiloop`	证据、日志、屏幕截图、报告、流程记忆
`runId`	未设置	可选的运行标识符；将构件写入 `.mobiloop/runs/<id>`
`maxCommandMs`	`120000`	默认命令超时时间
`maxOutputBytes`	`1048576`	命令工具的输出上限
`maxFixAttempts`	`3`	建议的修复循环次数上限
`maxTestIterations`	`5`	编排器循环次数上限
`maxRuntimeMinutes`	`30`	建议的总运行时间上限
`allowedBranchPattern`	`^feature/ai-[A-Za-z0-9._/-]+$`	允许使用提交工具的分支
`appiumServerUrl`	`http://127.0.0.1:4723`	受信任模式下的 Appium 端点；安全模式使用主机环境
`adbPath`	`adb`	Android Debug Bridge 路径
`emulatorPath`	`emulator`	Android 模拟器 CLI 路径
`xcrunPath`	`xcrun`	iOS 模拟器 CLI 路径
`xcodebuildPath`	`xcodebuild`	Xcode 构建 CLI 路径
`sqlitePath`	`sqlite3`	用于只读断言的 SQLite CLI 路径
`apiAllowlist`	仅限 localhost	API 验证允许访问的 URL
`appiumAllowlist`	仅限 localhost	受信任模式下的 Appium 来源允许列表
`forbiddenPathGlobs`	类机密文件的默认模式	禁止读取或写入的文件
`toolPolicies`	内置默认值	受信任模式下逐工具风险和审批元数据的覆盖项
`requireApproval`	安全模式下为 `true`	高影响工具必须提供审批载荷
`redactArtifacts`	`true`	对文本构件和文本响应中的常见机密信息及 PII 进行脱敏

MOBILOOP_ARTIFACTS_DIR 可指向由主机控制的专用证据挂载点，例如只读 Docker 安全服务中的 /artifacts。

环境变量可覆盖指定字段：

export MOBILOOP_WORKSPACE_ROOT=/absolute/path/to/mobile/app
export APPIUM_SERVER_URL=http://127.0.0.1:4723
export MOBILOOP_RUN_ID=local-login-smoke
export MOBILOOP_REQUIRE_APPROVAL=true
export MOBILOOP_SECURITY_MODE=secure

配置架构见 schema/mobiloop.config.schema.json。另请参阅 docs/CONFIGURATION.md。

审批载荷采用以下格式：

{
  "approval": {
    "approved": true,
    "approvedBy": "human-or-ci",
    "reason": "Run Android validation on emulator",
    "expiresAt": "2026-05-11T12:00:00Z"
  }
}

实时 Appium 验证

v0.1.0-alpha.10 已在 Genymotion Galaxy S24（运行 Android 15）上安装的 MiniTakip Android 应用中完成验证。这项不修改应用状态的验证使用 MobiLoop 发现 ADB 目标、创建 Appium 3 UiAutomator2 会话、捕获屏幕截图和页面源 XML、读取无障碍树，然后关闭会话。验证没有输入表单数据、创建记录或删除应用数据。

appium.create_session 接受如下所示的直接 W3C 功能。MobiLoop 会在发送给 Appium 前，将它们封装在 WebDriver 的 capabilities 信封中：

{
  "capabilities": {
    "alwaysMatch": {
      "platformName": "Android",
      "appium:automationName": "UiAutomator2",
      "appium:udid": "127.0.0.1:6555",
      "appium:appPackage": "com.example.app",
      "appium:appActivity": ".MainActivity",
      "appium:noReset": true
    }
  },
  "approval": {
    "approved": true,
    "approvedBy": "human-or-ci",
    "reason": "Open an Appium session for a bounded validation run"
  }
}

创建会话后，使用 appium.observe_screen 和 appium.get_accessibility_tree 收集证据，然后务必调用 appium.delete_session。会话成功仅能证明所选屏幕及断言通过；这并不表示整个产品流程均已通过。

对于 Flutter Android 应用，工具的大致调用顺序如下：

env.preflight { "target": "flutter" }
security.scan_source
security.generate_test_plan
flow.analyze_from_code
build.detect_project
build.install_dependencies
build.run_lint
build.run_unit_tests
build.build_debug_apk
device.list_devices
device.install_app
appium.create_session
appium.wait_for_visible
appium.tap_by_text
verify.assert_no_crash_in_logcat
verify.collect_evidence
loop.record_iteration
loop.generate_report

Android 编排器

orchestrator.run_android_validation_loop 会在构建、安装、Appium、验证、证据和迭代记录之间运行一个有界的 Android 流程。

最简示例：

{
  "goal": "Build and verify login flow on Android.",
  "kind": "flutter",
  "packageName": "com.example.app",
  "serial": "emulator-5554",
  "runLint": true,
  "runUnitTests": true,
  "buildDebugApk": true,
  "clearAppData": false,
  "collectEvidence": true,
  "maxTestIterations": 3,
  "appiumCapabilities": {
    "platformName": "Android",
    "appium:automationName": "UiAutomator2",
    "appium:deviceName": "Android Emulator",
    "appium:udid": "emulator-5554",
    "appium:appPackage": "com.example.app",
    "appium:appActivity": ".MainActivity",
    "appium:noReset": true
  },
  "appiumSteps": [
    {
      "tool": "appium.wait_for_visible",
      "args": {
        "locator": { "strategy": "text", "value": "Login" },
        "timeoutMs": 10000
      }
    }
  ],
  "expectedTexts": ["Home"],
  "approval": {
    "approved": true,
    "approvedBy": "project-owner",
    "reason": "Build, install and test the selected test app using authorized synthetic data"
  }
}

最简示例并非完整的登录场景。请根据实际定位器、表单操作和结果断言，调整完整的 Android 示例。审批载荷代表真实授权；重置应用需要单独授权。

iOS 编排器

orchestrator.run_ios_validation_loop 会在 xcodebuild、模拟器启动、应用安装与启动、Appium XCUITest、验证、证据和迭代记录之间运行一个有界的 iOS 模拟器流程。

Flutter 最简示例：

{
  "goal": "Build and verify login flow on iOS.",
  "kind": "flutter",
  "workspace": "ios/Runner.xcworkspace",
  "scheme": "Runner",
  "configuration": "Debug",
  "sdk": "iphonesimulator",
  "destination": "platform=iOS Simulator,name=iPhone 15",
  "buildSettings": {
    "ARCHS": "arm64",
    "EXCLUDED_ARCHS": ""
  },
  "simulatorDevice": "iPhone 15",
  "bundleId": "com.example.app",
  "runLint": true,
  "runUnitTests": true,
  "buildIosApp": true,
  "bootSimulator": true,
  "installApp": true,
  "launchApp": true,
  "collectEvidence": true,
  "maxTestIterations": 2,
  "appiumCapabilities": {
    "platformName": "iOS",
    "appium:automationName": "XCUITest",
    "appium:deviceName": "iPhone 15",
    "appium:bundleId": "com.example.app",
    "appium:noReset": true
  },
  "appiumSteps": [
    {
      "tool": "appium.wait_for_visible",
      "args": {
        "locator": { "strategy": "text", "value": "Login" },
        "timeoutMs": 15000
      }
    }
  ],
  "expectedTexts": ["Home"],
  "approval": {
    "approved": true,
    "approvedBy": "project-owner",
    "reason": "Build, install and test only the selected simulator demo"
  }
}

请参阅 examples/flutter-ios-validation-loop.json 和 docs/QUICKSTART_FLUTTER.md。

buildSettings 和 xcodebuildArgs 会转发给 ios.build_app，因此项目可以处理特定主机的模拟器要求，例如 Apple Silicon arm64 模拟器构建或自定义 DerivedData 设置，而无需离开 MCP 流程。

AI 生成的场景候选项

MobiLoop 可以根据应用源码生成候选 E2E 场景，让 Agent 从具体的测试计划开始，而不是面对空白屏幕。

{
  "tool": "flow.generate_test_scenarios",
  "args": {
    "goal": "cover onboarding, login, form validation, and main navigation",
    "maxScenarios": 8,
    "includeNegativeCases": true
  }
}

输出包含优先级、候选步骤、断言、源码引用和限制。请将这些内容视为可执行的候选项：Agent 应通过 Appium 运行它们、收集证据，并将其完善为稳定的检查点路径。

如需脚本化执行，而不编写自定义客户端代码：

{
  "tool": "flow.run_script",
  "args": {
    "sessionId": "APPIUM_SESSION_ID",
    "steps": [
      { "action": "observe", "waitForAnyText": ["Giriş Yap", "Login"], "waitForPackageIdle": true },
      { "action": "tapText", "text": "Giriş Yap", "matchMode": "auto" },
      {
        "action": "type",
        "locator": { "strategy": "text", "value": "E-posta" },
        "text": "[email protected]",
        "mode": "sendKeys"
      },
      { "action": "assertText", "text": "Ana Sayfa" },
      { "action": "collectEvidence", "label": "login-result" }
    ]
  }
}

流程记忆与自动重放

流程记忆可以加快重复的移动测试，同时不会假装设置屏幕已经通过。

current Appium source
  -> normalized screen signature
  -> match recorded checkpoint
  -> replay known semantic actions
  -> arrive at target checkpoint
  -> continue test-specific assertions

屏幕签名根据 Appium 页面源构建，包含：

可见文本
无障碍标签和内容描述
资源 ID
类名
可点击文本

这些数据会持久化到：

.mobiloop/flow/memory.json

启用 runId 后，相同文件会存放在 .mobiloop/runs/<runId>/flow/memory.json 下。

记录检查点

在稳定的屏幕上：

{
  "testName": "onboarding-to-login",
  "name": "Onboarding 1",
  "order": 1,
  "sessionId": "APPIUM_SESSION_ID",
  "actionToNext": {
    "tool": "appium.tap_by_text",
    "args": {
      "text": "Next"
    }
  }
}

在下一个屏幕上：

{
  "testName": "onboarding-to-login",
  "name": "Login",
  "order": 2,
  "sessionId": "APPIUM_SESSION_ID"
}

记录通过的路径：

{
  "testName": "onboarding-to-login",
  "status": "passed",
  "checkpointIds": ["onboarding-to-login-001-onboarding-1", "onboarding-to-login-002-login"]
}

稍后重放

规划但不执行：

{
  "sessionId": "APPIUM_SESSION_ID",
  "testName": "onboarding-to-login",
  "targetCheckpointId": "onboarding-to-login-002-login",
  "dryRun": true
}

执行：

{
  "sessionId": "APPIUM_SESSION_ID",
  "testName": "onboarding-to-login",
  "targetCheckpointId": "onboarding-to-login-002-login",
  "minimumScore": 0.55,
  "delayMs": 500
}

支持的重放操作：

appium.tap_by_text
appium.tap_by_accessibility_id
appium.tap_by_resource_id
appium.tap_coordinates
appium.type_text
appium.swipe
appium.go_back
appium.wait_for_visible
appium.assert_visible

优先使用语义操作。坐标应作为最后的备用方案。

参见 examples/flow-memory-replay.json。

Docker

推荐的 Docker 模式如下：

Docker container
  - read-only Security MCP for static project review

Trusted isolated worktree or self-hosted runner
  - approved build, device, Appium, and patch actions
  - Android SDK/emulator/device, Appium, Flutter/Gradle/React Native
  - Xcode and iOS Simulator on macOS

构建：

docker build -t mobiloop-mcp:local .

已发布的 GHCR 镜像：

docker pull ghcr.io/enessubass/mobiloop-mcp:latest

作为 MCP stdio 服务运行：

docker run --rm -i \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  --tmpfs /artifacts:rw,noexec,nosuid,size=256m,uid=10001,gid=10001,mode=0770 \
  -e MOBILOOP_WORKSPACE_ROOT=/workspace \
  -e MOBILOOP_ARTIFACTS_DIR=/artifacts \
  -e MOBILOOP_SECURITY_MODE=secure \
  -v /absolute/path/to/mobile/app:/workspace:ro \
  --entrypoint node \
  ghcr.io/enessubass/mobiloop-mcp:latest /app/dist/src/servers/security.js

参见 docs/DOCKER.md。

安全模型

默认设置有意采取保守策略。

符号链接解析后，文件访问仅限于 workspaceRoot。
安全模式会忽略项目本地配置、要求审批，并使用由主机控制的回环 Appium。
禁止访问类似机密的路径。
默认情况下，提交工具仅适用于匹配 feature/ai-* 的分支。
不提供通用 Shell 执行工具。
API 检查受 apiAllowlist 限制。
证据会写入 .mobiloop；除非主机有意提供专用的 MOBILOOP_ARTIFACTS_DIR 挂载点。
强制执行运行时和输出限制。

默认禁止的路径包括：

.env、.env.*
*.keystore、*.jks、*.p12
*.mobileprovision
GoogleService-Info.plist
google-services.json
包含 secret 或 credential 的路径

安全模式会对高影响操作强制要求审批，例如安装依赖、运行 lint/test/build 命令、设备交互、应用补丁、提交、推送和创建 PR。 MobiLoop 通过 mobiloop list-tools --json 提供机器可读的策略元数据；参见 docs/TOOL_REFERENCE.md。

参见 docs/SECURITY.md。

构件

默认构件目录为：

.mobiloop

设置 runId 或 MOBILOOP_RUN_ID 后，构件写入器会使用按运行隔离的根目录：

.mobiloop/runs/<runId>

典型内容：

目录	内容
`build/`	依赖、lint、测试和 APK 构建日志
`screenshots/`	Appium 或设备截图
`sources/`	Appium 页面源 XML
`logs/`	设备或模拟器日志
`evidence/`	合并后的验证构件
`flow/`	源流程分析、检查点记忆、重放记录
`loop/`	JSONL 迭代记录
`reports/`	Markdown 最终报告
`ci/`	CI 清单、摘要、注释
`security/`	源代码扫描、生成的计划、比较结果

工具组

代码

code.read_file
code.search_code
code.apply_patch
code.git_diff
code.create_branch
code.commit_changes
code.open_pr

环境

env.preflight
env.compatibility_matrix
env.ensure_appium

构建

build.detect_project
build.install_dependencies
build.run_lint
build.run_unit_tests
build.build_debug_apk
build.build_release_candidate
build.collect_build_logs

安全

security.scan_source
security.generate_test_plan
security.compare_scans
security.release_gate

Android 设备

device.list_devices
device.start_emulator
device.stop_emulator
device.install_app
device.uninstall_app
device.clear_app_data
device.grant_permissions
device.capture_screenshot
device.pull_logs

iOS

ios.list_simulators
ios.boot_simulator
ios.shutdown_simulator
ios.build_app
ios.install_app
ios.launch_app
ios.capture_screenshot
ios.collect_logs

Appium

appium.create_session
appium.delete_session
appium.observe_screen
appium.get_page_source
appium.get_accessibility_tree
appium.tap_by_text
appium.tap_by_accessibility_id
appium.tap_by_resource_id
appium.tap_coordinates
appium.type_text
appium.swipe
appium.go_back
appium.wait_for_visible
appium.assert_visible
appium.assert_not_visible

验证

verify.assert_screen_contains_text
verify.assert_no_crash_in_logcat
verify.assert_appium_session_healthy
verify.assert_api_response
verify.collect_evidence
verify.assert_navigation_reached
verify.assert_accessibility_labels
verify.assert_screenshot_diff
verify.assert_sqlite_query
verify.hash_artifact

流程

flow.analyze_from_code
flow.generate_test_scenarios
flow.run_script
flow.record_checkpoint
flow.record_test_run
flow.plan_replay
flow.replay_to_checkpoint
flow.read_memory
flow.clear_memory

循环

loop.record_iteration
loop.read_iterations
loop.generate_report

CI

ci.collect_artifact_manifest
ci.write_github_step_summary
ci.comment_pr
ci.create_github_annotations

策略

policy.list_tools

编排器

orchestrator.run_android_validation_loop
orchestrator.run_ios_validation_loop

故障排除

`env.preflight` 提示缺少 Appium

启动 Appium，并确保 APPIUM_SERVER_URL 指向它：

APPIUM_SERVER_URL=http://127.0.0.1:4723

env.preflight 接受可访问的 Appium 服务或全局 appium 命令。

Appium 找不到 Android SDK

使用 Android 环境变量启动 Appium：

ANDROID_HOME=/absolute/path/to/android/sdk \
ANDROID_SDK_ROOT=/absolute/path/to/android/sdk \
PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH" \
appium --address 127.0.0.1 --port 4723

Appium 点按了文本，但屏幕没有变化

优先使用无障碍 ID 或资源 ID。如果使用文本，此服务会先尝试查找包含该文本的可点击父元素，然后再回退到文本节点。对于自定义 Flutter 或 React Native 控件，请尽可能添加稳定的语义/无障碍 ID。

Flow 回放匹配到了错误的屏幕

先使用 flow.plan_replay。提高 minimumScore，记录更好的检查点，并避免将临时加载状态设为检查点。

Docker 无法访问模拟器或 Appium

在主机上运行 Appium，并使用 host.docker.internal 将容器指向它。在 Linux 上，添加 --add-host=host.docker.internal:host-gateway。

iOS 无法在 Docker 中运行

iOS 模拟器工作流需要 macOS 和 Xcode。请直接在 macOS 主机或 macOS 可自托管 runner 上运行 iOS 工具。

`npm pack --dry-run` 因 npm 缓存权限而失败

使用干净的缓存：

npm_config_cache=/tmp/mobiloop-npm-cache npm pack --dry-run

开发

npm ci
npm run format:check
npm run lint
npm run typecheck
npm test
npm run site:check
npm run pack:check

Dockerfile 还会在构建镜像时运行测试套件。

Project Files

License

MIT. See LICENSE.

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。