@mobilenext/mobile-mcp 1.0.6 → 1.0.8
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 +15 -1
- package/README.zh-CN.md +15 -1
- package/lib/index.js +28 -39
- package/lib/mobile-device.js +5 -1
- package/package.json +2 -2
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
|
@@ -58,6 +58,11 @@ How we help to scale mobile automation:
|
|
|
58
58
|
- 🧠 **No platform expertise required**: no XCUITest, no Espresso, no per-platform glue — describe the goal and the agent does it.
|
|
59
59
|
- 🧰 **Full device control**: taps, swipes, and gestures; app install/launch/terminate; screen recording; hardware buttons; deep links; orientation.
|
|
60
60
|
- 📊 **Structured, deterministic output**: reads real UI elements and extracts structured data, cutting the ambiguity of screenshot-only approaches.
|
|
61
|
+
- 🪞 **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.
|
|
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
|
### 🎯 Platform Support
|
|
63
68
|
|
|
@@ -209,7 +214,16 @@ To setup Cline, just add the json above to your MCP settings file.
|
|
|
209
214
|
<details>
|
|
210
215
|
<summary>Claude Code</summary>
|
|
211
216
|
|
|
212
|
-
|
|
217
|
+
Install the plugin from inside Claude Code. It adds the Mobile MCP server and `/mobile-mirror`:
|
|
218
|
+
|
|
219
|
+
```
|
|
220
|
+
/plugin marketplace add mobile-next/mobile-mcp
|
|
221
|
+
/plugin install mobile-mcp@mobile-mcp
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`/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.
|
|
225
|
+
|
|
226
|
+
If you can't use plugins, add only the MCP server with the Claude Code CLI:
|
|
213
227
|
|
|
214
228
|
```bash
|
|
215
229
|
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/index.js
CHANGED
|
@@ -2,11 +2,15 @@
|
|
|
2
2
|
"use strict";
|
|
3
3
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
4
|
const express_1 = require("@modelcontextprotocol/express");
|
|
5
|
-
const stdio_1 = require("@modelcontextprotocol/server/stdio");
|
|
6
5
|
const node_1 = require("@modelcontextprotocol/node");
|
|
7
|
-
const server_1 = require("
|
|
6
|
+
const server_1 = require("@modelcontextprotocol/server");
|
|
7
|
+
const stdio_1 = require("@modelcontextprotocol/server/stdio");
|
|
8
|
+
const server_2 = require("./server");
|
|
8
9
|
const logger_1 = require("./logger");
|
|
9
10
|
const commander_1 = require("commander");
|
|
11
|
+
const logMcpError = (err) => {
|
|
12
|
+
(0, logger_1.error)("Error handling MCP request: " + (err.stack ?? String(err)));
|
|
13
|
+
};
|
|
10
14
|
const startHttpServer = async (host, port) => {
|
|
11
15
|
// createMcpExpressApp applies express.json() and Host-header DNS rebinding
|
|
12
16
|
// protection automatically when binding to localhost / 127.0.0.1 / ::1.
|
|
@@ -36,37 +40,18 @@ const startHttpServer = async (host, port) => {
|
|
|
36
40
|
next();
|
|
37
41
|
});
|
|
38
42
|
}
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
});
|
|
52
|
-
await server.connect(transport);
|
|
53
|
-
await transport.handleRequest(req, res, req.body);
|
|
54
|
-
}
|
|
55
|
-
catch (err) {
|
|
56
|
-
(0, logger_1.error)("Error handling MCP request: " + (err instanceof Error ? err.stack : String(err)));
|
|
57
|
-
if (!res.headersSent) {
|
|
58
|
-
res.status(500).json({
|
|
59
|
-
jsonrpc: "2.0",
|
|
60
|
-
error: {
|
|
61
|
-
code: -32603,
|
|
62
|
-
message: "Internal server error",
|
|
63
|
-
},
|
|
64
|
-
id: null,
|
|
65
|
-
});
|
|
66
|
-
}
|
|
67
|
-
}
|
|
68
|
-
};
|
|
69
|
-
app.post("/mcp", handleMcpRequest);
|
|
43
|
+
// createMcpHandler serves both protocol eras from one factory: requests
|
|
44
|
+
// carrying the per-request `_meta` envelope (revision 2026-07-28, answered
|
|
45
|
+
// with `server/discover` and the modern result vocabulary) get a fresh
|
|
46
|
+
// era-marked instance, and legacy `initialize` traffic is served stateless
|
|
47
|
+
// from the same factory — the same per-request model as before.
|
|
48
|
+
// onerror keeps request-handling and transport failures in the application
|
|
49
|
+
// log (the SDK otherwise answers HTTP 500 silently).
|
|
50
|
+
const handler = (0, server_1.createMcpHandler)(() => (0, server_2.createMcpServer)(), { onerror: logMcpError });
|
|
51
|
+
const node = (0, node_1.toNodeHandler)(handler, { onerror: logMcpError });
|
|
52
|
+
app.post("/mcp", (req, res) => {
|
|
53
|
+
void node(req, res, req.body);
|
|
54
|
+
});
|
|
70
55
|
// Stateless mode has no long-lived sessions; GET (SSE stream) and DELETE
|
|
71
56
|
// (session teardown) are not applicable. Return 405 per SDK guidance.
|
|
72
57
|
const methodNotAllowed = (_req, res) => {
|
|
@@ -82,14 +67,18 @@ const startHttpServer = async (host, port) => {
|
|
|
82
67
|
app.get("/mcp", methodNotAllowed);
|
|
83
68
|
app.delete("/mcp", methodNotAllowed);
|
|
84
69
|
app.listen(port, host, () => {
|
|
85
|
-
(0, logger_1.error)(`mobile-mcp ${(0,
|
|
70
|
+
(0, logger_1.error)(`mobile-mcp ${(0, server_2.getAgentVersion)()} streamable http server listening on http://${host}:${port}/mcp`);
|
|
86
71
|
});
|
|
87
72
|
};
|
|
88
73
|
const startStdioServer = async () => {
|
|
89
74
|
try {
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
75
|
+
// serveStdio owns the transport and the era decision for the
|
|
76
|
+
// connection: a `server/discover` probe (revision 2026-07-28) pins
|
|
77
|
+
// the connection modern, while an `initialize` handshake keeps
|
|
78
|
+
// serving the 2025-era protocol exactly as before. The factory runs
|
|
79
|
+
// lazily on the first message, so a failing createMcpServer() surfaces
|
|
80
|
+
// through onerror rather than the catch below.
|
|
81
|
+
(0, stdio_1.serveStdio)(() => (0, server_2.createMcpServer)(), { onerror: logMcpError });
|
|
93
82
|
// Exit cleanly on termination signals so node flushes pending work
|
|
94
83
|
// (including NODE_V8_COVERAGE output). Node's default SIGINT/SIGTERM
|
|
95
84
|
// handling terminates the process without writing the coverage file,
|
|
@@ -99,7 +88,7 @@ const startStdioServer = async () => {
|
|
|
99
88
|
};
|
|
100
89
|
process.on("SIGINT", shutdown);
|
|
101
90
|
process.on("SIGTERM", shutdown);
|
|
102
|
-
(0, logger_1.error)(`mobile-mcp ${(0,
|
|
91
|
+
(0, logger_1.error)(`mobile-mcp ${(0, server_2.getAgentVersion)()} (mcp sdk ${(0, server_2.getSdkVersion)()}) server running on stdio`);
|
|
103
92
|
}
|
|
104
93
|
catch (err) {
|
|
105
94
|
console.error("Fatal error in main():", err);
|
|
@@ -109,7 +98,7 @@ const startStdioServer = async () => {
|
|
|
109
98
|
};
|
|
110
99
|
const main = async () => {
|
|
111
100
|
commander_1.program
|
|
112
|
-
.version((0,
|
|
101
|
+
.version((0, server_2.getAgentVersion)())
|
|
113
102
|
.option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
|
|
114
103
|
.option("--stdio", "Start stdio server (default)")
|
|
115
104
|
.parse(process.argv);
|
package/lib/mobile-device.js
CHANGED
|
@@ -169,7 +169,11 @@ class MobileDevice {
|
|
|
169
169
|
}
|
|
170
170
|
async getElementsOnScreen() {
|
|
171
171
|
const response = this.runJsonCommand(["dump", "ui"]);
|
|
172
|
-
|
|
172
|
+
const elements = response.data?.elements;
|
|
173
|
+
if (!elements) {
|
|
174
|
+
throw new robot_1.ActionableError("No UI hierarchy was returned for this device - its screen is most likely off or locked. Wake it up (for example with mobile_press_button using HOME, or POWER when that is supported) and try again");
|
|
175
|
+
}
|
|
176
|
+
return elements.flatMap(element => flattenUIElement(element));
|
|
173
177
|
}
|
|
174
178
|
async setOrientation(orientation) {
|
|
175
179
|
this.runCommand(["device", "orientation", "set", orientation]);
|
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.8",
|
|
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.63",
|
|
36
36
|
"qs": "^6.15.0",
|
|
37
37
|
"zod": "^4.2.0",
|
|
38
38
|
"zod-to-json-schema": "3.25.0"
|