@mobilenext/mobile-mcp 1.0.13 → 1.0.15

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
@@ -34,6 +34,18 @@
34
34
 
35
35
  https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
36
36
 
37
+ ## 🚀 クイックスタート
38
+
39
+ **クイックインストール**: このマシン上の MCP クライアント(Claude Code、Codex、Cursor、VS Code、Gemini CLI など)を検出し、設定するクライアントを選択できます:
40
+
41
+ ```bash
42
+ npx @mobilenext/mobile-mcp@latest install
43
+ ```
44
+
45
+ `--yes` を付けると、確認なしで検出されたすべてのクライアントを設定します。
46
+
47
+ クライアントごとの手動設定: [インストールと設定](#インストールと設定)
48
+
37
49
 
38
50
  <p align="center">
39
51
  <a href="https://github.com/mobile-next/">
@@ -144,7 +156,7 @@ MCP をエージェントおよびモバイルデバイスに接続するため
144
156
 
145
157
  ## インストールと設定
146
158
 
147
- **標準設定** はほとんどのツールで動作します:
159
+ ほとんどのツールで動作する **標準設定**:
148
160
 
149
161
  ```json
150
162
  {
@@ -393,6 +405,22 @@ npx @mobilenext/mobile-mcp@latest
393
405
 
394
406
  実行中のシミュレーター、エミュレーター、接続済みのデバイスが返ってくるはずです。返ってくれば、Mobile MCP は正しく設定されています。リストが空の場合は、シミュレーターまたはエミュレーターが起動していることを確認してください([前提条件](#前提条件)を参照)。さらに詳しくは [wiki](https://github.com/mobile-next/mobile-mcp/wiki) をご覧ください。
395
407
 
408
+ ### 🧪 エージェントのセッションを CI テストに
409
+
410
+ Mobile MCP でモバイルアプリを自動化、またはテストしていますか? エージェントに、その操作フローを **[Mobilewright](https://mobilewright.dev/?utm_source=mobile-mcp&utm_medium=readme&utm_campaign=agent-to-ci)** のテストとして書くよう指示しましょう。テストは決定論的になり、CI/CD ワークフローに組み込めます。
411
+
412
+ ```ts
413
+ import { test, expect } from '@mobilewright/test';
414
+
415
+ test('sign in', async ({ screen }) => {
416
+ await screen.getByLabel('Email').fill('user@example.com');
417
+ await screen.getByRole('button', { name: 'Sign In' }).tap();
418
+ await expect(screen.getByText('Welcome back')).toBeVisible();
419
+ });
420
+ ```
421
+
422
+ `npm init mobilewright@latest` から始めましょう。エージェントのセッションから GitHub Actions で動くテストまでの流れは[ステップバイステップガイド](docs/mobilewright-ci.md)(英語)をご覧ください。
423
+
396
424
  ### ☁️ クラウドデバイスでスケールする
397
425
 
398
426
  数百台規模のデバイスにスケールしたい場合は? CI/CD パイプラインで Mobile MCP を使いたい場合は?
package/README.md CHANGED
@@ -43,6 +43,18 @@ Run it against devices on your own machine, or against real iOS and Android devi
43
43
 
44
44
  https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
45
45
 
46
+ ## 🚀 Quick start
47
+
48
+ **Quick install** detects the MCP clients on this machine (Claude Code, Codex, Cursor, VS Code, Gemini CLI and more) and lets you pick which ones to configure:
49
+
50
+ ```bash
51
+ npx @mobilenext/mobile-mcp@latest install
52
+ ```
53
+
54
+ Add `--yes` to configure every detected client without asking.
55
+
56
+ Manual setup per client: [Installation and configuration](#installation-and-configuration)
57
+
46
58
 
47
59
  <p align="center">
48
60
  <a href="https://github.com/mobile-next/">
@@ -106,6 +118,7 @@ How we help to scale mobile automation:
106
118
  - **`mobile_terminate_app`** - Stop and terminate a running app
107
119
  - **`mobile_install_app`** - Install an app from file (.apk, .ipa, .app, .zip)
108
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)
109
122
 
110
123
  ### Screen Interaction
111
124
  - **`mobile_take_screenshot`** - Take a screenshot to understand what's on screen
@@ -154,7 +167,7 @@ What you will need to connect MCP with your agent and mobile devices:
154
167
 
155
168
  ## Installation and configuration
156
169
 
157
- **Standard config** works in most of the tools:
170
+ To configure it by hand, this **standard config** works in most of the tools:
158
171
 
159
172
  ```json
160
173
  {
@@ -403,6 +416,22 @@ Once the server is configured, ask your agent to list devices:
403
416
 
404
417
  You should get back your running simulators, emulators, and connected devices. If you do, Mobile MCP is wired up correctly. If the list is empty, make sure a simulator or emulator is running (see [Prerequisites](#prerequisites)) — for more help, check the [wiki](https://github.com/mobile-next/mobile-mcp/wiki).
405
418
 
419
+ ### 🧪 From agent session to CI test
420
+
421
+ Using Mobile MCP to automate a mobile app, or to test one? Tell your agent to write the flow as a **[Mobilewright](https://mobilewright.dev/?utm_source=mobile-mcp&utm_medium=readme&utm_campaign=agent-to-ci)** test. It becomes deterministic, and part of your CI/CD workflow.
422
+
423
+ ```ts
424
+ import { test, expect } from '@mobilewright/test';
425
+
426
+ test('sign in', async ({ screen }) => {
427
+ await screen.getByLabel('Email').fill('user@example.com');
428
+ await screen.getByRole('button', { name: 'Sign In' }).tap();
429
+ await expect(screen.getByText('Welcome back')).toBeVisible();
430
+ });
431
+ ```
432
+
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.
434
+
406
435
  ### ☁️ Scale up, use a cloud device
407
436
 
408
437
  Want to scale to hundreds of devices? Use Mobile MCP in your CI/CD pipeline?
package/README.zh-CN.md CHANGED
@@ -34,6 +34,18 @@
34
34
 
35
35
  https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
36
36
 
37
+ ## 🚀 快速开始
38
+
39
+ **快速安装**:自动检测本机上的 MCP 客户端(Claude Code、Codex、Cursor、VS Code、Gemini CLI 等),并让你选择要配置哪些:
40
+
41
+ ```bash
42
+ npx @mobilenext/mobile-mcp@latest install
43
+ ```
44
+
45
+ 加上 `--yes` 可不经询问直接配置所有检测到的客户端。
46
+
47
+ 各客户端的手动配置: [安装与配置](#安装与配置)
48
+
37
49
 
38
50
  <p align="center">
39
51
  <a href="https://github.com/mobile-next/">
@@ -144,7 +156,7 @@ https://github.com/user-attachments/assets/bb084777-beb3-4930-ae6f-8d3fe694ddde
144
156
 
145
157
  ## 安装与配置
146
158
 
147
- **标准配置** 适用于大多数工具:
159
+ 适用于大多数工具的 **标准配置**:
148
160
 
149
161
  ```json
150
162
  {
@@ -393,6 +405,22 @@ npx @mobilenext/mobile-mcp@latest
393
405
 
394
406
  你应当会看到正在运行的模拟器、仿真器以及已连接的设备。如果能看到,说明 Mobile MCP 已正确接入。如果列表为空,请确认已经启动了模拟器或仿真器(参见[前置条件](#前置条件))—— 需要更多帮助请查看 [wiki](https://github.com/mobile-next/mobile-mcp/wiki)。
395
407
 
408
+ ### 🧪 把智能体会话变成 CI 测试
409
+
410
+ 在用 Mobile MCP 自动化或测试移动应用?让你的智能体把这段操作流程写成 **[Mobilewright](https://mobilewright.dev/?utm_source=mobile-mcp&utm_medium=readme&utm_campaign=agent-to-ci)** 测试。这样测试就是确定性的,并能成为你 CI/CD 工作流的一部分。
411
+
412
+ ```ts
413
+ import { test, expect } from '@mobilewright/test';
414
+
415
+ test('sign in', async ({ screen }) => {
416
+ await screen.getByLabel('Email').fill('user@example.com');
417
+ await screen.getByRole('button', { name: 'Sign In' }).tap();
418
+ await expect(screen.getByText('Welcome back')).toBeVisible();
419
+ });
420
+ ```
421
+
422
+ 从 `npm init mobilewright@latest` 开始。[分步指南](docs/mobilewright-ci.md)(英文)介绍了如何从一次智能体会话得到在 GitHub Actions 中运行的测试。
423
+
396
424
  ### ☁️ 扩展规模,使用云设备
397
425
 
398
426
  想扩展到数百台设备?想在 CI/CD 流水线中使用 Mobile MCP?
package/lib/index.js CHANGED
@@ -96,12 +96,43 @@ const startStdioServer = async () => {
96
96
  process.exit(1);
97
97
  }
98
98
  };
99
- const main = async () => {
100
- commander_1.program
101
- .version((0, server_2.getAgentVersion)())
102
- .option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
103
- .option("--stdio", "Start stdio server (default)")
104
- .parse(process.argv);
99
+ const installIntoDetectedClients = async (options) => {
100
+ // add-mcp is ESM-only, loaded lazily so a normal server start does not pay for it
101
+ const { agents, detectGlobalAgents, upsertServer } = await import("add-mcp");
102
+ const prompts = await import("@clack/prompts");
103
+ const config = { command: "npx", args: ["-y", "@mobilenext/mobile-mcp@latest"] };
104
+ const detected = await detectGlobalAgents();
105
+ if (detected.length === 0) {
106
+ console.log("No MCP clients detected. See https://github.com/mobile-next/mobile-mcp#installation-and-configuration");
107
+ return;
108
+ }
109
+ // no terminal to draw checkboxes on (e.g. an agent ran us), so behave like --yes
110
+ let selected = detected;
111
+ if (!options.yes && process.stdin.isTTY) {
112
+ const answer = await prompts.multiselect({
113
+ message: "Install mobile-mcp into which clients?",
114
+ options: detected.map(agent => ({ value: agent, label: agents[agent].displayName })),
115
+ initialValues: detected,
116
+ required: false,
117
+ });
118
+ if (prompts.isCancel(answer)) {
119
+ prompts.cancel("Installation cancelled.");
120
+ return;
121
+ }
122
+ selected = answer;
123
+ }
124
+ for (const agent of selected) {
125
+ const result = upsertServer(agent, "mobile-mcp", config);
126
+ if (result.success) {
127
+ console.log(`✓ ${agents[agent].displayName}: ${result.path}`);
128
+ }
129
+ else {
130
+ console.log(`✗ ${agents[agent].displayName}: ${result.error}`);
131
+ process.exitCode = 1;
132
+ }
133
+ }
134
+ };
135
+ const startServer = async () => {
105
136
  const options = commander_1.program.opts();
106
137
  if (options.listen) {
107
138
  const listen = options.listen.trim();
@@ -126,4 +157,17 @@ const main = async () => {
126
157
  await startStdioServer();
127
158
  }
128
159
  };
160
+ const main = async () => {
161
+ commander_1.program
162
+ .version((0, server_2.getAgentVersion)())
163
+ .option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
164
+ .option("--stdio", "Start stdio server (default)")
165
+ .action(startServer);
166
+ commander_1.program
167
+ .command("install")
168
+ .description("Add mobile-mcp to the MCP clients detected on this machine")
169
+ .option("-y, --yes", "Install into every detected client without asking")
170
+ .action(installIntoDetectedClients);
171
+ await commander_1.program.parseAsync(process.argv);
172
+ };
129
173
  main().then();
@@ -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
  }
package/lib/server.js CHANGED
@@ -473,6 +473,17 @@ const createMcpServer = () => {
473
473
  await robot.terminateApp(packageName);
474
474
  return `Terminated app ${packageName}`;
475
475
  });
476
+ 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.", {
477
+ 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
+ packageName: zod_1.z.string().describe("The package name (Android) or bundle id (iOS) of the app to clear"),
479
+ }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ device, packageName }) => {
480
+ const robot = getRobotFromDevice(device);
481
+ if (!robot.clearAppData) {
482
+ throw new robot_1.ActionableError("Clearing app data is not supported in legacy robot mode");
483
+ }
484
+ await robot.clearAppData(packageName);
485
+ return `Cleared app data for ${packageName}`;
486
+ });
476
487
  tool("mobile_install_app", "Install App", "Install an app on mobile device", {
477
488
  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
489
  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"),
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.13",
4
+ "version": "1.0.15",
5
5
  "description": "Mobile MCP",
6
6
  "repository": {
7
7
  "type": "git",
@@ -25,9 +25,11 @@
25
25
  "lib"
26
26
  ],
27
27
  "dependencies": {
28
+ "@clack/prompts": "^0.9.1",
28
29
  "@modelcontextprotocol/express": "2.0.2",
29
- "@modelcontextprotocol/node": "2.0.0",
30
+ "@modelcontextprotocol/node": "^2.1.2",
30
31
  "@modelcontextprotocol/server": "2.4.0",
32
+ "add-mcp": "^2.6.0",
31
33
  "ajv": "^8.18.0",
32
34
  "commander": "14.0.0",
33
35
  "express": "5.1.0",