@zhihand/mcp 0.23.0 → 0.24.1

package/README.md

@@ -2,7 +2,7 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.23.0`
+Version: `0.24.1`
 
 ## What is this?
 
@@ -96,6 +96,7 @@ zhihand start -d           Start daemon in background (logs to ~/.zhihand/daemon
 zhihand stop               Stop the running daemon
 zhihand status             Show daemon status, pairing info, device, backend, and model
 
+zhihand test               Test device connectivity (screenshot, click, swipe, home, back)
 zhihand pair               Pair with a phone (QR code in terminal)
 zhihand detect             List detected CLI tools and their login status
 zhihand serve              Start MCP Server (stdio mode, backward compatible)

package/bin/zhihand

@@ -51,6 +51,7 @@ Usage:
   zhihand pair               Pair with a phone device
   zhihand detect             Detect available CLI tools
 
+  zhihand test               Test device connectivity (sends click + type commands)
   zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
@@ -280,6 +281,87 @@ switch (command) {
     break;
   }
 
+  case "test": {
+    const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.js");
+    const { createControlCommand, enqueueCommand } = await import("../dist/core/command.js");
+    const { waitForCommandAck } = await import("../dist/core/sse.js");
+    const { fetchScreenshotBinary } = await import("../dist/core/screenshot.js");
+
+    let testConfig;
+    try {
+      testConfig = resolveTestConfig(values.device ?? process.env.ZHIHAND_DEVICE);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      console.error("Run 'zhihand setup' to pair a device first.");
+      process.exit(1);
+    }
+
+    console.log("🧪 ZhiHand Device Test");
+    console.log(`   Device: ${testConfig.credentialId}`);
+    console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
+
+    const steps = [
+      { label: "1. Screenshot", type: "screenshot" },
+      { label: "2. Click center", type: "hid", params: { action: "click", xRatio: 0.5, yRatio: 0.5 } },
+      { label: "3. Swipe up", type: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 } },
+      { label: "4. Swipe down", type: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 } },
+      { label: "5. Press Home", type: "hid", params: { action: "home" } },
+      { label: "6. Press Back", type: "hid", params: { action: "back" } },
+      { label: "7. Screenshot", type: "screenshot" },
+    ];
+
+    let passed = 0;
+    let failed = 0;
+
+    for (const step of steps) {
+      process.stdout.write(`   ${step.label}... `);
+      const t0 = Date.now();
+      try {
+        if (step.type === "screenshot") {
+          // Screenshot: send receive_screenshot command, then fetch binary
+          const cmd = createControlCommand({ action: "screenshot" });
+          const queued = await enqueueCommand(testConfig, cmd);
+          const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+          if (ack.acked) {
+            const buf = await fetchScreenshotBinary(testConfig);
+            const ms = Date.now() - t0;
+            console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${ms}ms)`);
+            passed++;
+          } else {
+            console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+            failed++;
+          }
+        } else {
+          const cmd = createControlCommand(step.params);
+          const queued = await enqueueCommand(testConfig, cmd);
+          const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+          const ms = Date.now() - t0;
+          if (ack.acked) {
+            console.log(`✅ (${ms}ms)`);
+            passed++;
+          } else {
+            console.log(`⏱️  Timeout (${ms}ms)`);
+            failed++;
+          }
+        }
+      } catch (err) {
+        const ms = Date.now() - t0;
+        console.log(`❌ ${err.message} (${ms}ms)`);
+        failed++;
+      }
+      // Pause between commands: let phone process + user can observe
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+
+    console.log(`\n   Result: ${passed}/${steps.length} passed`);
+    if (failed === 0) {
+      console.log("   ✅ Device is responding to all commands!");
+    } else {
+      console.log("   ⚠️  Some commands failed. Check phone connectivity.");
+    }
+    process.exit(failed > 0 ? 1 : 0);
+  }
+
   default:
     console.error(`Unknown command: ${command}. Run 'zhihand --help' for usage.`);
     process.exit(1);

package/dist/daemon/dispatcher.js

@@ -7,6 +7,8 @@ import { DEFAULT_MODELS } from "../core/config.js";
 import { resolveGemini, resolveClaude, resolveCodex } from "../core/resolve-path.js";
 const CLI_TIMEOUT = 300_000; // 300s (5min) per prompt — MCP tool chains need multiple turns
 const SIGKILL_DELAY = 2_000; // 2s after SIGTERM
+const MCP_PORT = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+const MCP_URL = `http://127.0.0.1:${MCP_PORT}/mcp`;
 const MAX_OUTPUT_BYTES = 100 * 1024; // 100KB (for one-shot backends)
 const MAX_HISTORY_TURNS = 20; // keep last N exchanges in conversation history
 // Gemini session file polling
@@ -540,11 +542,14 @@ async function dispatchClaudeWithHistory(prompt, startTime, log, model) {
     log(`[claude] One-shot dispatch (history: ${conversationHistory.length} turns)`);
     // Pass prompt via stdin (-p -) to avoid ARG_MAX limit with long conversation history
     // --permission-mode bypassPermissions: auto-approve all tool calls (like gemini's --approval-mode yolo)
+    // --mcp-config: explicitly pass MCP server URL so Claude finds it regardless of cwd
+    const mcpConfig = JSON.stringify({ mcpServers: { zhihand: { type: "http", url: MCP_URL } } });
     const child = spawn(claudePath, [
         "-p", "-",
         "--model", model,
         "--output-format", "json",
         "--permission-mode", "bypassPermissions",
+        "--mcp-config", mcpConfig,
     ], {
         env: process.env,
         stdio: ["pipe", "pipe", "pipe"],
@@ -553,11 +558,29 @@ async function dispatchClaudeWithHistory(prompt, startTime, log, model) {
     // Write prompt to stdin, then close to signal EOF
     child.stdin?.write(fullPrompt);
     child.stdin?.end();
-    const result = await collectChildOutput(child, startTime);
+    const raw = await collectChildOutput(child, startTime);
+    // Claude --output-format json wraps the result in a JSON envelope — extract the actual text
+    const result = extractClaudeResult(raw);
     recordTurn("user", prompt);
     recordTurn("assistant", result.text);
     return result;
 }
+/** Parse Claude JSON output and extract the result text. */
+function extractClaudeResult(raw) {
+    try {
+        const parsed = JSON.parse(raw.text);
+        if (!parsed || typeof parsed !== "object")
+            return raw;
+        const resultText = typeof parsed.result === "string" ? parsed.result : raw.text;
+        const isError = parsed.is_error === true || parsed.subtype === "error";
+        // Preserve process exit failure: only succeed if both JSON and process agree
+        return { text: resultText, success: raw.success && !isError, durationMs: raw.durationMs };
+    }
+    catch {
+        // Not JSON — return as-is
+        return raw;
+    }
+}
 // ── Codex JSONL Output Collector ──────────────────────────────
 function collectCodexOutput(child, startTime) {
     return new Promise((resolve) => {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const PACKAGE_VERSION = "0.23.0";
+export declare const PACKAGE_VERSION = "0.24.1";
 export declare function createServer(deviceName?: string): McpServer;
 export declare function startStdioServer(deviceName?: string): Promise<void>;

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";
-export const PACKAGE_VERSION = "0.23.0";
+export const PACKAGE_VERSION = "0.24.1";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/package.json

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