@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 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 CLI を使って Mobile MCP サーバーを追加します:
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
- Use the Claude Code CLI to add the Mobile MCP server:
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
- 使用 Claude Code CLI 添加 Mobile MCP 服务器:
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("./server");
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
- 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 node_1.NodeStreamableHTTPServerTransport({
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);
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, server_1.getAgentVersion)()} streamable http server listening on http://${host}:${port}/mcp`);
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
- const transport = new stdio_1.StdioServerTransport();
91
- const server = (0, server_1.createMcpServer)();
92
- await server.connect(transport);
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, server_1.getAgentVersion)()} (mcp sdk ${(0, server_1.getSdkVersion)()}) server running on stdio`);
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, server_1.getAgentVersion)())
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);
@@ -169,7 +169,11 @@ class MobileDevice {
169
169
  }
170
170
  async getElementsOnScreen() {
171
171
  const response = this.runJsonCommand(["dump", "ui"]);
172
- return response.data.elements.flatMap(element => flattenUIElement(element));
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.6",
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.62",
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"