@zhihand/mcp 0.12.0 → 0.12.1

package/dist/core/config.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+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");
+export function resolveZhiHandDir() {
+    return ZHIHAND_DIR;
+}
+export function ensureZhiHandDir() {
+    fs.mkdirSync(ZHIHAND_DIR, { recursive: true });
+}
+export function loadCredentialStore() {
+    if (!fs.existsSync(CREDENTIALS_PATH))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadDefaultCredential() {
+    const store = loadCredentialStore();
+    if (!store)
+        return null;
+    return store.devices[store.default] ?? null;
+}
+export function saveCredential(name, cred, setDefault = true) {
+    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) {
+    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() {
+    if (!fs.existsSync(STATE_PATH))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(STATE_PATH, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveState(state) {
+    ensureZhiHandDir();
+    fs.writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}

package/dist/core/pair.d.ts

@@ -0,0 +1,45 @@
+import type { DeviceCredential } from "./config.ts";
+export interface PluginRecord {
+    id: string;
+    edge_id: string;
+    adapter_kind: string;
+    display_name?: string;
+    stable_identity?: string;
+    status: string;
+    created_at: string;
+}
+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[];
+}
+/**
+ * Register this MCP instance as a plugin with the server.
+ * Server requires a registered plugin (edge_id) before pairing can begin.
+ * Idempotent — re-registering with the same stable_identity returns the existing plugin.
+ */
+export declare function registerPlugin(endpoint: string, options: {
+    stableIdentity: string;
+    displayName?: string;
+    adapterKind?: string;
+}): Promise<PluginRecord>;
+export declare function createPairingSession(endpoint: string, options: CreatePairingOptions): Promise<PairingSession>;
+export declare function getPairingSession(endpoint: string, sessionId: string): Promise<PairingSession>;
+export declare function waitForPairingClaim(endpoint: string, sessionId: string, timeoutMs?: number): Promise<PairingSession>;
+export declare function renderPairingQRCode(url: string): Promise<string>;
+export declare function executePairing(endpoint: string, edgeId: string, deviceName?: string): Promise<{
+    session: PairingSession;
+    credential: DeviceCredential;
+}>;
+export declare function formatPairingStatus(cred: DeviceCredential | null): string;

package/dist/core/pair.js

@@ -0,0 +1,124 @@
+import QRCode from "qrcode";
+import { saveCredential, saveState } from "./config.js";
+const DEFAULT_SCOPES = [
+    "observe",
+    "session.control",
+    "screen.read",
+    "screen.capture",
+    "ble.control",
+];
+/**
+ * Register this MCP instance as a plugin with the server.
+ * Server requires a registered plugin (edge_id) before pairing can begin.
+ * Idempotent — re-registering with the same stable_identity returns the existing plugin.
+ */
+export async function registerPlugin(endpoint, options) {
+    const response = await fetch(`${endpoint}/v1/plugins`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            adapter_kind: options.adapterKind ?? "mcp",
+            display_name: options.displayName ?? "ZhiHand MCP Server",
+            stable_identity: options.stableIdentity,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Register plugin failed: ${response.status} ${await response.text()}`);
+    }
+    const payload = (await response.json());
+    return payload.plugin;
+}
+export async function createPairingSession(endpoint, options) {
+    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());
+    return {
+        ...payload.session,
+        controller_token: payload.controller_token ?? payload.session.controller_token,
+    };
+}
+export async function getPairingSession(endpoint, sessionId) {
+    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());
+    return payload.session;
+}
+export async function waitForPairingClaim(endpoint, sessionId, timeoutMs = 600_000) {
+    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) {
+    return QRCode.toString(url, { type: "utf8", margin: 1 });
+}
+export async function executePairing(endpoint, edgeId, deviceName) {
+    // Step 0: Register plugin first — server requires a known edge_id before pairing.
+    // Uses edgeId as stable_identity so re-runs are idempotent.
+    const plugin = await registerPlugin(endpoint, {
+        stableIdentity: edgeId,
+        displayName: deviceName ? `ZhiHand MCP — ${deviceName}` : "ZhiHand MCP Server",
+    });
+    const registeredEdgeId = plugin.edge_id;
+    const session = await createPairingSession(endpoint, { edgeId: registeredEdgeId });
+    // 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 = {
+        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) {
+    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/dist/core/screenshot.d.ts

@@ -0,0 +1,2 @@
+import type { ZhiHandConfig } from "./config.ts";
+export declare function fetchScreenshotBinary(config: ZhiHandConfig): Promise<Buffer>;

package/dist/core/screenshot.js

@@ -0,0 +1,21 @@
+export async function fetchScreenshotBinary(config) {
+    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/dist/core/sse.d.ts

@@ -0,0 +1,35 @@
+import type { ZhiHandConfig } from "./config.ts";
+import type { QueuedCommandRecord, WaitForCommandAckResult } from "./command.ts";
+export interface SSEEvent {
+    id: string;
+    topic: string;
+    kind: string;
+    credential_id: string;
+    command?: QueuedCommandRecord;
+    sequence: number;
+}
+export declare function handleSSEEvent(event: SSEEvent): void;
+export declare function subscribeToCommandAck(commandId: string, callback: (cmd: QueuedCommandRecord) => void): () => void;
+/**
+ * Connect to the SSE event stream for command ACKs.
+ * Maintains a persistent connection that dispatches events to registered callbacks.
+ * Reconnects automatically on connection loss.
+ */
+export declare function connectSSE(config: ZhiHandConfig): void;
+/**
+ * Disconnect the SSE event stream.
+ */
+export declare function disconnectSSE(): void;
+/**
+ * Whether the SSE stream is currently connected.
+ */
+export declare function isSSEConnected(): boolean;
+/**
+ * Wait for command ACK via SSE push.
+ * Falls back to polling if SSE is not active.
+ */
+export declare function waitForCommandAck(config: ZhiHandConfig, options: {
+    commandId: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WaitForCommandAckResult>;

package/dist/core/sse.js

@@ -0,0 +1,149 @@
+import { getCommand } from "./command.js";
+// Per-commandId callback registry for SSE-based ACK
+const ackCallbacks = new Map();
+// Active SSE connection state
+let sseAbortController = null;
+let sseConnected = false;
+export function handleSSEEvent(event) {
+    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, callback) {
+    ackCallbacks.set(commandId, callback);
+    return () => { ackCallbacks.delete(commandId); };
+}
+/**
+ * Connect to the SSE event stream for command ACKs.
+ * Maintains a persistent connection that dispatches events to registered callbacks.
+ * Reconnects automatically on connection loss.
+ */
+export function connectSSE(config) {
+    if (sseAbortController)
+        return; // Already connected
+    sseAbortController = new AbortController();
+    const { signal } = sseAbortController;
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/events?topic=commands`;
+    (async () => {
+        while (!signal.aborted) {
+            try {
+                const response = await fetch(url, {
+                    headers: {
+                        "Accept": "text/event-stream",
+                        "x-zhihand-controller-token": config.controllerToken,
+                    },
+                    signal,
+                });
+                if (!response.ok) {
+                    throw new Error(`SSE connect failed: ${response.status}`);
+                }
+                sseConnected = true;
+                const reader = response.body?.getReader();
+                if (!reader)
+                    throw new Error("No response body for SSE");
+                const decoder = new TextDecoder();
+                let buffer = "";
+                while (!signal.aborted) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    let eventData = "";
+                    for (const line of lines) {
+                        if (line.startsWith("data: ")) {
+                            eventData += line.slice(6);
+                        }
+                        else if (line === "" && eventData) {
+                            try {
+                                const event = JSON.parse(eventData);
+                                handleSSEEvent(event);
+                            }
+                            catch {
+                                // Malformed event, skip
+                            }
+                            eventData = "";
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (signal.aborted)
+                    break;
+                sseConnected = false;
+                // Backoff before reconnect
+                await new Promise((r) => setTimeout(r, 3000));
+            }
+        }
+        sseConnected = false;
+    })();
+}
+/**
+ * Disconnect the SSE event stream.
+ */
+export function disconnectSSE() {
+    sseAbortController?.abort();
+    sseAbortController = null;
+    sseConnected = false;
+}
+/**
+ * Whether the SSE stream is currently connected.
+ */
+export function isSSEConnected() {
+    return sseConnected;
+}
+/**
+ * Wait for command ACK via SSE push.
+ * Falls back to polling if SSE is not active.
+ */
+export async function waitForCommandAck(config, options) {
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    // Ensure SSE is connected for real-time ACKs
+    connectSSE(config);
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        let pollInterval;
+        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 connected yet or may be reconnecting)
+        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/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(deviceName?: string): McpServer;
+export declare function startStdioServer(deviceName?: string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,43 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "./core/config.js";
+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.1";
+export function createServer(deviceName) {
+    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) {
+    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/dist/openclaw.adapter.d.ts

@@ -0,0 +1,49 @@
+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;
+};
+export declare function registerOpenClawTools(api: OpenClawPluginApi, deviceName?: string): void;
+export default registerOpenClawTools;

package/dist/openclaw.adapter.js

@@ -0,0 +1,72 @@
+/**
+ * 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.js";
+import { executeControl } from "./tools/control.js";
+import { handleScreenshot } from "./tools/screenshot.js";
+import { handlePair } from "./tools/pair.js";
+import { detectCLITools, formatDetectedTools } from "./cli/detect.js";
+import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+function zodSchemaToJsonSchema(zodShape) {
+    // Simplified conversion — OpenClaw uses JSON Schema-like parameter objects.
+    // The actual Zod schemas are used for validation inside tool handlers.
+    const properties = {};
+    for (const [key, value] of Object.entries(zodShape)) {
+        const v = value;
+        properties[key] = {
+            type: "string",
+            description: v.description ?? key,
+        };
+    }
+    return { type: "object", properties };
+}
+export function registerOpenClawTools(api, deviceName) {
+    const log = (msg) => 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);
+            return result;
+        },
+    });
+    // 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;
+        },
+    });
+    // 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);
+            return result;
+        },
+    }, { 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/dist/tools/control.d.ts

@@ -0,0 +1,18 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+import type { ControlParams } from "../core/command.ts";
+type TextContent = {
+    type: "text";
+    text: string;
+};
+type ImageContent = {
+    type: "image";
+    data: string;
+    mimeType: "image/jpeg";
+};
+type ToolContent = TextContent | ImageContent;
+type ToolResult = {
+    content: ToolContent[];
+};
+export declare function executeControl(config: ZhiHandConfig, params: ControlParams): Promise<ToolResult>;
+export declare function executeScreenshot(config: ZhiHandConfig): Promise<ToolResult>;
+export {};