# JevSim

[English](README.md) | [简体中文](README.zh-CN.md)

**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](https://typesafe.ai/), 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.

| Approach | Median execution time | Verified runs | Speedup |
| --- | ---: | ---: | ---: |
| Pure agent + XcodeBuildMCP | 117.3 s | 3/3 | 1× |
| Agent + JevSim + XcodeBuildMCP | **35.7 s** | **3/3** | **3.3×** |

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](https://github.com/huaaudio/jevsim/blob/main/development/reports/agent-comparison.md).

## 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](docs/getting-started.md#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](docs/android.md). 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](docs/getting-started.md#local-env-file-launch) if needed. Preserve an existing `.env`; use [.env.example](.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](docs/getting-started.md) 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

| Tool | Use it to |
| --- | --- |
| `jevsim_status` | Check backend connectivity, credential presence, and device inventory |
| `jevsim_inspect` | Read the current accessibility state of one explicit device |
| `jevsim_run_steps` | Execute 1–10 supplied steps within 60 seconds; receive outcomes, timings, and any stop reason |

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**:

```json
{
  "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](docs/tools.md).

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](docs/agent-guide.md).

## 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](docs/privacy.md).

## Reference

[Agent installation](docs/getting-started.md) · [Agent usage](docs/agent-guide.md) · [Tools](docs/tools.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md) · [Release notes](CHANGELOG.md)

Contributors: [development guide](https://github.com/huaaudio/jevsim/blob/main/development/README.md) for fixtures, tests, benchmark reproduction, and implementation history.

[MIT](LICENSE). Independent project; automation backends and the TypeSafe service have their own terms and licenses.