@zhihand/mcp 0.15.0 → 0.16.3

package/README.md

@@ -2,22 +2,30 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.15.0`
+Version: `0.16.0`
 
 ## What is this?
 
-`@zhihand/mcp` is the core integration layer for ZhiHand. It provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes phone control tools to any compatible AI agent, including:
+`@zhihand/mcp` is the core integration layer for ZhiHand. It runs as a **persistent daemon** that exposes phone control tools to any compatible AI agent via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/), including:
 
 - **Claude Code**
 - **Codex CLI**
 - **Gemini CLI**
 - **OpenClaw**
 
-One npm package, two entry points:
+The daemon is a single persistent process that bundles three subsystems:
+
+| Subsystem | Purpose |
+|---|---|
+| **MCP Server** | HTTP Streamable transport on `localhost:18686/mcp` — serves tool calls to AI agents |
+| **Relay** | Brain heartbeat (30s), prompt listener (phone-initiated tasks), CLI dispatch |
+| **Config API** | IPC endpoint for `zhihand gemini/claude/codex` backend switching |
+
+Legacy entry points (backward compatible):
 
 | Entry | Purpose |
 |---|---|
-| `zhihand serve` | MCP Server (stdio) — used by Claude Code, Codex, Gemini CLI |
+| `zhihand serve` | MCP Server (stdio mode) — legacy, still works for direct CLI integration |
 | `zhihand.openclaw` | OpenClaw Plugin entry — thin wrapper calling the same core |
 
 ## Requirements
@@ -53,10 +61,20 @@ This runs the full interactive setup:
 4. Saves credentials to `~/.zhihand/credentials.json`
 5. Detects installed CLI tools (Claude Code, Codex, Gemini CLI, OpenClaw)
 6. Auto-selects the best available tool and configures MCP automatically
+7. Starts the daemon (MCP Server + Relay + Config API)
 
 No manual MCP configuration needed — `zhihand setup` handles everything.
 
-### 2. Start using it
+### 2. Start the daemon
+
+```bash
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background (detached)
+```
+
+The daemon runs the MCP Server on `localhost:18686/mcp` (HTTP Streamable transport), maintains a brain heartbeat every 30 seconds (keeps the phone Brain indicator green), and listens for phone-initiated prompts.
+
+### 3. Start using it
 
 Once configured, your AI agent can use ZhiHand tools directly. For example, in Claude Code:
 
@@ -70,18 +88,36 @@ Once configured, your AI agent can use ZhiHand tools directly. For example, in C
 ## CLI Commands
 
 ```
-zhihand serve              Start MCP Server (stdio mode, called by AI tools)
-zhihand setup              Interactive setup: pair + auto-detect + auto-configure
+zhihand setup              Interactive setup: pair + detect tools + auto-select + configure MCP + start daemon
+zhihand start              Start daemon (MCP Server + Relay + Config API)
+zhihand start -d           Start daemon in background (detached)
+zhihand stop               Stop the running daemon
+zhihand status             Show daemon status, pairing info, device, and active backend
+
 zhihand pair               Pair with a phone (QR code in terminal)
-zhihand status             Show pairing status, device info, and active backend
 zhihand detect             List detected CLI tools and their login status
+zhihand serve              Start MCP Server (stdio mode, backward compatible)
 zhihand --help             Show help
 
-zhihand claude             Switch backend to Claude Code (auto-configures MCP)
-zhihand codex              Switch backend to Codex CLI (auto-configures MCP)
-zhihand gemini             Switch backend to Gemini CLI (auto-configures MCP)
+zhihand claude             Switch backend to Claude Code (sends IPC to daemon, auto-configures MCP)
+zhihand codex              Switch backend to Codex CLI (sends IPC to daemon, auto-configures MCP)
+zhihand gemini             Switch backend to Gemini CLI (sends IPC to daemon, auto-configures MCP)
 ```
 
+### Daemon Lifecycle
+
+```bash
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background
+zhihand stop               # Stop the daemon
+zhihand status             # Check if daemon is running, show device & backend info
+```
+
+The daemon is a single persistent process that runs:
+- **MCP Server** on `localhost:18686/mcp` (HTTP Streamable transport)
+- **Relay**: brain heartbeat every 30s (keeps phone Brain indicator green), prompt listener (phone-initiated tasks dispatched to CLI), CLI dispatch
+- **Config API**: IPC endpoint for backend switching
+
 ### Switching Backends
 
 Use `zhihand claude`, `zhihand codex`, or `zhihand gemini` to switch the active backend:
@@ -93,6 +129,7 @@ zhihand codex              # Switch to Codex CLI
 ```
 
 When you switch:
+- The command sends an **IPC message to the running daemon**
 - MCP config is **automatically added** to the new backend
 - MCP config is **automatically removed** from the previous backend
 - If the tool is not installed, an error is shown
@@ -154,26 +191,40 @@ Pair with a phone device. Returns a QR code and pairing URL.
 ## How It Works
 
 ```
-AI Agent ←stdio→ zhihand serve (MCP Server)
-                       │
-                       ├── POST /v1/plugins           Register plugin
-                       ├── POST /v1/pairing/sessions   Create pairing
-                       ├── POST /v1/credentials/{id}/commands   Send command
-                       ├── GET  /v1/credentials/{id}/commands/{cid}   Poll ACK
-                       ├── SSE  /v1/credentials/{id}/events?topic=commands   Real-time ACK
-                       └── GET  /v1/credentials/{id}/screen   Fetch screenshot (JPEG)
-                       │
-                  ZhiHand Server
-                       │
-                  ZhiHand Mobile App
+AI Agent ←HTTP Streamable→ Daemon (localhost:18686/mcp)
+                               │
+                               ├── MCP Server ──→ ZhiHand Server ──→ Mobile App
+                               │     (tool calls: control, screenshot, pair)
+                               │
+                               ├── Relay
+                               │     ├── Brain heartbeat (30s) ──→ Server
+                               │     ├── Prompt listener (SSE) ←── Server ←── Phone
+                               │     └── CLI dispatch ──→ spawn claude/codex/gemini
+                               │
+                               └── Config API
+                                     └── IPC from zhihand claude/codex/gemini
 ```
 
+### Agent-initiated flow (tool calls)
+
 1. AI agent calls a tool (e.g. `zhihand_control` with `action: "click"`)
 2. MCP Server translates to a device command and enqueues it via the ZhiHand API
 3. Mobile app picks up the command, executes it, and sends an ACK
 4. MCP Server receives the ACK (via SSE or polling fallback)
 5. MCP Server fetches a fresh screenshot and returns it to the AI agent
 
+### Phone-initiated flow (prompt relay)
+
+1. User speaks or types a prompt on the phone
+2. Phone sends prompt to ZhiHand Server
+3. Daemon receives prompt via SSE
+4. Daemon spawns the active CLI tool (e.g. `claude`, `codex`, `gemini`) with the prompt
+5. CLI tool executes, result is sent back to the phone
+
+### Brain heartbeat
+
+The daemon sends a heartbeat to the ZhiHand Server every 30 seconds. This keeps the **Brain indicator green** on the phone, showing the user that an AI backend is connected and ready.
+
 Screenshots are transferred as raw JPEG binary and only base64-encoded at the LLM API boundary, minimizing bandwidth.
 
 ## Credential Storage
@@ -184,6 +235,7 @@ Pairing credentials are stored at:
 ~/.zhihand/
 ├── credentials.json    # Device credentials (credentialId, controllerToken, endpoint)
 ├── backend.json        # Active backend selection (claudecode/codex/gemini)
+├── daemon.pid          # Daemon PID file (for zhihand stop)
 └── state.json          # Current pairing session state
 ```
 
@@ -209,10 +261,10 @@ You can manage multiple devices. The `credentials.json` file stores a `default`
 ```
 packages/mcp/
 ├── bin/
-│   ├── zhihand              # Main CLI entry (serve/setup/pair/status/detect)
+│   ├── zhihand              # Main CLI entry (start/stop/status/setup/serve/pair/detect)
 │   └── zhihand.openclaw     # OpenClaw plugin entry
 ├── src/
-│   ├── index.ts             # MCP Server (stdio transport)
+│   ├── index.ts             # MCP Server (stdio transport, legacy)
 │   ├── openclaw.adapter.ts  # OpenClaw Plugin adapter (thin wrapper)
 │   ├── core/
 │   │   ├── config.ts        # Credential & config management (~/.zhihand/)
@@ -220,6 +272,11 @@ packages/mcp/
 │   │   ├── 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
+│   │   ├── 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)
 │   ├── tools/
 │   │   ├── schemas.ts       # Zod parameter schemas
 │   │   ├── control.ts       # zhihand_control handler

package/bin/zhihand

@@ -3,6 +3,7 @@
 import os from "node:os";
 import { parseArgs } from "node:util";
 import { startStdioServer } from "../dist/index.js";
+import { startDaemon, stopDaemon, isAlreadyRunning } from "../dist/daemon/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
 import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
 import { loadDefaultCredential, loadBackendConfig, saveBackendConfig } from "../dist/core/config.js";
@@ -22,9 +23,9 @@ const { positionals, values } = parseArgs({
   strict: false,
   options: {
     device: { type: "string" },
-    model: { type: "string" },
-    http: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
+    detach: { type: "boolean", short: "d", default: false },
+    port: { type: "string" },
   },
 });
 
@@ -32,28 +33,35 @@ const command = positionals[0] ?? "serve";
 
 if (values.help) {
   console.log(`
-zhihand — MCP Server for phone control
+zhihand — MCP Server and Relay for phone control
 
 Usage:
-  zhihand serve              Start MCP Server (stdio mode)
-  zhihand serve --http       Start MCP Server (HTTP mode)
-  zhihand pair               Pair with a phone device
-  zhihand status             Show pairing status and device info
-  zhihand detect             Detect available CLI tools
-  zhihand setup              Interactive setup: pair + auto-configure
+  zhihand start              Start daemon (MCP Server + Relay, foreground)
+  zhihand start -d           Start daemon in background (detach)
+  zhihand stop               Stop daemon
+  zhihand status             Show status (pairing, backend, brain)
 
+  zhihand gemini             Switch backend to Gemini CLI
   zhihand claude             Switch backend to Claude Code
   zhihand codex              Switch backend to Codex CLI
-  zhihand gemini             Switch backend to Gemini CLI
+
+  zhihand setup              Interactive setup: pair + configure + start
+  zhihand pair               Pair with a phone device
+  zhihand detect             Detect available CLI tools
+
+  zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
   --device <name>    Use a specific paired device
+  --port <port>      Override daemon port (default: 18686)
+  -d, --detach       Run daemon in background
   -h, --help         Show this help
 `);
   process.exit(0);
 }
 
-// Handle CLI tool subcommands: claude, codex, gemini → switch backend
+// ── Backend switch commands: claude, codex, gemini ─────────
+
 if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
   const backendName = CLI_TOOL_MAP[command];
   const tools = await detectCLITools();
@@ -69,6 +77,8 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
     console.error(`Warning: ${command} is installed but not logged in.`);
   }
 
+  // Check if daemon is running — if so, notify it via HTTP
+  const daemonPid = isAlreadyRunning();
   const config = loadBackendConfig();
   const previous = config.activeBackend;
 
@@ -78,20 +88,82 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
   }
 
   console.log(`Switching backend to ${displayName(backendName)}...`);
+
+  // Configure MCP (HTTP transport)
   const { configured, removed } = configureMCP(backendName, previous);
 
   if (configured) {
-    saveBackendConfig({ activeBackend: backendName });
-    console.log(`\nBackend switched to ${displayName(backendName)}.`);
-    if (previous) {
-      console.log(`Previous backend: ${displayName(previous)} ${removed ? '(MCP config removed)' : '(MCP config removal skipped)'}.`);
+    // Notify daemon if running
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/backend`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ backend: backendName }),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok) {
+          console.log(`\nDaemon notified. Backend switched to ${displayName(backendName)}.`);
+        }
+      } catch {
+        // Daemon not responding, just save config
+        saveBackendConfig({ activeBackend: backendName });
+        console.log(`\nBackend config saved. Daemon not responding — restart with 'zhihand start'.`);
+      }
+    } else {
+      saveBackendConfig({ activeBackend: backendName });
+      console.log(`\nBackend switched to ${displayName(backendName)}.`);
+      console.log(`Start the daemon to receive prompts: zhihand start`);
+    }
+
+    if (previous && removed) {
+      console.log(`Previous backend: ${displayName(previous)} (MCP config removed).`);
     }
   }
   process.exit(0);
 }
 
+// ── Other commands ─────────────────────────────────────────
+
 switch (command) {
+  case "start":
+  case "relay": {
+    if (values.detach) {
+      const { spawn: spawnChild } = await import("node:child_process");
+      const args = [process.argv[1], "start"];
+      if (values.port) args.push("--port", values.port);
+      if (values.device) args.push("--device", values.device);
+
+      const child = spawnChild(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env },
+      });
+      child.unref();
+      console.log(`Daemon starting in background (PID ${child.pid}).`);
+      process.exit(0);
+    }
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
+    break;
+  }
+
+  case "stop": {
+    const stopped = stopDaemon();
+    if (stopped) {
+      console.log("Daemon stopped.");
+    } else {
+      console.log("No daemon is running.");
+    }
+    break;
+  }
+
   case "serve": {
+    // Backward compatible: stdio MCP server (for old configs)
     await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
     break;
   }
@@ -106,18 +178,31 @@ switch (command) {
   case "status": {
     const cred = loadDefaultCredential();
     const backend = loadBackendConfig();
+    const daemonPid = isAlreadyRunning();
+
     if (cred) {
       console.log(`Paired device: ${cred.deviceName}`);
       console.log(`Credential ID: ${cred.credentialId}`);
       console.log(`Endpoint: ${cred.endpoint}`);
-      console.log(`Paired at: ${cred.pairedAt}`);
     } else {
-      console.log("No paired device. Run: zhihand pair");
+      console.log("No paired device. Run: zhihand setup");
     }
-    if (backend.activeBackend) {
-      console.log(`Active backend: ${displayName(backend.activeBackend)}`);
-    } else {
-      console.log("No active backend. Run: zhihand claude / zhihand gemini / zhihand codex");
+    console.log(`Active backend: ${backend.activeBackend ? displayName(backend.activeBackend) : "(none)"}`);
+    console.log(`Daemon: ${daemonPid ? `running (PID ${daemonPid})` : "not running"}`);
+
+    // If daemon running, get live status
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/status`, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+          const status = await res.json();
+          console.log(`Processing: ${status.processing ? "yes" : "idle"}`);
+          console.log(`Queue: ${status.queueLength} prompt(s)`);
+        }
+      } catch { /* daemon not responding */ }
     }
     break;
   }
@@ -129,7 +214,7 @@ switch (command) {
   }
 
   case "setup": {
-    // 1. Check/create pairing
+    // 1. Pair
     let cred = loadDefaultCredential();
     if (!cred) {
       console.log("No paired device found. Starting pairing...\n");
@@ -142,30 +227,34 @@ switch (command) {
       console.log(`\nPaired: ${cred.deviceName} (${cred.credentialId})\n`);
     }
 
-    // 2. Detect CLI tools
+    // 2. Detect tools
     const tools = await detectCLITools();
     console.log(formatDetectedTools(tools));
 
     if (tools.length === 0) {
-      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI, OpenClaw.");
+      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI.");
       break;
     }
 
-    // 3. Auto-select best tool (logged in + highest priority) and configure
+    // 3. Auto-select best tool and configure MCP (HTTP transport)
     const best = tools.find((t) => t.loggedIn) ?? tools[0];
     const config = loadBackendConfig();
 
     console.log(`\nAuto-selecting backend: ${displayName(best.name)}...`);
-
-    if (best.name === "openclaw") {
-      await detectAndSetupOpenClaw();
-    } else {
-      configureMCP(best.name, config.activeBackend);
+    // Ensure MCP URL uses correct port
+    if (values.port) {
+      process.env.ZHIHAND_PORT = values.port;
     }
-
+    configureMCP(best.name, config.activeBackend);
     saveBackendConfig({ activeBackend: best.name });
-    console.log(`\nSetup complete. Backend: ${displayName(best.name)}.`);
-    console.log(`To switch backend later: zhihand claude / zhihand gemini / zhihand codex`);
+
+    // 4. Start daemon
+    console.log(`\nStarting daemon...\n`);
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
     break;
   }
 

package/dist/cli/mcp-config.d.ts

@@ -1,6 +1,6 @@
 import type { BackendName } from "../core/config.ts";
 /**
- * Configure MCP for the selected backend and remove from others.
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
  */
 export declare function configureMCP(backend: BackendName, previousBackend: BackendName | null): {
     configured: boolean;

package/dist/cli/mcp-config.js

@@ -1,15 +1,20 @@
 import { execSync } from "node:child_process";
+const DEFAULT_PORT = 18686;
+function mcpUrl() {
+    const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT;
+    return `http://localhost:${port}/mcp`;
+}
 const MCP_COMMANDS = {
     claudecode: {
-        add: "claude mcp add zhihand -- zhihand serve",
+        add: () => `claude mcp add --transport http zhihand ${mcpUrl()}`,
         remove: "claude mcp remove zhihand",
     },
     codex: {
-        add: "codex mcp add zhihand -- zhihand serve",
+        add: () => `codex mcp add zhihand --url ${mcpUrl()}`,
         remove: "codex mcp remove zhihand",
     },
     gemini: {
-        add: "gemini mcp add --scope user zhihand zhihand -- serve",
+        add: () => `gemini mcp add --transport http --scope user zhihand ${mcpUrl()}`,
         remove: "gemini mcp remove --scope user zhihand",
     },
 };
@@ -29,7 +34,7 @@ function tryRun(cmd) {
     }
 }
 /**
- * Configure MCP for the selected backend and remove from others.
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
  */
 export function configureMCP(backend, previousBackend) {
     let removed = false;
@@ -49,9 +54,10 @@ export function configureMCP(backend, previousBackend) {
     }
     else {
         const cmds = MCP_COMMANDS[backend];
-        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]}...`);
+        const addCmd = cmds.add();
+        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]} (HTTP transport)...`);
         try {
-            execSync(cmds.add, { stdio: "inherit", timeout: 10_000 });
+            execSync(addCmd, { stdio: "inherit", timeout: 10_000 });
             configured = true;
         }
         catch (err) {

package/dist/daemon/dispatcher.d.ts

@@ -0,0 +1,13 @@
+import type { ZhiHandConfig, BackendName } from "../core/config.ts";
+export interface DispatchResult {
+    text: string;
+    success: boolean;
+    durationMs: number;
+}
+/**
+ * Kill the active child process. Returns a promise that resolves
+ * when the child has exited (or immediately if no child).
+ */
+export declare function killActiveChild(): Promise<void>;
+export declare function dispatchToCLI(backend: Exclude<BackendName, "openclaw">, prompt: string, log: (msg: string) => void, model?: string): Promise<DispatchResult>;
+export declare function postReply(config: ZhiHandConfig, promptId: string, text: string): Promise<boolean>;