@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 +15 -1
- package/README.md +29 -6
- package/README.zh-CN.md +15 -1
- package/lib/mobile-device.js +13 -0
- package/lib/server.js +61 -26
- package/package.json +3 -3
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
package/lib/mobile-device.js
CHANGED
|
@@ -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
|
|
69
|
-
|
|
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
|
-
|
|
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
|
|
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 -
|
|
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
|
|
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
|
-
|
|
466
|
-
}, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device,
|
|
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(
|
|
469
|
-
return `Uninstalled app ${
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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("
|
|
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.
|
|
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.
|
|
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.
|
|
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",
|