@zhihand/mcp 0.12.0 → 0.12.2

package/dist/tools/control.js

@@ -0,0 +1,52 @@
+import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
+import { fetchScreenshotBinary } from "../core/screenshot.js";
+import { waitForCommandAck } from "../core/sse.js";
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function executeControl(config, params) {
+    // 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 = [
+        { 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) {
+    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/dist/tools/pair.d.ts

@@ -0,0 +1,8 @@
+export declare function handlePair(params: {
+    forceNew?: boolean;
+}, endpoint?: string): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/pair.js

@@ -0,0 +1,49 @@
+import { loadDefaultCredential } from "../core/config.js";
+import { createPairingSession, registerPlugin, renderPairingQRCode, formatPairingStatus, } 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;
+    // Check existing credential
+    if (!params.forceNew) {
+        const existing = loadDefaultCredential();
+        if (existing) {
+            return {
+                content: [
+                    { type: "text", text: formatPairingStatus(existing) },
+                ],
+            };
+        }
+    }
+    // Register plugin first — server requires a known edge_id before pairing
+    const stableIdentity = generateEdgeId();
+    const plugin = await registerPlugin(resolvedEndpoint, {
+        stableIdentity,
+    });
+    // Create new pairing session with the registered edge_id
+    const session = await createPairingSession(resolvedEndpoint, {
+        edgeId: plugin.edge_id,
+    });
+    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/dist/tools/schemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const controlSchema: {
+    action: z.ZodEnum<["click", "doubleclick", "rightclick", "middleclick", "type", "swipe", "scroll", "keycombo", "clipboard", "wait", "screenshot"]>;
+    xRatio: z.ZodOptional<z.ZodNumber>;
+    yRatio: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodEnum<["up", "down", "left", "right"]>>;
+    amount: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    keys: z.ZodOptional<z.ZodString>;
+    clipboardAction: z.ZodOptional<z.ZodEnum<["get", "set"]>>;
+    durationMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    startXRatio: z.ZodOptional<z.ZodNumber>;
+    startYRatio: z.ZodOptional<z.ZodNumber>;
+    endXRatio: z.ZodOptional<z.ZodNumber>;
+    endYRatio: z.ZodOptional<z.ZodNumber>;
+};
+export declare const screenshotSchema: {};
+export declare const pairSchema: {
+    forceNew: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+};

package/dist/tools/schemas.js

@@ -0,0 +1,25 @@
+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/dist/tools/screenshot.d.ts

@@ -0,0 +1,11 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+export declare function handleScreenshot(config: ZhiHandConfig): Promise<{
+    content: ({
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: "image/jpeg";
+    })[];
+}>;

package/dist/tools/screenshot.js

@@ -0,0 +1,4 @@
+import { executeScreenshot } from "./control.js";
+export async function handleScreenshot(config) {
+    return await executeScreenshot(config);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",
@@ -16,19 +16,22 @@
     "zhihand.openclaw": "./bin/zhihand.openclaw"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./openclaw": "./src/openclaw.adapter.ts"
+    ".": "./dist/index.js",
+    "./openclaw": "./dist/openclaw.adapter.js"
   },
   "files": [
     "README.md",
     "bin/",
-    "src/"
+    "dist/"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "start": "node --experimental-strip-types src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "node --experimental-strip-types src/index.ts",
     "test": "node --test --experimental-strip-types src/**/*.test.ts"
   },
   "dependencies": {
@@ -38,5 +41,10 @@
   },
   "engines": {
     "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/qrcode": "^1.5.6",
+    "typescript": "^6.0.2"
   }
 }

package/src/cli/detect.ts

@@ -1,90 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,144 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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));
-}