@zhihand/mcp 0.12.0 → 0.12.2

package/src/core/pair.ts

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

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

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

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

@@ -1,116 +0,0 @@
-/**
- * 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

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

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

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

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