mobai-mcp 2.0.0 → 2.1.0

package/README.md

@@ -3,24 +3,27 @@
 [![npm version](https://badge.fury.io/js/mobai-mcp.svg)](https://www.npmjs.com/package/mobai-mcp)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-MCP (Model Context Protocol) server for [MobAI](https://mobai.run) - AI-powered mobile device automation. This server enables AI coding assistants like Cursor, Windsurf, Cline, and other MCP-compatible tools to control Android and iOS devices, emulators, and simulators.
+MCP (Model Context Protocol) server for [MobAI](https://mobai.run) — AI-powered mobile device automation. Lets AI assistants (Claude Code, Cursor, Windsurf, Cline, and other MCP-compatible tools) control Android and iOS devices, emulators, and simulators via a single DSL-first interface.
 
-## Features
+## How it works
 
-- **Device Control**: List, connect, and manage Android/iOS devices
-- **UI Automation**: Tap, type, swipe, and interact with native apps
-- **Web Automation**: Control Safari/Chrome and WebViews with CSS selectors
-- **DSL Batch Execution**: Execute multiple automation steps efficiently
-- **AI Agent**: Run autonomous agents to complete complex tasks
-- **Screenshot Capture**: Capture and save device screenshots
+All device interaction is batched through one primary tool: **`execute_dsl`**. Instead of exposing dozens of fine-grained tools (tap, swipe, type…), the server accepts a JSON script describing a sequence of actions with predicates, assertions, waits, and conditional branches. This keeps round-trips low and encodes retry/failure strategies server-side.
+
+A small set of companion tools handles device discovery, screenshots, app management, and running `.mob` test files.
 
 ## Prerequisites
 
 - Node.js 18+
-- [MobAI desktop app](https://mobai.run) running locally (provides the HTTP API on port 8686)
-- Connected Android or iOS device (or emulator/simulator)
+- [MobAI desktop app](https://mobai.run) running locally (HTTP API on `127.0.0.1:8686`)
+- A connected Android or iOS device, emulator, or simulator
+
+## Installation
+
+### Claude Code
 
-## Installation & Configuration
+```bash
+claude mcp add mobai -- npx -y mobai-mcp
+```
 
 ### Cursor
 
@@ -39,7 +42,7 @@ Add to `.cursor/mcp.json`:
 
 ### Claude Desktop
 
-Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
@@ -52,146 +55,107 @@ Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_deskt
 }
 ```
 
-### Windsurf
+### Windsurf / Cline / other MCP clients
 
-Add to Windsurf MCP config:
+The server speaks stdio — use your client's generic MCP configuration:
 
 ```json
 {
-  "mcpServers": {
-    "mobai": {
-      "command": "npx",
-      "args": ["-y", "mobai-mcp"]
-    }
-  }
+  "command": "npx",
+  "args": ["-y", "mobai-mcp"]
 }
 ```
 
-### Cline / Other MCP Clients
+## Tools
 
-Configure according to your client's MCP server setup. The server uses stdio transport.
+### Device management
 
-```json
-{
-  "command": "npx",
-  "args": ["-y", "mobai-mcp"]
-}
-```
+| Tool | Description |
+|---|---|
+| `list_devices` | List all connected Android and iOS devices |
+| `get_device` | Get details about a specific device |
+| `start_bridge` | Start the automation bridge on a device (required before interaction) |
+| `stop_bridge` | Stop the automation bridge |
 
-## Available Tools
+### Screenshots
 
-### Device Management
-- `list_devices` - List all connected devices
-- `get_device` - Get device information
-- `start_bridge` - Start on-device automation bridge
-- `stop_bridge` - Stop automation bridge
+| Tool | Description |
+|---|---|
+| `get_screenshot` | Fast, low-quality screenshot for LLM visual analysis (may be downscaled; response includes scale factor) |
+| `save_screenshot` | Full-quality PNG to disk for reporting, debugging, or sharing |
 
-### UI Automation
-- `get_screenshot` - Capture device screenshot
-- `get_ui_tree` - Get accessibility tree (supports text_regex and bounds filtering)
-- `tap` - Tap element by index or coordinates
-- `type_text` - Type text
-- `swipe` - Perform swipe gesture
-- `go_home` - Navigate to home screen
-- `launch_app` - Launch app by bundle ID
-- `list_apps` - List installed apps
+### Apps
 
-### DSL Execution
-- `execute_dsl` - Execute batch automation script
+| Tool | Description |
+|---|---|
+| `list_apps` | List installed apps on the device |
+| `install_app` | Install an `.apk` or `.ipa` from a local file path |
+| `uninstall_app` | Uninstall an app by bundle ID / package name |
+| `debug_app` | Launch an app in debug mode and write stdout/stderr to a log file |
 
-### AI Agent
-- `run_agent` - Run autonomous agent for complex tasks
+### Automation
 
-### Web Automation
-- `web_list_pages` - List browser tabs/WebViews
-- `web_navigate` - Navigate to URL
-- `web_get_dom` - Get DOM tree
-- `web_click` - Click element by CSS selector
-- `web_type` - Type into element by CSS selector
-- `web_execute_js` - Execute JavaScript
+| Tool | Description |
+|---|---|
+| `execute_dsl` | **Primary tool.** Execute a batch of DSL steps: tap, type, swipe, observe, assertions, web automation, metrics, screen recording, and more. |
 
-### Low-Level
-- `http_request` - Make raw HTTP request to MobAI API
+### Test management
 
-## Available Resources
+Tests are `.mob` files on disk inside project directories. You read, write, and edit them directly using your assistant's filesystem tools — MobAI watches for changes and updates the UI live. MCP is only needed to discover projects and run tests.
 
-- `mobai://api-reference` - Complete API documentation
-- `mobai://dsl-guide` - DSL batch execution guide
-- `mobai://native-runner` - Native app automation guide
-- `mobai://web-runner` - Web automation guide
+| Tool | Description |
+|---|---|
+| `test_get_active` | Get the active test project directory and its `.mob` cases |
+| `test_list_projects` | List all known test project directories with their `.mob` cases |
+| `test_run` | Run a `.mob` test case on a device (`project_dir` + `case_path` + `device_id`) |
 
-## Example Usage
+## Resources
 
-### List devices and take screenshot
+Read these **before** attempting any device interaction — they describe the DSL schema, action set, predicates, failure strategies, and `.mob` syntax.
 
-```
-Use the list_devices tool to see connected devices.
-Then use get_screenshot with the device ID.
-```
+| URI | Purpose |
+|---|---|
+| `mobai://reference/device-automation` | How to control devices — guide, all DSL actions, predicates, and failure strategies |
+| `mobai://reference/testing` | Testing workflow, rules, error fixes, and `.mob` script syntax |
 
-### Automate Settings app
+## Example
 
-```
-Use execute_dsl with:
+Open the iOS Settings app, navigate to Wi-Fi, and verify the toggle exists:
+
+```json
 {
   "version": "0.2",
   "steps": [
     {"action": "open_app", "bundle_id": "com.apple.Preferences"},
-    {"action": "delay", "duration_ms": 1000},
-    {"action": "observe", "context": "native", "include": ["ui_tree"]},
-    {"action": "tap", "predicate": {"text_contains": "General"}}
+    {"action": "wait_for", "predicate": {"text": "Settings"}, "timeout_ms": 3000},
+    {"action": "tap", "predicate": {"text_contains": "Wi-Fi"}},
+    {"action": "wait_for", "predicate": {"type": "switch"}, "timeout_ms": 3000},
+    {"action": "assert_exists", "predicate": {"type": "switch"}},
+    {"action": "observe", "include": ["ui_tree"]}
   ]
 }
 ```
 
-### Run AI agent
-
-```
-Use run_agent with device_id and task: "Open Settings and enable WiFi"
-```
-
-## Comparison with Claude Code Plugin
-
-| Feature | Claude Code Plugin | MCP Server |
-|---------|-------------------|------------|
-| Platform | Claude Code only | Any MCP client |
-| Tools | http_request (generic) | Named tools + http_request |
-| Resources | Skills (markdown) | MCP resources |
-| Setup | Plugin install | npx |
-
-The MCP server provides the same functionality as the Claude Code plugin but works with any MCP-compatible AI tool.
+Pass this as the `commands` argument (a JSON string) to `execute_dsl` along with a `device_id` from `list_devices`.
 
 ## Troubleshooting
 
-### "Connection refused" error
-- Ensure MobAI desktop app is running
-- Check that API is available at http://127.0.0.1:8686
+**"Connection refused"** — Make sure the MobAI desktop app is running and the API is reachable at `http://127.0.0.1:8686`.
 
-### "Bridge not running" error
-- Use `start_bridge` tool first before automation
-- iOS bridge may take up to 60 seconds to start
+**"Bridge not running"** — Call `start_bridge` first. The iOS bridge can take up to a minute to come up.
 
-### Screenshots not visible
-- Screenshots are saved to `/tmp/mobai/screenshots/`
-- Use your AI tool's file reading capability to view them
+**Screenshots not visible** — `get_screenshot` saves to `/tmp/mobai/screenshots/` by default and returns the file path. Use your assistant's file-reading capability to view them. DSL `observe` screenshots are extracted from the response and saved to the same directory.
 
 ## Development
 
 ```bash
-# Clone the repository
 git clone https://github.com/MobAI-App/mobai-mcp.git
 cd mobai-mcp
-
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run locally
 node dist/index.js
 ```
 
 ## License
 
-Apache 2.0 - see [LICENSE](LICENSE) for details.
+Apache 2.0 — see [LICENSE](LICENSE).

package/dist/index.js

@@ -107,8 +107,6 @@ async function doRequest(method, urlPath, payload, timeoutMs = DEFAULT_TIMEOUT_M
 const doGet = (p) => doRequest("GET", p);
 const doPost = (p, body) => doRequest("POST", p, body);
 const doDelete = (p) => doRequest("DELETE", p);
-const doPut = (p, body) => doRequest("PUT", p, body);
-const doPatch = (p, body) => doRequest("PATCH", p, body);
 function textResult(data) {
     return {
         content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }],
@@ -127,8 +125,8 @@ function errResult(err) {
 const server = new Server({ name: "mobai", version: "1.0.0" }, {
     capabilities: { tools: {}, resources: {} },
     instructions: `MobAI controls Android and iOS devices. Before starting any device task, read the relevant MCP resources:
-- mobai://reference/device-automation — how to control devices
-- mobai://reference/testing — testing workflow, rules, and .mob script syntax
+- mobai://reference/device-automation — how to control devices (read before ANY device interaction)
+- mobai://reference/testing — .mob script syntax (read ONLY when user asks to create or fix test scripts)
 Check available skills in current work directory and load any relevant to the user's request.`,
 });
 // ---------------------------------------------------------------------------
@@ -171,7 +169,7 @@ const TOOLS = [
     // Screenshot
     {
         name: "get_screenshot",
-        description: "Capture a fast, low-quality screenshot for LLM visual analysis. Returns the file path to the saved image. Use this for AI/LLM processing only — for full-quality screenshots use save_screenshot instead.",
+        description: "Capture a fast, low-quality screenshot for LLM visual analysis. Returns the file path to the saved image. The image may be downscaled by an integer factor so its long edge stays ≤ 2000px; when that happens the response includes a scale factor — multiply any coordinates you read off the image by that factor before using them in device actions (tap, swipe, drag, long-press, etc.). UI tree coordinates are already in device pixels, do not scale those. Use this for AI/LLM processing only — for full-quality screenshots use save_screenshot instead.",
         inputSchema: {
             type: "object",
             properties: { device_id: { type: "string", description: "Device ID" } },
@@ -191,6 +189,20 @@ const TOOLS = [
             required: ["device_id"],
         },
     },
+    // Debug launch
+    {
+        name: "debug_app",
+        description: "Launch an app in debug mode and write logs to a file. Returns the log file path — use Read/Grep to inspect logs. Use kill_app to stop.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                bundle_id: { type: "string", description: "Bundle ID of the app to debug" },
+                log_path: { type: "string", description: "Directory for log file (supports ~/). Defaults to OS temp directory." },
+            },
+            required: ["device_id", "bundle_id"],
+        },
+    },
     // App management
     {
         name: "list_apps",
@@ -230,7 +242,7 @@ const TOOLS = [
         name: "execute_dsl",
         description: `Execute a batch of DSL commands on a device. This is the primary tool for all device interaction — tap, type, swipe, observe, launch apps, assertions, web automation, and more.
 
-Read the MCP resource mobai://reference/device-automation to learn how to control devices before using this tool.
+You MUST read the MCP resource mobai://reference/device-automation to learn how to control devices before using this tool.
 
 Input: JSON string with "version": "0.2" and "steps" array. Example:
 {"version":"0.2","steps":[
@@ -250,150 +262,25 @@ Input: JSON string with "version": "0.2" and "steps" array. Example:
     // Test management
     {
         name: "test_get_active",
-        description: "Get the currently active test project and its cases. Use this to discover which test cases are available.",
+        description: "Get the currently active test project directory and its .mob test cases. Use this to discover the project path and available tests. The agent can then read/write/create/delete .mob files directly in the returned directory.",
         inputSchema: { type: "object", properties: {}, required: [] },
     },
     {
         name: "test_list_projects",
-        description: "List all test projects with their test cases included inline",
+        description: "List all known test project directories with their .mob test cases. Each project is a directory containing .mob script files.",
         inputSchema: { type: "object", properties: {}, required: [] },
     },
-    {
-        name: "test_create_project",
-        description: "Create a new test project",
-        inputSchema: {
-            type: "object",
-            properties: { name: { type: "string", description: "Project name" } },
-            required: ["name"],
-        },
-    },
-    {
-        name: "test_rename_project",
-        description: "Rename an existing test project",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                name: { type: "string", description: "New project name" },
-            },
-            required: ["project_id", "name"],
-        },
-    },
-    {
-        name: "test_create_case",
-        description: "Create a new test case in a project",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                name: { type: "string", description: "Test case name" },
-                folder: { type: "string", description: "Optional folder path within the project" },
-            },
-            required: ["project_id", "name"],
-        },
-    },
-    {
-        name: "test_rename_case",
-        description: "Rename an existing test case",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-                name: { type: "string", description: "New test case name" },
-            },
-            required: ["project_id", "case_id", "name"],
-        },
-    },
-    {
-        name: "test_delete_case",
-        description: "Delete a test case from a project",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-            },
-            required: ["project_id", "case_id"],
-        },
-    },
-    {
-        name: "test_get_script",
-        description: "Get the .mob script content for a test case (with 1-based line numbers)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-            },
-            required: ["project_id", "case_id"],
-        },
-    },
-    {
-        name: "test_replace_script",
-        description: "Replace the entire .mob script for a test case",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-                script: { type: "string", description: "New script content (without line numbers)" },
-            },
-            required: ["project_id", "case_id", "script"],
-        },
-    },
-    {
-        name: "test_update_line",
-        description: "Update a single line in the .mob script",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-                line_number: { type: "number", description: "1-based line number to update" },
-                content: { type: "string", description: "New line content" },
-            },
-            required: ["project_id", "case_id", "line_number", "content"],
-        },
-    },
-    {
-        name: "test_insert_after",
-        description: "Insert a new line after the specified line number in the .mob script",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-                line_number: { type: "number", description: "1-based line number to insert after (0 = insert at beginning)" },
-                content: { type: "string", description: "Line content to insert" },
-            },
-            required: ["project_id", "case_id", "line_number", "content"],
-        },
-    },
-    {
-        name: "test_delete_line",
-        description: "Delete a line from the .mob script",
-        inputSchema: {
-            type: "object",
-            properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
-                line_number: { type: "number", description: "1-based line number to delete" },
-            },
-            required: ["project_id", "case_id", "line_number"],
-        },
-    },
     {
         name: "test_run",
-        description: "Run a test case on a device",
+        description: "Run a .mob test case on a device. The case_path is relative to the project directory.",
         inputSchema: {
             type: "object",
             properties: {
-                project_id: { type: "string", description: "Project ID" },
-                case_id: { type: "string", description: "Test case ID" },
+                project_dir: { type: "string", description: "Absolute path to the project directory" },
+                case_path: { type: "string", description: "Relative path to the .mob file within the project, e.g. auth/login.mob" },
                 device_id: { type: "string", description: "Device ID to run the test on" },
             },
-            required: ["project_id", "case_id", "device_id"],
+            required: ["project_dir", "case_path", "device_id"],
         },
     },
 ];
@@ -406,13 +293,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 // ---------------------------------------------------------------------------
 // Tool call handler
 // ---------------------------------------------------------------------------
-function testCasePath(args) {
-    const projectId = args?.project_id;
-    const caseId = args?.case_id;
-    if (!projectId || !caseId)
-        throw new Error("project_id and case_id are required");
-    return `/tests/projects/${projectId}/cases/${caseId}`;
-}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
@@ -442,6 +322,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return textResult(screenshotToFile(body));
             }
             // App management
+            case "debug_app": {
+                const body = { bundleId: args?.bundle_id };
+                if (args?.log_path)
+                    body.logPath = args.log_path;
+                return textResult(await doPost(`/devices/${args?.device_id}/debug/launch`, body));
+            }
             case "list_apps":
                 return textResult(await doGet(`/devices/${args?.device_id}/apps`));
             case "install_app":
@@ -468,56 +354,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return textResult(await doGet("/tests/active"));
             case "test_list_projects":
                 return textResult(await doGet("/tests/projects"));
-            case "test_create_project":
-                return textResult(await doPost("/tests/projects", { name: args?.name }));
-            case "test_rename_project":
-                return textResult(await doPatch(`/tests/projects/${args?.project_id}`, { name: args?.name }));
-            case "test_create_case": {
-                const body = { name: args?.name };
-                if (args?.folder)
-                    body.folder = args.folder;
-                return textResult(await doPost(`/tests/projects/${args?.project_id}/cases`, body));
-            }
-            case "test_rename_case": {
-                const p = testCasePath(args);
-                return textResult(await doPatch(p, { name: args?.name }));
-            }
-            case "test_delete_case": {
-                const p = testCasePath(args);
-                return textResult(await doDelete(p));
-            }
-            case "test_get_script": {
-                const p = testCasePath(args);
-                return textResult(await doGet(`${p}/script`));
-            }
-            case "test_replace_script": {
-                const p = testCasePath(args);
-                return textResult(await doPut(`${p}/script`, { script: args?.script }));
-            }
-            case "test_update_line": {
-                const p = testCasePath(args);
-                return textResult(await doPost(`${p}/script/update-line`, {
-                    line_number: args?.line_number,
-                    content: args?.content,
+            case "test_run":
+                return textResult(await doPost("/tests/cases/run", {
+                    project_dir: args?.project_dir,
+                    case_path: args?.case_path,
+                    device_id: args?.device_id,
                 }));
-            }
-            case "test_insert_after": {
-                const p = testCasePath(args);
-                return textResult(await doPost(`${p}/script/insert-after`, {
-                    line_number: args?.line_number,
-                    content: args?.content,
-                }));
-            }
-            case "test_delete_line": {
-                const p = testCasePath(args);
-                return textResult(await doPost(`${p}/script/delete-line`, {
-                    line_number: args?.line_number,
-                }));
-            }
-            case "test_run": {
-                const p = testCasePath(args);
-                return textResult(await doPost(`${p}/run`, { device_id: args?.device_id }));
-            }
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }

package/dist/resources.js

@@ -22,9 +22,6 @@ export function getResourceContent(uri) {
             return null;
     }
 }
-// ---------------------------------------------------------------------------
-// Resource content — copied verbatim from Go resources.go
-// ---------------------------------------------------------------------------
 const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
 <guide>
@@ -54,8 +51,8 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   </ocr-fallback>
 
   <execution-modes>
-    Default (explore mode): non-last observe actions are skipped — only final observe executes. Use "mode": "deterministic" when you need every observe to execute (observe → act → observe → act → observe).
-    Example: {"version": "0.2", "mode": "deterministic", "steps": [{"action": "observe", "include": ["ui_tree"]}, {"action": "tap", "predicate": {"text": "Next"}}, {"action": "observe", "include": ["ui_tree"]}]}
+    Default (explore mode): only the last observe in a script runs — earlier observes are skipped. This is the right mode for the typical pattern: actions first, then one observe at the end to see the result. If a step fails, the error includes a debug UI tree so you don't need a separate observe.
+    Deterministic mode: every observe runs. Use only when you need to capture screen state between actions within a single script (rare — prefer separate execute_dsl calls so you can reason between steps).
   </execution-modes>
 
   <workflow>Observe screen → plan → act via execute_dsl → verify (end script with wait_for stable + observe) → repeat until done.</workflow>
@@ -63,6 +60,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <screenshot-tools>
     get_screenshot — fast low-quality image for LLM visual analysis.
     save_screenshot — full-quality PNG for reporting, debugging, or sharing.
+    To verify animations and UI transitions, use record_start/record_stop.
   </screenshot-tools>
 
   <infinite-scrolling>To collect data from infinite-scrolling views (feeds, search results), scroll to load a batch first, then observe with only_visible:false to get all loaded items in one go.</infinite-scrolling>
@@ -79,14 +77,13 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <target-element>{"predicate": Predicate}</target-element>
 
   <predicate context="native">
-    <note>Prefer text_contains or text_regex over text (exact match) — UI text often changes with state, locale, or dynamic content. Exact match breaks easily. Prefer text fields over label fields — text is what the user sees on screen and is more reliable.</note>
+    <note>Prefer text_contains or text_regex over text (exact match) — UI text often changes with state, locale, or dynamic content. Exact match breaks easily.</note>
     <field name="text" type="string">Exact match — use only when the full text is short, static, and unique</field>
     <field name="text_contains" type="string">Substring, case-insensitive — preferred for most matching</field>
     <field name="text_starts_with" type="string">Prefix match</field>
     <field name="text_regex" type="string">Regex pattern — use for dynamic text (numbers, dates, counts)</field>
     <field name="type" type="string">button, input, switch, text, image, cell, scrollview</field>
-    <field name="label" type="string">Accessibility label (exact) — use only when text fields are empty</field>
-    <field name="label_contains" type="string">Accessibility label (partial) — use only when text fields are empty</field>
+    <field name="accessibility_id" type="string">Exact match on the #id shown in UI tree (without the # prefix)</field>
     <field name="enabled" type="bool">Enabled state</field>
     <field name="visible" type="bool">Visible state</field>
     <field name="selected" type="bool">Selected state</field>
@@ -165,9 +162,10 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     Direction = semantic (where to look), not finger movement.
     <field name="direction" required="yes">down (look below), up (look above)</field>
     <field name="to_element" type="TargetElement"/>
-    <field name="max_scrolls" type="int"/>
+    <field name="max_scrolls" type="int" default="10"/>
     <field name="amount">small, page, full</field>
     <example>{"action": "scroll", "direction": "down", "to_element": {"predicate": {"text": "Privacy"}}, "max_scrolls": 10}</example>
+    <note>scroll with to_element returns "reached end of scrollable content" if the list ends before the element is found. If it returns "element not found after scrolling" instead, the list has more content — increase max_scrolls or call scroll again to continue searching.</note>
   </action>
 
   <action name="drag">
@@ -190,7 +188,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
   <action name="toggle">
     <field name="predicate" required="yes"/>
-    <field name="state" required="yes">on or off</field>
+    <field name="state" required="no">Desired state: "on" or "off". If omitted, always toggles. If set, skips when already correct.</field>
     <example>{"action": "toggle", "predicate": {"type": "switch", "text_contains": "Wi-Fi"}, "state": "on"}</example>
   </action>
 
@@ -342,6 +340,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <action name="record_stop">
     <field name="file_path">Override output directory</field>
     <returns>recording_path, frame_count, transition_hints (anomalies: jump/flash/stutter/incoherent_motion with from_frame, to_frame, type, delta_percent, region, message)</returns>
+    <note>transition_hints contains anomalous frame pairs (from_frame, to_frame). If transition_hints is empty, do not read any frames. If not empty, read only the flagged frame pairs. Read additional frames only if strictly necessary to investigate a flagged anomaly.</note>
   </action>
 </screen-recording>
 
@@ -351,8 +350,15 @@ const TESTING_REF = `<testing-reference>
 
 <important>Read mobai://reference/device-automation to learn how to control devices before interacting with them.</important>
 
+<file-model>
+  Tests are .mob files on disk inside project directories. You work with them directly:
+  - Use test_list_projects to discover project directories and their .mob files
+  - Read .mob files directly from the project directory using filesystem tools
+  - Create, edit, rename, and delete .mob files directly — MobAI watches for changes and updates the UI live
+  - Use test_run to execute a test on a device — this is the only operation that requires MCP
+</file-model>
+
 <rules>
-  <rule>Test scripts are ONLY accessible via MCP test_* tools. There are NO .mob files on disk. Do NOT use grep, find, cat, or any filesystem commands to look for scripts.</rule>
   <rule>Never ask the user for information you can get yourself — use observe, list_apps, get_ui_tree.</rule>
   <rule>Always add wait_for before every element interaction (tap, type, toggle, long_press, double_tap, drag). Exception: the element was asserted on the immediately preceding line.</rule>
   <rule>Always use predicates over coordinates — predicates survive layout changes.</rule>
@@ -361,22 +367,21 @@ const TESTING_REF = `<testing-reference>
 </rules>
 
 <workflow-create>
-  1. Observe the current screen
-  2. Plan the test steps from the user's description
-  3. Execute each action via DSL — add wait_for before every element interaction
-  4. Assert after key actions — verify expected state with assert_exists/assert_not_exists
-  5. Output the full script using MCP test tools
-  6. Verify — run the full script end-to-end
-  7. Fix — if steps fail, observe the screen, fix the failing lines
-  8. Re-run to verify fixes (max 3 retry cycles)
+  1. Call test_list_projects to find the project directory and existing tests
+  2. Observe the current screen on the device
+  3. Plan the test steps from the user's description
+  4. Write the .mob file directly to the project directory
+  5. Run the test with test_run
+  6. Fix — if steps fail, read the error, observe the screen, edit the .mob file
+  7. Re-run to verify fixes (max 3 retry cycles)
 </workflow-create>
 
 <workflow-fix>
-  1. Read the current script
+  1. Read the .mob file from disk
   2. Analyze the error messages — they reference exact line numbers
-  3. Reproduce — run the failing line individually via DSL to observe device state
-  4. Fix — update, insert, or delete lines as needed
-  5. Verify — re-run the test
+  3. Reproduce — run a failing action via DSL to observe device state
+  4. Edit the .mob file directly
+  5. Re-run with test_run
 </workflow-fix>
 
 <error-fixes>
@@ -405,10 +410,9 @@ const TESTING_REF = `<testing-reference>
 
 <verification>
   Check before every response:
-  1. Did you use MCP tools for all script mutations? (bare .mob lines in text are silently ignored)
-  2. Does every element interaction have a wait_for on the preceding line?
-  3. Are predicates used instead of coordinates wherever possible?
-  4. Did you observe the screen before acting?
+  1. Does every element interaction have a wait_for on the preceding line?
+  2. Are predicates used instead of coordinates wherever possible?
+  3. Did you observe the screen before acting?
 </verification>
 
 <mob-script-syntax>
@@ -452,6 +456,14 @@ const TESTING_REF = `<testing-reference>
     delay 1000                          — wait N ms
     press_key home|back|enter           — hardware key
     navigate back|home                  — navigation shortcut
+    two_finger_tap "Map"                — two-finger tap
+    pinch "Map" scale:0.5               — pinch (scale <1 = zoom out, >1 = zoom in)
+    pinch "Photo" scale:2.0             — pinch to zoom in
+    hide_keyboard                       — dismiss keyboard
+    copy_text "Field"                   — copy text from element
+    paste_text "Field"                  — paste clipboard into element
+    set_location 40.7128,-74.0060       — simulate GPS location (lat,lon)
+    reset_location                      — stop location simulation
     observe                             — observe screen
     screenshot "path.png"               — take screenshot
   </actions>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobai-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "mcpName": "io.github.MobAI-App/mobai-mcp",
   "description": "MCP server for MobAI - AI-powered mobile device automation",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/MobAI-App/mobai-mcp",
     "source": "github"
   },
-  "version": "2.0.0",
+  "version": "2.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mobai-mcp",
-      "version": "2.0.0",
+      "version": "2.1.0",
       "transport": {
         "type": "stdio"
       }