@mobilenext/mobile-mcp 1.0.8 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -31,6 +31,15 @@ Run it against devices on your own machine, or against real iOS and Android devi
31
31
  </a>
32
32
  </h4>
33
33
 
34
+ <p align="center">
35
+ <a href="https://www.star-history.com/?repos=mobile-next%2Fmobile-mcp">
36
+ <picture>
37
+ <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending&theme=dark" />
38
+ <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending" />
39
+ <img alt="GitHub Trending Repository of the Day" src="https://api.star-history.com/badge?repo=mobile-next/mobile-mcp&type=trending" />
40
+ </picture>
41
+ </a>
42
+ </p>
34
43
 
35
44
  https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
36
45
 
@@ -96,15 +105,15 @@ How we help to scale mobile automation:
96
105
  - **`mobile_launch_app`** - Launch an app using its package name
97
106
  - **`mobile_terminate_app`** - Stop and terminate a running app
98
107
  - **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
99
- - **`mobile_uninstall_app`** - Uninstall an app using bundle ID or package name
108
+ - **`mobile_uninstall_app`** - Uninstall an app by its package name or bundle ID
100
109
 
101
110
  ### Screen Interaction
102
111
  - **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
103
112
  - **`mobile_save_screenshot`** - Save a screenshot to a file
104
113
  - **`mobile_list_elements_on_screen`** - List UI elements with their coordinates and properties
105
- - **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates
106
- - **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates
107
- - **`mobile_long_press_on_screen_at_coordinates`** - Long press at specific coordinates
114
+ - **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates or on an element by its ref
115
+ - **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates or on an element by its ref
116
+ - **`mobile_long_press_on_screen_at_coordinates`** - Long press at specific coordinates or on an element by its ref
108
117
  - **`mobile_swipe_on_screen`** - Swipe in any direction (up, down, left, right)
109
118
  - **`mobile_start_screen_recording`** - Start recording the device screen to a video file
110
119
  - **`mobile_stop_screen_recording`** - Stop the active screen recording and save the video
@@ -112,7 +121,7 @@ How we help to scale mobile automation:
112
121
  ### Input & Navigation
113
122
  - **`mobile_type_keys`** - Type text into focused elements with optional submit
114
123
  - **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
115
- - **`mobile_open_url`** - Open URLs in the device browser
124
+ - **`mobile_open_url`** - Open http/https URLs in the device browser
116
125
 
117
126
  ### Logs & Crash Reports
118
127
  - **`mobile_get_device_logs`** - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
@@ -164,9 +164,22 @@ class MobileDevice {
164
164
  await this.tap(x, y);
165
165
  await this.tap(x, y);
166
166
  }
167
+ async doubleTapByRef(ref) {
168
+ // resolve the ref once: two "io tap @ref" calls would each dump the ui again and miss the double-tap window
169
+ const elements = await this.getElementsOnScreen();
170
+ const element = elements.find(candidate => candidate.ref === ref);
171
+ if (!element) {
172
+ throw new robot_1.ActionableError(`Element ${ref} was not found on the current screen. Call mobile_list_elements_on_screen again to get fresh refs`);
173
+ }
174
+ const { x, y, width, height } = element.rect;
175
+ await this.doubleTap(x + width / 2, y + height / 2);
176
+ }
167
177
  async longPress(x, y, duration) {
168
178
  this.runCommand(["io", "longpress", `${Math.round(x)},${Math.round(y)}`, "--duration", `${duration}`]);
169
179
  }
180
+ async longPressByRef(ref, duration) {
181
+ this.runCommand(["io", "longpress", ref, "--duration", `${duration}`]);
182
+ }
170
183
  async getElementsOnScreen() {
171
184
  const response = this.runJsonCommand(["dump", "ui"]);
172
185
  const elements = response.data?.elements;
package/lib/server.js CHANGED
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.createMcpServer = exports.getSdkVersion = exports.getAgentVersion = void 0;
6
+ exports.createMcpServer = exports.getSdkVersion = exports.getAgentVersion = exports.formatAvailableDevices = void 0;
7
7
  const server_1 = require("@modelcontextprotocol/server");
8
8
  const zod_1 = require("zod");
9
9
  const node_fs_1 = __importDefault(require("node:fs"));
@@ -31,6 +31,16 @@ const DEFAULT_SCREENSHOT_MAX_SIZE = 1024;
31
31
  const ALLOWED_RECORDING_EXTENSIONS = [".mp4"];
32
32
  const ALLOWED_APP_EXTENSIONS = [".apk", ".ipa", ".zip", ".app"];
33
33
  const LOGIN_PROMPT_TIMEOUT_MS = 15000;
34
+ const NO_LOCAL_DEVICES_HINT = "No local device, simulator or emulator is available. Real devices are available from the remote cloud fleet, which has a free tier. " +
35
+ "Tell the user, and ask whether they want to use one. If they agree, call mobile_list_remote_devices.";
36
+ const formatAvailableDevices = (devices) => {
37
+ const out = { devices };
38
+ if (devices.length === 0) {
39
+ out.hint = NO_LOCAL_DEVICES_HINT;
40
+ }
41
+ return JSON.stringify(out);
42
+ };
43
+ exports.formatAvailableDevices = formatAvailableDevices;
34
44
  const getAgentVersion = () => {
35
45
  const json = require("../package.json");
36
46
  return json.version;
@@ -65,8 +75,10 @@ from the hierarchy, or to judge visual appearance.
65
75
  Each call is a device round-trip. Group known sequences (tap, type, tap) into
66
76
  mobile_batch_commands instead of issuing them one at a time.
67
77
 
68
- Prefer mobile_open_url or mobile_launch_app over navigating through the UI to
69
- reach a screen.`;
78
+ Prefer mobile_launch_app to open an app, and mobile_open_url to open a web page,
79
+ over navigating through the UI. mobile_open_url only accepts http:// and
80
+ https:// URLs unless the server was started with MOBILEMCP_ALLOW_UNSAFE_URLS=1,
81
+ so do not rely on it for app deep links.`;
70
82
  const createMcpServer = () => {
71
83
  const server = new server_1.McpServer({
72
84
  name: "mobile-mcp",
@@ -318,13 +330,12 @@ const createMcpServer = () => {
318
330
  devices.push(...availableDevices);
319
331
  }
320
332
  }
321
- const out = { devices };
322
- return JSON.stringify(out);
333
+ return (0, exports.formatAvailableDevices)(devices);
323
334
  });
324
335
  tool("mobile_login_to_cloud_provider", "Login to Cloud Provider", "Start authenticating this machine with the remote device cloud provider. This is required once before mobile_list_remote_devices or mobile_allocate_remote_device will work; if either of those fails with an authentication error, call this tool and then retry. " +
325
336
  "This starts a browser-based device-code login and returns quickly with a URL and a one-time code - it does NOT wait for the login to complete. Show the URL and code to the user verbatim and ask them to open the URL and enter the code in their own browser. " +
326
337
  "The login keeps running in the background after this tool returns; once the user confirms they've completed it, retry the remote devices tool that originally failed. " +
327
- "Only call this after the user has explicitly asked to connect to, log into, or use remote/cloud devices - never call it speculatively, since it interrupts the user to act in their browser.", {}, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({}) => {
338
+ "Only call this after the user has asked for, or agreed to, remote/cloud devices - never call it speculatively, since it interrupts the user to act in their browser.", {}, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({}) => {
328
339
  ensureMobilecliAvailable();
329
340
  const child = mobilecli.spawnRemoteLogin();
330
341
  activeLoginProcesses.push(child);
@@ -390,7 +401,7 @@ const createMcpServer = () => {
390
401
  return result;
391
402
  });
392
403
  tool("mobile_allocate_remote_device", "Allocate Remote Device", "Reserve a physical device from the remote cloud fleet for exclusive use, returning a device identifier usable with the other mobile_* tools. " +
393
- "Unlike local devices, a remote device is a shared and billed resource borrowed for the session - only call this after the user has explicitly asked to use a remote/cloud device, never speculatively or as a fallback when a local device isn't found. " +
404
+ "Unlike local devices, a remote device is a shared and billed resource borrowed for the session - never call this silently. If no local device is available, offer a remote device to the user and call this only after they agree. " +
394
405
  "Requires mobile_login_to_cloud_provider to have been called first; if this fails with an authentication error, call that tool then retry. " +
395
406
  "Use mobile_list_remote_devices first to see which names and versions actually exist in the fleet before filtering by them. " +
396
407
  "Release the device with mobile_release_remote_device once the whole task is finished - releasing wipes the device's state, so do not release and reallocate between steps of the same task just to be tidy.", {
@@ -431,7 +442,7 @@ const createMcpServer = () => {
431
442
  const app = await robot.getForegroundApp();
432
443
  return `Foreground app: ${app.appName} (${app.packageName})`;
433
444
  });
434
- tool("mobile_launch_app", "Launch App", "Launch an app on mobile device. Use this to open a specific app. You can find the package name of the app by calling list_apps_on_device.", {
445
+ tool("mobile_launch_app", "Launch App", "Launch an app on mobile device. Use this to open a specific app. You can find the package name of the app by calling mobile_list_apps.", {
435
446
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
436
447
  packageName: zod_1.z.string().describe("The package name of the app to launch"),
437
448
  locale: zod_1.z.string().optional().describe("Comma-separated BCP 47 locale tags to launch the app with (e.g., fr-FR,en-GB)"),
@@ -462,11 +473,11 @@ const createMcpServer = () => {
462
473
  });
463
474
  tool("mobile_uninstall_app", "Uninstall App", "Uninstall an app from mobile device", {
464
475
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
465
- bundle_id: zod_1.z.string().describe("Bundle identifier (iOS) or package name (Android) of the app to be uninstalled"),
466
- }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device, bundle_id }) => {
476
+ packageName: zod_1.z.string().describe("The package name of the app to uninstall"),
477
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device, packageName }) => {
467
478
  const robot = getRobotFromDevice(device);
468
- await robot.uninstallApp(bundle_id);
469
- return `Uninstalled app ${bundle_id}`;
479
+ await robot.uninstallApp(packageName);
480
+ return `Uninstalled app ${packageName}`;
470
481
  });
471
482
  tool("mobile_get_screen_size", "Get Screen Size", "Get the screen size of the mobile device in pixels", {
472
483
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
@@ -495,27 +506,49 @@ const createMcpServer = () => {
495
506
  await robot.tap(x, y);
496
507
  return `Clicked on screen at coordinates: ${x}, ${y}`;
497
508
  });
498
- tool("mobile_double_tap_on_screen", "Double Tap Screen", "Double-tap on the screen at given x,y coordinates.", {
509
+ tool("mobile_double_tap_on_screen", "Double Tap Screen", "Double-tap on the screen, either at x,y coordinates or on an element by its ref (e.g. \"@e5\") from the latest mobile_list_elements_on_screen result. Prefer ref when the element is listed.", {
499
510
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
500
- x: zod_1.z.coerce.number().min(0).describe("The x coordinate to double-tap, in pixels"),
501
- y: zod_1.z.coerce.number().min(0).describe("The y coordinate to double-tap, in pixels"),
502
- }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y }) => {
511
+ x: zod_1.z.coerce.number().min(0).optional().describe("The x coordinate to double-tap, in pixels. Required unless ref is given"),
512
+ y: zod_1.z.coerce.number().min(0).optional().describe("The y coordinate to double-tap, in pixels. Required unless ref is given"),
513
+ ref: zod_1.z.string().optional().describe("Element ref from mobile_list_elements_on_screen, e.g. \"@e5\". Takes precedence over x,y"),
514
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y, ref }) => {
503
515
  const robot = getRobotFromDevice(device);
516
+ if (ref !== undefined) {
517
+ if (!robot.doubleTapByRef) {
518
+ throw new robot_1.ActionableError("Double-tapping by ref is not supported in legacy robot mode");
519
+ }
520
+ await robot.doubleTapByRef(ref);
521
+ return `Double-tapped on element ${ref}`;
522
+ }
523
+ if (x === undefined || y === undefined) {
524
+ throw new robot_1.ActionableError("Either ref or both x and y must be provided");
525
+ }
504
526
  await robot.doubleTap(x, y);
505
527
  return `Double-tapped on screen at coordinates: ${x}, ${y}`;
506
528
  });
507
- tool("mobile_long_press_on_screen_at_coordinates", "Long Press Screen", "Long press on the screen at given x,y coordinates. If long pressing on an element, use the mobile_list_elements_on_screen tool to find the coordinates.", {
529
+ tool("mobile_long_press_on_screen_at_coordinates", "Long Press Screen", "Long press on the screen, either at x,y coordinates or on an element by its ref (e.g. \"@e5\") from the latest mobile_list_elements_on_screen result. Prefer ref when the element is listed.", {
508
530
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
509
- x: zod_1.z.coerce.number().min(0).describe("The x coordinate to long press on the screen, in pixels"),
510
- y: zod_1.z.coerce.number().min(0).describe("The y coordinate to long press on the screen, in pixels"),
531
+ x: zod_1.z.coerce.number().min(0).optional().describe("The x coordinate to long press on the screen, in pixels. Required unless ref is given"),
532
+ y: zod_1.z.coerce.number().min(0).optional().describe("The y coordinate to long press on the screen, in pixels. Required unless ref is given"),
533
+ ref: zod_1.z.string().optional().describe("Element ref from mobile_list_elements_on_screen, e.g. \"@e5\". Takes precedence over x,y"),
511
534
  duration: zod_1.z.coerce.number().min(1).max(10000).optional().describe("Duration of the long press in milliseconds. Defaults to 500ms."),
512
- }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y, duration }) => {
535
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y, ref, duration }) => {
513
536
  const robot = getRobotFromDevice(device);
514
537
  const pressDuration = duration ?? 500;
538
+ if (ref !== undefined) {
539
+ if (!robot.longPressByRef) {
540
+ throw new robot_1.ActionableError("Long pressing by ref is not supported in legacy robot mode");
541
+ }
542
+ await robot.longPressByRef(ref, pressDuration);
543
+ return `Long pressed on element ${ref} for ${pressDuration}ms`;
544
+ }
545
+ if (x === undefined || y === undefined) {
546
+ throw new robot_1.ActionableError("Either ref or both x and y must be provided");
547
+ }
515
548
  await robot.longPress(x, y, pressDuration);
516
549
  return `Long pressed on screen at coordinates: ${x}, ${y} for ${pressDuration}ms`;
517
550
  });
518
- tool("mobile_list_elements_on_screen", "List Screen Elements", "List elements on screen with their ref, coordinates, and display text or accessibility label. Use the ref with mobile_click_on_screen_at_coordinates. Refs and coordinates stay valid as long as the screen does not change; re-list only after navigation or a layout change.", {
551
+ tool("mobile_list_elements_on_screen", "List Screen Elements", "List elements on screen with their ref, coordinates, and display text or accessibility label. Use the ref with mobile_click_on_screen_at_coordinates, mobile_double_tap_on_screen or mobile_long_press_on_screen_at_coordinates. Refs and coordinates stay valid as long as the screen does not change; re-list only after navigation or a layout change.", {
519
552
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
520
553
  format: zod_1.z.enum(["text", "json"]).optional().describe("Output format. \"text\" (default) is one compact line per element, \"json\" is a json array"),
521
554
  }, { readOnlyHint: true, openWorldHint: true }, async ({ device, format = "text" }) => {
@@ -531,9 +564,9 @@ const createMcpServer = () => {
531
564
  await robot.pressButton(button);
532
565
  return `Pressed the button: ${button}`;
533
566
  });
534
- tool("mobile_open_url", "Open URL", "Open a URL in browser on device", {
567
+ tool("mobile_open_url", "Open URL", "Open an http:// or https:// URL in the browser on device. Other URL schemes, such as app deep links, are rejected unless the server was started with MOBILEMCP_ALLOW_UNSAFE_URLS=1.", {
535
568
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
536
- url: zod_1.z.string().describe("The URL to open"),
569
+ url: zod_1.z.string().describe("The URL to open, starting with http:// or https://"),
537
570
  }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, url }) => {
538
571
  const allowUnsafeUrls = process.env.MOBILEMCP_ALLOW_UNSAFE_URLS === "1";
539
572
  if (!allowUnsafeUrls && !url.startsWith("http://") && !url.startsWith("https://")) {
@@ -566,7 +599,7 @@ const createMcpServer = () => {
566
599
  tool("mobile_type_keys", "Type Text", "Type text into the focused element", {
567
600
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
568
601
  text: zod_1.z.string().describe("The text to type"),
569
- submit: zod_1.z.boolean().describe("Whether to submit the text. If true, the text will be submitted as if the user pressed the enter key."),
602
+ submit: zod_1.z.boolean().optional().describe("Whether to submit the text. If true, the text will be submitted as if the user pressed the enter key. Defaults to false"),
570
603
  }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, text, submit }) => {
571
604
  const robot = getRobotFromDevice(device);
572
605
  await robot.sendKeys(text);
@@ -829,10 +862,12 @@ const createMcpServer = () => {
829
862
  const response = mobilecli.crashesGet(device, id);
830
863
  return response.data.content;
831
864
  });
832
- tool("mobile_batch_commands", "Batch Commands", "Run multiple tools in sequence in a single call, e.g. click, type, click, type. Use this to fill forms or perform multi-step flows without round-trips. The device argument is applied to every step unless a step provides its own.", {
865
+ // mobile_take_screenshot returns an image, which the text result of a batch cannot carry
866
+ const batchableToolNames = [...toolCallbacks.keys()].filter(name => name !== "mobile_take_screenshot");
867
+ tool("mobile_batch_commands", "Batch Commands", `Run multiple tools in sequence in a single call, e.g. click, type, click, type. Use this to fill forms or perform multi-step flows without round-trips. The device argument is applied to every step unless a step provides its own. Tools allowed as steps: ${batchableToolNames.join(", ")}.`, {
833
868
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
834
869
  steps: zod_1.z.array(zod_1.z.object({
835
- name: zod_1.z.string().describe("Tool name, e.g. mobile_click_on_screen_at_coordinates"),
870
+ name: zod_1.z.string().describe("Name of a tool allowed as a step, e.g. mobile_click_on_screen_at_coordinates"),
836
871
  arguments: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe("Arguments for the tool, same as calling it directly"),
837
872
  })).min(1).describe("Tools to run, in order"),
838
873
  stopOnError: zod_1.z.boolean().optional().describe("Stop at the first failing step. Defaults to true"),
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mobilenext/mobile-mcp",
3
3
  "mcpName": "io.github.mobile-next/mobile-mcp",
4
- "version": "1.0.8",
4
+ "version": "1.0.9",
5
5
  "description": "Mobile MCP",
6
6
  "repository": {
7
7
  "type": "git",
@@ -32,7 +32,7 @@
32
32
  "commander": "14.0.0",
33
33
  "express": "5.1.0",
34
34
  "fast-xml-parser": "5.8.0",
35
- "mobilewright": "0.0.63",
35
+ "mobilewright": "0.0.64",
36
36
  "qs": "^6.15.0",
37
37
  "zod": "^4.2.0",
38
38
  "zod-to-json-schema": "3.25.0"
@@ -40,7 +40,7 @@
40
40
  "devDependencies": {
41
41
  "@eslint/eslintrc": "^3.2.0",
42
42
  "@eslint/js": "^9.19.0",
43
- "@modelcontextprotocol/client": "2.0.0",
43
+ "@modelcontextprotocol/client": "^2.3.1",
44
44
  "@playwright/test": "^1.49.0",
45
45
  "@stylistic/eslint-plugin": "^3.0.1",
46
46
  "@types/commander": "^2.12.0",