@mobilenext/mobile-mcp 1.0.14 → 1.0.16

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
@@ -419,7 +419,7 @@ test('sign in', async ({ screen }) => {
419
419
  });
420
420
  ```
421
421
 
422
- `npm init mobilewright@latest` から始めましょう。
422
+ `npm init mobilewright@latest` から始めましょう。エージェントのセッションから GitHub Actions で動くテストまでの流れは[ステップバイステップガイド](docs/mobilewright-ci.md)(英語)をご覧ください。
423
423
 
424
424
  ### ☁️ クラウドデバイスでスケールする
425
425
 
package/README.md CHANGED
@@ -118,6 +118,7 @@ How we help to scale mobile automation:
118
118
  - **`mobile_terminate_app`** - Stop and terminate a running app
119
119
  - **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
120
120
  - **`mobile_uninstall_app`** - Uninstall an app by its package name or bundle ID
121
+ - **`mobile_clear_app_data`** - Clear an app's data so it starts fresh (Android and iOS Simulator)
121
122
 
122
123
  ### Screen Interaction
123
124
  - **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
@@ -429,7 +430,7 @@ test('sign in', async ({ screen }) => {
429
430
  });
430
431
  ```
431
432
 
432
- Start with `npm init mobilewright@latest`.
433
+ Start with `npm init mobilewright@latest`. The [step-by-step guide](docs/mobilewright-ci.md) goes from an agent session to a test running in GitHub Actions.
433
434
 
434
435
  ### ☁️ Scale up, use a cloud device
435
436
 
package/README.zh-CN.md CHANGED
@@ -419,7 +419,7 @@ test('sign in', async ({ screen }) => {
419
419
  });
420
420
  ```
421
421
 
422
- 从 `npm init mobilewright@latest` 开始。
422
+ 从 `npm init mobilewright@latest` 开始。[分步指南](docs/mobilewright-ci.md)(英文)介绍了如何从一次智能体会话得到在 GitHub Actions 中运行的测试。
423
423
 
424
424
  ### ☁️ 扩展规模,使用云设备
425
425
 
@@ -141,6 +141,9 @@ class MobileDevice {
141
141
  async terminateApp(packageName) {
142
142
  this.runCommand(["apps", "terminate", packageName]);
143
143
  }
144
+ async clearAppData(packageName) {
145
+ this.runCommand(["apps", "clear", packageName]);
146
+ }
144
147
  async installApp(path) {
145
148
  this.runCommand(["apps", "install", path]);
146
149
  }
@@ -193,6 +196,18 @@ class MobileDevice {
193
196
  }
194
197
  return elements.flatMap(element => flattenUIElement(element));
195
198
  }
199
+ async getRawUIHierarchy() {
200
+ const response = this.runJsonCommand(["dump", "ui", "--format", "raw", "--full"]);
201
+ const rawData = response.data?.rawData;
202
+ if (rawData === undefined || rawData === null) {
203
+ throw new robot_1.ActionableError("No raw UI hierarchy was returned for this device. Its screen may be off or locked, or the installed mobilecli version may not support raw UI dumps");
204
+ }
205
+ // mobilecli returns android rawData as a json string, ios as an object
206
+ if (typeof rawData === "string") {
207
+ return JSON.parse(rawData);
208
+ }
209
+ return rawData;
210
+ }
196
211
  async setOrientation(orientation) {
197
212
  this.runCommand(["device", "orientation", "set", orientation]);
198
213
  }
package/lib/server.js CHANGED
@@ -21,6 +21,7 @@ const mobilecli_1 = require("./mobilecli");
21
21
  const mobile_device_1 = require("./mobile-device");
22
22
  const utils_1 = require("./utils");
23
23
  const format_elements_1 = require("./format-elements");
24
+ const telemetry_quota_1 = require("./telemetry-quota");
24
25
  const ALLOWED_LOG_EXTENSIONS = [".log", ".txt", ".jsonl"];
25
26
  const DEFAULT_DEVICE_LOG_ENTRIES = 100;
26
27
  const MAX_DEVICE_LOG_ENTRIES = 10000;
@@ -142,6 +143,10 @@ const createMcpServer = () => {
142
143
  if (process.env.MOBILEMCP_DISABLE_TELEMETRY) {
143
144
  return;
144
145
  }
146
+ const toolName = typeof properties.ToolName === "string" ? properties.ToolName : undefined;
147
+ if (!(0, telemetry_quota_1.shouldSendEvent)(event, toolName)) {
148
+ return;
149
+ }
145
150
  try {
146
151
  const url = "https://us.i.posthog.com/i/v0/e/";
147
152
  const api_key = "phc_KHRTZmkDsU7A8EbydEK8s4lJpPoTDyyBhSlwer694cS";
@@ -473,6 +478,17 @@ const createMcpServer = () => {
473
478
  await robot.terminateApp(packageName);
474
479
  return `Terminated app ${packageName}`;
475
480
  });
481
+ tool("mobile_clear_app_data", "Clear App Data", "Clear an app's data, such as its cache, documents, preferences and databases, and stop the app, so the next launch starts as if freshly installed. The app stays installed. Supported on Android devices and emulators and on iOS simulators, not on real iOS devices.", {
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."),
483
+ packageName: zod_1.z.string().describe("The package name (Android) or bundle id (iOS) of the app to clear"),
484
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device, packageName }) => {
485
+ const robot = getRobotFromDevice(device);
486
+ if (!robot.clearAppData) {
487
+ throw new robot_1.ActionableError("Clearing app data is not supported in legacy robot mode");
488
+ }
489
+ await robot.clearAppData(packageName);
490
+ return `Cleared app data for ${packageName}`;
491
+ });
476
492
  tool("mobile_install_app", "Install App", "Install an app on mobile device", {
477
493
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
478
494
  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"),
@@ -564,9 +580,15 @@ const createMcpServer = () => {
564
580
  });
565
581
  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.", {
566
582
  device: zod_1.z.string().describe("The device identifier to use. Use mobile_list_available_devices to find which devices are available to you."),
567
- format: zod_1.z.enum(["text", "json"]).optional().describe("Output format. \"text\" (default) is one compact line per element, \"json\" is a json array"),
568
- }, { readOnlyHint: true, openWorldHint: true }, async ({ device, format = "text" }) => {
583
+ format: zod_1.z.enum(["text", "json", "raw"]).default("text").describe("Output format. \"text\" (default) is one compact line per element, \"json\" is a json array, \"raw\" is the unfiltered platform-specific hierarchy as JSON (mobilecli only). Raw nodes may be offscreen and do not have element refs"),
584
+ }, { readOnlyHint: true, openWorldHint: true }, async ({ device, format }) => {
569
585
  const robot = getRobotFromDevice(device);
586
+ if (format === "raw") {
587
+ if (!robot.getRawUIHierarchy) {
588
+ throw new robot_1.ActionableError("Raw UI hierarchy is not supported in legacy robot mode");
589
+ }
590
+ return JSON.stringify(await robot.getRawUIHierarchy());
591
+ }
570
592
  const elements = await robot.getElementsOnScreen();
571
593
  return (0, format_elements_1.formatElements)(elements, format);
572
594
  });
@@ -0,0 +1,71 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.shouldSendEvent = void 0;
7
+ const node_fs_1 = __importDefault(require("node:fs"));
8
+ const node_os_1 = __importDefault(require("node:os"));
9
+ const node_path_1 = __importDefault(require("node:path"));
10
+ // events not listed here are always sent (get_more_tools' $mcp_missing_capability)
11
+ const DAILY_CAPS = {
12
+ "launch": 1,
13
+ "tool_invoked": 1,
14
+ "tool_failed": 100,
15
+ };
16
+ // get_more_tools is rare and is the signal we want the most, never cap it
17
+ const UNCAPPED_TOOLS = ["get_more_tools"];
18
+ // share mobilecli's state dir (it keeps daemon.pid/sock/log there), honoring the same override
19
+ const stateDir = () => process.env.MOBILECLI_HOME || node_path_1.default.join(node_os_1.default.homedir(), ".mobilecli");
20
+ const defaultQuotaPath = () => node_path_1.default.join(stateDir(), "mobile-mcp-telemetry.json");
21
+ const today = (now) => now.toISOString().slice(0, 10);
22
+ const isValidCounts = (counts) => {
23
+ if (typeof counts !== "object" || counts === null || Array.isArray(counts)) {
24
+ return false;
25
+ }
26
+ return Object.values(counts).every(count => Number.isInteger(count) && count >= 0);
27
+ };
28
+ const readState = (statePath, day) => {
29
+ try {
30
+ const state = JSON.parse(node_fs_1.default.readFileSync(statePath, "utf8"));
31
+ if (state?.day === day && isValidCounts(state.counts)) {
32
+ return state;
33
+ }
34
+ }
35
+ catch {
36
+ // missing or corrupt file, start a fresh day
37
+ }
38
+ return { day, counts: {} };
39
+ };
40
+ const writeState = (statePath, state) => {
41
+ node_fs_1.default.mkdirSync(node_path_1.default.dirname(statePath), { recursive: true, mode: 0o700 });
42
+ // write a temp file and rename over the target, so a planted link at statePath is replaced, not written through
43
+ const tempPath = `${statePath}.${process.pid}.tmp`;
44
+ node_fs_1.default.writeFileSync(tempPath, JSON.stringify(state), { mode: 0o600 });
45
+ node_fs_1.default.renameSync(tempPath, statePath);
46
+ };
47
+ // ponytail: read-modify-write without a lock, so concurrent launches may slightly exceed a cap.
48
+ // add a lock file if that ever matters.
49
+ const shouldSendEvent = (event, toolName, statePath = defaultQuotaPath(), now = new Date()) => {
50
+ const cap = DAILY_CAPS[event];
51
+ if (cap === undefined) {
52
+ return true;
53
+ }
54
+ if (toolName !== undefined && UNCAPPED_TOOLS.includes(toolName)) {
55
+ return true;
56
+ }
57
+ try {
58
+ const state = readState(statePath, today(now));
59
+ const sent = state.counts[event] ?? 0;
60
+ if (sent >= cap) {
61
+ return false;
62
+ }
63
+ writeState(statePath, { day: state.day, counts: { ...state.counts, [event]: sent + 1 } });
64
+ return true;
65
+ }
66
+ catch {
67
+ // can't persist the quota (read-only home, etc.), drop the event rather than flood
68
+ return false;
69
+ }
70
+ };
71
+ exports.shouldSendEvent = shouldSendEvent;
package/lib/utils.js CHANGED
@@ -15,6 +15,7 @@ exports.finishRecording = finishRecording;
15
15
  const node_path_1 = __importDefault(require("node:path"));
16
16
  const node_os_1 = __importDefault(require("node:os"));
17
17
  const node_fs_1 = __importDefault(require("node:fs"));
18
+ const node_crypto_1 = require("node:crypto");
18
19
  const robot_1 = require("./robot");
19
20
  function validatePackageName(packageName) {
20
21
  // iOS bundle identifiers (which flow through this same "packageName" parameter
@@ -145,17 +146,29 @@ function validateOutputPath(filePath) {
145
146
  throw new robot_1.ActionableError(`"${dir}" is not in the list of allowed directories. Allowed directories: ${allowedRoots.join(", ")}.`);
146
147
  }
147
148
  }
148
- // O_NOFOLLOW makes the open itself refuse a symlink at the final component, so a
149
- // link planted after validateOutputPath cannot redirect the write.
150
- // ponytail: windows has no O_NOFOLLOW, there we rely on validateOutputPath alone
151
- const WRITE_NO_FOLLOW_FLAGS = node_fs_1.default.constants.O_WRONLY | node_fs_1.default.constants.O_CREAT | node_fs_1.default.constants.O_TRUNC | (node_fs_1.default.constants.O_NOFOLLOW ?? 0);
149
+ // a sibling of `to` with an unguessable name, created with O_EXCL ("wx"), so a
150
+ // file or link planted there makes the write fail instead of redirecting it
151
+ function partialPathFor(to) {
152
+ return node_path_1.default.join(node_path_1.default.dirname(to), `.${node_path_1.default.basename(to)}.${(0, node_crypto_1.randomBytes)(8).toString("hex")}.partial`);
153
+ }
154
+ // write next to `filePath` and rename over it: rename replaces whatever sits at
155
+ // `filePath` (a symlink, a hard link, a regular file) instead of writing through
156
+ // it, so a link can never point the write at another file
152
157
  function writeOutputFile(filePath, data) {
153
- const fd = node_fs_1.default.openSync(filePath, WRITE_NO_FOLLOW_FLAGS);
158
+ const partial = partialPathFor(filePath);
159
+ const existing = node_fs_1.default.lstatSync(filePath, { throwIfNoEntry: false });
154
160
  try {
155
- node_fs_1.default.writeFileSync(fd, data);
161
+ // 0600 while half-written; a link at `filePath` is replaced, so only a
162
+ // regular file there passes its mode on to the new file
163
+ node_fs_1.default.writeFileSync(partial, data, { flag: "wx", mode: 0o600 });
164
+ if (existing?.isFile()) {
165
+ node_fs_1.default.chmodSync(partial, existing.mode & 0o777);
166
+ }
167
+ node_fs_1.default.renameSync(partial, filePath);
156
168
  }
157
- finally {
158
- node_fs_1.default.closeSync(fd);
169
+ catch (error) {
170
+ node_fs_1.default.rmSync(partial, { force: true });
171
+ throw error;
159
172
  }
160
173
  }
161
174
  // a fresh 0700 directory nobody else can plant a symlink in, for files written
@@ -177,7 +190,7 @@ function moveOutputFile(from, to) {
177
190
  throw error;
178
191
  }
179
192
  }
180
- const partial = node_path_1.default.join(node_path_1.default.dirname(to), `.${node_path_1.default.basename(to)}.${process.pid}-${Date.now()}.partial`);
193
+ const partial = partialPathFor(to);
181
194
  try {
182
195
  node_fs_1.default.copyFileSync(from, partial, node_fs_1.default.constants.COPYFILE_EXCL);
183
196
  node_fs_1.default.renameSync(partial, to);
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.14",
4
+ "version": "1.0.16",
5
5
  "description": "Mobile MCP",
6
6
  "repository": {
7
7
  "type": "git",
@@ -27,14 +27,14 @@
27
27
  "dependencies": {
28
28
  "@clack/prompts": "^0.9.1",
29
29
  "@modelcontextprotocol/express": "2.0.2",
30
- "@modelcontextprotocol/node": "2.0.0",
30
+ "@modelcontextprotocol/node": "^2.1.2",
31
31
  "@modelcontextprotocol/server": "2.4.0",
32
32
  "add-mcp": "^2.6.0",
33
33
  "ajv": "^8.18.0",
34
34
  "commander": "14.0.0",
35
35
  "express": "5.1.0",
36
36
  "fast-xml-parser": "5.8.0",
37
- "mobilewright": "0.0.67",
37
+ "mobilewright": "0.0.68",
38
38
  "qs": "^6.15.0",
39
39
  "zod": "^4.2.0",
40
40
  "zod-to-json-schema": "3.25.0"