@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 +1 -1
- package/README.md +2 -1
- package/README.zh-CN.md +1 -1
- package/lib/mobile-device.js +15 -0
- package/lib/server.js +24 -2
- package/lib/telemetry-quota.js +71 -0
- package/lib/utils.js +22 -9
- package/package.json +3 -3
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
package/lib/mobile-device.js
CHANGED
|
@@ -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"]).
|
|
568
|
-
}, { readOnlyHint: true, openWorldHint: true }, async ({ device, format
|
|
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
|
-
//
|
|
149
|
-
// link planted
|
|
150
|
-
|
|
151
|
-
|
|
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
|
|
158
|
+
const partial = partialPathFor(filePath);
|
|
159
|
+
const existing = node_fs_1.default.lstatSync(filePath, { throwIfNoEntry: false });
|
|
154
160
|
try {
|
|
155
|
-
|
|
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
|
-
|
|
158
|
-
node_fs_1.default.
|
|
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 =
|
|
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.
|
|
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.
|
|
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.
|
|
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"
|