@zhihand/mcp 0.17.1 → 0.18.0

package/dist/core/command.d.ts

@@ -15,6 +15,10 @@ export interface ControlParams {
     startYRatio?: number;
     endXRatio?: number;
     endYRatio?: number;
+    appPackage?: string;
+    bundleId?: string;
+    urlScheme?: string;
+    appName?: string;
 }
 export interface QueuedControlCommand {
     type: string;

package/dist/core/command.js

@@ -9,20 +9,23 @@ export function createControlCommand(params) {
             return { type: "receive_click", payload: { x: params.xRatio, y: params.yRatio } };
         case "doubleclick":
             return { type: "receive_doubleclick", payload: { x: params.xRatio, y: params.yRatio } };
+        case "longclick":
+            return { type: "receive_longclick", payload: { x: params.xRatio, y: params.yRatio, time: params.durationMs ?? 800 } };
         case "rightclick":
             return { type: "receive_rightclick", payload: { x: params.xRatio, y: params.yRatio } };
         case "middleclick":
             return { type: "receive_middleclick", payload: { x: params.xRatio, y: params.yRatio } };
         case "type":
-            return { type: "receive_type", payload: { text: params.text } };
+            return { type: "receive_input", payload: { input: params.text, mode: "auto", submit: false } };
         case "swipe":
             return {
-                type: "receive_swipe",
+                type: "receive_slide",
                 payload: {
-                    startX: params.startXRatio,
-                    startY: params.startYRatio,
-                    endX: params.endXRatio,
-                    endY: params.endYRatio,
+                    x1: params.startXRatio,
+                    y1: params.startYRatio,
+                    x2: params.endXRatio,
+                    y2: params.endYRatio,
+                    time: params.durationMs ?? 300,
                 },
             };
         case "scroll":
@@ -36,12 +39,30 @@ export function createControlCommand(params) {
                 },
             };
         case "keycombo":
-            return { type: "receive_keycombo", payload: { keys: params.keys } };
+            return { type: "receive_key_combo", payload: { keys: params.keys } };
+        case "back":
+            return { type: "receive_back", payload: {} };
+        case "home":
+            return { type: "receive_home", payload: {} };
+        case "enter":
+            return { type: "receive_enter", payload: {} };
         case "clipboard":
             return {
                 type: "receive_clipboard",
                 payload: { action: params.clipboardAction, text: params.text },
             };
+        case "open_app": {
+            const appPayload = {};
+            if (params.appPackage)
+                appPayload.app_package = params.appPackage;
+            if (params.bundleId)
+                appPayload.bundle_id = params.bundleId;
+            if (params.urlScheme)
+                appPayload.url_scheme = params.urlScheme;
+            if (params.appName)
+                appPayload.app_name = params.appName;
+            return { type: "receive_app", payload: appPayload };
+        }
         case "screenshot":
             return { type: "receive_screenshot", payload: {} };
         default:

package/dist/daemon/dispatcher.js

@@ -329,13 +329,35 @@ export function killActiveChild() {
 function wrapPrompt(userPrompt) {
     return `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
 
-You have the following MCP tools to interact with the phone:
-- zhihand_screenshot: Take a screenshot of the phone screen. Use this when the user asks to see, check, or look at their screen.
-- zhihand_control: Control the phone — click, type, swipe, scroll, key combos, clipboard, wait. Requires "action" parameter. For clicks, provide xRatio/yRatio (0-1 normalized coordinates).
-- zhihand_pair: Pair a new device (rarely needed).
+## Available MCP Tools
 
-When the user asks you to see their screen, look at something, or check what's on the phone, ALWAYS call zhihand_screenshot first.
-When the user asks you to tap, click, type, swipe, or interact with the phone, use zhihand_control.
+### zhihand_screenshot
+Take a screenshot of the phone screen. Use this when the user asks to see, check, or look at their screen.
+
+### zhihand_control
+Control the phone. Requires "action" parameter. All coordinates use normalized ratios [0,1].
+
+**Supported actions:**
+- click: Tap at position. Params: xRatio, yRatio
+- doubleclick: Double tap. Params: xRatio, yRatio
+- longclick: Long press. Params: xRatio, yRatio, durationMs (default 800)
+- type: Type text into focused field. Params: text
+- swipe: Swipe gesture. Params: startXRatio, startYRatio, endXRatio, endYRatio, durationMs (default 300)
+- scroll: Scroll at position. Params: xRatio, yRatio, direction (up/down/left/right), amount (default 3)
+- keycombo: Keyboard shortcut. Params: keys (e.g. "ctrl+c", "alt+tab")
+- back: Press Back button (no params)
+- home: Press Home button (no params)
+- enter: Press Enter key (no params)
+- open_app: Open an app. Params: appPackage (Android, e.g. "com.tencent.mm"), bundleId (iOS), urlScheme (e.g. "weixin://")
+- clipboard: Read/write clipboard. Params: clipboardAction ("get"/"set"), text
+- screenshot: Capture screen via control (same as zhihand_screenshot)
+- wait: Wait before next action. Params: durationMs (default 1000)
+
+## Rules
+- When the user asks to see their screen, ALWAYS call zhihand_screenshot first.
+- When the user asks to open an app (e.g. WeChat, Settings), use open_app action.
+- When the user asks to go back/home, use back/home actions.
+- For all tap/click operations, use xRatio and yRatio (0-1 normalized coordinates based on the screenshot).
 
 User message:
 ${userPrompt}`;
@@ -413,48 +435,16 @@ function dispatchClaude(prompt, startTime, model) {
     activeChild = child;
     return collectChildOutput(child, startTime);
 }
-// ── Codex JSONL Output Parser ──────────────────────────────
-/** Parse codex JSONL output and extract agent message text. */
-function parseCodexJsonl(raw) {
-    const lines = raw.split("\n").filter(Boolean);
-    const texts = [];
-    let hasError = false;
-    for (const line of lines) {
-        try {
-            const event = JSON.parse(line);
-            const type = String(event.type ?? "");
-            // Extract text from completed agent messages
-            if (type === "item.completed") {
-                const item = event.item;
-                if (item && typeof item.text === "string" && item.text.trim()) {
-                    texts.push(item.text.trim());
-                }
-            }
-            // Capture errors
-            if (type === "error") {
-                const msg = String(event.message ?? "");
-                if (msg)
-                    texts.push(`Error: ${msg}`);
-                hasError = true;
-            }
-            if (type === "turn.failed") {
-                hasError = true;
-            }
-        }
-        catch {
-            // Not valid JSON — skip (truncated line or stderr mixed in)
-        }
-    }
-    if (texts.length > 0) {
-        return { text: texts.join("\n\n"), success: !hasError };
-    }
-    return { text: raw.trim(), success: false };
-}
+/**
+ * Collect codex JSONL output with streaming line parsing.
+ * Processes each JSONL line as it arrives so we extract agent text
+ * without buffering large binary payloads (e.g. base64 screenshots).
+ */
 function collectCodexOutput(child, startTime) {
     return new Promise((resolve) => {
-        const chunks = [];
-        let totalBytes = 0;
-        let truncated = false;
+        const texts = [];
+        let hasError = false;
+        let lineBuffer = "";
         let settled = false;
         function settle(result) {
             if (settled)
@@ -462,36 +452,59 @@ function collectCodexOutput(child, startTime) {
             settled = true;
             resolve(result);
         }
-        const timer = setTimeout(() => { closeChild(child); }, CLI_TIMEOUT);
-        const collectOutput = (data) => {
-            if (truncated)
+        function processLine(line) {
+            if (!line.trim())
                 return;
-            totalBytes += data.length;
-            if (totalBytes > MAX_OUTPUT_BYTES) {
-                truncated = true;
-                chunks.push(data.subarray(0, MAX_OUTPUT_BYTES - (totalBytes - data.length)));
+            try {
+                const event = JSON.parse(line);
+                const type = String(event.type ?? "");
+                if (type === "item.completed") {
+                    const item = event.item;
+                    if (item && typeof item.text === "string" && item.text.trim()) {
+                        texts.push(item.text.trim());
+                    }
+                }
+                if (type === "error") {
+                    const msg = String(event.message ?? "");
+                    if (msg)
+                        texts.push(`Error: ${msg}`);
+                    hasError = true;
+                }
+                if (type === "turn.failed") {
+                    hasError = true;
+                }
             }
-            else {
-                chunks.push(data);
+            catch {
+                // Not valid JSON — skip
+            }
+        }
+        const timer = setTimeout(() => { closeChild(child); }, CLI_TIMEOUT);
+        const onData = (data) => {
+            lineBuffer += data.toString("utf8");
+            const lines = lineBuffer.split("\n");
+            // Keep the last (possibly incomplete) line in the buffer
+            lineBuffer = lines.pop() ?? "";
+            for (const line of lines) {
+                processLine(line);
             }
         };
-        child.stdout?.on("data", collectOutput);
-        child.stderr?.on("data", collectOutput);
+        child.stdout?.on("data", onData);
+        // stderr is not JSONL, just discard
+        child.stderr?.resume();
         child.on("close", (code) => {
             clearTimeout(timer);
             activeChild = null;
+            // Process any remaining data in the buffer
+            if (lineBuffer.trim())
+                processLine(lineBuffer);
             const durationMs = Date.now() - startTime;
-            const raw = Buffer.concat(chunks).toString("utf8").trim();
-            const parsed = parseCodexJsonl(raw);
-            let text = parsed.text;
-            if (truncated)
-                text += "\n\n[Output truncated at 100KB]";
+            let text = texts.join("\n\n");
             if (!text) {
                 text = code === 0
                     ? "Task completed (no output)."
                     : `CLI process exited with code ${code}.`;
             }
-            settle({ text, success: parsed.success && code === 0, durationMs });
+            settle({ text, success: !hasError && code === 0, durationMs });
         });
         child.on("error", (err) => {
             clearTimeout(timer);

package/dist/index.js

@@ -5,7 +5,7 @@ import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js"
 import { executeControl } from "./tools/control.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-const PACKAGE_VERSION = "0.17.1";
+const PACKAGE_VERSION = "0.18.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/dist/tools/schemas.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const controlSchema: {
-    action: z.ZodEnum<["click", "doubleclick", "rightclick", "middleclick", "type", "swipe", "scroll", "keycombo", "clipboard", "wait", "screenshot"]>;
+    action: z.ZodEnum<["click", "doubleclick", "longclick", "rightclick", "middleclick", "type", "swipe", "scroll", "keycombo", "back", "home", "enter", "clipboard", "open_app", "wait", "screenshot"]>;
     xRatio: z.ZodOptional<z.ZodNumber>;
     yRatio: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodString>;
@@ -13,6 +13,10 @@ export declare const controlSchema: {
     startYRatio: z.ZodOptional<z.ZodNumber>;
     endXRatio: z.ZodOptional<z.ZodNumber>;
     endYRatio: z.ZodOptional<z.ZodNumber>;
+    appPackage: z.ZodOptional<z.ZodString>;
+    bundleId: z.ZodOptional<z.ZodString>;
+    urlScheme: z.ZodOptional<z.ZodString>;
+    appName: z.ZodOptional<z.ZodString>;
 };
 export declare const screenshotSchema: {};
 export declare const pairSchema: {

package/dist/tools/schemas.js

@@ -1,9 +1,10 @@
 import { z } from "zod";
 export const controlSchema = {
     action: z.enum([
-        "click", "doubleclick", "rightclick", "middleclick",
+        "click", "doubleclick", "longclick", "rightclick", "middleclick",
         "type", "swipe", "scroll", "keycombo",
-        "clipboard",
+        "back", "home", "enter",
+        "clipboard", "open_app",
         "wait", "screenshot",
     ]),
     xRatio: z.number().min(0).max(1).optional().describe("Normalized horizontal position [0,1]"),
@@ -13,11 +14,15 @@ export const controlSchema = {
     amount: z.number().int().positive().default(3).optional().describe("Scroll steps (default 3)"),
     keys: z.string().optional().describe("Key combo string, e.g. 'ctrl+c', 'alt+tab'"),
     clipboardAction: z.enum(["get", "set"]).optional().describe("Clipboard action"),
-    durationMs: z.number().int().positive().max(10000).default(1000).optional().describe("Duration in ms for wait (default 1000, max 10000)"),
+    durationMs: z.number().int().positive().max(10000).default(1000).optional().describe("Duration in ms for wait, longclick, or swipe (default 1000, max 10000)"),
     startXRatio: z.number().min(0).max(1).optional().describe("Swipe start X [0,1]"),
     startYRatio: z.number().min(0).max(1).optional().describe("Swipe start Y [0,1]"),
     endXRatio: z.number().min(0).max(1).optional().describe("Swipe end X [0,1]"),
     endYRatio: z.number().min(0).max(1).optional().describe("Swipe end Y [0,1]"),
+    appPackage: z.string().optional().describe("Android package name, e.g. 'com.tencent.mm'"),
+    bundleId: z.string().optional().describe("iOS bundle ID, e.g. 'com.tencent.xin'"),
+    urlScheme: z.string().optional().describe("URL scheme, e.g. 'weixin://'"),
+    appName: z.string().optional().describe("Human-readable app name (for logging)"),
 };
 export const screenshotSchema = {};
 export const pairSchema = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",