@mobilenext/mobile-mcp 1.0.7 → 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.ja.md CHANGED
@@ -58,6 +58,11 @@ https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
58
58
  - 🧠 **プラットフォームの専門知識は不要**: XCUITest も Espresso もプラットフォームごとのつなぎコードも不要です。目的を伝えればエージェントが実行します。
59
59
  - 🧰 **完全なデバイス制御**: タップ、スワイプ、ジェスチャー、アプリのインストール / 起動 / 終了、画面録画、ハードウェアボタン、ディープリンク、画面の向き。
60
60
  - 📊 **構造化された決定的な出力**: 実際の UI 要素を読み取って構造化データを抽出し、スクリーンショットのみのアプローチにありがちな曖昧さを削減します。
61
+ - 🪞 **Claude Code でのデバイスミラーリング**: Ghostty または kitty で動作する Claude Code 向けです。プラグインをインストールして `/mobile-mirror` を実行すると、デバイスのライブ画面がサイドペインに表示され、ターミナルを離れずにタップ、文字入力、Home/Back の操作ができます。
62
+
63
+ <p align="center">
64
+ <img alt="/mobile-mirror showing an iOS simulator beside a Claude Code session" src="docs/screenshots/mobile-mirror.png" width="800" />
65
+ </p>
61
66
 
62
67
  ### 🎯 対応プラットフォーム
63
68
 
@@ -208,7 +213,16 @@ Cline をセットアップするには、上記の json を MCP 設定ファイ
208
213
  <details>
209
214
  <summary>Claude Code</summary>
210
215
 
211
- Claude Code CLI を使って Mobile MCP サーバーを追加します:
216
+ Claude Code 内でプラグインをインストールします。Mobile MCP サーバーと `/mobile-mirror` が追加されます:
217
+
218
+ ```
219
+ /plugin marketplace add mobile-next/mobile-mcp
220
+ /plugin install mobile-mcp@mobile-mcp
221
+ ```
222
+
223
+ `/mobile-mirror [device-id]` を実行すると、デバイスのライブ画面を表示するペインが開きます。画像をクリックするとタップ、キー入力でキーを送信でき、上部の Home、Back、App Switch、URL ボタンも使えます。画像の表示には kitty や Ghostty など、kitty グラフィックスプロトコルに対応したターミナルが必要です。
224
+
225
+ プラグインを使えない場合は、Claude Code CLI で MCP サーバーのみを追加します:
212
226
 
213
227
  ```bash
214
228
  claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
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
 
@@ -58,6 +67,11 @@ How we help to scale mobile automation:
58
67
  - 🧠 **No platform expertise required**: no XCUITest, no Espresso, no per-platform glue — describe the goal and the agent does it.
59
68
  - 🧰 **Full device control**: taps, swipes, and gestures; app install/launch/terminate; screen recording; hardware buttons; deep links; orientation.
60
69
  - 📊 **Structured, deterministic output**: reads real UI elements and extracts structured data, cutting the ambiguity of screenshot-only approaches.
70
+ - 🪞 **Device mirroring in Claude Code**: for Claude Code running in Ghostty or kitty. Install the plugin and run `/mobile-mirror` to see the device's live screen in a side pane, then tap, type and press Home/Back without leaving the terminal.
71
+
72
+ <p align="center">
73
+ <img alt="/mobile-mirror showing an iOS simulator beside a Claude Code session" src="docs/screenshots/mobile-mirror.png" width="800" />
74
+ </p>
61
75
 
62
76
  ### 🎯 Platform Support
63
77
 
@@ -91,15 +105,15 @@ How we help to scale mobile automation:
91
105
  - **`mobile_launch_app`** - Launch an app using its package name
92
106
  - **`mobile_terminate_app`** - Stop and terminate a running app
93
107
  - **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
94
- - **`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
95
109
 
96
110
  ### Screen Interaction
97
111
  - **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
98
112
  - **`mobile_save_screenshot`** - Save a screenshot to a file
99
113
  - **`mobile_list_elements_on_screen`** - List UI elements with their coordinates and properties
100
- - **`mobile_click_on_screen_at_coordinates`** - Click at specific x,y coordinates
101
- - **`mobile_double_tap_on_screen`** - Double-tap at specific coordinates
102
- - **`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
103
117
  - **`mobile_swipe_on_screen`** - Swipe in any direction (up, down, left, right)
104
118
  - **`mobile_start_screen_recording`** - Start recording the device screen to a video file
105
119
  - **`mobile_stop_screen_recording`** - Stop the active screen recording and save the video
@@ -107,7 +121,7 @@ How we help to scale mobile automation:
107
121
  ### Input & Navigation
108
122
  - **`mobile_type_keys`** - Type text into focused elements with optional submit
109
123
  - **`mobile_press_button`** - Press device buttons (HOME, BACK, VOLUME_UP/DOWN, ENTER, etc.)
110
- - **`mobile_open_url`** - Open URLs in the device browser
124
+ - **`mobile_open_url`** - Open http/https URLs in the device browser
111
125
 
112
126
  ### Logs & Crash Reports
113
127
  - **`mobile_get_device_logs`** - Collect live device logs (logcat on Android, unified log on iOS), optionally saved to a file
@@ -209,7 +223,16 @@ To setup Cline, just add the json above to your MCP settings file.
209
223
  <details>
210
224
  <summary>Claude Code</summary>
211
225
 
212
- Use the Claude Code CLI to add the Mobile MCP server:
226
+ Install the plugin from inside Claude Code. It adds the Mobile MCP server and `/mobile-mirror`:
227
+
228
+ ```
229
+ /plugin marketplace add mobile-next/mobile-mcp
230
+ /plugin install mobile-mcp@mobile-mcp
231
+ ```
232
+
233
+ `/mobile-mirror [device-id]` opens a pane with the device's live screen. Click the picture to tap, type to send keys, and use the Home, Back, App Switch and URL buttons above it. The picture needs a terminal with the kitty graphics protocol, such as kitty or Ghostty.
234
+
235
+ If you can't use plugins, add only the MCP server with the Claude Code CLI:
213
236
 
214
237
  ```bash
215
238
  claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
package/README.zh-CN.md CHANGED
@@ -58,6 +58,11 @@ https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
58
58
  - 🧠 **无需平台专业知识**: 不需要 XCUITest,不需要 Espresso,也不需要各平台的胶水代码 —— 描述目标,智能体来完成。
59
59
  - 🧰 **完整的设备控制**: 点击、滑动与手势;应用安装/启动/终止;屏幕录制;硬件按键;深度链接;屏幕方向。
60
60
  - 📊 **结构化、确定性的输出**: 读取真实的 UI 元素并提取结构化数据,减少纯截图方案带来的歧义。
61
+ - 🪞 **在 Claude Code 中镜像设备**: 适用于在 Ghostty 或 kitty 中运行的 Claude Code。安装插件后运行 `/mobile-mirror`,即可在侧边窗格中查看设备的实时画面,并且无需离开终端就能点按、输入文字以及按 Home/Back。
62
+
63
+ <p align="center">
64
+ <img alt="/mobile-mirror showing an iOS simulator beside a Claude Code session" src="docs/screenshots/mobile-mirror.png" width="800" />
65
+ </p>
61
66
 
62
67
  ### 🎯 平台支持
63
68
 
@@ -208,7 +213,16 @@ Antigravity 没有添加 MCP 服务器的 CLI 命令,因此需要手动添加
208
213
  <details>
209
214
  <summary>Claude Code</summary>
210
215
 
211
- 使用 Claude Code CLI 添加 Mobile MCP 服务器:
216
+ 在 Claude Code 中安装插件,它会添加 Mobile MCP 服务器和 `/mobile-mirror`:
217
+
218
+ ```
219
+ /plugin marketplace add mobile-next/mobile-mcp
220
+ /plugin install mobile-mcp@mobile-mcp
221
+ ```
222
+
223
+ `/mobile-mirror [device-id]` 会打开一个显示设备实时画面的窗格。点击画面即可点按设备,输入文字即可发送按键,上方还有 Home、Back、App Switch 和 URL 按钮。显示画面需要支持 kitty 图形协议的终端,例如 kitty 或 Ghostty。
224
+
225
+ 如果无法使用插件,可以用 Claude Code CLI 只添加 MCP 服务器:
212
226
 
213
227
  ```bash
214
228
  claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
@@ -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.7",
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",