@zhihand/mcp 0.25.0 → 0.26.2

package/README.md

@@ -2,7 +2,7 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.25.0`
+Version: `0.26.0`
 
 ## What is this?
 
@@ -177,7 +177,7 @@ When you switch:
 
 ## MCP Tools
 
-The server exposes three tools to AI agents:
+The server exposes these tools to AI agents:
 
 ### `zhihand_control`
 
@@ -212,6 +212,12 @@ Capture the current phone screen without performing any action. Returns an image
 
 No parameters required.
 
+### `zhihand_status`
+
+Get device status: platform, model, OS version, screen size, battery, network, BLE connection, dark mode, storage, and more. No parameters.
+
+Tool description and `open_app` guidance are **automatically adapted** based on the connected device platform (Android/iOS), so AI agents always send correct platform-specific parameters.
+
 ### `zhihand_pair`
 
 Pair with a phone device. Returns a QR code and pairing URL.
@@ -220,6 +226,10 @@ Pair with a phone device. Returns a QR code and pairing URL.
 |---|---|---|
 | `forceNew` | `boolean` | Force new pairing even if already paired (default: `false`) |
 
+### MCP Resource: `device://profile`
+
+Provides full device context (static + dynamic) as JSON. Includes platform, model, OS version, screen size, battery, network, BLE, dark mode, storage, thermal state, locale, and more.
+
 ## How It Works
 
 ```
@@ -302,12 +312,14 @@ packages/mcp/
 │   ├── core/
 │   │   ├── config.ts        # Credential & config management (~/.zhihand/), default models
 │   │   ├── resolve-path.ts  # Platform-aware executable path resolution (gemini/claude/codex)
+│   │   ├── device.ts        # Device context: static/dynamic profile, fetch, SSE updates
 │   │   ├── command.ts       # Command creation, enqueue, ACK formatting
 │   │   ├── screenshot.ts    # Binary screenshot fetch (JPEG)
 │   │   ├── sse.ts           # SSE client + hybrid ACK (SSE push + polling fallback)
 │   │   └── pair.ts          # Plugin registration + device pairing flow
 │   ├── daemon/
 │   │   ├── index.ts         # Daemon entry: HTTP server + MCP + Relay + Config API
+│   │   ├── logger.ts        # Debug logger (--debug flag)
 │   │   ├── heartbeat.ts     # Brain heartbeat loop (30s interval, 5s retry)
 │   │   ├── prompt-listener.ts # SSE + polling prompt listener with dedup
 │   │   └── dispatcher.ts    # Async CLI dispatch (spawn + timeout + two-stage kill)

package/bin/zhihand

@@ -311,8 +311,9 @@ switch (command) {
       { 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" },
+      { 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;
@@ -342,7 +343,10 @@ switch (command) {
           const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
           const ms = Date.now() - t0;
           if (ack.acked) {
-            console.log(`✅ (${ms}ms)`);
+            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)`);

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":
@@ -104,7 +122,8 @@ export async function getCommand(config, commandId) {
         throw new Error(`Get command failed: ${response.status}`);
     }
     const payload = (await response.json());
-    dbg(`[cmd] Got: id=${payload.command.id}, status=${payload.command.status}, acked=${!!payload.command.acked_at}`);
+    const cmd = payload.command;
+    dbg(`[cmd] Got: id=${cmd.id}, status=${cmd.status}, acked=${!!cmd.acked_at}, ack_status=${cmd.ack_status ?? "-"}, ack_result=${JSON.stringify(cmd.ack_result ?? null)}`);
     return payload.command;
 }
 export function formatAckSummary(action, result) {

package/dist/core/device.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Device Context — static + dynamic device info fetched from control plane.
+ *
+ * Static info (platform, model, screen size) is set once after pairing and
+ * injected into MCP tool descriptions so the LLM always knows the device.
+ *
+ * Dynamic info (battery, network, BLE) is updated via SSE push and exposed
+ * through the zhihand_status tool and device://profile resource.
+ */
+import type { ZhiHandConfig } from "./config.ts";
+export interface StaticContext {
+    platform: string;
+    model: string;
+    osVersion: string;
+    screenWidthPx: number;
+    screenHeightPx: number;
+    density: number;
+    formFactor: string;
+    locale: string;
+    textDirection: string;
+    timezone: string;
+    navigationMode?: string;
+    romFamily?: string;
+}
+export interface DynamicContext {
+    batteryLevel: number;
+    batteryState: string;
+    networkType: string;
+    bleRssi: number | null;
+    darkMode: boolean;
+    hidConnected: boolean;
+    recordingActive: boolean;
+    appInForeground: boolean;
+    availableStorageMb: number;
+    thermalState?: string;
+    fontScale: number;
+}
+export declare function getStaticContext(): StaticContext;
+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(raw: Record<string, unknown>): void;
+export declare function fetchDeviceProfile(config: ZhiHandConfig): Promise<void>;
+export declare function buildControlToolDescription(): string;
+export declare function buildScreenshotToolDescription(): string;
+export declare function formatDeviceStatus(): Record<string, unknown>;

package/dist/core/device.js

@@ -0,0 +1,207 @@
+/**
+ * Device Context — static + dynamic device info fetched from control plane.
+ *
+ * Static info (platform, model, screen size) is set once after pairing and
+ * injected into MCP tool descriptions so the LLM always knows the device.
+ *
+ * Dynamic info (battery, network, BLE) is updated via SSE push and exposed
+ * through the zhihand_status tool and device://profile resource.
+ */
+import { dbg } from "../daemon/logger.js";
+// ── Default values ────────────────────────────────────────
+const DEFAULT_STATIC = {
+    platform: "unknown",
+    model: "unknown",
+    osVersion: "unknown",
+    screenWidthPx: 0,
+    screenHeightPx: 0,
+    density: 1,
+    formFactor: "phone",
+    locale: "en-US",
+    textDirection: "ltr",
+    timezone: "UTC",
+};
+const DEFAULT_DYNAMIC = {
+    batteryLevel: -1,
+    batteryState: "unknown",
+    networkType: "unknown",
+    bleRssi: null,
+    darkMode: false,
+    hidConnected: false,
+    recordingActive: false,
+    appInForeground: false,
+    availableStorageMb: -1,
+    fontScale: 1,
+};
+// ── Module state ──────────────────────────────────────────
+let staticCtx = { ...DEFAULT_STATIC };
+let dynamicCtx = { ...DEFAULT_DYNAMIC };
+let loaded = false;
+export function getStaticContext() {
+    return staticCtx;
+}
+export function getDynamicContext() {
+    return dynamicCtx;
+}
+export function isDeviceProfileLoaded() {
+    return loaded;
+}
+// ── Extract helpers ───────────────────────────────────────
+function str(v, fallback) {
+    return typeof v === "string" && v ? v : fallback;
+}
+function num(v, fallback) {
+    return typeof v === "number" && !isNaN(v) ? v : fallback;
+}
+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,
+        model: str(profile.model, DEFAULT_STATIC.model),
+        osVersion,
+        screenWidthPx: screenW,
+        screenHeightPx: screenH,
+        density,
+        formFactor: str(profile.form_factor, DEFAULT_STATIC.formFactor),
+        locale: str(profile.locale, DEFAULT_STATIC.locale),
+        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,
+    };
+}
+export function extractDynamic(profile) {
+    return {
+        batteryLevel: num(profile.battery_level, DEFAULT_DYNAMIC.batteryLevel),
+        batteryState: str(profile.battery_state, DEFAULT_DYNAMIC.batteryState),
+        networkType: str(profile.network_type, DEFAULT_DYNAMIC.networkType),
+        bleRssi: typeof profile.ble_rssi === "number" ? profile.ble_rssi : null,
+        darkMode: bool(profile.dark_mode, DEFAULT_DYNAMIC.darkMode),
+        hidConnected: bool(profile.hid_connected, DEFAULT_DYNAMIC.hidConnected),
+        recordingActive: bool(profile.recording_active, DEFAULT_DYNAMIC.recordingActive),
+        appInForeground: bool(profile.app_in_foreground, DEFAULT_DYNAMIC.appInForeground),
+        availableStorageMb: num(profile.available_storage_mb, DEFAULT_DYNAMIC.availableStorageMb),
+        thermalState: typeof profile.thermal_state === "string" ? profile.thermal_state : undefined,
+        fontScale: num(profile.font_scale, DEFAULT_DYNAMIC.fontScale),
+    };
+}
+// ── Update from SSE event ─────────────────────────────────
+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;
+    dbg(`[device] Profile updated: platform=${staticCtx.platform}, model=${staticCtx.model}, screen=${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`);
+}
+// ── Fetch initial profile from API ────────────────────────
+export async function fetchDeviceProfile(config) {
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/device-profile`;
+    dbg(`[device] Fetching profile: GET ${url}`);
+    try {
+        const response = await fetch(url, {
+            headers: { "x-zhihand-controller-token": config.controllerToken },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            dbg(`[device] Profile fetch failed: ${response.status} ${response.statusText}`);
+            return;
+        }
+        const data = await response.json();
+        // 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) {
+        dbg(`[device] Profile fetch error: ${err.message}`);
+    }
+}
+// ── Build tool description with device info ───────────────
+export function buildControlToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "Control the connected mobile device. Supports click, swipe, type, scroll, open_app, back, home, and more. All coordinates use normalized ratios [0,1].";
+    }
+    const parts = [
+        `Control a ${staticCtx.platform} device`,
+        `(${staticCtx.model}, ${staticCtx.osVersion}`,
+        `${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`,
+        `${staticCtx.formFactor}, ${staticCtx.locale})`,
+    ];
+    let desc = parts.join(", ") + ".";
+    desc += " All coordinates use normalized ratios [0,1].";
+    // Platform-specific open_app guidance
+    if (staticCtx.platform === "android") {
+        desc += " For open_app, use appPackage (e.g. 'com.tencent.mm'). Do NOT send bundleId or urlScheme.";
+    }
+    else if (staticCtx.platform === "ios") {
+        desc += " For open_app, use bundleId (e.g. 'com.tencent.xin') or urlScheme (e.g. 'weixin://'). Do NOT send appPackage.";
+    }
+    return desc;
+}
+export function buildScreenshotToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "Take a screenshot of the phone screen.";
+    }
+    return `Take a screenshot of the ${staticCtx.platform} device (${staticCtx.model}, ${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}).`;
+}
+// ── Format status for zhihand_status tool ─────────────────
+export function formatDeviceStatus() {
+    return {
+        platform: staticCtx.platform,
+        model: staticCtx.model,
+        os_version: staticCtx.osVersion,
+        screen: `${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`,
+        density: staticCtx.density,
+        form_factor: staticCtx.formFactor,
+        locale: staticCtx.locale,
+        timezone: staticCtx.timezone,
+        navigation_mode: staticCtx.navigationMode ?? null,
+        battery: `${dynamicCtx.batteryLevel}% (${dynamicCtx.batteryState})`,
+        network: dynamicCtx.networkType,
+        ble: dynamicCtx.hidConnected
+            ? `connected${dynamicCtx.bleRssi !== null ? ` (RSSI: ${dynamicCtx.bleRssi})` : ""}`
+            : "disconnected",
+        dark_mode: dynamicCtx.darkMode,
+        storage_available_mb: dynamicCtx.availableStorageMb,
+        thermal: dynamicCtx.thermalState ?? "normal",
+        font_scale: dynamicCtx.fontScale,
+    };
+}

package/dist/core/sse.js

@@ -10,7 +10,7 @@ export function handleSSEEvent(event) {
     if (event.kind === "command.acked" && event.command) {
         const callback = ackCallbacks.get(event.command.id);
         if (callback) {
-            dbg(`[sse-cmd] ACK callback for ${event.command.id}, ack_status=${event.command.ack_status}`);
+            dbg(`[sse-cmd] ACK callback for ${event.command.id}, ack_status=${event.command.ack_status}, ack_result=${JSON.stringify(event.command.ack_result ?? null)}`);
             callback(event.command);
             ackCallbacks.delete(event.command.id);
         }

package/dist/daemon/dispatcher.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_MODELS } from "../core/config.js";
 import { resolveGemini, resolveClaude, resolveCodex } from "../core/resolve-path.js";
+import { getStaticContext, isDeviceProfileLoaded } from "../core/device.js";
 import { dbg } from "./logger.js";
 const CLI_TIMEOUT = 300_000; // 300s (5min) per prompt — MCP tool chains need multiple turns
 const SIGKILL_DELAY = 2_000; // 2s after SIGTERM
@@ -351,7 +352,30 @@ export async function killActiveChild() {
     conversationHistory.length = 0;
 }
 // ── System Prompt ─────────────────────────────────────────
-const SYSTEM_CONTEXT = `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
+/**
+ * Build system context dynamically — injects device platform info when available
+ * so the AI sends correct platform-specific parameters (e.g. appPackage vs bundleId).
+ */
+function buildSystemContext() {
+    const static_ = isDeviceProfileLoaded() ? getStaticContext() : null;
+    const deviceLine = static_
+        ? `Connected device: ${static_.platform} ${static_.model} (${static_.osVersion}), ${static_.screenWidthPx}x${static_.screenHeightPx}, ${static_.formFactor}, ${static_.locale}`
+        : "Connected device: unknown platform";
+    // Platform-specific open_app guidance
+    let openAppDoc;
+    if (static_?.platform === "android") {
+        openAppDoc = "- open_app: Open an app. Params: appPackage (e.g. 'com.tencent.mm'). Do NOT send bundleId or urlScheme on Android.";
+    }
+    else if (static_?.platform === "ios") {
+        openAppDoc = "- open_app: Open an app. Params: bundleId (e.g. 'com.tencent.xin') or urlScheme (e.g. 'weixin://'). Do NOT send appPackage on iOS.";
+    }
+    else {
+        openAppDoc = "- open_app: Open an app. Params: appPackage (Android, e.g. 'com.tencent.mm'), bundleId (iOS), urlScheme (e.g. 'weixin://')";
+    }
+    return `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
+
+## Device
+${deviceLine}
 
 ## Available MCP Tools
 
@@ -372,22 +396,26 @@ Control the phone. Requires "action" parameter. All coordinates use normalized r
 - 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://")
+${openAppDoc}
 - 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)
 
+### zhihand_status
+Get device status: platform, battery, network, BLE connection, dark mode, storage, etc.
+
 ## 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).`;
+}
 /**
  * Build the full system prompt with optional conversation history.
  * Used for first prompt in persistent sessions and all one-shot calls.
  */
 function wrapPrompt(userPrompt, history) {
-    let result = SYSTEM_CONTEXT;
+    let result = buildSystemContext();
     if (history && history.length > 0) {
         result += "\n\n## Recent Conversation\n";
         for (const turn of history) {

package/dist/daemon/index.js

@@ -11,6 +11,7 @@ import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline, setBrainMeta }
 import { PromptListener } from "./prompt-listener.js";
 import { dispatchToCLI, postReply, killActiveChild } from "./dispatcher.js";
 import { setDebugEnabled, dbg } from "./logger.js";
+import { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded } from "../core/device.js";
 const DEFAULT_PORT = 18686;
 const PID_FILE = "daemon.pid";
 // ── State ──────────────────────────────────────────────────
@@ -189,6 +190,15 @@ export async function startDaemon(options) {
     else {
         log(`[config] No backend configured. Use: zhihand gemini / zhihand claude / zhihand codex`);
     }
+    // Fetch device profile (platform, model, screen size) — non-blocking, best-effort
+    await fetchDeviceProfile(config);
+    if (isDeviceProfileLoaded()) {
+        const s = getStaticContext();
+        log(`[device] ${s.platform} ${s.model} (${s.osVersion}), ${s.screenWidthPx}x${s.screenHeightPx}, ${s.locale}`);
+    }
+    else {
+        log(`[device] Device profile not available — tool descriptions will use generic defaults`);
+    }
     // MCP sessions: each client gets its own McpServer + Transport pair
     // because McpServer.connect() can only be called once per instance
     const MAX_MCP_SESSIONS = 20;

package/dist/daemon/prompt-listener.js

@@ -1,3 +1,4 @@
+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;
@@ -131,6 +132,13 @@ 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);
+        }
     }
     startPolling() {
         if (this.pollTimer)

package/dist/index.d.ts

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

package/dist/index.js

@@ -5,29 +5,60 @@ 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.25.0";
+import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+export const PACKAGE_VERSION = "0.26.2";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",
         version: PACKAGE_VERSION,
     });
     // zhihand_control — main phone control tool
-    server.tool("zhihand_control", controlSchema, async (params) => {
+    // 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);
     });
     // zhihand_screenshot — capture current screen without any action
-    server.tool("zhihand_screenshot", screenshotSchema, async () => {
+    server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
         const config = resolveConfig(deviceName);
         return await handleScreenshot(config);
     });
+    // 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 () => {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(formatDeviceStatus(), null, 2),
+                }],
+        };
+    });
     // zhihand_pair — device pairing
-    server.tool("zhihand_pair", pairSchema, async (params) => {
+    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();
+        return {
+            contents: [{
+                    uri: "device://profile",
+                    mimeType: "application/json",
+                    text: JSON.stringify({ ...staticCtx, ...dynamicCtx }, 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);
     const transport = new StdioServerTransport();
     await server.connect(transport);

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.25.0",
+  "version": "0.26.2",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",