@zhihand/mcp 0.26.0 → 0.26.3

package/bin/zhihand

@@ -291,6 +291,7 @@ switch (command) {
     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");
+    const { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded, formatDeviceStatus } = await import("../dist/core/device.js");
 
     let testConfig;
     try {
@@ -305,68 +306,176 @@ switch (command) {
     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. Open WeChat", type: "hid", params: { action: "open_app", appPackage: "com.tencent.mm" } },
-      { label: "7. Press Back", type: "hid", params: { action: "back" } },
-      { label: "8. Screenshot", type: "screenshot" },
-    ];
-
     let passed = 0;
     let failed = 0;
+    let totalSteps = 0;
 
-    for (const step of steps) {
-      process.stdout.write(`   ${step.label}... `);
+    // ── Helper: run a single HID step ──
+    async function runHidStep(label, params) {
+      totalSteps++;
+      process.stdout.write(`   ${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++;
-          }
+        const cmd = createControlCommand(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) {
+          const ackStatus = ack.command?.ack_status ?? "ok";
+          const detail = ackStatus !== "ok" ? ` [${ackStatus}]` : "";
+          const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
+          console.log(`✅ (${ms}ms)${detail}${resultInfo}`);
+          passed++;
+          return ack;
         } else {
-          const cmd = createControlCommand(step.params);
-          const queued = await enqueueCommand(testConfig, cmd);
-          const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+          console.log(`⏱️  Timeout (${ms}ms)`);
+          failed++;
+          return null;
+        }
+      } catch (err) {
+        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+        failed++;
+        return null;
+      }
+    }
+
+    // ── Helper: run a screenshot step ──
+    async function runScreenshotStep(label) {
+      totalSteps++;
+      process.stdout.write(`   ${label}... `);
+      const t0 = Date.now();
+      try {
+        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;
-          if (ack.acked) {
-            const ackStatus = ack.command?.ack_status ?? "ok";
-            const detail = ackStatus !== "ok" ? ` [${ackStatus}]` : "";
-            const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
-            console.log(`✅ (${ms}ms)${detail}${resultInfo}`);
-            passed++;
-          } else {
-            console.log(`⏱️  Timeout (${ms}ms)`);
-            failed++;
-          }
+          console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${ms}ms)`);
+          passed++;
+        } else {
+          console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+          failed++;
         }
       } catch (err) {
+        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+        failed++;
+      }
+    }
+
+    const pause = () => new Promise((r) => setTimeout(r, 1500));
+
+    // ── Phase 1: Device Profile ──────────────────────────────
+    console.log("   ── Phase 1: Device Info ──");
+    totalSteps++;
+    process.stdout.write("   1. Fetch device profile... ");
+    {
+      const t0 = Date.now();
+      try {
+        await fetchDeviceProfile(testConfig);
         const ms = Date.now() - t0;
-        console.log(`❌ ${err.message} (${ms}ms)`);
+        if (isDeviceProfileLoaded()) {
+          const s = getStaticContext();
+          console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
+          passed++;
+        } else {
+          console.log(`⚠️  Loaded but empty (${ms}ms)`);
+          failed++;
+        }
+      } catch (err) {
+        console.log(`❌ ${err.message} (${Date.now() - t0}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`);
+    totalSteps++;
+    process.stdout.write("   2. Device status fields... ");
+    {
+      try {
+        const status = formatDeviceStatus();
+        const ignoredDefaults = new Set(["unknown", "0x0", "-1% (unknown)", "0"]);
+        const fields = Object.keys(status).filter((k) => {
+          const v = status[k];
+          if (v === null || v === undefined) return false;
+          if (ignoredDefaults.has(String(v))) return false;
+          return true;
+        });
+        console.log(`✅ ${fields.length} fields (${fields.join(", ")})`);
+        passed++;
+      } catch (err) {
+        console.log(`❌ ${err.message}`);
+        failed++;
+      }
+    }
+
+    await pause();
+
+    // ── Phase 2: Screenshot + Basic HID ──────────────────────
+    console.log("   ── Phase 2: Screenshot + HID ──");
+    await runScreenshotStep("3. Screenshot");
+    await pause();
+    await runHidStep("4. Click center", { action: "click", xRatio: 0.5, yRatio: 0.5 });
+    await pause();
+    await runHidStep("5. Swipe up", { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 });
+    await pause();
+    await runHidStep("6. Swipe down", { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 });
+    await pause();
+    await runHidStep("7. Scroll down", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 });
+    await pause();
+    await runHidStep("8. Scroll up", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 });
+    await pause();
+
+    // ── Phase 3: App + Navigation ────────────────────────────
+    console.log("   ── Phase 3: App + Navigation ──");
+    await runHidStep("9. Press Home", { action: "home" });
+    await pause();
+    {
+      const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "android";
+      const openParams = platform === "ios"
+        ? { action: "open_app", bundleId: "com.tencent.xin" }
+        : { action: "open_app", appPackage: "com.tencent.mm" };
+      await runHidStep(`10. Open WeChat (${platform})`, openParams);
+    }
+    await pause();
+    await runHidStep("11. Press Back", { action: "back" });
+    await pause();
+
+    // ── Phase 4: Clipboard Roundtrip ─────────────────────────
+    console.log("   ── Phase 4: Clipboard Roundtrip ──");
+    const clipboardTestText = `zhihand_test_${Date.now()}`;
+
+    const setAck = await runHidStep("12. Clipboard set", { action: "clipboard", clipboardAction: "set", text: clipboardTestText });
+    await pause();
+
+    const getAck = await runHidStep("13. Clipboard get", { action: "clipboard", clipboardAction: "get" });
+    await pause();
+
+    // Verify roundtrip
+    totalSteps++;
+    process.stdout.write("   14. Clipboard roundtrip verify... ");
+    if (setAck && getAck) {
+      const returned = getAck.command?.ack_result?.text ?? getAck.command?.ack_result?.clipboard ?? null;
+      if (returned === clipboardTestText) {
+        console.log(`✅ Match: "${clipboardTestText}"`);
+        passed++;
+      } else if (returned) {
+        console.log(`⚠️  Mismatch: sent "${clipboardTestText}", got "${returned}"`);
+        failed++;
+      } else {
+        console.log(`⚠️  No text in ack_result (keys: ${JSON.stringify(Object.keys(getAck.command?.ack_result ?? {}))})`);
+        failed++;
+      }
+    } else {
+      console.log(`⏭️  Skipped (clipboard set/get failed)`);
+      failed++;
+    }
+
+    // ── Summary ──────────────────────────────────────────────
+    console.log(`\n   Result: ${passed}/${totalSteps} passed`);
     if (failed === 0) {
-      console.log("   ✅ Device is responding to all commands!");
+      console.log("   ✅ All tests passed! Device is fully responsive.");
     } else {
-      console.log("   ⚠️  Some commands failed. Check phone connectivity.");
+      console.log(`   ⚠️  ${failed} test(s) failed. Check phone connectivity.`);
     }
     process.exit(failed > 0 ? 1 : 0);
   }

package/dist/core/command.d.ts

@@ -18,7 +18,6 @@ export interface ControlParams {
     appPackage?: string;
     bundleId?: string;
     urlScheme?: string;
-    appName?: string;
 }
 export interface QueuedControlCommand {
     type: string;

package/dist/core/command.js

@@ -1,3 +1,4 @@
+import { getStaticContext, isDeviceProfileLoaded } from "./device.js";
 import { dbg } from "../daemon/logger.js";
 let messageCounter = 0;
 function nextMessageId() {
@@ -54,17 +55,34 @@ export function createControlCommand(params) {
             };
         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;
+            const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
+            // Only send platform-appropriate fields — Android strict JSON rejects unknown keys
+            if (platform === "android") {
+                // Android: only app_package
+                if (params.appPackage)
+                    appPayload.app_package = params.appPackage;
+            }
+            else if (platform === "ios") {
+                // iOS: bundleId or urlScheme
+                if (params.bundleId)
+                    appPayload.bundle_id = params.bundleId;
+                if (params.urlScheme)
+                    appPayload.url_scheme = params.urlScheme;
+            }
+            else {
+                // Unknown platform: send only what's provided, prefer appPackage
+                if (params.appPackage)
+                    appPayload.app_package = params.appPackage;
+                else if (params.bundleId)
+                    appPayload.bundle_id = params.bundleId;
+                else if (params.urlScheme)
+                    appPayload.url_scheme = params.urlScheme;
+            }
+            // Never send app_name — phone strict JSON parser rejects unknown keys
             if (!appPayload.app_package && !appPayload.bundle_id && !appPayload.url_scheme) {
                 throw new Error("open_app requires at least one of: appPackage, bundleId, urlScheme");
             }
+            dbg(`[cmd] open_app: platform=${platform}, payload=${JSON.stringify(appPayload)}`);
             return { type: "receive_app", payload: appPayload };
         }
         case "screenshot":

package/dist/core/device.d.ts

@@ -40,7 +40,7 @@ export declare function getDynamicContext(): DynamicContext;
 export declare function isDeviceProfileLoaded(): boolean;
 export declare function extractStatic(profile: Record<string, unknown>): StaticContext;
 export declare function extractDynamic(profile: Record<string, unknown>): DynamicContext;
-export declare function updateDeviceProfile(profile: Record<string, unknown>): void;
+export declare function updateDeviceProfile(raw: Record<string, unknown>): void;
 export declare function fetchDeviceProfile(config: ZhiHandConfig): Promise<void>;
 export declare function buildControlToolDescription(): string;
 export declare function buildScreenshotToolDescription(): string;

package/dist/core/device.js

@@ -57,16 +57,37 @@ function bool(v, fallback) {
     return typeof v === "boolean" ? v : fallback;
 }
 export function extractStatic(profile) {
+    // Build OS version string from platform + system_release + api_level
+    const platform = str(profile.platform, DEFAULT_STATIC.platform);
+    const sysRelease = str(profile.system_release, "");
+    const apiLevel = typeof profile.api_level === "number" ? profile.api_level : null;
+    let osVersion;
+    if (platform === "android" && sysRelease && apiLevel) {
+        osVersion = `Android ${sysRelease} (API ${apiLevel})`;
+    }
+    else if (platform === "ios" && sysRelease) {
+        osVersion = `iOS ${sysRelease}`;
+    }
+    else {
+        osVersion = sysRelease || DEFAULT_STATIC.osVersion;
+    }
+    // Screen size: Android uses display_width_px/display_height_px, iOS uses display_width_pixels/display_height_pixels
+    const screenW = num(profile.display_width_px, num(profile.display_width_pixels, DEFAULT_STATIC.screenWidthPx));
+    const screenH = num(profile.display_height_px, num(profile.display_height_pixels, DEFAULT_STATIC.screenHeightPx));
+    // Density: Android uses density, iOS uses display_scale
+    const density = num(profile.density, num(profile.display_scale, DEFAULT_STATIC.density));
+    // Text direction: rtl is boolean
+    const textDirection = profile.rtl === true ? "rtl" : "ltr";
     return {
-        platform: str(profile.platform, DEFAULT_STATIC.platform),
+        platform,
         model: str(profile.model, DEFAULT_STATIC.model),
-        osVersion: str(profile.os_version, DEFAULT_STATIC.osVersion),
-        screenWidthPx: num(profile.screen_width_px, DEFAULT_STATIC.screenWidthPx),
-        screenHeightPx: num(profile.screen_height_px, DEFAULT_STATIC.screenHeightPx),
-        density: num(profile.density, DEFAULT_STATIC.density),
+        osVersion,
+        screenWidthPx: screenW,
+        screenHeightPx: screenH,
+        density,
         formFactor: str(profile.form_factor, DEFAULT_STATIC.formFactor),
         locale: str(profile.locale, DEFAULT_STATIC.locale),
-        textDirection: str(profile.text_direction, DEFAULT_STATIC.textDirection),
+        textDirection,
         timezone: str(profile.timezone, DEFAULT_STATIC.timezone),
         navigationMode: typeof profile.navigation_mode === "string" ? profile.navigation_mode : undefined,
         romFamily: typeof profile.rom_family === "string" ? profile.rom_family : undefined,
@@ -88,7 +109,16 @@ export function extractDynamic(profile) {
     };
 }
 // ── Update from SSE event ─────────────────────────────────
-export function updateDeviceProfile(profile) {
+export function updateDeviceProfile(raw) {
+    // SSE events may also wrap in { platform, attributes: {...} } — flatten if needed
+    let profile;
+    if (typeof raw.attributes === "object" && raw.attributes !== null) {
+        const attrs = raw.attributes;
+        profile = { ...attrs, platform: raw.platform ?? attrs.platform };
+    }
+    else {
+        profile = raw;
+    }
     staticCtx = extractStatic(profile);
     dynamicCtx = extractDynamic(profile);
     loaded = true;
@@ -108,10 +138,16 @@ export async function fetchDeviceProfile(config) {
             return;
         }
         const data = await response.json();
-        // API may wrap in { device_profile: {...} } or return flat
-        const profile = (typeof data.device_profile === "object" && data.device_profile !== null)
-            ? data.device_profile
+        // API returns { profile: { credential_id, platform, attributes: {...} } }
+        const wrapper = (typeof data.profile === "object" && data.profile !== null)
+            ? data.profile
             : data;
+        // Merge top-level fields (platform, edge_id) with attributes for flat extraction
+        const attrs = (typeof wrapper.attributes === "object" && wrapper.attributes !== null)
+            ? wrapper.attributes
+            : {};
+        const profile = { ...attrs, platform: wrapper.platform ?? attrs.platform };
+        dbg(`[device] Raw profile keys: ${Object.keys(profile).join(", ")}`);
         updateDeviceProfile(profile);
     }
     catch (err) {

package/dist/index.d.ts

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

package/dist/index.js

@@ -6,7 +6,7 @@ import { executeControl } from "./tools/control.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
 import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.26.0";
+export const PACKAGE_VERSION = "0.26.3";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/dist/tools/schemas.d.ts

@@ -16,7 +16,6 @@ export declare const controlSchema: {
     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

@@ -22,7 +22,6 @@ export const controlSchema = {
     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.26.0",
+  "version": "0.26.3",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",