mobai-mcp 1.0.0 → 1.0.1

package/dist/index.js

@@ -836,6 +836,36 @@ const API_REFERENCE = `# MobAI API Reference
 \`\`\`json
 {"error": "message", "code": "ERROR_CODE"}
 \`\`\`
+
+## DSL Action Reference
+
+### type Action
+- **predicate**: Required if keyboard not already open (auto-taps the element first)
+- **dismiss_keyboard**: Default \`false\` (keyboard stays open after typing)
+- **clear_first**: Optional, clears field before typing
+
+\`\`\`json
+{"action": "type", "text": "hello", "predicate": {"type": "input"}}
+\`\`\`
+
+### press_key Action
+- **key**: Keyboard key to press (return, tab, delete, escape, etc.)
+- **context**: Optional, "web" for web context (supports enter, tab, delete, escape)
+
+\`\`\`json
+{"action": "press_key", "key": "return"}
+{"action": "press_key", "key": "tab", "context": "web"}
+\`\`\`
+
+### select_web_context Action
+- **url_contains**: Filter by URL substring
+- **title_contains**: Filter by page title substring
+
+\`\`\`json
+{"action": "select_web_context"}
+{"action": "select_web_context", "url_contains": "example.com"}
+{"action": "select_web_context", "title_contains": "Login"}
+\`\`\`
 `;
 const DSL_GUIDE = `# MobAI DSL Guide
 
@@ -860,7 +890,8 @@ The DSL (Domain Specific Language) enables batch execution of multiple automatio
 |--------|-------------|------------|
 | observe | Get UI tree/screenshot | context, include (ui_tree, screenshot, installed_apps) |
 | tap | Tap element | predicate or coords |
-| type | Type text | text, predicate, clear_first |
+| type | Type text | text, predicate (if keyboard not open), dismiss_keyboard (default: false) |
+| press_key | Press keyboard key | key (return, tab, delete, etc.), context (optional: "web") |
 | toggle | Set switch state | predicate, state ("on"/"off") |
 | swipe | Swipe gesture | direction, distance, duration_ms |
 | scroll | Scroll in container | direction, predicate (container), to_element |
@@ -871,6 +902,7 @@ The DSL (Domain Specific Language) enables batch execution of multiple automatio
 | assert_not_exists | Verify element gone | predicate |
 | delay | Wait fixed time | duration_ms |
 | if_exists | Conditional | predicate, then, else |
+| select_web_context | Select browser/WebView | url_contains, title_contains (optional filters) |
 
 ## Predicates
 
@@ -894,9 +926,11 @@ Match elements by:
 
 ### Type Text
 \`\`\`json
-{"action": "type", "text": "Hello", "clear_first": true}
+{"action": "type", "text": "Hello", "predicate": {"type": "input"}}
 \`\`\`
 
+Note: \`predicate\` is required if keyboard is not already open. Use \`dismiss_keyboard: true\` to close keyboard after typing.
+
 ### Toggle Switch
 \`\`\`json
 {"action": "toggle", "predicate": {"type": "switch", "text_contains": "WiFi"}, "state": "on"}
@@ -926,13 +960,71 @@ const NATIVE_RUNNER_GUIDE = `# Native App Automation Guide
 
 Use this for automating native mobile apps (Settings, Mail, Instagram, etc.).
 
+## Script Writing Guidelines
+
+The DSL's purpose is to **minimize LLM calls** by encoding assumptions into comprehensive scripts. Write scripts that handle common scenarios without needing to re-observe.
+
+### Example: Handle Cookie Banner
+\`\`\`json
+{
+  "action": "if_exists",
+  "predicate": {"text_contains": "Accept Cookies"},
+  "then": [{"action": "tap", "predicate": {"text_contains": "Accept"}}]
+}
+\`\`\`
+
+### Common Knowledge (use without observing)
+- Safari has an address bar at the top
+- Settings app has Wi-Fi, Bluetooth, General sections
+- Alert dialogs have "OK", "Cancel", "Allow", "Don't Allow" buttons
+- iOS keyboard has "Done", "Return", "Search" keys
+
+### Script Writing Rules
+- **Use open_app** - Always start scripts with open_app to ensure correct app
+- **UI tree provided upfront** - You receive the initial UI tree, use it to plan the script
+- **Use if_exists for popups** - Handle cookie banners, permission dialogs, notifications
+- **observe only for assert_screen_changed** - Use observe to establish baseline, then assert_screen_changed to verify navigation
+
+## IMPORTANT: Browser Native UI
+
+When automating browsers (Safari, Chrome), use **Native Runner** for the browser's own UI:
+- Address bar / URL bar
+- Tab bar and tab management
+- Navigation buttons (back, forward, refresh)
+- Bookmarks bar
+- Browser menus and settings
+
+These are native OS elements, NOT web content. Only use Web Runner for the actual webpage content inside the browser.
+
 ## Workflow
 
 1. **Observe UI** - Get the accessibility tree
 2. **Match Elements** - Use predicates to find elements
-3. **Execute Actions** - Tap, type, swipe, etc.
+3. **Execute Actions** - Tap, type, swipe, press_key, etc.
 4. **Verify Results** - Check UI state changed
 
+## Type Action
+
+The \`type\` action requires either:
+1. Keyboard already open (from previous tap on input), OR
+2. A predicate to identify and tap the input field
+
+**dismiss_keyboard** default is \`false\` (keyboard stays open after typing).
+
+### Pattern 1: Tap then Type
+\`\`\`json
+[
+  {"action": "tap", "predicate": {"type": "input"}},
+  {"action": "type", "text": "username"},
+  {"action": "press_key", "key": "tab"}
+]
+\`\`\`
+
+### Pattern 2: Type with Predicate
+\`\`\`json
+{"action": "type", "text": "username", "predicate": {"type": "input", "label": "Username"}}
+\`\`\`
+
 ## Common Patterns
 
 ### Open App and Navigate
@@ -954,9 +1046,10 @@ Use this for automating native mobile apps (Settings, Mail, Instagram, etc.).
   "version": "0.2",
   "steps": [
     {"action": "tap", "predicate": {"type": "input"}},
-    {"action": "type", "text": "username", "clear_first": true},
-    {"action": "tap", "predicate": {"type": "input", "index": 1}},
-    {"action": "type", "text": "password", "clear_first": true}
+    {"action": "type", "text": "username"},
+    {"action": "press_key", "key": "tab"},
+    {"action": "type", "text": "password"},
+    {"action": "press_key", "key": "return"}
   ]
 }
 \`\`\`
@@ -986,16 +1079,45 @@ Use this for automating native mobile apps (Settings, Mail, Instagram, etc.).
 }
 \`\`\`
 
+## Quick Reference
+
+| Action | Description | Key Fields |
+|--------|-------------|------------|
+| tap | Tap element | predicate or coords |
+| type | Type text | text, predicate (if keyboard not open), dismiss_keyboard (default: false) |
+| press_key | Press keyboard key | key (return, tab, delete, etc.) |
+| swipe | Swipe gesture | direction, distance |
+| scroll | Scroll container | direction, to_element |
+
 ## Tips
 
 - **Always observe first** - Get UI tree before interacting
 - **Use predicates** - More robust than hardcoded indices
 - **Add delays after navigation** - Apps need time to render
 - **Use retry strategy** - Transient failures are common
+- **Use press_key for form navigation** - Tab between fields, Return to submit
 `;
 const WEB_RUNNER_GUIDE = `# Web Automation Guide
 
-Use this for automating browsers (Safari, Chrome) and WebViews on mobile devices.
+**Try native-runner first for simple taps/types.** Only use Web Runner when you need DOM manipulation, CSS selectors, or JavaScript execution.
+
+## When to Use Web Runner
+
+✅ **USE Web Runner for:**
+- Native runner returns NO_MATCH for web elements
+- CSS selector-based element targeting
+- JavaScript execution in page context
+- DOM manipulation and inspection
+- Complex form interactions requiring DOM access
+
+❌ **DO NOT use Web Runner for:**
+- Browser address bar / URL bar → use Native Runner
+- Browser tab bar → use Native Runner
+- Browser navigation buttons (back, forward, refresh) → use Native Runner
+- Browser menus and settings → use Native Runner
+- Any UI outside the webpage or webview content area → use Native Runner
+
+The browser's own UI (address bar, tabs, navigation) are **native OS elements**, not web content.
 
 ## Platform Support
 
@@ -1009,7 +1131,26 @@ Use this for automating browsers (Safari, Chrome) and WebViews on mobile devices
 1. **Select web context** - Connect to browser
 2. **Navigate** - Go to URL
 3. **Get DOM** - Inspect page structure
-4. **Interact** - Click, type using CSS selectors
+4. **Interact** - Click, type, press_key using CSS selectors
+
+## select_web_context Options
+
+\`\`\`json
+{"action": "select_web_context"}
+{"action": "select_web_context", "url_contains": "example.com"}
+{"action": "select_web_context", "title_contains": "Login"}
+\`\`\`
+
+Use \`url_contains\` or \`title_contains\` to select a specific tab/WebView when multiple are available.
+
+## press_key (Web Context)
+
+Press keyboard keys in web context. Supported keys: \`enter\`, \`tab\`, \`delete\`, \`escape\`
+
+\`\`\`json
+{"action": "press_key", "context": "web", "key": "enter"}
+{"action": "press_key", "context": "web", "key": "tab"}
+\`\`\`
 
 ## Common Patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobai-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for MobAI - AI-powered mobile device automation",
   "type": "module",
   "main": "dist/index.js",