ucu-mcp 0.1.3 → 0.3.0

package/dist/src/platform/base.d.ts

@@ -38,10 +38,12 @@ export interface AppInfo {
     windowCount: number;
 }
 export interface AppTarget {
+    targetId: string;
     appName: string;
     pid: number;
     windowId?: string;
     title?: string;
+    capturedAt: string;
 }
 export interface BrowserContext {
     appName: string;
@@ -81,6 +83,17 @@ export interface FindElementOptions {
     depth?: number;
     includeBounds?: boolean;
     maxResults?: number;
+    textMode?: "contains" | "exact" | "regex";
+    visibleOnly?: boolean;
+    /** Match against the AX element's current value attribute (respects textMode). */
+    value?: string;
+    /** Return only the Nth match (0-based) after all other filtering and sorting. */
+    index?: number;
+    /** Sort results by ascending distance to this point and return closest first. */
+    near?: {
+        x: number;
+        y: number;
+    };
 }
 export interface FindElementResult {
     id: string;
@@ -95,6 +108,16 @@ export interface FindElementResult {
     };
     description?: string;
 }
+export interface FindElementMetrics {
+    scannedCount: number;
+    matchedCount: number;
+    durationMs: number;
+    truncated: boolean;
+}
+export interface FindElementResponse {
+    results: FindElementResult[];
+    metrics: FindElementMetrics;
+}
 export interface WindowState {
     window: WindowInfo;
     focusedElement?: ElementInfo;
@@ -117,11 +140,13 @@ export interface Platform {
     ocr(display?: number, region?: ScreenRegion): Promise<OcrResult>;
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
-    findElement(options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(elementId: string, app?: string): Promise<void>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
     setElementValue?(elementId: string, value: string, app?: string): Promise<void>;
     isScreenLocked?(): boolean;
     saveFocus?(): Promise<void>;
     restoreFocus?(): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
 }

package/dist/src/platform/linux.d.ts

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResult } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -16,7 +16,9 @@ export declare class LinuxPlatform implements Platform {
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
-    findElement(_options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(_options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(_elementId: string, _app?: string): Promise<void>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
 }

package/dist/src/platform/linux.js

@@ -1,3 +1,27 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { PlatformError } from "../util/errors.js";
+/** Pick the first available clipboard utility, preferring xclip. */
+function pickClipboardTool() {
+    for (const bin of ["/usr/bin/xclip", "/usr/local/bin/xclip", "xclip"]) {
+        if (bin.startsWith("/") ? existsSync(bin) : which(bin))
+            return "xclip";
+    }
+    for (const bin of ["/usr/bin/xsel", "/usr/local/bin/xsel", "xsel"]) {
+        if (bin.startsWith("/") ? existsSync(bin) : which(bin))
+            return "xsel";
+    }
+    return undefined;
+}
+function which(bin) {
+    try {
+        execFileSync("which", [bin], { encoding: "utf-8", timeout: 2000, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -59,4 +83,31 @@ export class LinuxPlatform {
     async typeInElement(_elementId, _text, _app, _clearFirst) {
         throw new Error("Not implemented: Linux typeInElement");
     }
+    async readClipboard() {
+        const tool = pickClipboardTool();
+        if (!tool) {
+            throw new PlatformError("readClipboard requires xclip or xsel on PATH", false);
+        }
+        try {
+            const args = tool === "xclip" ? ["-selection", "clipboard", "-o"] : ["--clipboard", "--output"];
+            const out = execFileSync(tool, args, { encoding: "utf-8", timeout: 5000 });
+            return out;
+        }
+        catch (error) {
+            throw new PlatformError(`read_clipboard failed: ${error.message}`);
+        }
+    }
+    async writeClipboard(text) {
+        const tool = pickClipboardTool();
+        if (!tool) {
+            throw new PlatformError("writeClipboard requires xclip or xsel on PATH", false);
+        }
+        try {
+            const args = tool === "xclip" ? ["-selection", "clipboard"] : ["--clipboard", "--input"];
+            execFileSync(tool, args, { input: text, encoding: "utf-8", timeout: 5000 });
+        }
+        catch (error) {
+            throw new PlatformError(`write_clipboard failed: ${error.message}`);
+        }
+    }
 }

package/dist/src/platform/macos.d.ts

@@ -1,8 +1,10 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResult, AppInfo, AppTarget, BrowserContext, ScreenshotOptions } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, AppInfo, AppTarget, BrowserContext, ScreenshotOptions } from "./base.js";
 export declare class MacOSPlatform implements Platform {
     private readonly elementCache;
     private readonly elementCacheTtlMs;
     private readonly elementCacheMaxSize;
+    private readonly windowCacheTtlMs;
+    private windowCache;
     private activeTarget;
     private savedFocus;
     /** Remove expired entries from the element cache. */
@@ -11,6 +13,8 @@ export declare class MacOSPlatform implements Platform {
     private evictOverflowCacheEntries;
     /** Check whether a cached element descriptor has expired. */
     private isCacheEntryExpired;
+    /** Validate that the active target window still exists. */
+    validateActiveTarget(): Promise<void>;
     /** Save the current frontmost app/window so we can restore after an action. */
     saveFocus(): Promise<void>;
     /** Restore the previously saved frontmost app/window. */
@@ -30,10 +34,14 @@ export declare class MacOSPlatform implements Platform {
     scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
     getCursorPosition(): CursorPosition;
     ocr(display?: number, region?: ScreenRegion): Promise<OcrResult>;
+    private ocrNative;
+    private ocrJxa;
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
-    findElement(options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(elementId: string, app?: string): Promise<void>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
     setElementValue(elementId: string, value: string, app?: string): Promise<void>;
 }