ucu-mcp 0.3.9 → 0.4.2

package/dist/src/mcp/tools/helpers.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { MacOSPlatform } from "../../platform/macos/index.js";
+import { SafetyGuard, classifyAction } from "../../safety/guard.js";
+import { checkPermission } from "../../safety/permissions.js";
+import { retry } from "../../util/retry.js";
+import { metrics } from "../../util/metrics.js";
+import { SafetyError, PermissionError, UcuError, WindowNotFoundError } from "../../util/errors.js";
+let _platform;
+export function getPlatform() {
+    if (!_platform) {
+        _platform = process.platform === "darwin" ? new MacOSPlatform() : undefined;
+    }
+    return _platform;
+}
+export const safety = new SafetyGuard();
+let activeTargetContext;
+export function getActiveTarget() {
+    return activeTargetContext;
+}
+export function setActiveTarget(target) {
+    activeTargetContext = target;
+}
+let lastCursorPos = { x: 0, y: 0 };
+let userActivityInterval;
+export const captureAfterFields = {
+    captureAfter: z.boolean().default(false).describe("Take a screenshot after the action completes and include it in the response"),
+    captureMaxWidth: z.number().default(1280).describe("Maximum width for the post-action screenshot"),
+    captureFormat: z.enum(["png", "jpeg"]).default("jpeg").describe("Format for the post-action screenshot"),
+};
+export async function resolvePoint(x, y, windowId) {
+    if (!windowId)
+        return { x, y };
+    const win = (await getPlatform().listWindows()).find(w => w.id === windowId);
+    if (!win)
+        throw new WindowNotFoundError(windowId);
+    return { x: win.bounds.x + x, y: win.bounds.y + y };
+}
+export async function getSafetyContext(windowId) {
+    const target = activeTargetContext;
+    const effectiveWindowId = windowId ?? target?.windowId;
+    let windowTitle;
+    if (effectiveWindowId) {
+        try {
+            const windows = await getPlatform().listWindows();
+            const win = windows.find(w => w.id === effectiveWindowId);
+            windowTitle = win?.title;
+        }
+        catch { /* best effort */ }
+    }
+    if (!windowTitle && target?.title) {
+        windowTitle = target.title;
+    }
+    let url;
+    const platform = getPlatform();
+    if (platform.getActiveBrowserContext) {
+        try {
+            const appName = target?.appName;
+            const ctx = await platform.getActiveBrowserContext(appName);
+            url = ctx?.url;
+        }
+        catch { /* best effort */ }
+    }
+    return { windowTitle, url };
+}
+export function jsonText(value) {
+    return { type: "text", text: JSON.stringify(value, null, 2) };
+}
+export function recoveryHint(code) {
+    switch (code) {
+        case "WINDOW_NOT_FOUND":
+            return "Run list_windows again, then retry with a fresh windowId or omit windowId for screen coordinates.";
+        case "TARGET_STALE":
+            return "Run focus_app again for the target app, or run list_windows and retry with a fresh windowId.";
+        case "ELEMENT_NOT_FOUND":
+            return "Run find_element again, then retry with a fresh elementId.";
+        case "PERMISSION_DENIED":
+            return "Run doctor and grant the missing macOS permission, then restart the launching client.";
+        case "UNSUPPORTED_PARAMETER":
+            return "Remove or replace the unsupported parameter; inspect tools/list for this tool schema.";
+        case "SAFETY_BLOCKED":
+            return "Choose a less risky action or ask the user to perform it manually.";
+        case "INPUT_FAILED":
+            return "Observe current state with screenshot or get_window_state before retrying manually.";
+        case "CAPTURE_FAILED":
+            return "Run doctor to check Screen Recording permission, then retry screenshot or ocr.";
+        case "COORDINATE_OUT_OF_BOUNDS":
+            return "Run get_screen_size or list_windows, then retry with coordinates inside the active display or window bounds.";
+        default:
+            return "Inspect the error message, observe the current UI state, and retry only if the operation is safe.";
+    }
+}
+export function errorDetails(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const code = error instanceof UcuError ? error.code : "UNKNOWN_ERROR";
+    const retryable = error instanceof UcuError ? error.retryable : false;
+    const inlineHint = err instanceof UcuError ? err.hint : undefined;
+    const details = {
+        name: err.name,
+        code,
+        retryable,
+        message: err.message,
+        recovery: recoveryHint(code),
+    };
+    if (inlineHint) {
+        details.hint = inlineHint;
+    }
+    return details;
+}
+let _actionCounter = 0;
+function nextActionId() {
+    _actionCounter = (_actionCounter + 1) % 1_000_000;
+    return `a${Date.now().toString(36)}-${_actionCounter.toString(36)}`;
+}
+export function buildActionReceipt(action, status, target, result, captureRequested, captureFormat, captureMaxWidth, captureError, warnings = []) {
+    const captureStatus = captureRequested
+        ? captureError ? "error" : "ok"
+        : "skipped";
+    return {
+        actionId: nextActionId(),
+        action,
+        status,
+        target,
+        result,
+        capture: {
+            requested: captureRequested,
+            status: captureStatus,
+            ...(captureFormat && { format: captureFormat }),
+            ...(captureMaxWidth && { maxWidth: captureMaxWidth }),
+            ...(captureError && { error: captureError }),
+        },
+        warnings,
+        next: captureError
+            ? "screenshot"
+            : status === "partial"
+                ? "get_window_state"
+                : "find_element or get_window_state",
+    };
+}
+export function mcpErrorResponse(error) {
+    return {
+        isError: true,
+        content: [
+            jsonText({
+                error: errorDetails(error),
+            }),
+        ],
+    };
+}
+export async function actionResponse(action, result, target, captureAfter, captureFormat = "jpeg", captureMaxWidth = 1280, warnings = []) {
+    const receipt = buildActionReceipt(action, "ok", target, result, captureAfter ?? false, captureFormat, captureMaxWidth, undefined, warnings);
+    if (!captureAfter) {
+        return { content: [jsonText(receipt)] };
+    }
+    try {
+        const buf = await getPlatform().screenshot(undefined, undefined, {
+            format: captureFormat,
+            maxWidth: captureMaxWidth,
+        });
+        return {
+            content: [
+                jsonText(receipt),
+                {
+                    type: "image",
+                    data: buf.toString("base64"),
+                    mimeType: `image/${captureFormat}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const partialReceipt = buildActionReceipt(action, "partial", target, result, true, captureFormat, captureMaxWidth, errorDetails(error), [...warnings, "Post-action screenshot capture failed"]);
+        return { content: [jsonText(partialReceipt)] };
+    }
+}
+const retryableActions = new Set([
+    "screenshot",
+    "list_windows",
+    "list_apps",
+    "get_window_state",
+    "get_cursor_position",
+    "get_screen_size",
+    "ocr",
+    "doctor",
+    "find_element",
+]);
+export async function withSafety(sa) {
+    const platform = getPlatform();
+    if (platform.isScreenLocked?.())
+        throw new SafetyError("Screen is locked");
+    const check = safety.checkAction(sa.action, sa.params, {
+        skipUserActivityPause: sa.skipUserActivityPause ?? classifyAction(sa.action) === "observe",
+    });
+    if (!check.allowed)
+        throw new SafetyError(check.reason ?? "Action blocked by safety guard");
+    if (sa.requiresAccessibility) {
+        const { granted } = await checkPermission("accessibility");
+        if (!granted)
+            throw new PermissionError("accessibility", process.platform);
+    }
+    if (sa.requiresScreenRecording) {
+        const { granted } = await checkPermission("screenRecording");
+        if (!granted)
+            throw new PermissionError("screenRecording", process.platform);
+    }
+    if (sa.dryRun)
+        return `[DRY-RUN] ${await sa.dryRun()}`;
+    const start = Date.now();
+    try {
+        return retryableActions.has(sa.action)
+            ? await retry(() => sa.execute())
+            : await sa.execute();
+    }
+    finally {
+        metrics.record(sa.action, Date.now() - start);
+    }
+}
+export function startUserActivityMonitor() {
+    if (userActivityInterval)
+        return;
+    try {
+        lastCursorPos = getPlatform().getCursorPosition();
+    }
+    catch {
+        // Keep the default when the cursor cannot be queried during startup.
+    }
+    userActivityInterval = setInterval(() => {
+        try {
+            const pos = getPlatform().getCursorPosition();
+            if (pos.x !== lastCursorPos.x || pos.y !== lastCursorPos.y) {
+                safety.recordUserActivity();
+                lastCursorPos = pos;
+            }
+        }
+        catch { /* can't check cursor */ }
+    }, 500);
+    userActivityInterval.unref?.();
+}
+export function stopUserActivityMonitor() {
+    if (userActivityInterval) {
+        clearInterval(userActivityInterval);
+        userActivityInterval = undefined;
+    }
+}

package/dist/src/mcp/tools/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool registry for UCU-MCP.
+ *
+ * Registers 24 MCP tools on the server and dispatches each call through
+ * a shared safety/permission/retry pipeline (`withSafety`).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export { getActiveTarget } from "./helpers.js";
+export { startUserActivityMonitor, stopUserActivityMonitor } from "./helpers.js";
+export { findElementInputSchema } from "./element-tools.js";
+export declare class ToolRegistry {
+    private static _instance;
+    readonly tools: string[];
+    private readonly _handlers;
+    static get instance(): ToolRegistry;
+    register(name: string, handler?: (args: Record<string, unknown>) => Promise<unknown>): void;
+    dispatch(name: string, args: Record<string, unknown>): Promise<any>;
+}
+export declare function registerTools(server: McpServer): void;

package/dist/src/mcp/tools/index.js

@@ -0,0 +1,54 @@
+/**
+ * Tool registry for UCU-MCP.
+ *
+ * Registers 24 MCP tools on the server and dispatches each call through
+ * a shared safety/permission/retry pipeline (`withSafety`).
+ */
+import { createLogger } from "../../util/logger.js";
+import { mcpErrorResponse } from "./helpers.js";
+import { registerScreenTools } from "./screen-tools.js";
+import { registerInputTools } from "./input-tools.js";
+import { registerKeyboardTools } from "./keyboard-tools.js";
+import { registerElementTools } from "./element-tools.js";
+import { registerAppTools } from "./app-tools.js";
+export { getActiveTarget } from "./helpers.js";
+export { startUserActivityMonitor, stopUserActivityMonitor } from "./helpers.js";
+export { findElementInputSchema } from "./element-tools.js";
+const log = createLogger("tools");
+export class ToolRegistry {
+    static _instance;
+    tools = [];
+    _handlers = new Map();
+    static get instance() { if (!ToolRegistry._instance)
+        ToolRegistry._instance = new ToolRegistry(); return ToolRegistry._instance; }
+    register(name, handler) {
+        this.tools.push(name);
+        if (handler)
+            this._handlers.set(name, handler);
+    }
+    async dispatch(name, args) {
+        const handler = this._handlers.get(name);
+        if (!handler)
+            return { isError: true, content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+        return handler(args);
+    }
+}
+export function registerTools(server) {
+    const registry = ToolRegistry.instance;
+    const registerTool = (name, description, schema, handler) => {
+        server.tool(name, description, schema, async (params) => {
+            try {
+                return await handler(params);
+            }
+            catch (error) {
+                return mcpErrorResponse(error);
+            }
+        });
+    };
+    registerScreenTools(registerTool);
+    registerInputTools(registerTool);
+    registerKeyboardTools(registerTool);
+    registerElementTools(registerTool);
+    registerAppTools(registerTool);
+    log.info("Registered tools", { count: registry.tools.length, tools: registry.tools.join(", ") });
+}

package/dist/src/mcp/tools/input-tools.d.ts

@@ -0,0 +1,2 @@
+import { type RegisterToolFn } from "./helpers.js";
+export declare function registerInputTools(registerTool: RegisterToolFn): void;

package/dist/src/mcp/tools/input-tools.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { getPlatform, resolvePoint, getSafetyContext, withSafety, actionResponse, captureAfterFields, } from "./helpers.js";
+export function registerInputTools(registerTool) {
+    registerTool("click", "Click at screen coordinates", {
+        x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
+        button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
+        windowId: z.string().optional().describe("If set, x/y are relative to this window"),
+        ...captureAfterFields,
+    }, async (params) => {
+        const pt = await resolvePoint(params.x, params.y, params.windowId);
+        const safetyCtx = await getSafetyContext(params.windowId);
+        await withSafety({ action: "click", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button) });
+        return actionResponse("click", { clicked: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("double_click", "Double-click at screen coordinates", {
+        x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
+        button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
+        windowId: z.string().optional().describe("If set, x/y are relative to this window"),
+        ...captureAfterFields,
+    }, async (params) => {
+        const pt = await resolvePoint(params.x, params.y, params.windowId);
+        const safetyCtx = await getSafetyContext(params.windowId);
+        await withSafety({ action: "double_click", params: { x: pt.x, y: pt.y, doubleClick: true, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button, true) });
+        return actionResponse("double_click", { doubleClicked: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("scroll", "Scroll at coordinates", {
+        x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
+        deltaX: z.number().default(0).describe("Horizontal scroll"), deltaY: z.number().describe("Vertical scroll (negative = up)"),
+        windowId: z.string().optional().describe("If set, x/y are relative to this window"),
+        ...captureAfterFields,
+    }, async (params) => {
+        const pt = await resolvePoint(params.x, params.y, params.windowId);
+        const deltaX = params.deltaX ?? 0;
+        const safetyCtx = await getSafetyContext(params.windowId);
+        await withSafety({ action: "scroll", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().scroll(pt.x, pt.y, deltaX, params.deltaY) });
+        return actionResponse("scroll", { scrolled: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("drag", "Drag from one point to another", {
+        startX: z.number().describe("Start X"), startY: z.number().describe("Start Y"),
+        endX: z.number().describe("End X"), endY: z.number().describe("End Y"),
+        button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
+        windowId: z.string().optional().describe("If set, start/end coordinates are relative to this window"),
+        duration: z.number().optional().describe("Drag duration in ms"),
+        ...captureAfterFields,
+    }, async (params) => {
+        const start = await resolvePoint(params.startX, params.startY, params.windowId);
+        const end = await resolvePoint(params.endX, params.endY, params.windowId);
+        const safetyCtx = await getSafetyContext(params.windowId);
+        await withSafety({ action: "drag", params: { startX: start.x, startY: start.y, endX: end.x, endY: end.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().drag(start.x, start.y, end.x, end.y, params.button, params.duration) });
+        return actionResponse("drag", { dragged: true, startX: start.x, startY: start.y, endX: end.x, endY: end.y }, { startX: start.x, startY: start.y, endX: end.x, endY: end.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("move", "Move cursor to coordinates", {
+        x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
+        windowId: z.string().optional().describe("If set, x/y are relative to this window"),
+        ...captureAfterFields,
+    }, async (params) => {
+        const pt = await resolvePoint(params.x, params.y, params.windowId);
+        const safetyCtx = await getSafetyContext(params.windowId);
+        await withSafety({ action: "move", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().move(pt.x, pt.y) });
+        return actionResponse("move", { moved: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("get_cursor_position", "Get current cursor position", {}, async () => {
+        const pos = await withSafety({ action: "get_cursor_position", params: {}, execute: () => Promise.resolve(getPlatform().getCursorPosition()) });
+        return { content: [{ type: "text", text: JSON.stringify(pos, null, 2) }] };
+    });
+}

package/dist/src/mcp/tools/keyboard-tools.d.ts

@@ -0,0 +1,2 @@
+import { type RegisterToolFn } from "./helpers.js";
+export declare function registerKeyboardTools(registerTool: RegisterToolFn): void;

package/dist/src/mcp/tools/keyboard-tools.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { UnsupportedParameterError } from "../../util/errors.js";
+import { getPlatform, getSafetyContext, withSafety, actionResponse, captureAfterFields, } from "./helpers.js";
+export function registerKeyboardTools(registerTool) {
+    registerTool("type_text", "Type text at the current cursor position", {
+        text: z.string().describe("Text to type"), delay: z.number().optional().describe("Delay between keystrokes in ms"),
+        windowId: z.string().optional().describe("UNSUPPORTED: windowId-targeted keyboard typing is not implemented"),
+        ...captureAfterFields,
+    }, async (params) => {
+        if (params.windowId)
+            throw new UnsupportedParameterError("windowId-targeted keyboard typing is not implemented");
+        const safetyCtx = await getSafetyContext();
+        await withSafety({ action: "type_text", params: { text: params.text, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().type(params.text, params.delay) });
+        return actionResponse("type_text", { typed: true, charCount: params.text.length }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+    registerTool("press_key", "Press a keyboard shortcut", {
+        keys: z.array(z.string()).optional().describe("Keys to press simultaneously"),
+        key: z.string().optional().describe("Single key to press (alias for keys)"),
+        modifiers: z.array(z.string()).optional().describe("Modifier keys used with key, such as cmd, shift, alt, or ctrl"),
+        windowId: z.string().optional().describe("UNSUPPORTED: windowId-targeted key events are not implemented"),
+        ...captureAfterFields,
+    }, async (params) => {
+        if (params.windowId)
+            throw new UnsupportedParameterError("windowId-targeted key events are not implemented");
+        const keys = params.keys ?? [
+            ...(params.modifiers ?? []),
+            ...(params.key ? [params.key] : []),
+        ];
+        if (keys.length === 0)
+            throw new UnsupportedParameterError("press_key requires at least one key");
+        const safetyCtx = await getSafetyContext();
+        await withSafety({ action: "press_key", params: { keys, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().key(keys) });
+        return actionResponse("press_key", { pressed: true, keys }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+    });
+}

package/dist/src/mcp/tools/screen-tools.d.ts

@@ -0,0 +1,2 @@
+import { type RegisterToolFn } from "./helpers.js";
+export declare function registerScreenTools(registerTool: RegisterToolFn): void;

package/dist/src/mcp/tools/screen-tools.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { checkPermission } from "../../safety/permissions.js";
+import { UnsupportedParameterError } from "../../util/errors.js";
+import { getPlatform, getActiveTarget, withSafety, } from "./helpers.js";
+export function registerScreenTools(registerTool) {
+    registerTool("screenshot", "Capture a screenshot of the entire screen or a region", {
+        display: z.number().optional().describe("Display index (default 0)"),
+        windowId: z.string().optional().describe("Window ID from list_windows; when set, captures that window"),
+        region: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional().describe("Region to capture"),
+        format: z.enum(["png", "jpeg"]).default("png").describe("Image format"),
+        maxWidth: z.number().default(1280).describe("Maximum output width in pixels. Aspect ratio is preserved."),
+    }, async (params) => {
+        if (params.windowId && params.region)
+            throw new UnsupportedParameterError("screenshot windowId cannot be combined with region");
+        const options = { format: params.format, maxWidth: params.maxWidth };
+        const buf = await withSafety({
+            action: "screenshot",
+            params,
+            requiresScreenRecording: true,
+            execute: () => params.windowId
+                ? getPlatform().screenshotWindow
+                    ? getPlatform().screenshotWindow(params.windowId, options)
+                    : Promise.reject(new UnsupportedParameterError("window screenshots are not implemented on this platform"))
+                : getPlatform().screenshot(params.display, params.region, options),
+        });
+        return { content: [{ type: "image", data: buf.toString("base64"), mimeType: `image/${params.format}` }] };
+    });
+    registerTool("list_windows", "List all visible windows on screen", {
+        includeMinimized: z.boolean().optional().describe("Include minimized windows"),
+    }, async (params) => {
+        const windows = await withSafety({ action: "list_windows", params: {}, requiresAccessibility: true, execute: () => getPlatform().listWindows(params.includeMinimized) });
+        let diagnostics;
+        if (windows.length === 0) {
+            let accessibility = "unknown";
+            try {
+                const { granted } = await checkPermission("accessibility");
+                accessibility = granted ? "granted" : "denied";
+            }
+            catch { /* keep unknown */ }
+            const axNote = accessibility === "denied"
+                ? "Accessibility is currently denied to this terminal — grant it via System Settings > Privacy & Security > Accessibility, then retry."
+                : accessibility === "granted"
+                    ? "Accessibility is granted. If you expected a specific app to appear here, it is likely an Electron app whose AX tree is not exposed to System Events. Pixel-level workaround: call screenshot, then ocr to locate the target UI text and get its bounding box, then click(x, y) at those screen coordinates. Alternatively, modify the app's config file or database directly."
+                    : "Accessibility status is unknown. Run `doctor` first to verify.";
+            diagnostics = { hint: `list_windows returned 0 windows. ${axNote}`, accessibility };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(diagnostics ? { windows, diagnostics } : windows, null, 2) }] };
+    });
+    registerTool("get_window_state", "Get detailed state of a window including accessibility tree", {
+        windowId: z.string().optional().describe("Window ID"), depth: z.number().optional().describe("AX tree depth"), includeBounds: z.boolean().optional().describe("Include element bounds"),
+    }, async (params) => {
+        const effectiveWindowId = params.windowId || getActiveTarget()?.windowId;
+        const state = await withSafety({ action: "get_window_state", params: {}, requiresAccessibility: true, execute: () => getPlatform().getWindowState(effectiveWindowId, params.depth, params.includeBounds) });
+        return { content: [{ type: "text", text: JSON.stringify(state, null, 2) }] };
+    });
+    registerTool("get_screen_size", "Get screen dimensions and scale factor", {
+        display: z.number().optional().describe("Display index"),
+    }, async (params) => {
+        const result = await withSafety({ action: "get_screen_size", params: {}, execute: () => Promise.resolve(getPlatform().getScreenSize(params.display)) });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+    registerTool("ocr", "Perform OCR on screen region", {
+        display: z.number().optional().describe("Display index"),
+        region: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional().describe("Region to OCR"),
+    }, async (params) => {
+        const result = await withSafety({ action: "ocr", params: {}, requiresScreenRecording: true, execute: () => getPlatform().ocr(params.display, params.region) });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    });
+}

package/dist/src/mcp/tools.d.ts

@@ -11,6 +11,15 @@ import type { AppTarget } from "../platform/base.js";
  * Get the currently active target context (set by focus_app).
  */
 export declare function getActiveTarget(): AppTarget | undefined;
+/**
+ * Exported so unit tests can pin the schema constraint directly instead
+ * of going through the McpServer wrapper (which `handler()` calls
+ * bypass). (Herschel review Major: 0.3.5's value='' test was a
+ * tautology because it re-created a local zod schema instead of
+ * asserting against this one.)
+ *
+ * @internal Not part of the public API — may change without a semver bump.
+ */
 export declare const findElementInputSchema: {
     text: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;