@zhihand/mcp 0.12.0

package/bin/zhihand

@@ -0,0 +1,104 @@
+#!/usr/bin/env node --experimental-strip-types
+
+import os from "node:os";
+import { parseArgs } from "node:util";
+import { startStdioServer } from "../src/index.ts";
+import { detectCLITools, formatDetectedTools } from "../src/cli/detect.ts";
+import { detectAndSetupOpenClaw } from "../src/cli/openclaw.ts";
+import { loadDefaultCredential } from "../src/core/config.ts";
+import { executePairing } from "../src/core/pair.ts";
+
+const DEFAULT_ENDPOINT = "https://api.zhihand.com";
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: {
+    device: { type: "string" },
+    http: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+});
+
+const command = positionals[0] ?? "serve";
+
+if (values.help) {
+  console.log(`
+zhihand — MCP Server 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 + configure
+
+Options:
+  --device <name>    Use a specific paired device
+  -h, --help         Show this help
+`);
+  process.exit(0);
+}
+
+switch (command) {
+  case "serve": {
+    await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
+    break;
+  }
+
+  case "pair": {
+    const edgeId = `mcp-${Date.now().toString(36)}`;
+    const deviceName = values.device ?? `mcp-${os.hostname()}`;
+    await executePairing(DEFAULT_ENDPOINT, edgeId, deviceName);
+    break;
+  }
+
+  case "status": {
+    const cred = loadDefaultCredential();
+    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");
+    }
+    break;
+  }
+
+  case "detect": {
+    const tools = await detectCLITools();
+    console.log(formatDetectedTools(tools));
+    break;
+  }
+
+  case "setup": {
+    // 1. Check/create pairing
+    let cred = loadDefaultCredential();
+    if (!cred) {
+      console.log("No paired device found. Starting pairing...\n");
+      const edgeId = `mcp-${Date.now().toString(36)}`;
+      const deviceName = values.device ?? `mcp-${os.hostname()}`;
+      await executePairing(DEFAULT_ENDPOINT, edgeId, deviceName);
+      cred = loadDefaultCredential();
+    }
+    if (cred) {
+      console.log(`\nPaired: ${cred.deviceName} (${cred.credentialId})\n`);
+    }
+
+    // 2. Detect CLI tools
+    const tools = await detectCLITools();
+    console.log(formatDetectedTools(tools));
+
+    // 3. Setup OpenClaw if present
+    await detectAndSetupOpenClaw();
+
+    console.log("\nSetup complete. Add to your CLI tool's MCP config:");
+    console.log('  { "mcpServers": { "zhihand": { "command": "zhihand", "args": ["serve"] } } }');
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: ${command}. Run 'zhihand --help' for usage.`);
+    process.exit(1);
+}

package/bin/zhihand.openclaw

@@ -0,0 +1,13 @@
+#!/usr/bin/env node --experimental-strip-types
+
+/**
+ * OpenClaw Plugin entry point.
+ * This script is invoked by OpenClaw when the zhihand plugin is loaded.
+ * It bridges the OpenClaw Plugin API to MCP core logic via the adapter.
+ */
+import { registerOpenClawTools } from "../src/openclaw.adapter.ts";
+
+// OpenClaw injects the plugin API as the default export's argument
+export default function activate(api) {
+  registerOpenClawTools(api);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zhihand/mcp",
+  "version": "0.12.0",
+  "private": false,
+  "type": "module",
+  "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",
+  "license": "MIT",
+  "homepage": "https://github.com/handgpt/zhihand/tree/main/packages/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/handgpt/zhihand.git",
+    "directory": "packages/mcp"
+  },
+  "bin": {
+    "zhihand": "./bin/zhihand",
+    "zhihand.openclaw": "./bin/zhihand.openclaw"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./openclaw": "./src/openclaw.adapter.ts"
+  },
+  "files": [
+    "README.md",
+    "bin/",
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node --experimental-strip-types src/index.ts",
+    "test": "node --test --experimental-strip-types src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "qrcode": "^1.5.4",
+    "zod": "^3.24.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/cli/detect.ts

@@ -0,0 +1,90 @@
+import { execSync } from "node:child_process";
+
+export interface CLITool {
+  name: "claudecode" | "codex" | "gemini" | "openclaw";
+  command: string;
+  version: string;
+  loggedIn: boolean;
+  priority: number;
+}
+
+function tryExec(cmd: string): string | null {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isCommandAvailable(cmd: string): boolean {
+  return tryExec(`which ${cmd}`) !== null;
+}
+
+async function detectClaudeCode(): Promise<CLITool | null> {
+  if (!isCommandAvailable("claude")) return null;
+  const version = tryExec("claude --version") ?? "unknown";
+  // Check login: claude has config in ~/.claude/
+  const loggedIn = tryExec("ls ~/.claude/settings.json") !== null;
+  return { name: "claudecode", command: "claude", version, loggedIn, priority: 1 };
+}
+
+async function detectCodex(): Promise<CLITool | null> {
+  if (!isCommandAvailable("codex")) return null;
+  const version = tryExec("codex --version") ?? "unknown";
+  // Check login: OPENAI_API_KEY env var or config
+  const loggedIn = !!process.env.OPENAI_API_KEY || tryExec("ls ~/.codex/") !== null;
+  return { name: "codex", command: "codex", version, loggedIn, priority: 2 };
+}
+
+async function detectGemini(): Promise<CLITool | null> {
+  if (!isCommandAvailable("gemini")) return null;
+  const version = tryExec("gemini --version") ?? "unknown";
+  // Check login: Google Cloud auth
+  const loggedIn = tryExec("gemini auth status") !== null;
+  return { name: "gemini", command: "gemini", version, loggedIn, priority: 3 };
+}
+
+async function detectOpenClaw(): Promise<CLITool | null> {
+  if (!isCommandAvailable("openclaw")) return null;
+  const version = tryExec("openclaw --version") ?? "unknown";
+  const loggedIn = tryExec("ls ~/.openclaw/openclaw.json") !== null;
+  return { name: "openclaw", command: "openclaw", version, loggedIn, priority: 4 };
+}
+
+export async function detectCLITools(): Promise<CLITool[]> {
+  const results = await Promise.allSettled([
+    detectClaudeCode(),
+    detectCodex(),
+    detectGemini(),
+    detectOpenClaw(),
+  ]);
+
+  return results
+    .filter((r): r is PromiseFulfilledResult<CLITool | null> => r.status === "fulfilled")
+    .map((r) => r.value)
+    .filter((t): t is CLITool => t !== null)
+    .sort((a, b) => a.priority - b.priority);
+}
+
+export async function detectBestCLI(): Promise<CLITool | null> {
+  const cliOverride = process.env.ZHIHAND_CLI;
+  const tools = await detectCLITools();
+
+  if (cliOverride) {
+    const match = tools.find((t) => t.name === cliOverride || t.command === cliOverride);
+    if (match) return match;
+  }
+
+  // Return best available tool (logged in + highest priority)
+  return tools.find((t) => t.loggedIn) ?? tools[0] ?? null;
+}
+
+export function formatDetectedTools(tools: CLITool[]): string {
+  if (tools.length === 0) return "No CLI tools detected.";
+  return [
+    "Detected CLI tools:",
+    ...tools.map((t) =>
+      `  ${t.loggedIn ? "✓" : "✗"} ${t.name} (${t.command} ${t.version})${t.loggedIn ? "" : " — not logged in"}`
+    ),
+  ].join("\n");
+}

package/src/cli/openclaw.ts

@@ -0,0 +1,50 @@
+import { execSync } from "node:child_process";
+
+function tryExec(cmd: string): string | null {
+  try {
+    return execSync(cmd, { encoding: "utf8", timeout: 30_000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isCommandAvailable(cmd: string): boolean {
+  return tryExec(`which ${cmd}`) !== null;
+}
+
+export async function isZhiHandPluginInstalled(): Promise<boolean> {
+  const output = tryExec("openclaw plugins list");
+  if (!output) return false;
+  return output.includes("zhihand") || output.includes("@zhihand/mcp");
+}
+
+export async function installZhiHandPlugin(
+  options: { timeoutMs?: number; autoConfirm?: boolean } = {}
+): Promise<boolean> {
+  const timeout = options.timeoutMs ?? 30_000;
+  try {
+    execSync("openclaw plugins install @zhihand/mcp", {
+      encoding: "utf8",
+      timeout,
+      stdio: options.autoConfirm ? ["pipe", "pipe", "pipe"] : "inherit",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function detectAndSetupOpenClaw(): Promise<void> {
+  if (!isCommandAvailable("openclaw")) return;
+
+  const pluginInstalled = await isZhiHandPluginInstalled();
+  if (pluginInstalled) return;
+
+  process.stderr.write("[zhihand] Detected OpenClaw without ZhiHand plugin. Installing...\n");
+  const success = await installZhiHandPlugin({ timeoutMs: 30_000, autoConfirm: true });
+  if (success) {
+    process.stderr.write("[zhihand] ZhiHand plugin installed to OpenClaw.\n");
+  } else {
+    process.stderr.write("[zhihand] Failed to install ZhiHand plugin to OpenClaw.\n");
+  }
+}

package/src/cli/spawn.ts

@@ -0,0 +1,34 @@
+import { execSync } from "node:child_process";
+import type { CLITool } from "./detect.ts";
+
+function shellEscape(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+export async function spawnCLITask(tool: CLITool, prompt: string): Promise<string> {
+  const escaped = shellEscape(prompt);
+  switch (tool.name) {
+    case "claudecode":
+      return execSync(`${tool.command} -p ${escaped} --output-format json`, {
+        encoding: "utf8",
+        timeout: 300_000,
+      });
+    case "codex":
+      return execSync(`${tool.command} -q ${escaped} --json`, {
+        encoding: "utf8",
+        timeout: 300_000,
+      });
+    case "gemini":
+      return execSync(`${tool.command} -p ${escaped}`, {
+        encoding: "utf8",
+        timeout: 300_000,
+      });
+    case "openclaw":
+      return execSync(`${tool.command} run ${escaped}`, {
+        encoding: "utf8",
+        timeout: 300_000,
+      });
+    default:
+      throw new Error(`Unsupported CLI tool: ${tool.name}`);
+  }
+}

package/src/core/command.ts

@@ -0,0 +1,144 @@
+import type { ZhiHandConfig } from "./config.ts";
+
+export type ScrollDirection = "up" | "down" | "left" | "right";
+export type ClipboardAction = "get" | "set";
+
+export interface ControlParams {
+  action: string;
+  xRatio?: number;
+  yRatio?: number;
+  text?: string;
+  direction?: ScrollDirection;
+  amount?: number;
+  keys?: string;
+  clipboardAction?: ClipboardAction;
+  durationMs?: number;
+  startXRatio?: number;
+  startYRatio?: number;
+  endXRatio?: number;
+  endYRatio?: number;
+}
+
+export interface QueuedControlCommand {
+  type: string;
+  payload?: Record<string, unknown>;
+  messageId?: number;
+}
+
+export interface QueuedCommandRecord {
+  id: string;
+  credential_id: string;
+  status: string;
+  command: QueuedControlCommand;
+  created_at: string;
+  acked_at?: string;
+  ack_status?: string;
+  ack_result?: Record<string, unknown>;
+}
+
+export interface WaitForCommandAckResult {
+  acked: boolean;
+  command?: QueuedCommandRecord;
+}
+
+let messageCounter = 0;
+
+function nextMessageId(): number {
+  messageCounter = (messageCounter + 1) % 1000;
+  return (Date.now() * 1000) + messageCounter;
+}
+
+export function createControlCommand(params: ControlParams): QueuedControlCommand {
+  switch (params.action) {
+    case "click":
+      return { type: "receive_click", payload: { x: params.xRatio, y: params.yRatio } };
+    case "doubleclick":
+      return { type: "receive_doubleclick", payload: { x: params.xRatio, y: params.yRatio } };
+    case "rightclick":
+      return { type: "receive_rightclick", payload: { x: params.xRatio, y: params.yRatio } };
+    case "middleclick":
+      return { type: "receive_middleclick", payload: { x: params.xRatio, y: params.yRatio } };
+    case "type":
+      return { type: "receive_type", payload: { text: params.text } };
+    case "swipe":
+      return {
+        type: "receive_swipe",
+        payload: {
+          startX: params.startXRatio,
+          startY: params.startYRatio,
+          endX: params.endXRatio,
+          endY: params.endYRatio,
+        },
+      };
+    case "scroll":
+      return {
+        type: "receive_scroll",
+        payload: {
+          x: params.xRatio,
+          y: params.yRatio,
+          direction: params.direction,
+          amount: params.amount ?? 3,
+        },
+      };
+    case "keycombo":
+      return { type: "receive_keycombo", payload: { keys: params.keys } };
+    case "clipboard":
+      return {
+        type: "receive_clipboard",
+        payload: { action: params.clipboardAction, text: params.text },
+      };
+    case "screenshot":
+      return { type: "receive_screenshot", payload: {} };
+    default:
+      throw new Error(`Unsupported action: ${params.action}`);
+  }
+}
+
+export async function enqueueCommand(
+  config: ZhiHandConfig,
+  command: QueuedControlCommand
+): Promise<QueuedCommandRecord> {
+  const response = await fetch(
+    `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-zhihand-controller-token": config.controllerToken,
+      },
+      body: JSON.stringify({
+        command: { ...command, message_id: command.messageId ?? nextMessageId() },
+      }),
+    }
+  );
+  if (!response.ok) {
+    throw new Error(`Enqueue command failed: ${response.status}`);
+  }
+  const payload = (await response.json()) as { command: QueuedCommandRecord };
+  return payload.command;
+}
+
+export async function getCommand(
+  config: ZhiHandConfig,
+  commandId: string
+): Promise<QueuedCommandRecord> {
+  const response = await fetch(
+    `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands/${encodeURIComponent(commandId)}`,
+    {
+      headers: { "x-zhihand-controller-token": config.controllerToken },
+    }
+  );
+  if (!response.ok) {
+    throw new Error(`Get command failed: ${response.status}`);
+  }
+  const payload = (await response.json()) as { command: QueuedCommandRecord };
+  return payload.command;
+}
+
+export function formatAckSummary(action: string, result: WaitForCommandAckResult): string {
+  if (!result.acked) {
+    return `Sent ${action}, waiting for ACK (timed out).`;
+  }
+  const ackStatus = result.command?.ack_status ?? "ok";
+  return `Sent ${action}. ACK: ${ackStatus}`;
+}

package/src/core/config.ts

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface DeviceCredential {
+  credentialId: string;
+  controllerToken: string;
+  endpoint: string;
+  deviceName?: string;
+  pairedAt?: string;
+}
+
+export interface CredentialStore {
+  default: string;
+  devices: Record<string, DeviceCredential>;
+}
+
+export interface ZhiHandConfig {
+  controlPlaneEndpoint: string;
+  credentialId: string;
+  controllerToken: string;
+  edgeId?: string;
+  timeoutMs?: number;
+}
+
+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");
+
+export function resolveZhiHandDir(): string {
+  return ZHIHAND_DIR;
+}
+
+export function ensureZhiHandDir(): void {
+  fs.mkdirSync(ZHIHAND_DIR, { recursive: true });
+}
+
+export function loadCredentialStore(): CredentialStore | null {
+  if (!fs.existsSync(CREDENTIALS_PATH)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf8")) as CredentialStore;
+  } catch {
+    return null;
+  }
+}
+
+export function loadDefaultCredential(): DeviceCredential | null {
+  const store = loadCredentialStore();
+  if (!store) return null;
+  return store.devices[store.default] ?? null;
+}
+
+export function saveCredential(name: string, cred: DeviceCredential, setDefault: boolean = true): void {
+  ensureZhiHandDir();
+  let store = loadCredentialStore() ?? { default: name, devices: {} };
+  store.devices[name] = cred;
+  if (setDefault) store.default = name;
+  fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(store, null, 2));
+}
+
+export function resolveConfig(deviceName?: string): ZhiHandConfig {
+  const store = loadCredentialStore();
+  if (!store) {
+    throw new Error("No ZhiHand credentials found. Run 'zhihand pair' first.");
+  }
+  const name = deviceName ?? store.default;
+  const cred = store.devices[name];
+  if (!cred) {
+    throw new Error(`Device '${name}' not found. Available: ${Object.keys(store.devices).join(", ")}`);
+  }
+  return {
+    controlPlaneEndpoint: cred.endpoint,
+    credentialId: cred.credentialId,
+    controllerToken: cred.controllerToken,
+    timeoutMs: 10_000,
+  };
+}
+
+export function loadState<T = unknown>(): T | null {
+  if (!fs.existsSync(STATE_PATH)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(STATE_PATH, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function saveState(state: unknown): void {
+  ensureZhiHandDir();
+  fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}

package/src/core/pair.ts

@@ -0,0 +1,143 @@
+import QRCode from "qrcode";
+import type { ZhiHandConfig, DeviceCredential } from "./config.ts";
+import { saveCredential, loadDefaultCredential, ensureZhiHandDir, saveState } from "./config.ts";
+
+export interface PairingSession {
+  id: string;
+  pair_url: string;
+  qr_payload: string;
+  controller_token?: string;
+  edge_id: string;
+  status: "pending" | "claimed" | "expired" | string;
+  credential_id?: string;
+  expires_at: string;
+  requested_scopes?: string[];
+}
+
+export interface CreatePairingOptions {
+  edgeId: string;
+  ttlSeconds?: number;
+  requestedScopes?: string[];
+}
+
+const DEFAULT_SCOPES = [
+  "observe",
+  "session.control",
+  "screen.read",
+  "screen.capture",
+  "ble.control",
+];
+
+export async function createPairingSession(
+  endpoint: string,
+  options: CreatePairingOptions
+): Promise<PairingSession> {
+  const response = await fetch(`${endpoint}/v1/pairing/sessions`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      edge_id: options.edgeId,
+      ttl_seconds: options.ttlSeconds ?? 600,
+      requested_scopes: options.requestedScopes ?? DEFAULT_SCOPES,
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`Create pairing session failed: ${response.status}`);
+  }
+  const payload = (await response.json()) as { session: PairingSession; controller_token?: string };
+  return {
+    ...payload.session,
+    controller_token: payload.controller_token ?? payload.session.controller_token,
+  };
+}
+
+export async function getPairingSession(
+  endpoint: string,
+  sessionId: string
+): Promise<PairingSession> {
+  const response = await fetch(
+    `${endpoint}/v1/pairing/sessions/${encodeURIComponent(sessionId)}`
+  );
+  if (!response.ok) {
+    throw new Error(`Get pairing session failed: ${response.status}`);
+  }
+  const payload = (await response.json()) as { session: PairingSession };
+  return payload.session;
+}
+
+export async function waitForPairingClaim(
+  endpoint: string,
+  sessionId: string,
+  timeoutMs: number = 600_000
+): Promise<PairingSession> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const session = await getPairingSession(endpoint, sessionId);
+    if (session.status === "claimed" && session.credential_id) {
+      return session;
+    }
+    if (session.status === "expired") {
+      throw new Error("Pairing session expired.");
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  throw new Error("Pairing timeout.");
+}
+
+export async function renderPairingQRCode(url: string): Promise<string> {
+  return QRCode.toString(url, { type: "utf8", margin: 1 });
+}
+
+export async function executePairing(
+  endpoint: string,
+  edgeId: string,
+  deviceName?: string
+): Promise<{ session: PairingSession; credential: DeviceCredential }> {
+  const session = await createPairingSession(endpoint, { edgeId });
+
+  // Save pending state
+  saveState({
+    sessionId: session.id,
+    controllerToken: session.controller_token,
+    edgeId: session.edge_id,
+    pairUrl: session.pair_url,
+    status: "pending",
+    expiresAt: session.expires_at,
+  });
+
+  // Wait for phone to scan
+  const claimed = await waitForPairingClaim(endpoint, session.id);
+
+  const credential: DeviceCredential = {
+    credentialId: claimed.credential_id!,
+    controllerToken: claimed.controller_token ?? session.controller_token!,
+    endpoint,
+    deviceName: deviceName ?? `device_${Date.now()}`,
+    pairedAt: new Date().toISOString(),
+  };
+
+  const name = deviceName ?? credential.deviceName!;
+  saveCredential(name, credential, true);
+
+  // Update state
+  saveState({
+    sessionId: session.id,
+    controllerToken: credential.controllerToken,
+    edgeId: session.edge_id,
+    credentialId: credential.credentialId,
+    pairUrl: session.pair_url,
+    status: "claimed",
+  });
+
+  return { session: claimed, credential };
+}
+
+export function formatPairingStatus(cred: DeviceCredential | null): string {
+  if (!cred) return "Not paired. Run 'zhihand pair' to connect a device.";
+  return [
+    `Paired to: ${cred.deviceName ?? "unknown device"}`,
+    `Endpoint: ${cred.endpoint}`,
+    `Credential: ${cred.credentialId}`,
+    `Paired at: ${cred.pairedAt ?? "unknown"}`,
+  ].join("\n");
+}

package/src/core/screenshot.ts

@@ -0,0 +1,28 @@
+import type { ZhiHandConfig } from "./config.ts";
+
+export async function fetchScreenshotBinary(config: ZhiHandConfig): Promise<Buffer> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 10_000);
+
+  try {
+    const response = await fetch(
+      `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/screen`,
+      {
+        method: "GET",
+        headers: {
+          "x-zhihand-controller-token": config.controllerToken,
+          "Accept": "image/jpeg",
+        },
+        signal: controller.signal,
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Screenshot fetch failed: ${response.status}`);
+    }
+
+    return Buffer.from(await response.arrayBuffer());
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/core/sse.ts

@@ -0,0 +1,88 @@
+import type { ZhiHandConfig } from "./config.ts";
+import type { QueuedCommandRecord, WaitForCommandAckResult } from "./command.ts";
+import { getCommand } from "./command.ts";
+
+export interface SSEEvent {
+  id: string;
+  topic: string;
+  kind: string;
+  credential_id: string;
+  command?: QueuedCommandRecord;
+  sequence: number;
+}
+
+// Per-commandId callback registry for SSE-based ACK
+const ackCallbacks = new Map<string, (command: QueuedCommandRecord) => void>();
+
+export function handleSSEEvent(event: SSEEvent): void {
+  if (event.kind === "command.acked" && event.command) {
+    const callback = ackCallbacks.get(event.command.id);
+    if (callback) {
+      callback(event.command);
+      ackCallbacks.delete(event.command.id);
+    }
+  }
+}
+
+export function subscribeToCommandAck(
+  commandId: string,
+  callback: (cmd: QueuedCommandRecord) => void
+): () => void {
+  ackCallbacks.set(commandId, callback);
+  return () => { ackCallbacks.delete(commandId); };
+}
+
+/**
+ * Wait for command ACK via SSE push.
+ * Falls back to polling if SSE is not active.
+ */
+export async function waitForCommandAck(
+  config: ZhiHandConfig,
+  options: { commandId: string; timeoutMs?: number; signal?: AbortSignal }
+): Promise<WaitForCommandAckResult> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+
+  // Try SSE-based ACK first (if callbacks are being dispatched by an active SSE stream)
+  return new Promise<WaitForCommandAckResult>((resolve, reject) => {
+    let resolved = false;
+    let pollInterval: ReturnType<typeof setInterval> | undefined;
+
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve({ acked: false });
+    }, timeoutMs);
+
+    const unsubscribe = subscribeToCommandAck(options.commandId, (ackedCommand) => {
+      if (resolved) return;
+      resolved = true;
+      cleanup();
+      resolve({ acked: true, command: ackedCommand });
+    });
+
+    // Also poll as fallback (SSE may not be active)
+    pollInterval = setInterval(async () => {
+      if (resolved) return;
+      try {
+        const cmd = await getCommand(config, options.commandId);
+        if (cmd.acked_at) {
+          resolved = true;
+          cleanup();
+          resolve({ acked: true, command: cmd });
+        }
+      } catch {
+        // Polling failure is non-fatal; SSE or next poll may succeed
+      }
+    }, 500);
+
+    options.signal?.addEventListener("abort", () => {
+      cleanup();
+      reject(new Error("The operation was aborted"));
+    }, { once: true });
+
+    function cleanup() {
+      clearTimeout(timeout);
+      unsubscribe();
+      if (pollInterval) clearInterval(pollInterval);
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { resolveConfig } from "./core/config.ts";
+import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.ts";
+import { executeControl } from "./tools/control.ts";
+import { handleScreenshot } from "./tools/screenshot.ts";
+import { handlePair } from "./tools/pair.ts";
+
+const PACKAGE_VERSION = "0.11.0";
+
+export function createServer(deviceName?: string): McpServer {
+  const server = new McpServer({
+    name: "zhihand",
+    version: PACKAGE_VERSION,
+  });
+
+  // zhihand_control — main phone control tool
+  server.tool("zhihand_control", 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 () => {
+    const config = resolveConfig(deviceName);
+    return await handleScreenshot(config);
+  });
+
+  // zhihand_pair — device pairing
+  server.tool("zhihand_pair", pairSchema, async (params) => {
+    return await handlePair(params);
+  });
+
+  return server;
+}
+
+export async function startStdioServer(deviceName?: string): Promise<void> {
+  const server = createServer(deviceName);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Direct execution: start stdio server
+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) => {
+    process.stderr.write(`ZhiHand MCP Server failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/src/openclaw.adapter.ts

@@ -0,0 +1,116 @@
+/**
+ * OpenClaw Plugin adapter — thin wrapper that bridges OpenClaw Plugin API
+ * to MCP core logic. All business logic lives in core/ and tools/.
+ */
+import { resolveConfig } from "./core/config.ts";
+import { executeControl } from "./tools/control.ts";
+import { handleScreenshot } from "./tools/screenshot.ts";
+import { handlePair } from "./tools/pair.ts";
+import { detectCLITools, formatDetectedTools } from "./cli/detect.ts";
+import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.ts";
+
+type OpenClawLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+type OpenClawRuntime = {
+  state: { resolveStateDir: () => string };
+  stt?: { transcribeAudioFile: (input: { path: string }) => Promise<{ text?: string } | string> };
+};
+
+type OpenClawToolRegistration = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (id: string, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+
+type OpenClawPluginApi = {
+  logger: OpenClawLogger;
+  runtime: OpenClawRuntime;
+  pluginConfig?: Record<string, unknown>;
+  registerService: (service: { id: string; start: () => Promise<void>; stop: () => Promise<void> }) => void;
+  registerCommand: (command: {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    handler: (ctx: { args?: string }) => Promise<{ text: string }>;
+  }) => void;
+  registerTool: (tool: OpenClawToolRegistration, options?: { optional?: boolean }) => void;
+};
+
+function zodSchemaToJsonSchema(zodShape: Record<string, unknown>): Record<string, unknown> {
+  // Simplified conversion — OpenClaw uses JSON Schema-like parameter objects.
+  // The actual Zod schemas are used for validation inside tool handlers.
+  const properties: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(zodShape)) {
+    const v = value as { description?: string; _def?: { typeName?: string } };
+    properties[key] = {
+      type: "string",
+      description: v.description ?? key,
+    };
+  }
+  return { type: "object", properties };
+}
+
+export function registerOpenClawTools(api: OpenClawPluginApi, deviceName?: string): void {
+  const log = (msg: string) => api.logger.info?.(msg);
+
+  // zhihand_control
+  api.registerTool({
+    name: "zhihand_control",
+    label: "ZhiHand Control",
+    description: "Control a paired phone: tap, swipe, type, scroll, screenshot, and more.",
+    parameters: zodSchemaToJsonSchema(controlSchema),
+    execute: async (_id, params) => {
+      const config = resolveConfig(deviceName);
+      const result = await executeControl(config, params as Parameters<typeof executeControl>[1]);
+      return result as unknown as Record<string, unknown>;
+    },
+  });
+
+  // zhihand_screenshot
+  api.registerTool({
+    name: "zhihand_screenshot",
+    label: "ZhiHand Screenshot",
+    description: "Capture current phone screen without performing any action.",
+    parameters: zodSchemaToJsonSchema(screenshotSchema),
+    execute: async (_id, _params) => {
+      const config = resolveConfig(deviceName);
+      const result = await handleScreenshot(config);
+      return result as unknown as Record<string, unknown>;
+    },
+  });
+
+  // zhihand_pair
+  api.registerTool(
+    {
+      name: "zhihand_pair",
+      label: "ZhiHand Pair",
+      description: "Pair with a phone. Returns QR code and pairing URL.",
+      parameters: zodSchemaToJsonSchema(pairSchema),
+      execute: async (_id, params) => {
+        const result = await handlePair(params as { forceNew?: boolean });
+        return result as unknown as Record<string, unknown>;
+      },
+    },
+    { optional: true },
+  );
+
+  // detect command
+  api.registerCommand({
+    name: "zhihand-detect",
+    description: "Detect available CLI tools (Claude Code, Codex, Gemini, OpenClaw)",
+    handler: async () => {
+      const tools = await detectCLITools();
+      return { text: formatDetectedTools(tools) };
+    },
+  });
+
+  log("[zhihand] OpenClaw tools registered via MCP core adapter");
+}
+
+export default registerOpenClawTools;

package/src/tools/control.ts

@@ -0,0 +1,66 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.ts";
+import type { ControlParams } from "../core/command.ts";
+import { fetchScreenshotBinary } from "../core/screenshot.ts";
+import { waitForCommandAck } from "../core/sse.ts";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export async function executeControl(
+  config: ZhiHandConfig,
+  params: ControlParams
+): Promise<{ content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }> {
+  // wait: Plugin-local implementation, no server round-trip
+  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)
+  if (params.action === "screenshot") {
+    return await executeScreenshot(config);
+  }
+
+  // HID operations: enqueue → ACK → GET screenshot
+  const command = createControlCommand(params);
+  const queued = await enqueueCommand(config, command);
+  const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
+
+  const content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> = [
+    { type: "text", text: formatAckSummary(params.action, ack) },
+  ];
+
+  if (ack.acked) {
+    try {
+      const screenshot = await fetchScreenshotBinary(config);
+      content.push({ type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" });
+    } catch {
+      // Screenshot is best-effort after ACK
+    }
+  }
+
+  return { content };
+}
+
+export async function executeScreenshot(
+  config: ZhiHandConfig
+): Promise<{ content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }> {
+  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" },
+    ],
+  };
+}

package/src/tools/pair.ts

@@ -0,0 +1,58 @@
+import { loadDefaultCredential } from "../core/config.ts";
+import {
+  createPairingSession,
+  renderPairingQRCode,
+  formatPairingStatus,
+} from "../core/pair.ts";
+
+const DEFAULT_ENDPOINT = "https://api.zhihand.com";
+const DEFAULT_EDGE_ID_PREFIX = "mcp-";
+
+function generateEdgeId(): string {
+  return `${DEFAULT_EDGE_ID_PREFIX}${Date.now().toString(36)}`;
+}
+
+export async function handlePair(
+  params: { forceNew?: boolean },
+  endpoint?: string
+): Promise<{ content: Array<{ type: string; text?: string }> }> {
+  const resolvedEndpoint = endpoint ?? DEFAULT_ENDPOINT;
+
+  // Check existing credential
+  if (!params.forceNew) {
+    const existing = loadDefaultCredential();
+    if (existing) {
+      return {
+        content: [
+          { type: "text", text: formatPairingStatus(existing) },
+        ],
+      };
+    }
+  }
+
+  // Create new pairing session
+  const session = await createPairingSession(resolvedEndpoint, {
+    edgeId: generateEdgeId(),
+  });
+
+  const qr = await renderPairingQRCode(session.pair_url);
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: [
+          "Scan QR code or open URL on your phone to pair:",
+          "",
+          qr,
+          "",
+          `URL: ${session.pair_url}`,
+          `Expires at: ${session.expires_at}`,
+          "",
+          "Waiting for phone to scan...",
+          "(Call zhihand_pair again after scanning to check status)",
+        ].join("\n"),
+      },
+    ],
+  };
+}

package/src/tools/schemas.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const controlSchema = {
+  action: z.enum([
+    "click", "doubleclick", "rightclick", "middleclick",
+    "type", "swipe", "scroll", "keycombo",
+    "clipboard",
+    "wait", "screenshot",
+  ]),
+  xRatio: z.number().min(0).max(1).optional().describe("Normalized horizontal position [0,1]"),
+  yRatio: z.number().min(0).max(1).optional().describe("Normalized vertical position [0,1]"),
+  text: z.string().optional().describe("Text for type or clipboard set"),
+  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: z.enum(["get", "set"]).optional().describe("Clipboard action"),
+  durationMs: z.number().int().positive().max(10000).default(1000).optional().describe("Duration in ms for wait (default 1000, 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]"),
+  endXRatio: z.number().min(0).max(1).optional().describe("Swipe end X [0,1]"),
+  endYRatio: z.number().min(0).max(1).optional().describe("Swipe end Y [0,1]"),
+};
+
+export const screenshotSchema = {};
+
+export const pairSchema = {
+  forceNew: z.boolean().default(false).optional().describe("Force new pairing even if already paired"),
+};

package/src/tools/screenshot.ts

@@ -0,0 +1,8 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+import { executeScreenshot } from "./control.ts";
+
+export async function handleScreenshot(
+  config: ZhiHandConfig
+): Promise<{ content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }> {
+  return await executeScreenshot(config);
+}