@zhihand/mcp 0.30.0 → 0.32.1

package/dist/daemon/prompt-listener.js

@@ -1,15 +1,14 @@
+import { ReconnectingWebSocket } from "../core/ws.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;
 const POLL_INTERVAL = 2_000;
 export class PromptListener {
     config;
     handler;
     log;
     processedIds = new Set();
-    sseAbort = null;
+    rws = null;
     pollTimer = null;
-    sseConnected = false;
+    wsConnected = false;
     stopped = false;
     constructor(config, handler, log) {
         this.config = config;
@@ -18,16 +17,14 @@ export class PromptListener {
     }
     start() {
         this.stopped = false;
-        this.connectSSE();
+        this.connectWS();
     }
     stop() {
         this.stopped = true;
-        this.sseAbort?.abort();
-        this.sseAbort = null;
-        if (this.pollTimer) {
-            clearTimeout(this.pollTimer);
-            this.pollTimer = null;
-        }
+        this.rws?.stop();
+        this.rws = null;
+        this.wsConnected = false;
+        this.stopPolling();
     }
     dispatchPrompt(prompt) {
         if (this.processedIds.has(prompt.id)) {
@@ -43,113 +40,78 @@ export class PromptListener {
         }
         this.handler(prompt);
     }
-    async connectSSE() {
-        while (!this.stopped) {
-            try {
-                this.sseAbort = new AbortController();
-                const url = `${this.config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/events/stream?topic=prompts`;
-                dbg(`[sse] Connecting to ${url}`);
-                const response = await fetch(url, {
-                    headers: {
-                        "Accept": "text/event-stream",
-                        "x-zhihand-controller-token": this.config.controllerToken,
-                    },
-                    signal: this.sseAbort.signal,
-                });
-                if (!response.ok) {
-                    dbg(`[sse] Connect failed: ${response.status} ${response.statusText}`);
-                    throw new Error(`SSE connect failed: ${response.status}`);
-                }
-                this.sseConnected = true;
+    connectWS() {
+        if (this.stopped)
+            return;
+        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/ws?topic=prompts`;
+        dbg(`[ws] Connecting to ${wsUrl}`);
+        this.rws = new ReconnectingWebSocket({
+            url: wsUrl,
+            headers: {
+                "Authorization": `Bearer ${this.config.controllerToken}`,
+            },
+            onOpen: () => {
+                this.wsConnected = true;
                 this.stopPolling();
-                this.log("[sse] Connected to prompt stream.");
-                const reader = response.body?.getReader();
-                if (!reader)
-                    throw new Error("No response body for SSE");
-                const decoder = new TextDecoder();
-                let buffer = "";
-                let watchdog = this.resetWatchdog();
-                try {
-                    while (!this.stopped) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        // Reset watchdog on any data (including keepalive comments)
-                        clearTimeout(watchdog);
-                        watchdog = this.resetWatchdog();
-                        buffer += decoder.decode(value, { stream: true });
-                        const lines = buffer.split("\n");
-                        buffer = lines.pop() ?? "";
-                        let eventData = "";
-                        for (const line of lines) {
-                            if (line.startsWith("data: ")) {
-                                eventData += (eventData ? "\n" : "") + line.slice(6);
-                            }
-                            else if (line === "" && eventData) {
-                                try {
-                                    const event = JSON.parse(eventData);
-                                    this.handleSSEEvent(event);
-                                }
-                                catch {
-                                    // Malformed event
-                                }
-                                eventData = "";
-                            }
-                        }
-                    }
-                }
-                finally {
-                    // Always clear watchdog — prevents leaked timer from aborting next connection
-                    clearTimeout(watchdog);
+                this.log("[ws] Connected to prompt stream.");
+            },
+            onClose: (_code, _reason) => {
+                if (this.wsConnected) {
+                    this.wsConnected = false;
+                    this.log("[ws] Disconnected. Falling back to polling.");
+                    this.startPolling();
                 }
-            }
-            catch (err) {
-                if (this.stopped)
-                    break;
-                this.sseConnected = false;
-                this.log(`[sse] Disconnected. Falling back to polling. (${err.message})`);
-                this.startPolling();
-                await new Promise((r) => setTimeout(r, SSE_RECONNECT_DELAY));
-            }
-        }
+            },
+            onMessage: (data) => {
+                this.handleWSMessage(data);
+            },
+            onError: (err) => {
+                dbg(`[ws] Error: ${err.message}`);
+            },
+        });
+        this.rws.start();
     }
-    resetWatchdog() {
-        return setTimeout(() => {
-            this.log("[sse] Watchdog timeout (120s no data). Reconnecting...");
-            this.sseAbort?.abort();
-        }, SSE_WATCHDOG_TIMEOUT);
+    handleWSMessage(data) {
+        const msg = data;
+        // Application-level ping (if server sends these alongside protocol pings)
+        if (msg.type === "ping") {
+            this.rws?.send(JSON.stringify({ type: "pong" }));
+            return;
+        }
+        // Event dispatch
+        if (msg.type === "event" || msg.kind) {
+            this.handleEvent(msg);
+        }
     }
-    handleSSEEvent(event) {
-        dbg(`[sse] Event: kind=${event.kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
-        if (event.kind === "prompt.queued" && event.prompt) {
+    handleEvent(event) {
+        const kind = event.kind;
+        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
+        if (kind === "prompt.queued" && event.prompt) {
             this.dispatchPrompt(event.prompt);
         }
-        else if (event.kind === "prompt.snapshot" && event.prompts) {
+        else if (kind === "prompt.snapshot" && event.prompts) {
             for (const p of event.prompts) {
                 if (p.status === "pending" || p.status === "processing") {
                     this.dispatchPrompt(p);
                 }
             }
         }
-        else if (event.kind === "device_profile.updated" && event.device_profile) {
-            // Registry owns device-profile updates; this listener is only for prompts.
+        else if (kind === "device_profile.updated") {
             this.log("[device] device_profile.updated event received on prompts stream (ignored; registry handles it)");
         }
     }
     startPolling() {
-        if (this.pollTimer)
+        if (this.pollTimer || this.stopped)
             return;
         this.schedulePoll();
     }
-    /** Recursive setTimeout: waits for fetch to complete before scheduling next poll. */
     schedulePoll() {
         if (this.pollTimer)
             return;
         this.pollTimer = setTimeout(async () => {
             this.pollTimer = null;
             await this.poll();
-            // Schedule next poll only if SSE is still disconnected
-            if (!this.sseConnected && !this.stopped) {
+            if (!this.wsConnected && !this.stopped) {
                 this.schedulePoll();
             }
         }, POLL_INTERVAL);
@@ -165,7 +127,7 @@ export class PromptListener {
             const url = `${this.config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/prompts?limit=5`;
             dbg(`[poll] GET ${url}`);
             const response = await fetch(url, {
-                headers: { "x-zhihand-controller-token": this.config.controllerToken },
+                headers: { "Authorization": `Bearer ${this.config.controllerToken}` },
                 signal: AbortSignal.timeout(10_000),
             });
             if (!response.ok) {
@@ -174,6 +136,8 @@ export class PromptListener {
             }
             const data = (await response.json());
             dbg(`[poll] Got ${data.items?.length ?? 0} prompt(s)`);
+            if (this.stopped)
+                return; // Guard against late responses after stop()
             for (const prompt of data.items ?? []) {
                 this.dispatchPrompt(prompt);
             }

package/dist/index.d.ts

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

package/dist/index.js

@@ -6,9 +6,9 @@ import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
 import { resolveTargetDevice } from "./tools/resolve.js";
-import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, extractDynamic, } from "./core/device.js";
 import { registry } from "./core/registry.js";
-export const PACKAGE_VERSION = "0.30.0";
+export const PACKAGE_VERSION = "0.31.0";
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
@@ -17,7 +17,8 @@ export function createServer() {
         name: "zhihand",
         version: PACKAGE_VERSION,
     });
-    const controlTool = server.tool("zhihand_control", buildControlToolDescription(null, registry.listOnline()), controlSchema, async (params) => {
+    const multiUser = registry.isMultiUser();
+    const controlTool = server.tool("zhihand_control", buildControlToolDescription(null, registry.listOnline(), multiUser), controlSchema, async (params) => {
         const resolved = resolveTargetDevice(params.device_id);
         if ("error" in resolved)
             return errorResult(resolved.error);
@@ -26,7 +27,7 @@ export function createServer() {
         const platform = state.profile?.platform ?? "unknown";
         return await executeControl(cfg, params, platform, state.capabilities);
     });
-    const systemTool = server.tool("zhihand_system", buildSystemToolDescription(null, registry.listOnline()), systemSchema, async (params) => {
+    const systemTool = server.tool("zhihand_system", buildSystemToolDescription(null, registry.listOnline(), multiUser), systemSchema, async (params) => {
         const resolved = resolveTargetDevice(params.device_id);
         if ("error" in resolved)
             return errorResult(resolved.error);
@@ -35,7 +36,7 @@ export function createServer() {
         const platform = state.profile?.platform ?? "unknown";
         return await executeSystem(cfg, params, platform);
     });
-    const screenshotTool = server.tool("zhihand_screenshot", buildScreenshotToolDescription(null, registry.listOnline()), screenshotSchema, async (params) => {
+    const screenshotTool = server.tool("zhihand_screenshot", buildScreenshotToolDescription(null, registry.listOnline(), multiUser), screenshotSchema, async (params) => {
         const resolved = resolveTargetDevice(params.device_id);
         if ("error" in resolved)
             return errorResult(resolved.error);
@@ -54,14 +55,17 @@ export function createServer() {
                 }],
         };
     });
-    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();
+    server.tool("zhihand_list_devices", "List ALL configured ZhiHand devices with their online status. Returns device_id, label, platform, online, battery, is_default, last_active for each. Call this before zhihand_control/system/screenshot/status when multiple devices may be online.", listDevicesSchema, async () => {
+        const mu = registry.isMultiUser();
+        const defaultDev = registry.resolveDefault();
         const devices = registry.list().map((d) => ({
-            credential_id: d.credentialId,
-            label: d.label,
+            device_id: d.credentialId,
+            label: mu ? `[${d.userLabel}] ${d.label}` : d.label,
             platform: d.platform,
             online: d.online,
-            last_seen_ms_ago: d.lastSeenAtMs > 0 ? now - d.lastSeenAtMs : -1,
+            battery: d.rawAttributes ? extractDynamic(d.rawAttributes).batteryLevel : null,
+            is_default: d === defaultDev,
+            last_active: d.lastSeenAtMs > 0 ? new Date(d.lastSeenAtMs).toISOString() : null,
         }));
         return {
             content: [{
@@ -74,21 +78,19 @@ export function createServer() {
         return await handlePair(params);
     });
     // 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();
+        const mu = registry.isMultiUser();
         try {
-            controlTool.update({ description: buildControlToolDescription(null, online) });
+            controlTool.update({ description: buildControlToolDescription(null, online, mu) });
         }
         catch { /* best-effort */ }
         try {
-            systemTool.update({ description: buildSystemToolDescription(null, online) });
+            systemTool.update({ description: buildSystemToolDescription(null, online, mu) });
         }
         catch { /* best-effort */ }
         try {
-            screenshotTool.update({ description: buildScreenshotToolDescription(null, online) });
+            screenshotTool.update({ description: buildScreenshotToolDescription(null, online, mu) });
         }
         catch { /* best-effort */ }
         try {

package/dist/tools/control.js

@@ -1,6 +1,6 @@
 import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
 import { fetchScreenshot } from "../core/screenshot.js";
-import { waitForCommandAck } from "../core/sse.js";
+import { waitForCommandAck } from "../core/ws.js";
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }

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,29 +1,26 @@
-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() {
-    return `${DEFAULT_EDGE_ID_PREFIX}${Date.now().toString(36)}`;
-}
-export async function handlePair(params, endpoint) {
-    const resolvedEndpoint = endpoint ?? DEFAULT_ENDPOINT;
-    if (!params.forceNew) {
-        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") }] };
-        }
+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") }] };
     }
-    const stableIdentity = generateEdgeId();
-    const plugin = await registerPlugin(resolvedEndpoint, { stableIdentity });
-    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/system.js

@@ -1,5 +1,5 @@
 import { createSystemCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
-import { waitForCommandAck } from "../core/sse.js";
+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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.30.0",
+  "version": "0.32.1",
   "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"
   }
 }