@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 +29 -1
- package/README.md +30 -1
- package/README.zh-CN.md +29 -1
- package/lib/index.js +50 -6
- package/lib/mobile-device.js +3 -0
- package/lib/server.js +11 -0
- package/lib/utils.js +22 -9
- package/package.json +4 -2
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
|
-
**
|
|
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
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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();
|
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
|
}
|
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
|
-
//
|
|
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.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.
|
|
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",
|