@mobilenext/mobile-mcp 1.0.2 → 1.0.4
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 +577 -0
- package/README.md +49 -18
- package/README.zh-CN.md +577 -0
- package/lib/coordinate-mapping.js +27 -0
- package/lib/format-elements.js +82 -0
- package/lib/index.js +65 -39
- package/lib/jpeg.js +41 -0
- package/lib/mobile-device.js +85 -6
- package/lib/mobilecli.js +18 -14
- package/lib/server.js +247 -91
- package/package.json +4 -3
- package/lib/image-utils.js +0 -155
package/lib/index.js
CHANGED
|
@@ -1,21 +1,31 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
"use strict";
|
|
3
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
4
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
5
|
-
};
|
|
6
3
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
-
const
|
|
4
|
+
const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
|
|
8
5
|
const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
6
|
+
const express_js_1 = require("@modelcontextprotocol/sdk/server/express.js");
|
|
9
7
|
const server_1 = require("./server");
|
|
10
8
|
const logger_1 = require("./logger");
|
|
11
|
-
const express_1 = __importDefault(require("express"));
|
|
12
9
|
const commander_1 = require("commander");
|
|
13
|
-
const
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
const startHttpServer = async (host, port) => {
|
|
11
|
+
// createMcpExpressApp applies express.json() and Host-header DNS rebinding
|
|
12
|
+
// protection automatically when binding to localhost / 127.0.0.1 / ::1.
|
|
13
|
+
const app = (0, express_js_1.createMcpExpressApp)({ host });
|
|
14
|
+
// Migration hint for clients still pointing at the removed SSE transport.
|
|
15
|
+
// Registered before auth so unauthenticated clients see the reason, not a 401.
|
|
16
|
+
app.all("/sse", (_req, res) => {
|
|
17
|
+
res.status(410).json({
|
|
18
|
+
jsonrpc: "2.0",
|
|
19
|
+
error: {
|
|
20
|
+
code: -32000,
|
|
21
|
+
message: "SSE transport removed. mobile-mcp now serves MCP Streamable HTTP at /mcp. See https://github.com/mobile-next/mobile-mcp#streamable-http-server-mode",
|
|
22
|
+
},
|
|
23
|
+
id: null,
|
|
24
|
+
});
|
|
25
|
+
});
|
|
16
26
|
const authToken = process.env.MOBILEMCP_AUTH;
|
|
17
27
|
if (!authToken) {
|
|
18
|
-
(0, logger_1.error)("WARNING: MOBILEMCP_AUTH is not set. The
|
|
28
|
+
(0, logger_1.error)("WARNING: MOBILEMCP_AUTH is not set. The HTTP server will accept unauthenticated connections. Set MOBILEMCP_AUTH to require Bearer token authentication.");
|
|
19
29
|
}
|
|
20
30
|
if (authToken) {
|
|
21
31
|
app.use((req, res, next) => {
|
|
@@ -26,37 +36,53 @@ const startSseServer = async (host, port) => {
|
|
|
26
36
|
next();
|
|
27
37
|
});
|
|
28
38
|
}
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
transport.handlePostMessage(req, res);
|
|
39
|
+
const handleMcpRequest = async (req, res) => {
|
|
40
|
+
// Stateless Streamable HTTP: fresh server + transport per request
|
|
41
|
+
// (Smithery / horizontal-host friendly; no session affinity).
|
|
42
|
+
const server = (0, server_1.createMcpServer)();
|
|
43
|
+
try {
|
|
44
|
+
const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
|
|
45
|
+
sessionIdGenerator: undefined,
|
|
46
|
+
});
|
|
47
|
+
// Register cleanup first: the response can close before handleRequest resolves.
|
|
48
|
+
res.on("close", () => {
|
|
49
|
+
transport.close();
|
|
50
|
+
server.close();
|
|
51
|
+
});
|
|
52
|
+
await server.connect(transport);
|
|
53
|
+
await transport.handleRequest(req, res, req.body);
|
|
45
54
|
}
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
+
}
|
|
51
67
|
}
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
68
|
+
};
|
|
69
|
+
app.post("/mcp", handleMcpRequest);
|
|
70
|
+
// Stateless mode has no long-lived sessions; GET (SSE stream) and DELETE
|
|
71
|
+
// (session teardown) are not applicable. Return 405 per SDK guidance.
|
|
72
|
+
const methodNotAllowed = (_req, res) => {
|
|
73
|
+
res.status(405).json({
|
|
74
|
+
jsonrpc: "2.0",
|
|
75
|
+
error: {
|
|
76
|
+
code: -32000,
|
|
77
|
+
message: "Method not allowed.",
|
|
78
|
+
},
|
|
79
|
+
id: null,
|
|
80
|
+
});
|
|
81
|
+
};
|
|
82
|
+
app.get("/mcp", methodNotAllowed);
|
|
83
|
+
app.delete("/mcp", methodNotAllowed);
|
|
58
84
|
app.listen(port, host, () => {
|
|
59
|
-
(0, logger_1.error)(`mobile-mcp ${(0, server_1.getAgentVersion)()}
|
|
85
|
+
(0, logger_1.error)(`mobile-mcp ${(0, server_1.getAgentVersion)()} streamable http server listening on http://${host}:${port}/mcp`);
|
|
60
86
|
});
|
|
61
87
|
};
|
|
62
88
|
const startStdioServer = async () => {
|
|
@@ -84,7 +110,7 @@ const startStdioServer = async () => {
|
|
|
84
110
|
const main = async () => {
|
|
85
111
|
commander_1.program
|
|
86
112
|
.version((0, server_1.getAgentVersion)())
|
|
87
|
-
.option("--listen <listen>", "Start
|
|
113
|
+
.option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
|
|
88
114
|
.option("--stdio", "Start stdio server (default)")
|
|
89
115
|
.parse(process.argv);
|
|
90
116
|
const options = commander_1.program.opts();
|
|
@@ -105,7 +131,7 @@ const main = async () => {
|
|
|
105
131
|
(0, logger_1.error)(`Invalid --listen value "${listen}". Expected [host:]port with port 1-65535.`);
|
|
106
132
|
process.exit(1);
|
|
107
133
|
}
|
|
108
|
-
await
|
|
134
|
+
await startHttpServer(host, port);
|
|
109
135
|
}
|
|
110
136
|
else {
|
|
111
137
|
await startStdioServer();
|
package/lib/jpeg.js
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.getJpegDimensions = void 0;
|
|
4
|
+
const robot_1 = require("./robot");
|
|
5
|
+
const JPEG_SOI = 0xffd8;
|
|
6
|
+
const MARKER_PREFIX = 0xff;
|
|
7
|
+
// length(2) precision(1) height(2) width(2) components(1)
|
|
8
|
+
const SOF_MIN_SEGMENT_LENGTH = 8;
|
|
9
|
+
// SOFn markers carry the frame header with the image dimensions. 0xc4 (DHT),
|
|
10
|
+
// 0xc8 (JPG) and 0xcc (DAC) sit in the same range but are not frame headers.
|
|
11
|
+
const isStartOfFrameMarker = (marker) => marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
|
|
12
|
+
const getJpegDimensions = (buffer) => {
|
|
13
|
+
if (buffer.length < 4 || buffer.readUInt16BE(0) !== JPEG_SOI) {
|
|
14
|
+
throw new robot_1.ActionableError("Invalid JPEG");
|
|
15
|
+
}
|
|
16
|
+
let offset = 2;
|
|
17
|
+
while (offset + 4 <= buffer.length) {
|
|
18
|
+
if (buffer[offset] !== MARKER_PREFIX) {
|
|
19
|
+
throw new robot_1.ActionableError("Invalid JPEG");
|
|
20
|
+
}
|
|
21
|
+
// a marker may be preceded by any number of 0xff fill bytes
|
|
22
|
+
while (buffer[offset + 1] === MARKER_PREFIX && offset + 4 < buffer.length) {
|
|
23
|
+
offset++;
|
|
24
|
+
}
|
|
25
|
+
const marker = buffer[offset + 1];
|
|
26
|
+
const segmentLength = buffer.readUInt16BE(offset + 2);
|
|
27
|
+
if (isStartOfFrameMarker(marker)) {
|
|
28
|
+
// segment: length(2) precision(1) height(2) width(2) ...
|
|
29
|
+
if (segmentLength < SOF_MIN_SEGMENT_LENGTH || offset + 9 > buffer.length) {
|
|
30
|
+
throw new robot_1.ActionableError("Invalid JPEG");
|
|
31
|
+
}
|
|
32
|
+
return {
|
|
33
|
+
height: buffer.readUInt16BE(offset + 5),
|
|
34
|
+
width: buffer.readUInt16BE(offset + 7),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
offset += 2 + segmentLength;
|
|
38
|
+
}
|
|
39
|
+
throw new robot_1.ActionableError("Invalid JPEG");
|
|
40
|
+
};
|
|
41
|
+
exports.getJpegDimensions = getJpegDimensions;
|
package/lib/mobile-device.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.MobileDevice = void 0;
|
|
4
4
|
const mobilecli_1 = require("./mobilecli");
|
|
5
|
+
const robot_1 = require("./robot");
|
|
5
6
|
const flattenUIElement = (element) => {
|
|
6
7
|
const screenElement = {
|
|
7
8
|
type: element.type,
|
|
@@ -11,7 +12,11 @@ const flattenUIElement = (element) => {
|
|
|
11
12
|
value: element.value,
|
|
12
13
|
identifier: element.identifier,
|
|
13
14
|
rect: element.rect,
|
|
15
|
+
ref: element.ref,
|
|
14
16
|
focused: element.focused,
|
|
17
|
+
selected: element.selected,
|
|
18
|
+
checked: element.checked,
|
|
19
|
+
enabled: element.enabled,
|
|
15
20
|
};
|
|
16
21
|
if (!element.children) {
|
|
17
22
|
return [screenElement];
|
|
@@ -29,8 +34,17 @@ class MobileDevice {
|
|
|
29
34
|
const fullArgs = [...args, "--device", this.deviceId];
|
|
30
35
|
return this.mobilecli.executeCommand(fullArgs);
|
|
31
36
|
}
|
|
37
|
+
runJsonCommand(args) {
|
|
38
|
+
const output = this.runCommand(args);
|
|
39
|
+
try {
|
|
40
|
+
return JSON.parse(output);
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
throw new robot_1.ActionableError(`Failed to parse JSON response from mobilecli ${args.join(" ")}`);
|
|
44
|
+
}
|
|
45
|
+
}
|
|
32
46
|
async getScreenSize() {
|
|
33
|
-
const response =
|
|
47
|
+
const response = this.runJsonCommand(["device", "info"]);
|
|
34
48
|
if (response.data.device.screenSize) {
|
|
35
49
|
return response.data.device.screenSize;
|
|
36
50
|
}
|
|
@@ -85,17 +99,34 @@ class MobileDevice {
|
|
|
85
99
|
}
|
|
86
100
|
this.runCommand(["io", "swipe", `${Math.round(x)},${Math.round(y)},${Math.round(endX)},${Math.round(endY)}`]);
|
|
87
101
|
}
|
|
88
|
-
async getScreenshot() {
|
|
89
|
-
const
|
|
102
|
+
async getScreenshot(options) {
|
|
103
|
+
const format = options?.format || "png";
|
|
104
|
+
const fullArgs = ["screenshot", "--device", this.deviceId, "--format", format, "--output", "-"];
|
|
105
|
+
if (format === "jpeg" && options?.quality !== undefined) {
|
|
106
|
+
fullArgs.push("--quality", `${options.quality}`);
|
|
107
|
+
}
|
|
108
|
+
if (options?.maxSize !== undefined) {
|
|
109
|
+
fullArgs.push("--max-size", `${options.maxSize}`);
|
|
110
|
+
}
|
|
111
|
+
if (options?.scale !== undefined && options.scale !== 1) {
|
|
112
|
+
fullArgs.push("--scale", `${options.scale}`);
|
|
113
|
+
}
|
|
90
114
|
return this.mobilecli.executeCommandBuffer(fullArgs);
|
|
91
115
|
}
|
|
92
116
|
async listApps() {
|
|
93
|
-
const response =
|
|
117
|
+
const response = this.runJsonCommand(["apps", "list"]);
|
|
94
118
|
return response.data.map(app => ({
|
|
95
119
|
appName: app.appName || app.packageName,
|
|
96
120
|
packageName: app.packageName,
|
|
97
121
|
}));
|
|
98
122
|
}
|
|
123
|
+
async getForegroundApp() {
|
|
124
|
+
const response = this.runJsonCommand(["apps", "foreground"]);
|
|
125
|
+
return {
|
|
126
|
+
appName: response.data.appName || response.data.packageName,
|
|
127
|
+
packageName: response.data.packageName,
|
|
128
|
+
};
|
|
129
|
+
}
|
|
99
130
|
async launchApp(packageName, locale) {
|
|
100
131
|
const args = ["apps", "launch", packageName];
|
|
101
132
|
if (locale) {
|
|
@@ -125,6 +156,9 @@ class MobileDevice {
|
|
|
125
156
|
// mobilecli rejects fractional coordinates ("x and y must be integers")
|
|
126
157
|
this.runCommand(["io", "tap", `${Math.round(x)},${Math.round(y)}`]);
|
|
127
158
|
}
|
|
159
|
+
async tapByRef(ref) {
|
|
160
|
+
this.runCommand(["io", "tap", ref]);
|
|
161
|
+
}
|
|
128
162
|
async doubleTap(x, y) {
|
|
129
163
|
// TODO: should move into mobilecli itself as "io doubletap"
|
|
130
164
|
await this.tap(x, y);
|
|
@@ -134,15 +168,60 @@ class MobileDevice {
|
|
|
134
168
|
this.runCommand(["io", "longpress", `${Math.round(x)},${Math.round(y)}`, "--duration", `${duration}`]);
|
|
135
169
|
}
|
|
136
170
|
async getElementsOnScreen() {
|
|
137
|
-
const response =
|
|
171
|
+
const response = this.runJsonCommand(["dump", "ui"]);
|
|
138
172
|
return response.data.elements.flatMap(element => flattenUIElement(element));
|
|
139
173
|
}
|
|
140
174
|
async setOrientation(orientation) {
|
|
141
175
|
this.runCommand(["device", "orientation", "set", orientation]);
|
|
142
176
|
}
|
|
143
177
|
async getOrientation() {
|
|
144
|
-
const response =
|
|
178
|
+
const response = this.runJsonCommand(["device", "orientation", "get"]);
|
|
145
179
|
return response.data.orientation;
|
|
146
180
|
}
|
|
181
|
+
async setLocation(latitude, longitude) {
|
|
182
|
+
this.runCommand(["device", "location", "set", `${latitude},${longitude}`]);
|
|
183
|
+
}
|
|
184
|
+
async clearLocation() {
|
|
185
|
+
this.runCommand(["device", "location", "clear"]);
|
|
186
|
+
}
|
|
187
|
+
async getClipboard() {
|
|
188
|
+
const response = this.runJsonCommand(["io", "clipboard", "get"]);
|
|
189
|
+
return response.data.text;
|
|
190
|
+
}
|
|
191
|
+
async setClipboard(text) {
|
|
192
|
+
this.runCommand(["io", "clipboard", "set", text]);
|
|
193
|
+
}
|
|
194
|
+
getLogs(limit, filters, timeoutMs) {
|
|
195
|
+
const args = ["device", "logs", "--limit", String(limit), ...filters.flatMap(filter => ["--filter", filter]), "--device", this.deviceId];
|
|
196
|
+
const child = this.mobilecli.spawnCommand(args, true);
|
|
197
|
+
return new Promise((resolve, reject) => {
|
|
198
|
+
const stdout = [];
|
|
199
|
+
const stderr = [];
|
|
200
|
+
let silenceTimer;
|
|
201
|
+
// kill the stream once no log entry arrived for timeoutMs, then return what was captured
|
|
202
|
+
const restartSilenceTimer = () => {
|
|
203
|
+
clearTimeout(silenceTimer);
|
|
204
|
+
silenceTimer = setTimeout(() => child.kill(), timeoutMs);
|
|
205
|
+
};
|
|
206
|
+
child.stdout?.on("data", (chunk) => {
|
|
207
|
+
stdout.push(chunk);
|
|
208
|
+
restartSilenceTimer();
|
|
209
|
+
});
|
|
210
|
+
child.stderr?.on("data", (chunk) => stderr.push(chunk));
|
|
211
|
+
child.on("error", err => {
|
|
212
|
+
clearTimeout(silenceTimer);
|
|
213
|
+
reject(err);
|
|
214
|
+
});
|
|
215
|
+
child.on("close", code => {
|
|
216
|
+
clearTimeout(silenceTimer);
|
|
217
|
+
if (code !== 0 && !child.killed) {
|
|
218
|
+
reject(new Error(`mobilecli device logs failed with code ${code}: ${Buffer.concat(stderr).toString().trim()}`));
|
|
219
|
+
return;
|
|
220
|
+
}
|
|
221
|
+
resolve(Buffer.concat(stdout).toString().trim());
|
|
222
|
+
});
|
|
223
|
+
restartSilenceTimer();
|
|
224
|
+
});
|
|
225
|
+
}
|
|
147
226
|
}
|
|
148
227
|
exports.MobileDevice = MobileDevice;
|
package/lib/mobilecli.js
CHANGED
|
@@ -24,10 +24,10 @@ class Mobilecli {
|
|
|
24
24
|
}
|
|
25
25
|
return (0, node_child_process_1.execFileSync)(path, args, options).toString().trim();
|
|
26
26
|
}
|
|
27
|
-
spawnCommand(args) {
|
|
27
|
+
spawnCommand(args, captureOutput = false) {
|
|
28
28
|
const binaryPath = this.getPath();
|
|
29
29
|
return (0, node_child_process_1.spawn)(binaryPath, args, {
|
|
30
|
-
stdio: ["ignore", "ignore", "ignore"],
|
|
30
|
+
stdio: ["ignore", captureOutput ? "pipe" : "ignore", captureOutput ? "pipe" : "ignore"],
|
|
31
31
|
});
|
|
32
32
|
}
|
|
33
33
|
executeCommandBuffer(args) {
|
|
@@ -47,26 +47,30 @@ class Mobilecli {
|
|
|
47
47
|
const normalizedPlatform = platform === "win32" ? "windows" : platform;
|
|
48
48
|
const normalizedArch = arch === "arm64" ? "arm64" : "amd64";
|
|
49
49
|
const ext = platform === "win32" ? ".exe" : "";
|
|
50
|
-
const
|
|
50
|
+
const scopedPackage = `mobilecli-${normalizedPlatform}-${normalizedArch}`;
|
|
51
|
+
const binaryName = `${scopedPackage}${ext}`;
|
|
52
|
+
const nodeModulesRoots = [];
|
|
51
53
|
// Check if mobile-mcp is installed as a package
|
|
52
54
|
const currentPath = __filename;
|
|
53
55
|
const pathParts = currentPath.split(node_path_1.sep);
|
|
54
56
|
const lastNodeModulesIndex = pathParts.lastIndexOf("node_modules");
|
|
55
57
|
if (lastNodeModulesIndex !== -1) {
|
|
56
58
|
// We're inside node_modules, go to the last node_modules in the path
|
|
57
|
-
|
|
58
|
-
const lastNodeModulesPath = nodeModulesParts.join(node_path_1.sep);
|
|
59
|
-
const mobilecliPath = (0, node_path_1.join)(lastNodeModulesPath, "mobilecli", "bin", binaryName);
|
|
60
|
-
if ((0, node_fs_1.existsSync)(mobilecliPath)) {
|
|
61
|
-
return mobilecliPath;
|
|
62
|
-
}
|
|
59
|
+
nodeModulesRoots.push(pathParts.slice(0, lastNodeModulesIndex + 1).join(node_path_1.sep));
|
|
63
60
|
}
|
|
64
61
|
// Not in node_modules, look one directory up from current script
|
|
65
|
-
|
|
66
|
-
const
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
62
|
+
nodeModulesRoots.push((0, node_path_1.join)((0, node_path_1.dirname)((0, node_path_1.dirname)(__filename)), "node_modules"));
|
|
63
|
+
for (const root of nodeModulesRoots) {
|
|
64
|
+
// mobilecli <= 1.0.6 shipped the binary in its own bin directory
|
|
65
|
+
const legacyPath = (0, node_path_1.join)(root, "mobilecli", "bin", binaryName);
|
|
66
|
+
if ((0, node_fs_1.existsSync)(legacyPath)) {
|
|
67
|
+
return legacyPath;
|
|
68
|
+
}
|
|
69
|
+
// mobilecli >= 1.0.7 ships per-platform binaries in scoped packages
|
|
70
|
+
const scopedPath = (0, node_path_1.join)(root, "@mobilenext", scopedPackage, binaryName);
|
|
71
|
+
if ((0, node_fs_1.existsSync)(scopedPath)) {
|
|
72
|
+
return scopedPath;
|
|
73
|
+
}
|
|
70
74
|
}
|
|
71
75
|
throw new Error(`Could not find mobilecli binary for platform: ${platform}`);
|
|
72
76
|
}
|