
MobiLoop
io.github.enessubassPublished by GitHub account enessubassv0.1.0-alpha.15Updated Oct 24, 2026
Guarded AI mobile Appium testing, security scanning, verification, and fix-retest MCP tools.
Overview
MobiLoop is a guarded MCP tool layer that lets an AI coding agent build, install, drive and verify Android and iOS apps through Appium, with evidence-backed tri
- What you can do
- Read, search and patch workspace code, inspect diffs, create branches, commit and open pull requests within guarded limits. Run environment preflight, dependency install, lint, unit tests and debug or release builds. Manage Android devices and emulators and iOS simulators: list, start, install, launch, screenshot and pull logs. Drive the app through Appium sessions: tap, type, swipe, wait, assert visibility and read page source or accessibility trees. Verify results with logcat, screen text, API, SQLite and screenshot-diff assertions, collect evidence and record iterations. Analyze source flows, generate test scenarios, replay checkpoints, run Android or iOS validation loops, scan mobile app
- When to use it
- Use it when an agent should do more than write mobile code: build the app, run it on a real emulator, device or simulator, exercise user flows through Appium, and hand back evidence and failure classification. It suits Flutter, React Native, Android and iOS projects with an existing toolchain.
- Requirements
- A local process run with Node.js 20+ or Docker. Set MOBILOOP_WORKSPACE_ROOT to the mobile app and APPIUM_SERVER_URL to a running Appium server. Android work needs the Android SDK, adb, an emulator or device and the UiAutomator2 driver; iOS needs macOS with Xcode, xcrun simctl and the XCUITest driver. No account or API key is declared.
Installation
In SourceWeft
- Open MobiLoop in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
MobiLoop MCP
Guarded MCP servers for agentic mobile build-test-fix loops.
Documentation site | Installation | Security model | Tool reference
MobiLoop MCP is a controlled tool layer between an AI coding agent and a real mobile development environment. It lets an MCP client read and patch a mobile project, build it, install it on Android or iOS targets, drive the app through Appium, verify logs/screens/API results, remember known app-flow checkpoints, and produce evidence-based reports.
The name reflects the core contract: mobile work should run through a measurable loop of change, build, device execution, verification, and evidence-backed triage.
It is built for the workflow where the agent does not just write code. It builds, runs, tests, observes, classifies failures, and hands back evidence. An agent can still use the separate guarded code tools to patch and retest, but that patch step is intentionally outside the default orchestrator.
Today, MobiLoop provides guarded build-test-verify loops and evidence-based failure classification. Fully automated patch-and-retest is intentionally kept outside the default orchestrator until stricter approval, rollback, and review controls are enabled.
Highlights
- Evidence-first mobile loops: build logs, screenshots, Appium XML source, logcat/simulator logs, API responses, screenshot diffs, and iteration records.
- Android and iOS tool split: Android
adb/emulator tools and iOSxcrun simctl/xcodebuildtools are separated. - Appium UI automation: semantic taps, typing, swipes, back navigation, visibility assertions, screenshots, and accessibility summaries.
- Flow memory: record runtime screen checkpoints, remember the latest passing path, and auto-replay stable setup steps to a target checkpoint.
- Scenario generation and flow DSL: scan source for candidate E2E scenarios, then run high-level JSON flows with wait/tap/type/assert/evidence steps.
- Source-flow analysis: scan Flutter, React Native, Android, and iOS source for screen, route, transition, and visible-text candidates.
- Root-cause classification: classify logcat evidence into app bugs, automation errors, missing environment, remote rules, and test-data issues.
- Server-side approval gate: secure mode requires valid approval payloads for high-impact tools.
- Built-in mobile security loop: scan source and platform settings, generate a test plan, compare fixes, and gate release decisions without another scanner package.
- Redaction by default: redact common secrets, bearer tokens, API keys, emails, and phone numbers from text artifacts, command output, and MCP/CLI text responses.
- Guarded code tools: workspace-only reads/searches/patches, forbidden secret paths, guarded branches, commits, and PR creation.
- Docker-ready MCP runtime: package the Node MCP server in Docker while keeping mobile SDKs, emulators, devices, and Appium on the host or runner.
- Composable binaries: run everything as one server or split each responsibility into its own MCP server.
- Portable mobile QA skill: an MIT-licensed agent skill for planning tests, collecting evidence, and running bounded fix-and-retest workflows with the existing tools.
What This Is
This project provides MCP tools for this architecture:
The server does not claim that a test passed because a model says so. A pass should be backed by tool output: command exit codes, screenshots, page source, log checks, API assertions, and recorded loop iterations.
What This Is Not
- It is not a replacement for Android SDK, Xcode, Flutter, Gradle, React Native, Appium, or platform drivers.
- It is not a universal mobile emulator container. iOS simulator requires macOS, and Android emulator portability depends on host acceleration and device access.
- It is not an unrestricted shell bridge. Tools are structured and guarded.
- It is not a production deployer. Release signing, store upload, and production secrets remain outside the default scope.
Requirements
Install only what your target app needs.
Start Appium before Appium or flow replay tools:
Local Appium installs also work:
For Android, make sure the Appium process can see:
For an already-running Genymotion device, add its Android SDK platform tools to PATH, then
verify the device before starting a flow:
Install From Source
Configure project-local MCP and the bundled skill, then diagnose the host:
Clients: codex, claude, cursor, vscode, generic. Use --dry-run to preview. Setup preserves other servers, backs up changed files, and does not install SDKs or modify app data. See installation for Windows, upgrades, and prerequisites. NPM registry publication is not enabled; these commands use the built checkout.
Run the all-in-one MCP server:
For development:
CLI Fallback
When an MCP client cannot expose the server as callable tools, use the CLI wrapper:
Inspect tool policy metadata:
The same metadata is available inside MCP through policy.list_tools.
Call any tool directly:
Generate scenario candidates:
MCP Client Configuration
All-In-One Server
Use this for local development and simpler MCP clients.
Split Servers
Use split servers when you want tighter policy boundaries per responsibility.
All binaries are listed below.
Configuration
Secure mode does not read configuration from the project directory. Set workspace and Appium values in the host environment:
For a host-controlled file configuration, copy the example and point to it explicitly:
Or point to it explicitly:
AGENTIC_MOBILE_MCP_CONFIG and AGENTIC_MOBILE_WORKSPACE_ROOT are still accepted as legacy fallbacks, but new projects should use the MOBILOOP_* names.
Common fields:
MOBILOOP_ARTIFACTS_DIR may point to a dedicated host-controlled evidence mount, such as /artifacts in the read-only Docker security server.
Environment variables override selected fields:
The config schema is available at schema/mobiloop.config.schema.json. See docs/CONFIGURATION.md.
Approval payloads use this shape:
Recommended First Run
- Point
MOBILOOP_WORKSPACE_ROOTat your mobile app. - Run
security.scan_sourceandsecurity.generate_test_plan. - Start an emulator or connect a device, then start Appium.
- Run
env.preflightandflow.analyze_from_code. - Run approved build/lint/unit-test actions.
- Install the app, create an Appium session, and verify one small user flow.
- Collect evidence; if a bug is confirmed, patch, rerun, and compare the security scan.
- Apply
security.release_gatebefore calling a fix ready for release.
Live Appium Proof
v0.1.0-alpha.10 was validated against an installed MiniTakip Android application on a
Genymotion Galaxy S24 running Android 15. The non-mutating proof used MobiLoop to discover the
ADB target, create an Appium 3 UiAutomator2 session, capture a screenshot and page-source XML,
read the accessibility tree, then close the session. It did not enter form data, create records,
or delete application data.
Direct W3C capabilities are accepted by appium.create_session as shown below. MobiLoop wraps
them in the WebDriver capabilities envelope before sending them to Appium:
After creating a session, use appium.observe_screen and appium.get_accessibility_tree for
evidence, then always call appium.delete_session. A successful session only proves the selected
screen and assertions; it does not claim that an entire product journey has passed.
For a Flutter Android app, the rough tool sequence is:
Android Orchestrator
orchestrator.run_android_validation_loop runs a bounded Android loop across build, install, Appium, verification, evidence, and iteration records.
Minimal shape:
The minimal shape is not a complete login scenario. Adapt the full Android example with actual locators, form actions, and outcome assertions. Approval payloads represent real permission; app resets require separate authorization.
iOS Orchestrator
orchestrator.run_ios_validation_loop runs a bounded iOS simulator loop across xcodebuild, simulator boot, app install/launch, Appium XCUITest, verification, evidence, and iteration records.
Minimal Flutter shape:
See examples/flutter-ios-validation-loop.json and docs/QUICKSTART_FLUTTER.md.
buildSettings and xcodebuildArgs are forwarded to ios.build_app, so projects can handle host-specific simulator requirements such as Apple Silicon arm64 simulator builds or custom DerivedData settings without leaving the MCP loop.
AI-Generated Scenario Candidates
MobiLoop can generate candidate E2E scenarios from the app source so the agent starts from a concrete test plan instead of an empty screen.
The output includes priorities, candidate steps, assertions, source references, and limitations. Treat these as executable candidates: the agent should run them through Appium, collect evidence, and refine them into stable checkpoint paths.
For scripted execution without writing custom client code:
Flow Memory And Auto-Replay
Flow memory makes repeated mobile tests faster without pretending that setup screens passed.
The screen signature is built from Appium page source:
- visible text
- accessibility labels and content descriptions
- resource ids
- class names
- clickable text
This data is persisted under:
With runId enabled, the same file lives under .mobiloop/runs/<runId>/flow/memory.json.
Record Checkpoints
At a stable screen:
At the next screen:
Record the passing path:
Replay Later
Plan without executing:
Execute:
Supported replay actions:
appium.tap_by_textappium.tap_by_accessibility_idappium.tap_by_resource_idappium.tap_coordinatesappium.type_textappium.swipeappium.go_backappium.wait_for_visibleappium.assert_visible
Prefer semantic actions. Coordinates should be the last fallback.
See examples/flow-memory-replay.json.
Docker
The recommended Docker model is:
Build:
Published GHCR image:
Run as an MCP stdio server:
See docs/DOCKER.md.
Safety Model
Defaults are intentionally conservative.
- File access is restricted to
workspaceRootafter symbolic-link resolution. - Secure mode ignores project-local config, requires approval, and uses host-controlled loopback Appium.
- Secret-like paths are blocked.
- Commit tools only work on branches matching
feature/ai-*by default. - There is no generic shell execution tool.
- API checks are restricted by
apiAllowlist. - Evidence is written under
.mobiloop, unless the host deliberately provides a dedicatedMOBILOOP_ARTIFACTS_DIRmount. - Runtime and output limits are enforced.
Default blocked paths include:
.env,.env.**.keystore,*.jks,*.p12*.mobileprovisionGoogleService-Info.plistgoogle-services.json- paths containing
secretorcredential
Secure mode enforces approval for high-impact operations such as dependency installation, lint/test/build commands, device interaction, patches, commits, pushes, and PR creation.
MobiLoop exposes machine-readable policy metadata through mobiloop list-tools --json; see docs/TOOL_REFERENCE.md.
See docs/SECURITY.md.
Artifacts
The default artifact directory is:
When runId or MOBILOOP_RUN_ID is set, artifact writers use a run-scoped root:
Typical contents:
Tool Groups
Code
code.read_filecode.search_codecode.apply_patchcode.git_diffcode.create_branchcode.commit_changescode.open_pr
Environment
env.preflightenv.compatibility_matrixenv.ensure_appium
Build
build.detect_projectbuild.install_dependenciesbuild.run_lintbuild.run_unit_testsbuild.build_debug_apkbuild.build_release_candidatebuild.collect_build_logs
Security
security.scan_sourcesecurity.generate_test_plansecurity.compare_scanssecurity.release_gate
Android Device
device.list_devicesdevice.start_emulatordevice.stop_emulatordevice.install_appdevice.uninstall_appdevice.clear_app_datadevice.grant_permissionsdevice.capture_screenshotdevice.pull_logs
iOS
ios.list_simulatorsios.boot_simulatorios.shutdown_simulatorios.build_appios.install_appios.launch_appios.capture_screenshotios.collect_logs
Appium
appium.create_sessionappium.delete_sessionappium.observe_screenappium.get_page_sourceappium.get_accessibility_treeappium.tap_by_textappium.tap_by_accessibility_idappium.tap_by_resource_idappium.tap_coordinatesappium.type_textappium.swipeappium.go_backappium.wait_for_visibleappium.assert_visibleappium.assert_not_visible
Verification
verify.assert_screen_contains_textverify.assert_no_crash_in_logcatverify.assert_appium_session_healthyverify.assert_api_responseverify.collect_evidenceverify.assert_navigation_reachedverify.assert_accessibility_labelsverify.assert_screenshot_diffverify.assert_sqlite_queryverify.hash_artifact
Flow
flow.analyze_from_codeflow.generate_test_scenariosflow.run_scriptflow.record_checkpointflow.record_test_runflow.plan_replayflow.replay_to_checkpointflow.read_memoryflow.clear_memory
Loop
loop.record_iterationloop.read_iterationsloop.generate_report
CI
ci.collect_artifact_manifestci.write_github_step_summaryci.comment_prci.create_github_annotations
Policy
policy.list_tools
Orchestrator
orchestrator.run_android_validation_looporchestrator.run_ios_validation_loop
Troubleshooting
env.preflight says Appium is missing
Start Appium and make sure APPIUM_SERVER_URL points to it:
env.preflight accepts either a reachable Appium server or a global appium command.
Appium cannot find Android SDK
Start Appium with Android environment variables:
Appium taps text but the screen does not move
Prefer accessibility ids or resource ids. If using text, this server first tries a clickable parent containing the text, then falls back to the text node. For custom Flutter or React Native widgets, add stable semantics/accessibility ids when possible.
Flow replay matched the wrong screen
Use flow.plan_replay first. Raise minimumScore, record better checkpoints, and avoid checkpointing transient loading states.
Docker cannot see the emulator or Appium
Run Appium on the host and point the container to it with host.docker.internal. On Linux, add --add-host=host.docker.internal:host-gateway.
iOS does not work in Docker
iOS simulator workflows require macOS with Xcode. Run iOS tools directly on the macOS host or a macOS self-hosted runner.
npm pack --dry-run fails with npm cache permissions
Use a clean cache:
Development
The Dockerfile also runs the test suite during image build.
Project Files
- docs/ARCHITECTURE.md
- docs/ARCHITECTURE_DETAILED.md
- docs/TOOL_REFERENCE.md
- docs/CONFIGURATION.md
- docs/AGENT_PROTOCOL.md
- docs/TEST_STRATEGY.md
- docs/CI_CD.md
- docs/SECURITY_THREAT_MODEL.md
- docs/OPERATIONS.md
- docs/OPERATIONS_RUNBOOK.md
- docs/TROUBLESHOOTING_DETAILED.md
- docs/FLOW_MEMORY.md
- docs/ORCHESTRATOR.md
- docs/RELEASE_PROCESS.md
- docs/LIMITATIONS.md
- docs/EXAMPLES.md
- docs/QUICKSTART_FLUTTER.md
- docs/DOCKER.md
- docs/SECURITY.md
- docs/demo/flutter-login-loop.md
- docs/releases/v0.1.0-alpha.1.md
- docs/releases/v0.1.0-alpha.2.md
- docs/releases/v0.1.0-alpha.3.md
- docs/releases/v0.1.0-alpha.4.md
- docs/releases/v0.1.0-alpha.10.md
- docs/releases/v0.1.0-alpha.11.md
- docs/releases/v0.1.0-alpha.14.md
- docs/releases/v0.1.0-alpha.15.md
- docs/releases/v0.1.0-alpha.13.md
- docs/releases/v0.1.0-alpha.12.md
- .github/workflows/android-fixture-e2e.yml
- .github/workflows/deploy-pages.yml
- examples/android-validation-loop.json
- examples/flutter-ios-validation-loop.json
- examples/flow-memory-replay.json
- examples/github-actions-mobiloop.yml
- examples/mobile-fixtures/flutter-login-demo
- examples/mobile-fixtures/android-kotlin-login-demo
- examples/mobile-fixtures/react-native-login-demo
- examples/artifacts/successful-loop-report.md
- examples/artifacts/real-runs/flutter-login-android
- examples/artifacts/real-runs/native-android-login
License
MIT. See LICENSE.
Source: README.md at commit 14a9389
Tools
0Version history
3- v0.1.0-alpha.15LatestOct 15, 2026
- v0.1.0-alpha.14Sep 23, 2026
- v0.1.0-alpha.13Sep 23, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts