@zhihand/mcp 0.29.0 → 0.32.0

package/dist/tools/control.js

@@ -1,40 +1,36 @@
 import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
 import { fetchScreenshot } from "../core/screenshot.js";
-import { waitForCommandAck } from "../core/sse.js";
-import { getCapabilities, isDeviceProfileLoaded } from "../core/device.js";
+import { waitForCommandAck } from "../core/ws.js";
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 /**
  * Build a short human-readable warning for the LLM if the underlying
- * capability isn't ready, or if the last screenshot is stale. Returns
- * empty string when everything is nominal.
+ * capability isn't ready, or if the last screenshot is stale.
  */
-function buildReadinessWarning(requiredCapability, screenshot) {
-    if (!isDeviceProfileLoaded())
+export function buildReadinessWarning(requiredCapability, capabilities, screenshot) {
+    if (!capabilities)
         return "";
-    const caps = getCapabilities();
     const warnings = [];
-    if (requiredCapability === "hid" && !caps.hid.ready) {
-        warnings.push(`⚠️ HID not ready: ${caps.hid.reason}`);
+    if (requiredCapability === "hid" && !capabilities.hid.ready) {
+        warnings.push(`⚠️ HID not ready: ${capabilities.hid.reason}`);
     }
-    if (requiredCapability === "screen" && !caps.screen_sharing.ready) {
-        warnings.push(`⚠️ Screen sharing not active: ${caps.screen_sharing.reason}`);
+    if (requiredCapability === "screen" && !capabilities.screen_sharing.ready) {
+        warnings.push(`⚠️ Screen sharing not active: ${capabilities.screen_sharing.reason}`);
     }
     if (screenshot && screenshot.stale) {
         warnings.push(`⚠️ Stale screenshot: age=${(screenshot.ageMs / 1000).toFixed(1)}s (phone may not be actively sharing the screen).`);
     }
-    if (caps.profile.stale) {
-        warnings.push(`⚠️ Stale device profile: ${(caps.profile.age_ms / 1000).toFixed(1)}s old — readiness flags may be out of date.`);
+    if (capabilities.profile.stale) {
+        warnings.push(`⚠️ Stale device profile: ${(capabilities.profile.age_ms / 1000).toFixed(1)}s old — readiness flags may be out of date.`);
     }
     return warnings.join("\n");
 }
-export async function executeControl(config, params) {
-    // wait: Plugin-local implementation, no server round-trip
+export async function executeControl(config, params, platform, capabilities) {
     if (params.action === "wait") {
         await sleep(params.durationMs ?? 1000);
         const shot = await fetchScreenshot(config);
-        const warning = buildReadinessWarning("screen", shot);
+        const warning = buildReadinessWarning("screen", capabilities, shot);
         const content = [];
         if (warning)
             content.push({ type: "text", text: warning });
@@ -42,12 +38,10 @@ export async function executeControl(config, params) {
         content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
         return { content };
     }
-    // screenshot: send receive_screenshot, App captures immediately (no 2s delay)
     if (params.action === "screenshot") {
-        return await executeScreenshot(config);
+        return await executeScreenshot(config, capabilities);
     }
-    // HID operations: enqueue → ACK → GET screenshot
-    const command = createControlCommand(params);
+    const command = createControlCommand(params, platform);
     const queued = await enqueueCommand(config, command);
     const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
     const content = [];
@@ -57,10 +51,10 @@ export async function executeControl(config, params) {
             shot = await fetchScreenshot(config);
         }
         catch {
-            // Screenshot is best-effort after ACK
+            // best-effort
         }
     }
-    const warning = buildReadinessWarning("hid", shot);
+    const warning = buildReadinessWarning("hid", capabilities, shot);
     if (warning)
         content.push({ type: "text", text: warning });
     content.push({ type: "text", text: formatAckSummary(params.action, ack) });
@@ -69,12 +63,12 @@ export async function executeControl(config, params) {
     }
     return { content };
 }
-export async function executeScreenshot(config) {
+export async function executeScreenshot(config, capabilities) {
     const command = createControlCommand({ action: "screenshot" });
     const queued = await enqueueCommand(config, command);
     const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 5_000 });
     const shot = await fetchScreenshot(config);
-    const warning = buildReadinessWarning("screen", shot);
+    const warning = buildReadinessWarning("screen", capabilities, shot);
     const content = [];
     if (warning)
         content.push({ type: "text", text: warning });

package/dist/tools/pair.d.ts

@@ -1,6 +1,6 @@
 export declare function handlePair(params: {
     forceNew?: boolean;
-}, endpoint?: string): Promise<{
+}): Promise<{
     content: {
         type: "text";
         text: string;

package/dist/tools/pair.js

@@ -1,32 +1,26 @@
-import { loadDefaultCredential } from "../core/config.js";
-import { createPairingSession, registerPlugin, renderPairingQRCode, formatPairingStatus, } from "../core/pair.js";
-const DEFAULT_ENDPOINT = "https://api.zhihand.com";
-const DEFAULT_EDGE_ID_PREFIX = "mcp-";
-function generateEdgeId() {
-    return `${DEFAULT_EDGE_ID_PREFIX}${Date.now().toString(36)}`;
-}
-export async function handlePair(params, endpoint) {
-    const resolvedEndpoint = endpoint ?? DEFAULT_ENDPOINT;
-    // Check existing credential
-    if (!params.forceNew) {
-        const existing = loadDefaultCredential();
-        if (existing) {
-            return {
-                content: [
-                    { type: "text", text: formatPairingStatus(existing) },
-                ],
-            };
-        }
+import { listUsers } from "../core/config.js";
+import { createPairingSession, registerPlugin, renderPairingQRCode, createUser, } from "../core/pair.js";
+import { resolveDefaultEndpoint } from "../core/config.js";
+export async function handlePair(params) {
+    const endpoint = resolveDefaultEndpoint();
+    const users = listUsers();
+    if (!params.forceNew && users.length > 0) {
+        const lines = [
+            "Already paired with:",
+            "",
+            ...users.map((u) => `  User: ${u.label} (${u.user_id})\n` +
+                u.devices.map((d) => `    - ${d.credential_id} (${d.label}, ${d.platform})`).join("\n")),
+            "",
+            "Pass forceNew=true to pair another device.",
+        ];
+        return { content: [{ type: "text", text: lines.join("\n") }] };
     }
-    // Register plugin first — server requires a known edge_id before pairing
-    const stableIdentity = generateEdgeId();
-    const plugin = await registerPlugin(resolvedEndpoint, {
-        stableIdentity,
-    });
-    // Create new pairing session with the registered edge_id
-    const session = await createPairingSession(resolvedEndpoint, {
-        edgeId: plugin.edge_id,
-    });
+    // Create a new user for MCP-tool pairing
+    const label = `MCP-${Date.now().toString(36)}`;
+    const userResp = await createUser(endpoint, label);
+    const stableIdentity = `mcp-${Date.now().toString(36)}`;
+    const plugin = await registerPlugin(endpoint, { stableIdentity });
+    const session = await createPairingSession(endpoint, userResp.user_id, userResp.controller_token, plugin.edge_id, 300);
     const qr = await renderPairingQRCode(session.pair_url);
     return {
         content: [

package/dist/tools/resolve.d.ts

@@ -0,0 +1,7 @@
+import { type DeviceState } from "../core/registry.ts";
+export type ResolveResult = {
+    state: DeviceState;
+} | {
+    error: string;
+};
+export declare function resolveTargetDevice(deviceId: string | undefined): ResolveResult;

package/dist/tools/resolve.js

@@ -0,0 +1,22 @@
+import { registry } from "../core/registry.js";
+export function resolveTargetDevice(deviceId) {
+    const online = registry.listOnline();
+    if (deviceId) {
+        const s = registry.get(deviceId);
+        if (!s) {
+            return { error: `Device '${deviceId}' not found. Call zhihand_list_devices.` };
+        }
+        if (!s.online) {
+            return { error: `Device '${deviceId}' is offline. Call zhihand_list_devices for online devices.` };
+        }
+        return { state: s };
+    }
+    if (online.length === 0) {
+        return { error: "No devices online. Ask user to open the ZhiHand app." };
+    }
+    if (online.length === 1) {
+        return { state: online[0] };
+    }
+    const ids = online.map((d) => `${d.credentialId} (${d.label})`).join(", ");
+    return { error: `Multiple devices online — pass device_id. Online: ${ids}` };
+}

package/dist/tools/schemas.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 export declare const controlSchema: {
+    device_id: z.ZodOptional<z.ZodString>;
     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>;
@@ -17,10 +18,17 @@ export declare const controlSchema: {
     urlScheme: z.ZodOptional<z.ZodString>;
 };
 export declare const systemSchema: {
+    device_id: z.ZodOptional<z.ZodString>;
     action: z.ZodEnum<["notification", "recent", "search", "switch_input", "siri", "control_center", "open_browser", "shortcut_help", "volume_up", "volume_down", "mute", "play_pause", "stop", "next_track", "prev_track", "fast_forward", "rewind", "brightness_up", "brightness_down", "power"]>;
     text: z.ZodOptional<z.ZodString>;
 };
-export declare const screenshotSchema: {};
+export declare const screenshotSchema: {
+    device_id: z.ZodOptional<z.ZodString>;
+};
 export declare const pairSchema: {
     forceNew: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 };
+export declare const listDevicesSchema: {};
+export declare const statusSchema: {
+    device_id: z.ZodOptional<z.ZodString>;
+};

package/dist/tools/schemas.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
+const deviceIdSchema = z.string().optional().describe("Credential ID of the target device. Optional if only one device is online. Call zhihand_list_devices to see online devices.");
 export const controlSchema = {
+    device_id: deviceIdSchema,
     action: z.enum([
         "click", "doubleclick", "longclick", "rightclick", "middleclick",
         "type", "swipe", "scroll", "keycombo",
@@ -13,7 +15,6 @@ export const controlSchema = {
     direction: z.enum(["up", "down", "left", "right"]).optional().describe("Scroll direction"),
     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 removed — app only supports set (text via "text" param)
     durationMs: z.number().int().positive().max(10000).optional().describe("Duration in ms: wait (default 1000), longclick (default 800), swipe (default 300). 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]"),
@@ -23,25 +24,26 @@ export const controlSchema = {
     bundleId: z.string().optional().describe("iOS bundle ID, e.g. 'com.tencent.xin'"),
     urlScheme: z.string().optional().describe("URL scheme, e.g. 'weixin://'"),
 };
-// zhihand_system — system navigation + media controls (separate from UI control)
 export const systemSchema = {
+    device_id: deviceIdSchema,
     action: z.enum([
-        // System navigation — cross-platform
         "notification", "recent", "search", "switch_input",
-        // System navigation — iOS only
         "siri", "control_center",
-        // System navigation — Android only
         "open_browser", "shortcut_help",
-        // Media controls — cross-platform
         "volume_up", "volume_down", "mute",
         "play_pause", "stop", "next_track", "prev_track",
         "fast_forward", "rewind",
-        // Hardware — cross-platform
         "brightness_up", "brightness_down", "power",
     ]).describe("System or media action to perform"),
     text: z.string().optional().describe("Optional text, e.g. search query for 'search' action"),
 };
-export const screenshotSchema = {};
+export const screenshotSchema = {
+    device_id: deviceIdSchema,
+};
 export const pairSchema = {
     forceNew: z.boolean().default(false).optional().describe("Force new pairing even if already paired"),
 };
+export const listDevicesSchema = {};
+export const statusSchema = {
+    device_id: deviceIdSchema,
+};

package/dist/tools/screenshot.d.ts

@@ -1,5 +1,6 @@
-import type { ZhiHandConfig } from "../core/config.ts";
-export declare function handleScreenshot(config: ZhiHandConfig): Promise<{
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
+import type { Capabilities } from "../core/device.ts";
+export declare function handleScreenshot(config: ZhiHandRuntimeConfig, capabilities: Capabilities | null): Promise<{
     content: ({
         type: "text";
         text: string;

package/dist/tools/screenshot.js

@@ -1,4 +1,4 @@
 import { executeScreenshot } from "./control.js";
-export async function handleScreenshot(config) {
-    return await executeScreenshot(config);
+export async function handleScreenshot(config, capabilities) {
+    return await executeScreenshot(config, capabilities);
 }

package/dist/tools/system.d.ts

@@ -1,10 +1,7 @@
 /**
  * zhihand_system tool handler — system navigation + media controls.
- *
- * Separated from zhihand_control to keep UI-control schema focused and
- * reduce LLM parameter hallucination (Gemini design review recommendation).
  */
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 import type { SystemParams } from "../core/command.ts";
 type TextContent = {
     type: "text";
@@ -12,6 +9,7 @@ type TextContent = {
 };
 type ToolResult = {
     content: TextContent[];
+    isError?: boolean;
 };
-export declare function executeSystem(config: ZhiHandConfig, params: SystemParams): Promise<ToolResult>;
+export declare function executeSystem(config: ZhiHandRuntimeConfig, params: SystemParams, platform: string): Promise<ToolResult>;
 export {};

package/dist/tools/system.js

@@ -1,11 +1,24 @@
 import { createSystemCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
-import { waitForCommandAck } from "../core/sse.js";
-export async function executeSystem(config, params) {
-    const command = createSystemCommand(params);
+import { waitForCommandAck } from "../core/ws.js";
+const IOS_ONLY = new Set(["siri", "control_center"]);
+const ANDROID_ONLY = new Set(["open_browser", "shortcut_help"]);
+export async function executeSystem(config, params, platform) {
+    // Platform guard
+    if (platform !== "ios" && IOS_ONLY.has(params.action)) {
+        return {
+            content: [{ type: "text", text: `Action ${params.action} is not supported on platform ${platform}` }],
+            isError: true,
+        };
+    }
+    if (platform !== "android" && ANDROID_ONLY.has(params.action)) {
+        return {
+            content: [{ type: "text", text: `Action ${params.action} is not supported on platform ${platform}` }],
+            isError: true,
+        };
+    }
+    const command = createSystemCommand(params, platform);
     const queued = await enqueueCommand(config, command);
     const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
     const summary = formatAckSummary(params.action, ack);
-    return {
-        content: [{ type: "text", text: summary }],
-    };
+    return { content: [{ type: "text", text: summary }] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.29.0",
+  "version": "0.32.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",
@@ -38,6 +38,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "qrcode": "^1.5.4",
+    "ws": "^8.20.0",
     "zod": "^3.24.0"
   },
   "engines": {
@@ -46,6 +47,7 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.18.1",
     "typescript": "^6.0.2"
   }
 }