JevSim

English | 简体中文

Complete a mobile UI sequence in one agent tool call.

JevSim is a local MCP server for agents working with iOS and Android apps. Give it a short plan—navigate, enter text, save, verify—and it executes the steps without returning to your main reasoning loop after every interaction. Jev, a text-based selection model, matches descriptions to current accessibility controls. XcodeBuildMCP (iOS) or Appium/UIAutomator2 (Android) performs the actions and checks the results.

If you are a human, give your agent this repository URL and ask: “Install JevSim for my iOS/Android project, connect it to your MCP tools, and verify the setup.” The instructions below are for that agent.

Speed comparison

We reran the same ten-tap iOS Settings tour with the same checks after every action: open five sections and return from each. Pure agent means the main agent reads each screen and chooses the next control through XcodeBuildMCP. Agent + JevSim means it delegates the full route in one jevsim_run_steps call, with Jev selecting all ten targets.

Measured September 21, 2026: GPT-6-astra (high reasoning) in Codex, Jev 1.13.0, XcodeBuildMCP 2.7.0, iPhone 17e / iOS 26.5 Simulator. Times include observations, target decisions, actions, checks, and intermediate agent/tool round trips; setup and initial route planning are excluded. This is one navigation benchmark with three runs per approach, not a general debugging or Android speed guarantee. Run details and reproduction.

Agent installation

1. Inspect the environment. Use Node.js 24 and npm. Choose the platform from the user's project; install only that backend. Reuse existing tools and credentials where available.
2. Use the npm package. Configure the MCP client to run npx -y --package=@huaaudio/jevsim@0.1.0 jevsim. This downloads the compiled package; no clone or build is needed. Use an absolute path to Node.js 24’s npx if the client has a restricted PATH. Source installation remains available for development.
3. Prepare the backend. For iOS, use macOS, Xcode, and a booted simulator; JevSim starts its own pinned XcodeBuildMCP process. For Android, prepare ADB and a device/emulator, then start local Appium with UIAutomator2 using the Android instructions. Build, install, and launch the user's app with your existing tools.
4. Configure Jev. Supply TYPESAFE_API_KEY through your client's secret/environment configuration. The npm launcher does not automatically read .env; use the env-file launch option if needed. Preserve an existing .env; use .env.example only as a template. Never print or commit the key. Exact-identifier workflows also work without a key.
5. Register and verify the MCP server. Follow the agent installation runbook for absolute launch paths, client configuration, and readiness checks. Preserve other MCP servers. Installation is complete when you can discover all three tools, connect to the chosen backend, and inspect the intended device. Report any missing prerequisite precisely.

Delegate a workflow

Call status and inspect first. For iOS, pass the observed simulatorId; for Android, pass platform: "android" and the ADB deviceId. Derive the plan from the app and the user's task. Every step must include a backend-verifiable expect condition.

For example, this is one step only if your app exposes the stated destination identifier:

{
  "action": "tap",
  "target": { "description": "Open the profile editor" },
  "expect": { "predicate": "exists", "identifier": "profile.name" }
}

Use a unique observed target.identifier when available; it skips the model request. Otherwise, Jev selects among current action-compatible controls or abstains. It cannot invent steps or generate typing text. Supported actions are tap, type, scroll, wait, and assert. See the request schema and complete example.

Reserve the device until the call returns. A completed result means every supplied expectation matched. If execution stops, inspect completedSteps, reason, and actionStatus, then inspect the app and re-plan. Never blindly replay a workflow or an uncertain action. See agent usage and recovery.

When to use it

Delegate known sequences: reproduce a bug, navigate to a screen, exercise a form, or verify a change. Keep builds, code edits, visual interpretation, and decisions that depend on new information in your main agent. Split longer work into bounded sequences.

• Supported: iOS Simulator and native Android accessibility. Android has been live-tested on an Android 15 emulator on macOS; physical Android devices and Windows/Linux hosts remain unvalidated.
• Input: Android supports Unicode and empty replacement. The tested iOS backend accepts nonempty printable ASCII only.
• Limits: inaccessible controls, Android WebViews, and arbitrary desktop GUIs need other tools. JevSim does not interpret screenshots.
• Data: semantic selection sends accessibility text and field values to TypeSafe. Exact-identifier workflows skip those requests. Tool transcripts and backend logs may contain app data; see data handling.

Reference

Agent installation · Agent usage · Tools · Configuration · Troubleshooting · Release notes

Contributors: development guide for fixtures, tests, benchmark reproduction, and implementation history.

MIT. Independent project; automation backends and the TypeSafe service have their own terms and licenses.