feat(session): consolidate device actions into appium_mobile_device_control by Mochxd · Pull Request #259 · appium/appium-mcp

Mochxd · 2026-04-10T11:49:12Z

Consolidates lock, unlock, shake, and open notifications into one intent-based tool: appium_mobile_device_control.

What changed

Replaced separate tools with a single tool:
- action: "lock" | "unlock" | "shake" | "open_notifications"
- optional seconds only for action="lock" (timed lock via mobile: lock)
shake: iOS XCUITest sessions only
open_notifications: Android only (UiAutomator2 openNotifications(), or mobile: openNotifications for remote sessions)
Updated tool registration in src/tools/index.ts
Updated docs (README.md, src/tools/README.md)

Behavior

action="lock" → mobile: lock (optional seconds)
action="unlock" → mobile: unlock
action="shake" → device shake (XCUITest)
action="open_notifications" → open notifications panel (Android)
Validation: seconds is rejected when action is not lock.

Mochxd · 2026-04-13T13:20:32Z

@KazuCocoa @saikrishna321 @SrinivasanTarget
there’s a lot of overlap with #260, so I compared the two approaches:

feat(session): consolidate device actions into appium_mobile_device_control #259 (appium_mobile_device_control) only merges lock / unlock / shake / open notifications, and keeps appium_mobile_device_info as its own tool (already consolidated on main).
feat: consolidate device management tools into single appium_device tool #260 (appium_device) merges those plus info / battery / time by absorbing device-info.ts into one mega-tool.

Design preference

I think we should keep device info (read-only / query: model, battery, time, etc.) and device mobile control (mutating: lock, unlock, shake, notifications) as separate MCP tools clearer responsibilities, smaller parameter surface per tool, and easier for clients to treat "read state" vs "act on device" differently.

Naming

Action string differs: open_notifications (feat(session): consolidate device actions into appium_mobile_device_control #259) vs notifications (feat: consolidate device management tools into single appium_device tool #260), and tool name differs: appium_mobile_device_control vs appium_device.

Behavior / review notes

Worth aligning error semantics: some unsupported-platform paths in feat: consolidate device management tools into single appium_device tool #260 return text without isError: true, while feat(session): consolidate device actions into appium_mobile_device_control #259 funnels failures through isError: true in the catch path.
Worth confirming whether seconds should be rejected for non-lock actions (explicit validation vs strict schema).

i think we should not align on naming and action strings only but I’d prefer not folding device info into the same tool as lock/shake/notifications.

SrinivasanTarget · 2026-04-15T06:34:59Z

@Mochxd thanks for your valuable contribution and suggestion. I agree with you on the suggestion. The design principle should be: one user intent = one tool, regardless of how many Appium APIs it takes underneath.

appium_mobile_device_control (lock, unlock, shake, open_notifications) = "control the physical device" one user intent, one tool. This is correct.
appium_mobile_device_info (info, battery, time) = "query device state" separate intent, separate tool. Also correct.

"control device" and "query device" are fundamentally different intents.

@navin772 @Delta456

SrinivasanTarget · 2026-04-15T06:52:37Z

+  PLATFORM,
+} from '../../session-store.js';
+import { execute } from '../../command.js';
+


seems like a giant. Can we do something like this?

async function handleLock(driver, seconds?: number): Promise { ... }
async function handleUnlock(driver): Promise { ... }
async function handleShake(driver): Promise { ... }
async function handleOpenNotifications(driver): Promise { ... }

good catch as usual, done extracted handleLock, handleUnlock, handleShake, and handleOpenNotifications into separate functions, the execute block is now a thin switch/case dispatcher

SrinivasanTarget · 2026-04-15T07:32:49Z

+  action: z
+    .enum(['lock', 'unlock', 'shake', 'open_notifications'])
+    .describe(
+      'Action to perform: lock/unlock device, shake (iOS XCUITest only), or open notifications (Android only).'


.describe(
'Action to perform. ' +
'lock: lock the device (optional seconds for timed lock). ' +
'unlock: unlock the device. ' +
'shake: perform shake gesture (iOS XCUITest only). ' +
'open_notifications: open notifications panel (Android only).'
)

SrinivasanTarget · 2026-04-15T07:33:25Z

+  server.addTool({
+    name: 'appium_mobile_device_control',
+    description:
+      'Control device-level actions in one tool. action=lock|unlock uses mobile: lock/unlock, action=shake performs iOS XCUITest shake, action=open_notifications opens Android notifications panel.',


Tool description could be more intent-oriented

e.g. Control device behavior: lock/unlock the screen, shake the device, or open the notifications panel. Use the action parameter to choose what to do.

done, i adopted your suggested intent-oriented description

SrinivasanTarget · 2026-04-15T07:34:53Z

 | `create_session` | Create a new mobile automation session for Android, iOS, or `general` capabilities (see 'general' mode above). If a remote Appium server is referenced, `create_session` forwards the final capabilities to that server via the WebDriver `newSession` API - include device selection (e.g., `appium:udid`) in `capabilities` when targeting a remote server. |
 | `delete_session` | Delete the current mobile session and clean up resources                                                    |
-| `appium_mobile_shake` | Shake gesture (`mobile: shake`) on **iOS Simulator only** (XCUITest). Not supported on Android or physical iOS devices. |
+| `appium_mobile_device_control` | Device controls in one tool (`action`: `lock` \| `unlock` \| `shake` \| `open_notifications`). `shake` requires iOS XCUITest; `open_notifications` is Android only; `seconds` is optional for timed lock. |


drop "XCUITest" from the README

…ontrol Replace separate shake, notifications, and lock/unlock tools with one action-based tool (lock, unlock, shake, open_notifications) and platform-specific validation.

- Extract handler functions: handleLock, handleUnlock, handleShake, handleOpenNotifications for cleaner separation - Use switch/case dispatch in execute - Update action .describe() with per-action explanations - Make tool description intent-oriented per reviewer suggestion - Drop XCUITest reference from README description

KazuCocoa mentioned this pull request Apr 10, 2026

feat: consolidate geolocation functionality into a single tool #256

Merged

Mochxd force-pushed the feat/mobile-device-lock-consolidation branch 2 times, most recently from a1243fe to 9c13fce Compare April 13, 2026 13:07

Mochxd changed the title ~~feat(session): consolidate lock and unlock into appium_mobile_device_lock~~ feat(session): consolidate device actions into appium_mobile_device_control Apr 13, 2026

Mochxd force-pushed the feat/mobile-device-lock-consolidation branch from 39727c9 to 9c13fce Compare April 13, 2026 13:47

SrinivasanTarget requested changes Apr 15, 2026

View reviewed changes

Mochxd added 2 commits April 15, 2026 15:41

feat(session): consolidate device actions into appium_mobile_device_c…

3cfec5d

…ontrol Replace separate shake, notifications, and lock/unlock tools with one action-based tool (lock, unlock, shake, open_notifications) and platform-specific validation.

Mochxd force-pushed the feat/mobile-device-lock-consolidation branch from 9c13fce to d7b22f7 Compare April 15, 2026 13:44

Mochxd requested a review from SrinivasanTarget April 15, 2026 14:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(session): consolidate device actions into appium_mobile_device_control#259

feat(session): consolidate device actions into appium_mobile_device_control#259
Mochxd wants to merge 2 commits intoappium:mainfrom
Mochxd:feat/mobile-device-lock-consolidation

Mochxd commented Apr 10, 2026 •

edited

Loading

Uh oh!

Mochxd commented Apr 13, 2026

Uh oh!

SrinivasanTarget commented Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Uh oh!

Mochxd Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Uh oh!

Mochxd Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Mochxd commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Behavior

Uh oh!

Mochxd commented Apr 13, 2026

Uh oh!

SrinivasanTarget commented Apr 15, 2026

Uh oh!

SrinivasanTarget Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Mochxd Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

SrinivasanTarget Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

SrinivasanTarget Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

SrinivasanTarget Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Mochxd Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

SrinivasanTarget Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mochxd commented Apr 10, 2026 •

edited

Loading