@zhihand/mcp 0.12.3 → 0.15.0

package/README.md

@@ -2,7 +2,7 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.12.1`
+Version: `0.15.0`
 
 ## What is this?
 
@@ -39,7 +39,7 @@ npx @zhihand/mcp serve
 
 ## Quick Start
 
-### 1. Pair your phone
+### 1. Setup and pair
 
 ```bash
 zhihand setup
@@ -52,64 +52,11 @@ This runs the full interactive setup:
 3. Waits for you to scan the QR code with the ZhiHand mobile app
 4. Saves credentials to `~/.zhihand/credentials.json`
 5. Detects installed CLI tools (Claude Code, Codex, Gemini CLI, OpenClaw)
-6. Prints the MCP configuration snippet for your tools
+6. Auto-selects the best available tool and configures MCP automatically
 
-### 2. Configure your AI tool
+No manual MCP configuration needed — `zhihand setup` handles everything.
 
-Add the ZhiHand MCP server to your tool's configuration:
-
-**Claude Code** — Add to `.mcp.json` in your project root, or run:
-
-```bash
-claude mcp add zhihand -- zhihand serve
-```
-
-Or manually create/edit `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**Codex CLI** — Add to your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**Gemini CLI** — Add to `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zhihand": {
-      "command": "zhihand",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-**OpenClaw** — Install the plugin directly:
-
-```bash
-openclaw plugins install @zhihand/mcp
-```
-
-### 3. Start using it
+### 2. Start using it
 
 Once configured, your AI agent can use ZhiHand tools directly. For example, in Claude Code:
 
@@ -124,13 +71,32 @@ Once configured, your AI agent can use ZhiHand tools directly. For example, in C
 
 ```
 zhihand serve              Start MCP Server (stdio mode, called by AI tools)
-zhihand setup              Interactive setup: pair + detect tools + print config
+zhihand setup              Interactive setup: pair + auto-detect + auto-configure
 zhihand pair               Pair with a phone (QR code in terminal)
-zhihand status             Show current pairing status and device info
+zhihand status             Show pairing status, device info, and active backend
 zhihand detect             List detected CLI tools and their login status
 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)
+```
+
+### Switching Backends
+
+Use `zhihand claude`, `zhihand codex`, or `zhihand gemini` to switch the active backend:
+
+```bash
+zhihand gemini             # Switch to Gemini CLI
+zhihand claude             # Switch to Claude Code
+zhihand codex              # Switch to Codex CLI
 ```
 
+When you switch:
+- 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
+
 ### Options
 
 | Option | Description |
@@ -217,6 +183,7 @@ Pairing credentials are stored at:
 ```
 ~/.zhihand/
 ├── credentials.json    # Device credentials (credentialId, controllerToken, endpoint)
+├── backend.json        # Active backend selection (claudecode/codex/gemini)
 └── state.json          # Current pairing session state
 ```
 
@@ -261,6 +228,7 @@ packages/mcp/
 │   └── cli/
 │       ├── detect.ts        # CLI tool detection (Claude Code, Codex, Gemini, OpenClaw)
 │       ├── spawn.ts         # CLI process spawning (for mobile-initiated tasks)
+│       ├── mcp-config.ts    # MCP auto-configuration (add/remove per backend)
 │       └── openclaw.ts      # OpenClaw auto-detect & plugin install
 ├── dist/                    # Compiled JavaScript (shipped in npm package)
 ├── package.json

package/bin/zhihand

@@ -5,15 +5,24 @@ import { parseArgs } from "node:util";
 import { startStdioServer } from "../dist/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
 import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
-import { loadDefaultCredential } from "../dist/core/config.js";
+import { loadDefaultCredential, loadBackendConfig, saveBackendConfig } from "../dist/core/config.js";
 import { executePairing } from "../dist/core/pair.js";
+import { configureMCP, displayName } from "../dist/cli/mcp-config.js";
 
 const DEFAULT_ENDPOINT = "https://api.zhihand.com";
 
+const CLI_TOOL_MAP = {
+  claude: "claudecode",
+  codex: "codex",
+  gemini: "gemini",
+};
+
 const { positionals, values } = parseArgs({
   allowPositionals: true,
+  strict: false,
   options: {
     device: { type: "string" },
+    model: { type: "string" },
     http: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -31,7 +40,11 @@ Usage:
   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 + configure
+  zhihand setup              Interactive setup: pair + auto-configure
+
+  zhihand claude             Switch backend to Claude Code
+  zhihand codex              Switch backend to Codex CLI
+  zhihand gemini             Switch backend to Gemini CLI
 
 Options:
   --device <name>    Use a specific paired device
@@ -40,6 +53,43 @@ Options:
   process.exit(0);
 }
 
+// Handle CLI tool subcommands: claude, codex, gemini → switch backend
+if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
+  const backendName = CLI_TOOL_MAP[command];
+  const tools = await detectCLITools();
+  const tool = tools.find((t) => t.name === backendName);
+
+  if (!tool) {
+    console.error(`Error: ${command} is not installed or not found in PATH.`);
+    console.error(`Install it first, then try again.`);
+    process.exit(1);
+  }
+
+  if (!tool.loggedIn) {
+    console.error(`Warning: ${command} is installed but not logged in.`);
+  }
+
+  const config = loadBackendConfig();
+  const previous = config.activeBackend;
+
+  if (previous === backendName) {
+    console.log(`Already using ${displayName(backendName)} as backend.`);
+    process.exit(0);
+  }
+
+  console.log(`Switching backend to ${displayName(backendName)}...`);
+  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)'}.`);
+    }
+  }
+  process.exit(0);
+}
+
 switch (command) {
   case "serve": {
     await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
@@ -55,6 +105,7 @@ switch (command) {
 
   case "status": {
     const cred = loadDefaultCredential();
+    const backend = loadBackendConfig();
     if (cred) {
       console.log(`Paired device: ${cred.deviceName}`);
       console.log(`Credential ID: ${cred.credentialId}`);
@@ -63,6 +114,11 @@ switch (command) {
     } else {
       console.log("No paired device. Run: zhihand pair");
     }
+    if (backend.activeBackend) {
+      console.log(`Active backend: ${displayName(backend.activeBackend)}`);
+    } else {
+      console.log("No active backend. Run: zhihand claude / zhihand gemini / zhihand codex");
+    }
     break;
   }
 
@@ -90,11 +146,26 @@ switch (command) {
     const tools = await detectCLITools();
     console.log(formatDetectedTools(tools));
 
-    // 3. Setup OpenClaw if present
-    await detectAndSetupOpenClaw();
+    if (tools.length === 0) {
+      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI, OpenClaw.");
+      break;
+    }
+
+    // 3. Auto-select best tool (logged in + highest priority) and configure
+    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);
+    }
 
-    console.log("\nSetup complete. Add to your CLI tool's MCP config:");
-    console.log('  { "mcpServers": { "zhihand": { "command": "zhihand", "args": ["serve"] } } }');
+    saveBackendConfig({ activeBackend: best.name });
+    console.log(`\nSetup complete. Backend: ${displayName(best.name)}.`);
+    console.log(`To switch backend later: zhihand claude / zhihand gemini / zhihand codex`);
     break;
   }
 

package/dist/cli/detect.js

@@ -30,8 +30,10 @@ async function detectGemini() {
     if (!isCommandAvailable("gemini"))
         return null;
     const version = tryExec("gemini --version") ?? "unknown";
-    // Check login: Google Cloud auth
-    const loggedIn = tryExec("gemini auth status") !== null;
+    // Check login: oauth_creds.json or GOOGLE_API_KEY env var
+    const loggedIn = !!process.env.GOOGLE_API_KEY
+        || !!process.env.GEMINI_API_KEY
+        || tryExec("ls ~/.gemini/oauth_creds.json") !== null;
     return { name: "gemini", command: "gemini", version, loggedIn, priority: 3 };
 }
 async function detectOpenClaw() {

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

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

package/dist/cli/mcp-config.js

@@ -0,0 +1,65 @@
+import { execSync } from "node:child_process";
+const MCP_COMMANDS = {
+    claudecode: {
+        add: "claude mcp add zhihand -- zhihand serve",
+        remove: "claude mcp remove zhihand",
+    },
+    codex: {
+        add: "codex mcp add zhihand -- zhihand serve",
+        remove: "codex mcp remove zhihand",
+    },
+    gemini: {
+        add: "gemini mcp add --scope user zhihand zhihand -- serve",
+        remove: "gemini mcp remove --scope user zhihand",
+    },
+};
+const DISPLAY_NAMES = {
+    claudecode: "Claude Code",
+    codex: "Codex CLI",
+    gemini: "Gemini CLI",
+    openclaw: "OpenClaw",
+};
+function tryRun(cmd) {
+    try {
+        execSync(cmd, { stdio: "pipe", timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Configure MCP for the selected backend and remove from others.
+ */
+export function configureMCP(backend, previousBackend) {
+    let removed = false;
+    let configured = false;
+    // Remove from previous backend if different
+    if (previousBackend && previousBackend !== backend && previousBackend !== "openclaw") {
+        const cmds = MCP_COMMANDS[previousBackend];
+        if (cmds) {
+            console.log(`  Removing MCP config from ${DISPLAY_NAMES[previousBackend]}...`);
+            removed = tryRun(cmds.remove);
+        }
+    }
+    // Add to new backend
+    if (backend === "openclaw") {
+        console.log(`  OpenClaw uses plugin system. Run: openclaw plugins install @zhihand/mcp`);
+        configured = true;
+    }
+    else {
+        const cmds = MCP_COMMANDS[backend];
+        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]}...`);
+        try {
+            execSync(cmds.add, { stdio: "inherit", timeout: 10_000 });
+            configured = true;
+        }
+        catch (err) {
+            console.error(`  Failed to configure ${DISPLAY_NAMES[backend]}: ${err.message}`);
+        }
+    }
+    return { configured, removed };
+}
+export function displayName(backend) {
+    return DISPLAY_NAMES[backend];
+}

package/dist/cli/spawn.d.ts

@@ -1,2 +1,23 @@
 import type { CLITool } from "./detect.ts";
-export declare function spawnCLITask(tool: CLITool, prompt: string): Promise<string>;
+export interface SpawnOptions {
+    model?: string;
+    timeout?: number;
+}
+/**
+ * Spawn a CLI tool interactively, inheriting stdio.
+ * Returns the exit code.
+ */
+export declare function spawnInteractive(command: string, args: string[], options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+}): Promise<number>;
+/**
+ * Launch a CLI tool with a prompt. For Gemini, uses interactive mode (-i).
+ * For others, uses their respective prompt flags.
+ */
+export declare function launchCLI(tool: CLITool, prompt: string, options?: SpawnOptions): Promise<number>;
+/**
+ * Non-interactive spawn that captures output (for MCP-initiated tasks).
+ * Uses spawnSync with argument arrays to avoid shell injection.
+ */
+export declare function spawnCLITask(tool: CLITool, prompt: string): string;

package/dist/cli/spawn.js

@@ -1,31 +1,96 @@
-import { execSync } from "node:child_process";
-function shellEscape(s) {
-    return `'${s.replace(/'/g, "'\\''")}'`;
+import { spawn } from "node:child_process";
+/**
+ * Spawn a CLI tool interactively, inheriting stdio.
+ * Returns the exit code.
+ */
+export function spawnInteractive(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            env: { ...process.env, ...options?.env },
+        });
+        const timer = options?.timeout
+            ? setTimeout(() => {
+                child.kill("SIGTERM");
+                reject(new Error(`Process timed out after ${options.timeout}ms`));
+            }, options.timeout)
+            : undefined;
+        child.on("error", (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve(code ?? 1);
+        });
+    });
 }
-export async function spawnCLITask(tool, prompt) {
-    const escaped = shellEscape(prompt);
+/**
+ * Launch a CLI tool with a prompt. For Gemini, uses interactive mode (-i).
+ * For others, uses their respective prompt flags.
+ */
+export async function launchCLI(tool, prompt, options) {
+    const timeout = options?.timeout ?? 300_000;
+    switch (tool.name) {
+        case "claudecode": {
+            const args = ["-p", prompt, "--output-format", "json"];
+            return spawnInteractive(tool.command, args, { timeout });
+        }
+        case "codex": {
+            const args = ["-q", prompt, "--json"];
+            return spawnInteractive(tool.command, args, { timeout });
+        }
+        case "gemini": {
+            const model = options?.model ?? process.env.CLAUDE_GEMINI_MODEL ?? "gemini-3.1-pro-preview";
+            const args = [
+                "--approval-mode", "yolo",
+                "--model", model,
+                "-i", prompt,
+            ];
+            const env = {
+                GEMINI_SANDBOX: "false",
+                TERM: process.env.TERM ?? "xterm-256color",
+                COLORTERM: process.env.COLORTERM ?? "truecolor",
+            };
+            return spawnInteractive(tool.command, args, { timeout, env });
+        }
+        case "openclaw": {
+            const args = ["run", prompt];
+            return spawnInteractive(tool.command, args, { timeout });
+        }
+        default:
+            throw new Error(`Unsupported CLI tool: ${tool.name}`);
+    }
+}
+/**
+ * Non-interactive spawn that captures output (for MCP-initiated tasks).
+ * Uses spawnSync with argument arrays to avoid shell injection.
+ */
+export function spawnCLITask(tool, prompt) {
+    const { spawnSync } = require("node:child_process");
+    const opts = { encoding: "utf8", timeout: 300_000 };
+    let result;
     switch (tool.name) {
         case "claudecode":
-            return execSync(`${tool.command} -p ${escaped} --output-format json`, {
-                encoding: "utf8",
-                timeout: 300_000,
-            });
+            result = spawnSync(tool.command, ["-p", prompt, "--output-format", "json"], opts);
+            break;
         case "codex":
-            return execSync(`${tool.command} -q ${escaped} --json`, {
-                encoding: "utf8",
-                timeout: 300_000,
-            });
+            result = spawnSync(tool.command, ["-q", prompt, "--json"], opts);
+            break;
         case "gemini":
-            return execSync(`${tool.command} -p ${escaped}`, {
-                encoding: "utf8",
-                timeout: 300_000,
-            });
+            result = spawnSync(tool.command, ["--approval-mode", "yolo", "-p", prompt], opts);
+            break;
         case "openclaw":
-            return execSync(`${tool.command} run ${escaped}`, {
-                encoding: "utf8",
-                timeout: 300_000,
-            });
+            result = spawnSync(tool.command, ["run", prompt], opts);
+            break;
         default:
             throw new Error(`Unsupported CLI tool: ${tool.name}`);
     }
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(result.stderr || `Process exited with code ${result.status}`);
+    return result.stdout;
 }

package/dist/core/config.d.ts

@@ -16,6 +16,10 @@ export interface ZhiHandConfig {
     edgeId?: string;
     timeoutMs?: number;
 }
+export type BackendName = "claudecode" | "codex" | "gemini" | "openclaw";
+export interface BackendConfig {
+    activeBackend: BackendName | null;
+}
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
 export declare function loadCredentialStore(): CredentialStore | null;
@@ -24,3 +28,5 @@ export declare function saveCredential(name: string, cred: DeviceCredential, set
 export declare function resolveConfig(deviceName?: string): ZhiHandConfig;
 export declare function loadState<T = unknown>(): T | null;
 export declare function saveState(state: unknown): void;
+export declare function loadBackendConfig(): BackendConfig;
+export declare function saveBackendConfig(config: BackendConfig): void;

package/dist/core/config.js

@@ -4,11 +4,12 @@ import os from "node:os";
 const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
 const CREDENTIALS_PATH = path.join(ZHIHAND_DIR, "credentials.json");
 const STATE_PATH = path.join(ZHIHAND_DIR, "state.json");
+const BACKEND_PATH = path.join(ZHIHAND_DIR, "backend.json");
 export function resolveZhiHandDir() {
     return ZHIHAND_DIR;
 }
 export function ensureZhiHandDir() {
-    fs.mkdirSync(ZHIHAND_DIR, { recursive: true });
+    fs.mkdirSync(ZHIHAND_DIR, { recursive: true, mode: 0o700 });
 }
 export function loadCredentialStore() {
     if (!fs.existsSync(CREDENTIALS_PATH))
@@ -32,7 +33,7 @@ export function saveCredential(name, cred, setDefault = true) {
     store.devices[name] = cred;
     if (setDefault)
         store.default = name;
-    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(store, null, 2));
+    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(store, null, 2), { mode: 0o600 });
 }
 export function resolveConfig(deviceName) {
     const store = loadCredentialStore();
@@ -65,3 +66,17 @@ export function saveState(state) {
     ensureZhiHandDir();
     fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
 }
+export function loadBackendConfig() {
+    if (!fs.existsSync(BACKEND_PATH))
+        return { activeBackend: null };
+    try {
+        return JSON.parse(fs.readFileSync(BACKEND_PATH, "utf8"));
+    }
+    catch {
+        return { activeBackend: null };
+    }
+}
+export function saveBackendConfig(config) {
+    ensureZhiHandDir();
+    fs.writeFileSync(BACKEND_PATH, JSON.stringify(config, null, 2));
+}

package/dist/index.js

@@ -5,7 +5,7 @@ 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";
-const PACKAGE_VERSION = "0.12.3";
+const PACKAGE_VERSION = "0.15.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.12.3",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",