mobai-mcp 1.5.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.d.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /**
- * MobAI MCP Server
+ * MobAI MCP Server (stdio)
  *
- * Provides tools for AI-powered mobile device automation through the MobAI HTTP API.
- * Works with both Android and iOS devices, emulators, and simulators.
+ * Mirrors the Go HTTP-based MCP server as a stdio transport.
+ * Proxies tool calls to the MobAI HTTP API at 127.0.0.1:8686.
  */
 export {};