@mobilenext/mobile-mcp 1.0.1 → 1.0.3

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/lib/server.js CHANGED
@@ -15,12 +15,19 @@ const android_1 = require("./android");
15
15
  const robot_1 = require("./robot");
16
16
  const ios_1 = require("./ios");
17
17
  const png_1 = require("./png");
18
- const image_utils_1 = require("./image-utils");
19
18
  const mobilecli_1 = require("./mobilecli");
20
19
  const mobile_device_1 = require("./mobile-device");
21
20
  const utils_1 = require("./utils");
21
+ const format_elements_1 = require("./format-elements");
22
+ const ALLOWED_LOG_EXTENSIONS = [".log", ".txt", ".jsonl"];
23
+ const DEFAULT_DEVICE_LOG_ENTRIES = 100;
24
+ const MAX_DEVICE_LOG_ENTRIES = 10000;
25
+ const DEVICE_LOG_TIMEOUT_MS = 30000;
26
+ const DEVICE_LOG_FILTER_PATTERN = /^(pid|process|tag|level|subsystem|category|message)!?=.+$/;
22
27
  const ALLOWED_SCREENSHOT_EXTENSIONS = [".png", ".jpg", ".jpeg"];
28
+ const DEFAULT_SCREENSHOT_MAX_SIZE = 1024;
23
29
  const ALLOWED_RECORDING_EXTENSIONS = [".mp4"];
30
+ const ALLOWED_APP_EXTENSIONS = [".apk", ".ipa", ".zip", ".app"];
24
31
  const LOGIN_PROMPT_TIMEOUT_MS = 15000;
25
32
  const getAgentVersion = () => {
26
33
  const json = require("../package.json");
@@ -42,7 +49,10 @@ const createMcpServer = () => {
42
49
  return "unknown";
43
50
  }
44
51
  };
52
+ // ponytail: batch calls tool callbacks directly, bypassing mcp transport
53
+ const toolCallbacks = new Map();
45
54
  const tool = (name, title, description, paramsSchema, annotations, cb) => {
55
+ toolCallbacks.set(name, { callback: cb, paramsSchema });
46
56
  server.registerTool(name, {
47
57
  title,
48
58
  description,
@@ -136,7 +146,18 @@ const createMcpServer = () => {
136
146
  throw new robot_1.ActionableError(`mobilecli is not available or not working properly. Please review the documentation at https://github.com/mobile-next/mobile-mcp/wiki for installation instructions`);
137
147
  }
138
148
  };
149
+ // cache per device id, saves ~0.2s (mobilecli --version + devices) on every tool call
150
+ const robotCache = new Map();
139
151
  const getRobotFromDevice = (deviceId) => {
152
+ const cached = robotCache.get(deviceId);
153
+ if (cached) {
154
+ return cached;
155
+ }
156
+ const robot = createRobotFromDevice(deviceId);
157
+ robotCache.set(deviceId, robot);
158
+ return robot;
159
+ };
160
+ const createRobotFromDevice = (deviceId) => {
140
161
  // from now on, we must have mobilecli working
141
162
  ensureMobilecliAvailable();
142
163
  const legacyRobot = process.env.MOBILEMCP_LEGACY_ROBOT === "1";
@@ -146,7 +167,6 @@ const createMcpServer = () => {
146
167
  const iosDevices = iosManager.listDevices();
147
168
  const iosDevice = iosDevices.find(d => d.deviceId === deviceId);
148
169
  if (iosDevice) {
149
- posthog("get_robot", { "DevicePlatform": "ios", "DeviceType": "real" }).then();
150
170
  return new ios_1.IosRobot(deviceId);
151
171
  }
152
172
  // Check if it's an Android device
@@ -154,7 +174,6 @@ const createMcpServer = () => {
154
174
  const androidDevices = androidManager.getConnectedDevices();
155
175
  const androidDevice = androidDevices.find(d => d.deviceId === deviceId);
156
176
  if (androidDevice) {
157
- posthog("get_robot", { "DevicePlatform": "android", "DeviceType": androidDevice.deviceType }).then();
158
177
  return new android_1.AndroidRobot(deviceId);
159
178
  }
160
179
  }
@@ -175,7 +194,6 @@ const createMcpServer = () => {
175
194
  }
176
195
  agentVerifiedSimulators.add(deviceId);
177
196
  }
178
- posthog("get_robot", { "DevicePlatform": device.platform, "DeviceType": device.type }).then();
179
197
  return new mobile_device_1.MobileDevice(deviceId);
180
198
  }
181
199
  }
@@ -183,7 +201,7 @@ const createMcpServer = () => {
183
201
  throw new robot_1.ActionableError(`Device "${deviceId}" not found. Use the mobile_list_available_devices tool to see available devices.`);
184
202
  };
185
203
  tool("mobile_list_available_devices", "List Devices", "List all available devices. This includes both physical mobile devices and mobile simulators and emulators. It returns both Android and iOS devices. " +
186
- "These are local devices already connected to this machine, ready to use immediately at no cost - for devices from the shared remote cloud fleet, use mobile_list_remote_devices instead.", {}, { readOnlyHint: true }, async ({}, telemetry) => {
204
+ "These are local devices already connected to this machine, ready to use immediately at no cost - for devices from the shared remote cloud fleet, use mobile_list_remote_devices instead.", {}, { readOnlyHint: true, openWorldHint: false }, async ({}, telemetry) => {
187
205
  // from today onward, we must have mobilecli working
188
206
  ensureMobilecliAvailable();
189
207
  const devices = [];
@@ -261,7 +279,7 @@ const createMcpServer = () => {
261
279
  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. " +
262
280
  "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. " +
263
281
  "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. " +
264
- "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.", {}, {}, async ({}) => {
282
+ "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 ({}) => {
265
283
  ensureMobilecliAvailable();
266
284
  const child = mobilecli.spawnRemoteLogin();
267
285
  activeLoginProcesses.push(child);
@@ -321,7 +339,7 @@ const createMcpServer = () => {
321
339
  tool("mobile_list_remote_devices", "List Remote Devices", "List the catalog of device models (make, platform, OS version) available to reserve from the remote cloud device fleet. " +
322
340
  "This is different from mobile_list_available_devices, which lists real devices and simulators/emulators already connected to this local machine and ready to use immediately at no cost. " +
323
341
  "Remote devices live in a shared cloud fleet: they are not usable until reserved with mobile_allocate_remote_device, and reserving one may be a limited/billed resource. " +
324
- "Requires mobile_login_to_cloud_provider to have been called first; if this fails with an authentication error, call that tool then retry.", {}, { readOnlyHint: true }, async ({}) => {
342
+ "Requires mobile_login_to_cloud_provider to have been called first; if this fails with an authentication error, call that tool then retry.", {}, { readOnlyHint: true, openWorldHint: true }, async ({}) => {
325
343
  ensureMobilecliAvailable();
326
344
  const result = mobilecli.remoteListDevices();
327
345
  return result;
@@ -337,7 +355,7 @@ const createMcpServer = () => {
337
355
  type: zod_1.z.enum(["real"]).optional().describe("Device type filter. Currently only \"real\" (physical devices) is supported by the fleet."),
338
356
  wait: zod_1.z.boolean().optional().describe("If true, block until the device has finished allocating and is ready to use, up to timeoutSeconds. If false/omitted, this returns as soon as the reservation is made, but the device may not be immediately ready."),
339
357
  timeoutSeconds: zod_1.z.coerce.number().int().positive().optional().describe("Seconds to wait for allocation when wait is true. Defaults to 900 (15 minutes). Only relevant when wait is true."),
340
- }, { destructiveHint: true }, async ({ platform, name, version, type, wait, timeoutSeconds }) => {
358
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ platform, name, version, type, wait, timeoutSeconds }) => {
341
359
  ensureMobilecliAvailable();
342
360
  const result = mobilecli.remoteAllocate({ platform, name, version, type, wait, timeoutSeconds });
343
361
  return result;
@@ -346,23 +364,33 @@ const createMcpServer = () => {
346
364
  "Releasing is destructive to the device's state: apps installed, files pushed, and any other changes made during this session are lost, and a later mobile_allocate_remote_device call may take time and could return a different physical unit. " +
347
365
  "Only release once the whole task is finished - if there is more work to do on the same device shortly, keep holding it rather than releasing and reallocating.", {
348
366
  device: zod_1.z.string().describe("The device identifier to release back to the remote fleet"),
349
- }, { destructiveHint: true }, async ({ device }) => {
367
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ device }) => {
350
368
  ensureMobilecliAvailable();
351
369
  const result = mobilecli.remoteRelease(device);
352
370
  return result;
353
371
  });
354
372
  tool("mobile_list_apps", "List Apps", "List all the installed apps on the device", {
355
373
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
356
- }, { readOnlyHint: true }, async ({ device }) => {
374
+ }, { readOnlyHint: true, openWorldHint: false }, async ({ device }) => {
357
375
  const robot = getRobotFromDevice(device);
358
376
  const result = await robot.listApps();
359
377
  return `Found these apps on device: ${result.map(app => `${app.appName} (${app.packageName})`).join(", ")}`;
360
378
  });
379
+ tool("mobile_get_foreground_app", "Get Foreground App", "Get the app currently in the foreground on the device. Use this to verify which app or screen you are on before interacting with it.", {
380
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
381
+ }, { readOnlyHint: true, openWorldHint: false }, async ({ device }) => {
382
+ const robot = getRobotFromDevice(device);
383
+ if (!robot.getForegroundApp) {
384
+ throw new robot_1.ActionableError("Getting the foreground app is not supported in legacy robot mode");
385
+ }
386
+ const app = await robot.getForegroundApp();
387
+ return `Foreground app: ${app.appName} (${app.packageName})`;
388
+ });
361
389
  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.", {
362
390
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
363
391
  packageName: zod_1.z.string().describe("The package name of the app to launch"),
364
392
  locale: zod_1.z.string().optional().describe("Comma-separated BCP 47 locale tags to launch the app with (e.g., fr-FR,en-GB)"),
365
- }, { destructiveHint: true }, async ({ device, packageName, locale }) => {
393
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, packageName, locale }) => {
366
394
  const robot = getRobotFromDevice(device);
367
395
  await robot.launchApp(packageName, locale);
368
396
  return `Launched app ${packageName}`;
@@ -370,7 +398,7 @@ const createMcpServer = () => {
370
398
  tool("mobile_terminate_app", "Terminate App", "Stop and terminate an app on mobile device", {
371
399
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
372
400
  packageName: zod_1.z.string().describe("The package name of the app to terminate"),
373
- }, { destructiveHint: true }, async ({ device, packageName }) => {
401
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, packageName }) => {
374
402
  const robot = getRobotFromDevice(device);
375
403
  await robot.terminateApp(packageName);
376
404
  return `Terminated app ${packageName}`;
@@ -378,7 +406,11 @@ const createMcpServer = () => {
378
406
  tool("mobile_install_app", "Install App", "Install an app on mobile device", {
379
407
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
380
408
  path: zod_1.z.string().describe("The path to the app file to install. For iOS simulators, provide a .zip file or a .app directory. For Android provide an .apk file. For iOS real devices provide an .ipa file"),
381
- }, { destructiveHint: true }, async ({ device, path }) => {
409
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, path }) => {
410
+ (0, utils_1.validateFileExtension)(path, ALLOWED_APP_EXTENSIONS, "install_app");
411
+ if (!node_fs_1.default.existsSync(path)) {
412
+ throw new robot_1.ActionableError(`App file not found: ${path}`);
413
+ }
382
414
  const robot = getRobotFromDevice(device);
383
415
  await robot.installApp(path);
384
416
  return `Installed app from ${path}`;
@@ -386,78 +418,70 @@ const createMcpServer = () => {
386
418
  tool("mobile_uninstall_app", "Uninstall App", "Uninstall an app from mobile device", {
387
419
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
388
420
  bundle_id: zod_1.z.string().describe("Bundle identifier (iOS) or package name (Android) of the app to be uninstalled"),
389
- }, { destructiveHint: true }, async ({ device, bundle_id }) => {
421
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device, bundle_id }) => {
390
422
  const robot = getRobotFromDevice(device);
391
423
  await robot.uninstallApp(bundle_id);
392
424
  return `Uninstalled app ${bundle_id}`;
393
425
  });
394
426
  tool("mobile_get_screen_size", "Get Screen Size", "Get the screen size of the mobile device in pixels", {
395
427
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
396
- }, { readOnlyHint: true }, async ({ device }) => {
428
+ }, { readOnlyHint: true, openWorldHint: false }, async ({ device }) => {
397
429
  const robot = getRobotFromDevice(device);
398
430
  const screenSize = await robot.getScreenSize();
399
431
  return `Screen size is ${screenSize.width}x${screenSize.height} pixels`;
400
432
  });
401
- tool("mobile_click_on_screen_at_coordinates", "Click Screen", "Click on the screen at given x,y coordinates. If clicking on an element, use the list_elements_on_screen tool to find the coordinates.", {
433
+ tool("mobile_click_on_screen_at_coordinates", "Click Screen", "Click 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.", {
402
434
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
403
- x: zod_1.z.coerce.number().describe("The x coordinate to click on the screen, in pixels"),
404
- y: zod_1.z.coerce.number().describe("The y coordinate to click on the screen, in pixels"),
405
- }, { destructiveHint: true }, async ({ device, x, y }) => {
435
+ x: zod_1.z.coerce.number().min(0).optional().describe("The x coordinate to click on the screen, in pixels. Required unless ref is given"),
436
+ y: zod_1.z.coerce.number().min(0).optional().describe("The y coordinate to click on the screen, in pixels. Required unless ref is given"),
437
+ ref: zod_1.z.string().optional().describe("Element ref from mobile_list_elements_on_screen, e.g. \"@e5\". Takes precedence over x,y"),
438
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y, ref }) => {
406
439
  const robot = getRobotFromDevice(device);
440
+ if (ref !== undefined) {
441
+ if (!robot.tapByRef) {
442
+ throw new robot_1.ActionableError("Clicking by ref is not supported in legacy robot mode");
443
+ }
444
+ await robot.tapByRef(ref);
445
+ return `Clicked on element ${ref}`;
446
+ }
447
+ if (x === undefined || y === undefined) {
448
+ throw new robot_1.ActionableError("Either ref or both x and y must be provided");
449
+ }
407
450
  await robot.tap(x, y);
408
451
  return `Clicked on screen at coordinates: ${x}, ${y}`;
409
452
  });
410
453
  tool("mobile_double_tap_on_screen", "Double Tap Screen", "Double-tap on the screen at given x,y coordinates.", {
411
454
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
412
- x: zod_1.z.coerce.number().describe("The x coordinate to double-tap, in pixels"),
413
- y: zod_1.z.coerce.number().describe("The y coordinate to double-tap, in pixels"),
414
- }, { destructiveHint: true }, async ({ device, x, y }) => {
455
+ x: zod_1.z.coerce.number().min(0).describe("The x coordinate to double-tap, in pixels"),
456
+ y: zod_1.z.coerce.number().min(0).describe("The y coordinate to double-tap, in pixels"),
457
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y }) => {
415
458
  const robot = getRobotFromDevice(device);
416
459
  await robot.doubleTap(x, y);
417
460
  return `Double-tapped on screen at coordinates: ${x}, ${y}`;
418
461
  });
419
- 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 list_elements_on_screen tool to find the coordinates.", {
462
+ 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.", {
420
463
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
421
- x: zod_1.z.coerce.number().describe("The x coordinate to long press on the screen, in pixels"),
422
- y: zod_1.z.coerce.number().describe("The y coordinate to long press on the screen, in pixels"),
464
+ x: zod_1.z.coerce.number().min(0).describe("The x coordinate to long press on the screen, in pixels"),
465
+ y: zod_1.z.coerce.number().min(0).describe("The y coordinate to long press on the screen, in pixels"),
423
466
  duration: zod_1.z.coerce.number().min(1).max(10000).optional().describe("Duration of the long press in milliseconds. Defaults to 500ms."),
424
- }, { destructiveHint: true }, async ({ device, x, y, duration }) => {
467
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, x, y, duration }) => {
425
468
  const robot = getRobotFromDevice(device);
426
469
  const pressDuration = duration ?? 500;
427
470
  await robot.longPress(x, y, pressDuration);
428
471
  return `Long pressed on screen at coordinates: ${x}, ${y} for ${pressDuration}ms`;
429
472
  });
430
- tool("mobile_list_elements_on_screen", "List Screen Elements", "List elements on screen and their coordinates, with display text or accessibility label. Do not cache this result.", {
431
- device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
432
- }, { readOnlyHint: true }, async ({ device }) => {
473
+ 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.", {
474
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
475
+ format: zod_1.z.enum(["text", "json"]).optional().describe("Output format. \"text\" (default) is one compact line per element, \"json\" is a json array"),
476
+ }, { readOnlyHint: true, openWorldHint: true }, async ({ device, format = "text" }) => {
433
477
  const robot = getRobotFromDevice(device);
434
478
  const elements = await robot.getElementsOnScreen();
435
- const result = elements.map(element => {
436
- const out = {
437
- type: element.type,
438
- text: element.text,
439
- label: element.label,
440
- name: element.name,
441
- value: element.value,
442
- identifier: element.identifier,
443
- coordinates: {
444
- x: element.rect.x,
445
- y: element.rect.y,
446
- width: element.rect.width,
447
- height: element.rect.height,
448
- },
449
- };
450
- if (element.focused) {
451
- out.focused = true;
452
- }
453
- return out;
454
- });
455
- return `Found these elements on screen: ${JSON.stringify(result)}`;
479
+ return (0, format_elements_1.formatElements)(elements, format);
456
480
  });
457
481
  tool("mobile_press_button", "Press Button", "Press a button on device", {
458
482
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
459
483
  button: zod_1.z.string().describe("The button to press. Supported buttons: BACK (android only), HOME, VOLUME_UP, VOLUME_DOWN, ENTER, DPAD_CENTER (android tv only), DPAD_UP (android tv only), DPAD_DOWN (android tv only), DPAD_LEFT (android tv only), DPAD_RIGHT (android tv only)"),
460
- }, { destructiveHint: true }, async ({ device, button }) => {
484
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, button }) => {
461
485
  const robot = getRobotFromDevice(device);
462
486
  await robot.pressButton(button);
463
487
  return `Pressed the button: ${button}`;
@@ -465,7 +489,7 @@ const createMcpServer = () => {
465
489
  tool("mobile_open_url", "Open URL", "Open a URL in browser on device", {
466
490
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
467
491
  url: zod_1.z.string().describe("The URL to open"),
468
- }, { destructiveHint: true }, async ({ device, url }) => {
492
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, url }) => {
469
493
  const allowUnsafeUrls = process.env.MOBILEMCP_ALLOW_UNSAFE_URLS === "1";
470
494
  if (!allowUnsafeUrls && !url.startsWith("http://") && !url.startsWith("https://")) {
471
495
  throw new robot_1.ActionableError("Only http:// and https:// URLs are allowed. Set MOBILEMCP_ALLOW_UNSAFE_URLS=1 to allow other URL schemes.");
@@ -477,10 +501,10 @@ const createMcpServer = () => {
477
501
  tool("mobile_swipe_on_screen", "Swipe Screen", "Swipe on the screen", {
478
502
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
479
503
  direction: zod_1.z.enum(["up", "down", "left", "right"]).describe("The direction to swipe"),
480
- x: zod_1.z.coerce.number().optional().describe("The x coordinate to start the swipe from, in pixels. If not provided, uses center of screen"),
481
- y: zod_1.z.coerce.number().optional().describe("The y coordinate to start the swipe from, in pixels. If not provided, uses center of screen"),
504
+ x: zod_1.z.coerce.number().min(0).optional().describe("The x coordinate to start the swipe from, in pixels. If not provided, uses center of screen"),
505
+ y: zod_1.z.coerce.number().min(0).optional().describe("The y coordinate to start the swipe from, in pixels. If not provided, uses center of screen"),
482
506
  distance: zod_1.z.coerce.number().optional().describe("The distance to swipe in pixels. Defaults to 400 pixels for iOS or 30% of screen dimension for Android"),
483
- }, { destructiveHint: true }, async ({ device, direction, x, y, distance }) => {
507
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, direction, x, y, distance }) => {
484
508
  const robot = getRobotFromDevice(device);
485
509
  if (x !== undefined && y !== undefined) {
486
510
  // Use coordinate-based swipe
@@ -498,7 +522,7 @@ const createMcpServer = () => {
498
522
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
499
523
  text: zod_1.z.string().describe("The text to type"),
500
524
  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."),
501
- }, { destructiveHint: true }, async ({ device, text, submit }) => {
525
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async ({ device, text, submit }) => {
502
526
  const robot = getRobotFromDevice(device);
503
527
  await robot.sendKeys(text);
504
528
  if (submit) {
@@ -509,11 +533,19 @@ const createMcpServer = () => {
509
533
  tool("mobile_save_screenshot", "Save Screenshot", "Save a screenshot of the mobile device to a file", {
510
534
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
511
535
  saveTo: zod_1.z.string().describe("The path to save the screenshot to. Filename must end with .png, .jpg, or .jpeg"),
512
- }, { destructiveHint: true }, async ({ device, saveTo }) => {
536
+ maxSize: zod_1.z.number().int().positive().optional().describe("Maximum width/height in pixels, keeping aspect ratio. Omit for full size."),
537
+ scale: zod_1.z.number().gt(0).max(1).optional().describe("Scale factor (0.0-1.0). Ignored if maxSize is provided."),
538
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, saveTo, maxSize, scale }) => {
513
539
  (0, utils_1.validateFileExtension)(saveTo, ALLOWED_SCREENSHOT_EXTENSIONS, "save_screenshot");
514
540
  (0, utils_1.validateOutputPath)(saveTo);
515
541
  const robot = getRobotFromDevice(device);
516
- const screenshot = await robot.getScreenshot();
542
+ const format = saveTo.toLowerCase().endsWith(".png") ? "png" : "jpeg";
543
+ const screenshot = await robot.getScreenshot({ format, maxSize, scale });
544
+ // legacy robots ignore the requested format and always return a png
545
+ const isPng = screenshot.length > 0 && screenshot[0] === 0x89;
546
+ if (format === "jpeg" && isPng) {
547
+ throw new robot_1.ActionableError("This device only supports png screenshots, save to a .png file instead.");
548
+ }
517
549
  node_fs_1.default.writeFileSync(saveTo, screenshot);
518
550
  return `Screenshot saved to: ${saveTo}`;
519
551
  });
@@ -521,33 +553,40 @@ const createMcpServer = () => {
521
553
  title: "Take Screenshot",
522
554
  description: "Take a screenshot of the mobile device. Use this to understand what's on screen, if you need to press an element that is available through view hierarchy then you must list elements on screen instead. Do not cache this result.",
523
555
  inputSchema: {
524
- device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
556
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
557
+ maxSize: zod_1.z.number().int().positive().optional().describe(`Maximum width/height in pixels, keeping aspect ratio. Defaults to ${DEFAULT_SCREENSHOT_MAX_SIZE}.`),
558
+ scale: zod_1.z.number().gt(0).max(1).optional().describe("Scale factor (0.0-1.0). Ignored if maxSize is provided."),
525
559
  },
526
560
  annotations: {
527
561
  readOnlyHint: true,
562
+ openWorldHint: true,
528
563
  },
529
- }, async ({ device }) => {
564
+ }, async ({ device, maxSize, scale }) => {
530
565
  try {
531
566
  const robot = getRobotFromDevice(device);
532
- const screenSize = await robot.getScreenSize();
533
- let screenshot = await robot.getScreenshot();
534
- let mimeType = "image/png";
535
- // validate we received a png, will throw exception otherwise
536
- const image = new png_1.PNG(screenshot);
537
- const pngSize = image.getDimensions();
538
- if (pngSize.width <= 0 || pngSize.height <= 0) {
539
- throw new robot_1.ActionableError("Screenshot is invalid. Please try again.");
567
+ // mobilecli scales and converts natively; legacy robots ignore the options and return a full-size png
568
+ // maxSize wins over scale (same precedence as mobilecli); the default applies only when neither is given
569
+ const options = { format: "jpeg", quality: 75 };
570
+ if (maxSize !== undefined) {
571
+ options.maxSize = maxSize;
572
+ }
573
+ else if (scale !== undefined) {
574
+ options.scale = scale;
575
+ }
576
+ else {
577
+ options.maxSize = DEFAULT_SCREENSHOT_MAX_SIZE;
540
578
  }
541
- if ((0, image_utils_1.isScalingAvailable)()) {
542
- (0, logger_1.trace)("Image scaling is available, resizing screenshot");
543
- const image = image_utils_1.Image.fromBuffer(screenshot);
544
- const beforeSize = screenshot.length;
545
- screenshot = image.resize(Math.floor(pngSize.width / screenSize.scale))
546
- .jpeg({ quality: 75 })
547
- .toBuffer();
548
- const afterSize = screenshot.length;
549
- (0, logger_1.trace)(`Screenshot resized from ${beforeSize} bytes to ${afterSize} bytes`);
550
- mimeType = "image/jpeg";
579
+ const screenshot = await robot.getScreenshot(options);
580
+ const isJpeg = screenshot.length > 2 && screenshot[0] === 0xff && screenshot[1] === 0xd8;
581
+ let mimeType = "image/jpeg";
582
+ if (!isJpeg) {
583
+ mimeType = "image/png";
584
+ // validate we received a png, will throw exception otherwise
585
+ const image = new png_1.PNG(screenshot);
586
+ const pngSize = image.getDimensions();
587
+ if (pngSize.width <= 0 || pngSize.height <= 0) {
588
+ throw new robot_1.ActionableError("Screenshot is invalid. Please try again.");
589
+ }
551
590
  }
552
591
  const screenshot64 = screenshot.toString("base64");
553
592
  (0, logger_1.trace)(`Screenshot taken: ${screenshot.length} bytes`);
@@ -555,8 +594,6 @@ const createMcpServer = () => {
555
594
  "ToolName": "mobile_take_screenshot",
556
595
  "ScreenshotFilesize": screenshot64.length,
557
596
  "ScreenshotMimeType": mimeType,
558
- "ScreenshotWidth": pngSize.width,
559
- "ScreenshotHeight": pngSize.height,
560
597
  }).then();
561
598
  return {
562
599
  content: [{ type: "image", data: screenshot64, mimeType }]
@@ -573,14 +610,69 @@ const createMcpServer = () => {
573
610
  tool("mobile_set_orientation", "Set Orientation", "Change the screen orientation of the device", {
574
611
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
575
612
  orientation: zod_1.z.enum(["portrait", "landscape"]).describe("The desired orientation"),
576
- }, { destructiveHint: true }, async ({ device, orientation }) => {
613
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, orientation }) => {
577
614
  const robot = getRobotFromDevice(device);
578
615
  await robot.setOrientation(orientation);
579
616
  return `Changed device orientation to ${orientation}`;
580
617
  });
618
+ tool("mobile_set_location", "Set Location", "Override the GPS location reported by the device, or clear the override to restore the real location. Omit latitude and longitude to clear.", {
619
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
620
+ latitude: zod_1.z.number().min(-90).max(90).optional().describe("Latitude in decimal degrees, e.g. 37.7749. Omit together with longitude to clear the override."),
621
+ longitude: zod_1.z.number().min(-180).max(180).optional().describe("Longitude in decimal degrees, e.g. -122.4194. Omit together with latitude to clear the override."),
622
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, latitude, longitude }) => {
623
+ const robot = getRobotFromDevice(device);
624
+ if (!robot.setLocation || !robot.clearLocation) {
625
+ throw new robot_1.ActionableError("Setting location is not supported in legacy robot mode");
626
+ }
627
+ if (latitude === undefined && longitude === undefined) {
628
+ await robot.clearLocation();
629
+ return "Cleared location override";
630
+ }
631
+ if (latitude === undefined || longitude === undefined) {
632
+ throw new robot_1.ActionableError("Both latitude and longitude are required to set a location");
633
+ }
634
+ await robot.setLocation(latitude, longitude);
635
+ return `Set device location to ${latitude},${longitude}`;
636
+ });
637
+ tool("mobile_clipboard", "Clipboard", "Read or replace the device clipboard. Pass text to set the clipboard, omit it to read the current clipboard.", {
638
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
639
+ text: zod_1.z.string().optional().describe("Text to place on the clipboard. Omit to read the clipboard instead."),
640
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, text }) => {
641
+ const robot = getRobotFromDevice(device);
642
+ if (!robot.getClipboard || !robot.setClipboard) {
643
+ throw new robot_1.ActionableError("Clipboard is not supported in legacy robot mode");
644
+ }
645
+ if (text === undefined) {
646
+ return await robot.getClipboard();
647
+ }
648
+ await robot.setClipboard(text);
649
+ return "Clipboard updated";
650
+ });
651
+ tool("mobile_get_device_logs", "Get Device Logs", "Collect live device logs (logcat on Android, unified log on iOS) as one JSON object per line. Only logs emitted after the call starts are captured, so trigger the behavior you want to observe right before or during the call. Stops after `limit` entries or after 30 seconds of silence. Each line of a stack trace counts as one entry, so filter by process or tag to avoid filling the limit with noise. Start with a small limit (20-50) for a quick look. For large captures, pass `saveTo` to write logs to a file and only the entry count is returned.", {
652
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
653
+ limit: zod_1.z.number().int().min(1).max(MAX_DEVICE_LOG_ENTRIES).default(DEFAULT_DEVICE_LOG_ENTRIES).describe("Stop after this many log entries"),
654
+ filter: zod_1.z.array(zod_1.z.string().regex(DEVICE_LOG_FILTER_PATTERN, "Filter must be key=value or key!=value with key in: pid, process, tag, level, subsystem, category, message")).default([]).describe("Filters, ANDed together. key=value includes, key!=value excludes. Keys: pid, process, tag, level, subsystem, category, message. Example: [\"tag=ActivityManager\", \"level=Error\", \"process!=SpringBoard\"]"),
655
+ saveTo: zod_1.z.string().optional().describe("Path to write the logs to instead of returning them. Filename must end with .log, .txt, or .jsonl"),
656
+ }, { readOnlyHint: true, openWorldHint: true }, async ({ device, limit, filter, saveTo }) => {
657
+ if (saveTo) {
658
+ (0, utils_1.validateFileExtension)(saveTo, ALLOWED_LOG_EXTENSIONS, "get_device_logs");
659
+ (0, utils_1.validateOutputPath)(saveTo);
660
+ }
661
+ const robot = getRobotFromDevice(device);
662
+ if (!robot.getLogs) {
663
+ throw new robot_1.ActionableError("Device logs are not supported in legacy robot mode");
664
+ }
665
+ const logs = await robot.getLogs(limit, filter, DEVICE_LOG_TIMEOUT_MS);
666
+ if (!saveTo) {
667
+ return logs || "No log entries received";
668
+ }
669
+ node_fs_1.default.writeFileSync(saveTo, logs + "\n");
670
+ const lineCount = logs ? logs.split("\n").length : 0;
671
+ return `Saved ${lineCount} log entries to: ${saveTo}`;
672
+ });
581
673
  tool("mobile_get_orientation", "Get Orientation", "Get the current screen orientation of the device", {
582
674
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you.")
583
- }, { readOnlyHint: true }, async ({ device }) => {
675
+ }, { readOnlyHint: true, openWorldHint: false }, async ({ device }) => {
584
676
  const robot = getRobotFromDevice(device);
585
677
  const orientation = await robot.getOrientation();
586
678
  return `Current device orientation is ${orientation}`;
@@ -589,7 +681,7 @@ const createMcpServer = () => {
589
681
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
590
682
  output: zod_1.z.string().optional().describe("The file path to save the recording to. Filename must end with .mp4. If not provided, a temporary path will be used."),
591
683
  timeLimit: zod_1.z.coerce.number().optional().describe("Maximum recording duration in seconds. The recording will stop automatically after this time."),
592
- }, { destructiveHint: true }, async ({ device, output, timeLimit }) => {
684
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device, output, timeLimit }) => {
593
685
  if (output) {
594
686
  (0, utils_1.validateFileExtension)(output, ALLOWED_RECORDING_EXTENSIONS, "start_screen_recording");
595
687
  (0, utils_1.validateOutputPath)(output);
@@ -618,7 +710,7 @@ const createMcpServer = () => {
618
710
  });
619
711
  tool("mobile_stop_screen_recording", "Stop Screen Recording", "Stop an active screen recording on a mobile device. Returns the file path, size, and approximate duration of the recording.", {
620
712
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
621
- }, { destructiveHint: true }, async ({ device }) => {
713
+ }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ device }) => {
622
714
  const recording = activeRecordings.get(device);
623
715
  if (!recording) {
624
716
  throw new robot_1.ActionableError(`No active recording found for device "${device}". Start a recording first with mobile_start_screen_recording.`);
@@ -646,7 +738,7 @@ const createMcpServer = () => {
646
738
  });
647
739
  tool("mobile_list_crashes", "List Crash Reports", "List crash reports available on the device", {
648
740
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
649
- }, { readOnlyHint: true }, async ({ device }) => {
741
+ }, { readOnlyHint: true, openWorldHint: true }, async ({ device }) => {
650
742
  ensureMobilecliAvailable();
651
743
  const response = mobilecli.crashesList(device);
652
744
  return JSON.stringify(response.data);
@@ -654,11 +746,52 @@ const createMcpServer = () => {
654
746
  tool("mobile_get_crash", "Get Crash Report", "Get the full content of a crash report by its ID. Use mobile_list_crashes to find available crash IDs.", {
655
747
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
656
748
  id: zod_1.z.string().describe("The crash report ID to retrieve"),
657
- }, { readOnlyHint: true }, async ({ device, id }) => {
749
+ }, { readOnlyHint: true, openWorldHint: true }, async ({ device, id }) => {
658
750
  ensureMobilecliAvailable();
659
751
  const response = mobilecli.crashesGet(device, id);
660
752
  return response.data.content;
661
753
  });
754
+ 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.", {
755
+ device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
756
+ steps: zod_1.z.array(zod_1.z.object({
757
+ name: zod_1.z.string().describe("Tool name, e.g. mobile_click_on_screen_at_coordinates"),
758
+ arguments: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe("Arguments for the tool, same as calling it directly"),
759
+ })).min(1).describe("Tools to run, in order"),
760
+ stopOnError: zod_1.z.boolean().optional().describe("Stop at the first failing step. Defaults to true"),
761
+ listElementsAtEnd: zod_1.z.boolean().optional().describe("Run mobile_list_elements_on_screen after the last step and include its result. Defaults to false"),
762
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ device, steps, stopOnError, listElementsAtEnd }, telemetry) => {
763
+ const shouldStopOnError = stopOnError ?? true;
764
+ const results = [];
765
+ telemetry.StepCount = steps.length;
766
+ for (let i = 0; i < steps.length; i++) {
767
+ const step = steps[i];
768
+ if (step.name === "mobile_batch_commands") {
769
+ throw new robot_1.ActionableError("mobile_batch_commands cannot be nested");
770
+ }
771
+ if (step.name === "mobile_take_screenshot") {
772
+ throw new robot_1.ActionableError("mobile_take_screenshot returns an image and cannot be used in a batch, use mobile_save_screenshot instead");
773
+ }
774
+ const entry = toolCallbacks.get(step.name);
775
+ if (!entry) {
776
+ throw new robot_1.ActionableError(`Unknown tool in step ${i + 1}: ${step.name}`);
777
+ }
778
+ try {
779
+ const args = zod_1.z.object(entry.paramsSchema).parse({ device, ...step.arguments });
780
+ const output = await entry.callback(args, {});
781
+ results.push(`Step ${i + 1} (${step.name}): ${output}`);
782
+ }
783
+ catch (error) {
784
+ results.push(`Step ${i + 1} (${step.name}) failed: ${error.message}`);
785
+ if (shouldStopOnError) {
786
+ break;
787
+ }
788
+ }
789
+ }
790
+ if (listElementsAtEnd) {
791
+ results.push(await toolCallbacks.get("mobile_list_elements_on_screen").callback({ device }, {}));
792
+ }
793
+ return results.join("\n");
794
+ });
662
795
  return server;
663
796
  };
664
797
  exports.createMcpServer = createMcpServer;
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.1",
4
+ "version": "1.0.3",
5
5
  "description": "Mobile MCP",
6
6
  "repository": {
7
7
  "type": "git",
@@ -29,7 +29,7 @@
29
29
  "commander": "14.0.0",
30
30
  "express": "5.1.0",
31
31
  "fast-xml-parser": "5.8.0",
32
- "mobilewright": "0.0.52",
32
+ "mobilewright": "0.0.57",
33
33
  "qs": "^6.15.0",
34
34
  "zod": "^4.1.13",
35
35
  "zod-to-json-schema": "3.25.0"