@zhihand/mcp 0.28.0 → 0.30.0

package/dist/daemon/prompt-listener.d.ts

@@ -1,4 +1,5 @@
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
+type ZhiHandConfig = ZhiHandRuntimeConfig;
 export interface MobilePrompt {
     id: string;
     credential_id: string;
@@ -32,3 +33,4 @@ export declare class PromptListener {
     private stopPolling;
     private poll;
 }
+export {};

package/dist/daemon/prompt-listener.js

@@ -1,4 +1,3 @@
-import { updateDeviceProfile } from "../core/device.js";
 import { dbg } from "./logger.js";
 const SSE_WATCHDOG_TIMEOUT = 120_000; // 120s no data → reconnect (servers may not send keepalive frequently)
 const SSE_RECONNECT_DELAY = 3_000;
@@ -133,11 +132,8 @@ export class PromptListener {
             }
         }
         else if (event.kind === "device_profile.updated" && event.device_profile) {
-            // NOTE: This event may only arrive if the server sends cross-topic events on
-            // the prompts stream, or if the API is updated to support multi-topic SSE.
-            // If not received, device profile is still fetched at daemon startup.
-            this.log("[device] Device profile updated via SSE");
-            updateDeviceProfile(event.device_profile);
+            // Registry owns device-profile updates; this listener is only for prompts.
+            this.log("[device] device_profile.updated event received on prompts stream (ignored; registry handles it)");
         }
     }
     startPolling() {

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,79 +1,141 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { resolveConfig } from "./core/config.js";
-import { controlSchema, systemSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { controlSchema, systemSchema, screenshotSchema, pairSchema, listDevicesSchema, statusSchema, } from "./tools/schemas.js";
 import { executeControl } from "./tools/control.js";
 import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.28.0";
-export function createServer(deviceName) {
+import { resolveTargetDevice } from "./tools/resolve.js";
+import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+import { registry } from "./core/registry.js";
+export const PACKAGE_VERSION = "0.30.0";
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function createServer() {
     const server = new McpServer({
         name: "zhihand",
         version: PACKAGE_VERSION,
     });
-    // zhihand_control — main phone control tool
-    // Description includes device info (platform, model, screen size) when available
-    server.tool("zhihand_control", buildControlToolDescription(), controlSchema, async (params) => {
-        const config = resolveConfig(deviceName);
-        return await executeControl(config, params);
+    const controlTool = server.tool("zhihand_control", buildControlToolDescription(null, registry.listOnline()), controlSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        const platform = state.profile?.platform ?? "unknown";
+        return await executeControl(cfg, params, platform, state.capabilities);
     });
-    // zhihand_system — system navigation + media controls (separate tool per Gemini design review)
-    server.tool("zhihand_system", buildSystemToolDescription(), systemSchema, async (params) => {
-        const config = resolveConfig(deviceName);
-        return await executeSystem(config, params);
+    const systemTool = server.tool("zhihand_system", buildSystemToolDescription(null, registry.listOnline()), systemSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        const platform = state.profile?.platform ?? "unknown";
+        return await executeSystem(cfg, params, platform);
     });
-    // zhihand_screenshot — capture current screen without any action
-    server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
-        const config = resolveConfig(deviceName);
-        return await handleScreenshot(config);
+    const screenshotTool = server.tool("zhihand_screenshot", buildScreenshotToolDescription(null, registry.listOnline()), screenshotSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        return await handleScreenshot(cfg, state.capabilities);
     });
-    // zhihand_status — return device context for LLM to query on demand
-    server.tool("zhihand_status", "Get device status: platform, model, OS version, screen size, battery, network, BLE, dark mode, storage, and more.", {}, async () => {
+    server.tool("zhihand_status", "Get device status and capability readiness for a device. Returns curated fields (platform, model, OS, screen, battery, network, BLE, ...), a `capabilities` object with `ready`/`reason` for screen_sharing, hid, live_session, profile.age, AND a `raw` map of allowlisted device attributes. Pass device_id when multiple devices are online.", statusSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify(formatDeviceStatus(), null, 2),
+                    text: JSON.stringify(formatDeviceStatus(resolved.state), null, 2),
+                }],
+        };
+    });
+    server.tool("zhihand_list_devices", "List ALL configured ZhiHand devices with their online status. Returns credential_id, label, platform, online, last_seen_ms_ago for each. Call this before zhihand_control/system/screenshot/status when multiple devices may be online.", listDevicesSchema, async () => {
+        const now = Date.now();
+        const devices = registry.list().map((d) => ({
+            credential_id: d.credentialId,
+            label: d.label,
+            platform: d.platform,
+            online: d.online,
+            last_seen_ms_ago: d.lastSeenAtMs > 0 ? now - d.lastSeenAtMs : -1,
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ devices }, null, 2),
                 }],
         };
     });
-    // zhihand_pair — device pairing
     server.tool("zhihand_pair", "Pair a new mobile device via QR code.", pairSchema, async (params) => {
         return await handlePair(params);
     });
-    // device://profile — MCP resource for device profile
-    server.resource("device-profile", "device://profile", { description: "Device static and dynamic context (platform, model, screen, battery, network, etc.)" }, async () => {
-        const staticCtx = getStaticContext();
-        const dynamicCtx = getDynamicContext();
+    // Dynamic tool-description updates on online-set change.
+    // Each .update() call also triggers sendToolListChanged() internally, but we
+    // wrap each individually so one throwing does NOT block the others, and we
+    // still call sendToolListChanged() explicitly as a belt-and-braces signal.
+    registry.subscribe(() => {
+        const online = registry.listOnline();
+        try {
+            controlTool.update({ description: buildControlToolDescription(null, online) });
+        }
+        catch { /* best-effort */ }
+        try {
+            systemTool.update({ description: buildSystemToolDescription(null, online) });
+        }
+        catch { /* best-effort */ }
+        try {
+            screenshotTool.update({ description: buildScreenshotToolDescription(null, online) });
+        }
+        catch { /* best-effort */ }
+        try {
+            server.server.sendToolListChanged();
+        }
+        catch { /* best-effort */ }
+    });
+    // device://profile — returns default online device
+    server.resource("device-profile", "device://profile", { description: "Device static and dynamic context for the default online device." }, async () => {
+        const state = registry.resolveDefault();
+        if (!state) {
+            return {
+                contents: [{
+                        uri: "device://profile",
+                        mimeType: "application/json",
+                        text: JSON.stringify({ error: "No device online" }, null, 2),
+                    }],
+            };
+        }
         return {
             contents: [{
                     uri: "device://profile",
                     mimeType: "application/json",
-                    text: JSON.stringify({ ...staticCtx, ...dynamicCtx }, null, 2),
+                    text: JSON.stringify(formatDeviceStatus(state), null, 2),
                 }],
         };
     });
     return server;
 }
-export async function startStdioServer(deviceName) {
-    // Fetch device profile before creating server so tool descriptions have platform info
-    try {
-        const config = resolveConfig(deviceName);
-        await fetchDeviceProfile(config);
-    }
-    catch {
-        // Non-fatal — server will use generic descriptions
-    }
-    const server = createServer(deviceName);
+export async function startStdioServer() {
+    await registry.init();
+    const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-// Direct execution: start stdio server
+function setupShutdown() {
+    const shutdown = () => {
+        registry.shutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+setupShutdown();
 const isDirectRun = process.argv[1]?.endsWith("index.ts") || process.argv[1]?.endsWith("index.js");
 if (isDirectRun) {
-    const deviceArg = process.argv.find((a) => a.startsWith("--device="))?.split("=")[1];
-    startStdioServer(deviceArg ?? process.env.ZHIHAND_DEVICE).catch((err) => {
+    startStdioServer().catch((err) => {
         process.stderr.write(`ZhiHand MCP Server failed: ${err.message}\n`);
         process.exit(1);
     });

package/dist/openclaw.adapter.js

@@ -8,6 +8,7 @@ import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
 import { detectCLITools, formatDetectedTools } from "./cli/detect.js";
 import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { registry } from "./core/registry.js";
 function zodSchemaToJsonSchema(zodShape) {
     // Simplified conversion — OpenClaw uses JSON Schema-like parameter objects.
     // The actual Zod schemas are used for validation inside tool handlers.
@@ -23,6 +24,8 @@ function zodSchemaToJsonSchema(zodShape) {
 }
 export function registerOpenClawTools(api, deviceName) {
     const log = (msg) => api.logger.info?.(msg);
+    // Kick off registry in the background so runtime config resolution benefits.
+    void registry.init().catch(() => { });
     // zhihand_control
     api.registerTool({
         name: "zhihand_control",
@@ -31,7 +34,10 @@ export function registerOpenClawTools(api, deviceName) {
         parameters: zodSchemaToJsonSchema(controlSchema),
         execute: async (_id, params) => {
             const config = resolveConfig(deviceName);
-            const result = await executeControl(config, params);
+            const state = registry.get(config.credentialId);
+            const platform = state?.profile?.platform ?? "unknown";
+            const caps = state?.capabilities ?? null;
+            const result = await executeControl(config, params, platform, caps);
             return result;
         },
     });
@@ -43,7 +49,9 @@ export function registerOpenClawTools(api, deviceName) {
         parameters: zodSchemaToJsonSchema(screenshotSchema),
         execute: async (_id, _params) => {
             const config = resolveConfig(deviceName);
-            const result = await handleScreenshot(config);
+            const state = registry.get(config.credentialId);
+            const caps = state?.capabilities ?? null;
+            const result = await handleScreenshot(config, caps);
             return result;
         },
     });

package/dist/tools/control.d.ts

@@ -1,5 +1,7 @@
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 import type { ControlParams } from "../core/command.ts";
+import type { ScreenshotResult } from "../core/screenshot.ts";
+import type { Capabilities } from "../core/device.ts";
 type TextContent = {
     type: "text";
     text: string;
@@ -13,6 +15,11 @@ type ToolContent = TextContent | ImageContent;
 type ToolResult = {
     content: ToolContent[];
 };
-export declare function executeControl(config: ZhiHandConfig, params: ControlParams): Promise<ToolResult>;
-export declare function executeScreenshot(config: ZhiHandConfig): Promise<ToolResult>;
+/**
+ * Build a short human-readable warning for the LLM if the underlying
+ * capability isn't ready, or if the last screenshot is stale.
+ */
+export declare function buildReadinessWarning(requiredCapability: "hid" | "screen" | "none", capabilities: Capabilities | null, screenshot: ScreenshotResult | null): string;
+export declare function executeControl(config: ZhiHandRuntimeConfig, params: ControlParams, platform: string, capabilities: Capabilities | null): Promise<ToolResult>;
+export declare function executeScreenshot(config: ZhiHandRuntimeConfig, capabilities: Capabilities | null): Promise<ToolResult>;
 export {};

package/dist/tools/control.js

@@ -1,52 +1,81 @@
 import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
-import { fetchScreenshotBinary } from "../core/screenshot.js";
+import { fetchScreenshot } from "../core/screenshot.js";
 import { waitForCommandAck } from "../core/sse.js";
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-export async function executeControl(config, params) {
-    // wait: Plugin-local implementation, no server round-trip
+/**
+ * Build a short human-readable warning for the LLM if the underlying
+ * capability isn't ready, or if the last screenshot is stale.
+ */
+export function buildReadinessWarning(requiredCapability, capabilities, screenshot) {
+    if (!capabilities)
+        return "";
+    const warnings = [];
+    if (requiredCapability === "hid" && !capabilities.hid.ready) {
+        warnings.push(`⚠️ HID not ready: ${capabilities.hid.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 (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, platform, capabilities) {
     if (params.action === "wait") {
         await sleep(params.durationMs ?? 1000);
-        const screenshot = await fetchScreenshotBinary(config);
-        return {
-            content: [
-                { type: "text", text: `Waited ${params.durationMs ?? 1000}ms` },
-                { type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" },
-            ],
-        };
-    }
-    // screenshot: send receive_screenshot, App captures immediately (no 2s delay)
+        const shot = await fetchScreenshot(config);
+        const warning = buildReadinessWarning("screen", capabilities, shot);
+        const content = [];
+        if (warning)
+            content.push({ type: "text", text: warning });
+        content.push({ type: "text", text: `Waited ${params.durationMs ?? 1000}ms` });
+        content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+        return { content };
+    }
     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 = [
-        { type: "text", text: formatAckSummary(params.action, ack) },
-    ];
+    const content = [];
+    let shot = null;
     if (ack.acked) {
         try {
-            const screenshot = await fetchScreenshotBinary(config);
-            content.push({ type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" });
+            shot = await fetchScreenshot(config);
         }
         catch {
-            // Screenshot is best-effort after ACK
+            // best-effort
         }
     }
+    const warning = buildReadinessWarning("hid", capabilities, shot);
+    if (warning)
+        content.push({ type: "text", text: warning });
+    content.push({ type: "text", text: formatAckSummary(params.action, ack) });
+    if (shot) {
+        content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+    }
     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 screenshot = await fetchScreenshotBinary(config);
-    return {
-        content: [
-            { type: "text", text: `Screenshot captured (acked: ${ack.acked})` },
-            { type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" },
-        ],
-    };
+    const shot = await fetchScreenshot(config);
+    const warning = buildReadinessWarning("screen", capabilities, shot);
+    const content = [];
+    if (warning)
+        content.push({ type: "text", text: warning });
+    content.push({
+        type: "text",
+        text: `Screenshot captured (acked: ${ack.acked}, age: ${shot.ageMs >= 0 ? `${shot.ageMs}ms` : "unknown"}, size: ${shot.width}x${shot.height}, seq: ${shot.sequence})`,
+    });
+    content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+    return { content };
 }

package/dist/tools/pair.js

@@ -1,5 +1,5 @@
-import { loadDefaultCredential } from "../core/config.js";
-import { createPairingSession, registerPlugin, renderPairingQRCode, formatPairingStatus, } from "../core/pair.js";
+import { loadConfig } from "../core/config.js";
+import { createPairingSession, registerPlugin, renderPairingQRCode, } from "../core/pair.js";
 const DEFAULT_ENDPOINT = "https://api.zhihand.com";
 const DEFAULT_EDGE_ID_PREFIX = "mcp-";
 function generateEdgeId() {
@@ -7,26 +7,23 @@ function generateEdgeId() {
 }
 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) },
-                ],
-            };
+        const cfg = loadConfig();
+        const records = Object.values(cfg.devices);
+        if (records.length > 0) {
+            const lines = [
+                "Already paired with:",
+                "",
+                ...records.map((r) => `  - ${r.credential_id} (${r.label}, ${r.platform}) via ${r.endpoint}`),
+                "",
+                "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,
-    });
+    const plugin = await registerPlugin(resolvedEndpoint, { stableIdentity });
+    const session = await createPairingSession(resolvedEndpoint, { edgeId: plugin.edge_id });
     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);
+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.28.0",
+  "version": "0.30.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",