ucu-mcp 0.1.0

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

@@ -0,0 +1,18 @@
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResult } from "./base.js";
+export declare class WindowsPlatform implements Platform {
+    screenshot(_display?: number, _region?: ScreenRegion): Promise<Buffer>;
+    getScreenSize(_display?: number): ScreenSize;
+    listWindows(_includeMinimized?: boolean): Promise<WindowInfo[]>;
+    getWindowState(_windowId?: string, _depth?: number, _includeBounds?: boolean): Promise<WindowState>;
+    click(_x: number, _y: number, _button?: "left" | "right" | "middle", _doubleClick?: boolean): Promise<void>;
+    move(_x: number, _y: number): Promise<void>;
+    drag(_startX: number, _startY: number, _endX: number, _endY: number, _button?: "left" | "right" | "middle", _duration?: number): Promise<void>;
+    scroll(_x: number, _y: number, _deltaX: number, _deltaY: number): Promise<void>;
+    getCursorPosition(): CursorPosition;
+    type(_text: string, _delay?: number): Promise<void>;
+    key(_keys: string[]): Promise<void>;
+    ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
+    findElement(_options: FindElementOptions): Promise<FindElementResult[]>;
+    clickElement(_elementId: string, _app?: string): Promise<void>;
+    typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
+}

package/dist/src/platform/windows.js

@@ -0,0 +1,48 @@
+export class WindowsPlatform {
+    async screenshot(_display, _region) {
+        throw new Error("Not implemented: Windows screenshot");
+    }
+    getScreenSize(_display) {
+        throw new Error("Not implemented: Windows getScreenSize");
+    }
+    async listWindows(_includeMinimized) {
+        throw new Error("Not implemented: Windows listWindows");
+    }
+    async getWindowState(_windowId, _depth, _includeBounds) {
+        // TODO: Implement using UI Automation API
+        throw new Error("Not implemented: Windows getWindowState");
+    }
+    async click(_x, _y, _button, _doubleClick) {
+        throw new Error("Not implemented: Windows click");
+    }
+    async move(_x, _y) {
+        throw new Error("Not implemented: Windows move");
+    }
+    async drag(_startX, _startY, _endX, _endY, _button, _duration) {
+        throw new Error("Not implemented: Windows drag");
+    }
+    async scroll(_x, _y, _deltaX, _deltaY) {
+        throw new Error("Not implemented: Windows scroll");
+    }
+    getCursorPosition() {
+        throw new Error("Not implemented: Windows getCursorPosition");
+    }
+    async type(_text, _delay) {
+        throw new Error("Not implemented: Windows type");
+    }
+    async key(_keys) {
+        throw new Error("Not implemented: Windows key");
+    }
+    async ocr(_display, _region) {
+        throw new Error("Not implemented: Windows OCR");
+    }
+    async findElement(_options) {
+        throw new Error("Not implemented: Windows findElement");
+    }
+    async clickElement(_elementId, _app) {
+        throw new Error("Not implemented: Windows clickElement");
+    }
+    async typeInElement(_elementId, _text, _app, _clearFirst) {
+        throw new Error("Not implemented: Windows typeInElement");
+    }
+}

package/dist/src/safety/guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SafetyGuard - Action safety checker for UCU automation.
+ *
+ * Evaluates proposed actions against a set of configurable rules:
+ *   - key-blocklist: blocks dangerous keyboard shortcuts
+ *   - window-skip:   skips sensitive windows (banking, password managers)
+ *   - rate-limit:    throttles action frequency
+ */
+export interface SafetyCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+export interface SafetyGuardConfig {
+    /** Extra shortcut patterns to block (in addition to built-ins). */
+    blockedKeys?: string[];
+    /** Extra window title patterns to skip (in addition to built-ins). */
+    skippedWindows?: string[];
+    /** Extra URL patterns to block (in addition to built-ins). */
+    blockedUrls?: string[];
+    /** Disable text injection scanning for controlled test harnesses. */
+    allowUnsafeText?: boolean;
+    /** Minimum milliseconds between consecutive actions (default 100). */
+    rateLimitMs?: number;
+}
+export declare class SafetyGuard {
+    private readonly blockedKeys;
+    private readonly skippedWindows;
+    private readonly blockedUrls;
+    private readonly allowUnsafeText;
+    private readonly rateLimitMs;
+    private lastActionTime;
+    private lastUserActivityTime;
+    private userActivityPauseMs;
+    constructor(config?: SafetyGuardConfig);
+    /**
+     * Evaluate whether the proposed action should be allowed.
+     *
+     * @param action  The action type (e.g. "key", "click", "type", "screenshot").
+     * @param params  Arbitrary action parameters; expected keys depend on action.
+     *                - "key":         { keys: string[] }
+     *                - any action:    { windowTitle?: string }
+     */
+    checkAction(action: string, params?: Record<string, unknown>): SafetyCheckResult;
+    /** Record that the user performed an activity (mouse/keyboard). */
+    recordUserActivity(): void;
+    /** Set the pause duration after user activity (default 2000ms). */
+    setUserActivityPauseMs(ms: number): void;
+    /** Check if user activity pause is still active. */
+    isUserActivityPauseActive(): boolean;
+}

package/dist/src/safety/guard.js

@@ -0,0 +1,220 @@
+/**
+ * SafetyGuard - Action safety checker for UCU automation.
+ *
+ * Evaluates proposed actions against a set of configurable rules:
+ *   - key-blocklist: blocks dangerous keyboard shortcuts
+ *   - window-skip:   skips sensitive windows (banking, password managers)
+ *   - rate-limit:    throttles action frequency
+ */
+// ---------------------------------------------------------------------------
+// Built-in blocked shortcuts
+// ---------------------------------------------------------------------------
+const DEFAULT_BLOCKED_KEYS = [
+    // macOS – app-level
+    "cmd+q",
+    "cmd+w",
+    "cmd+l", // lock screen
+    // macOS – system-level
+    "cmd+option+esc", // Force-quit dialog
+    "cmd+ctrl+power", // force restart
+    "cmd+option+power", // sleep
+    // Windows / Linux
+    "alt+f4",
+    "alt+f2", // Linux run dialog
+    "ctrl+alt+del",
+    "ctrl+alt+backspace", // Linux kill X
+    "ctrl+alt+t", // Linux terminal
+];
+// ---------------------------------------------------------------------------
+// Built-in sensitive window patterns (case-insensitive substring match)
+// ---------------------------------------------------------------------------
+const DEFAULT_SKIPPED_WINDOWS = [
+    "1password",
+    "bitwarden",
+    "lastpass",
+    "keepass",
+    "dashlane",
+    "keychain access",
+    "钥匙串访问",
+    "bank",
+    "银行",
+    "paypal",
+    "stripe",
+    "robinhood",
+    "coinbase",
+];
+const DEFAULT_BLOCKED_URL_PATTERNS = [
+    "1password.com",
+    "bitwarden.com",
+    "lastpass.com",
+    "dashlane.com",
+    "keepersecurity.com",
+    "icloud.com/keychain",
+    "paypal.com",
+    "stripe.com",
+    "bank",
+    "bankofamerica.com",
+    "chase.com",
+    "wellsfargo.com",
+    "capitalone.com",
+    "americanexpress.com",
+    "coinbase.com",
+    "robinhood.com",
+    "binance.com",
+    "kraken.com",
+];
+const DEFAULT_TEXT_INJECTION_PATTERNS = [
+    { pattern: /\$\s*\(/, reason: "shell command substitution" },
+    { pattern: /`[^`]+`/, reason: "shell backtick substitution" },
+    { pattern: /&&|\|\|/, reason: "shell command chaining" },
+    { pattern: /\|\s*(sh|bash|zsh|python|ruby|perl|node)\b/i, reason: "piping into an interpreter" },
+    { pattern: /\b(sudo\s+rm|rm\s+-rf|mkfs|diskutil\s+erase|dd\s+if=|chmod\s+-R\s+777)\b/i, reason: "dangerous shell command" },
+    { pattern: /\b(ObjC\.import|Application\s*\(|do\s+shell\s+script)\b/, reason: "AppleScript/JXA injection primitive" },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Normalize a shortcut string to lowercase, trimmed, sorted modifiers. */
+function normalizeShortcut(raw) {
+    return raw
+        .toLowerCase()
+        .split("+")
+        .map((s) => s.trim())
+        .sort()
+        .join("+");
+}
+// ---------------------------------------------------------------------------
+// SafetyGuard
+// ---------------------------------------------------------------------------
+export class SafetyGuard {
+    blockedKeys;
+    skippedWindows;
+    blockedUrls;
+    allowUnsafeText;
+    rateLimitMs;
+    lastActionTime = 0;
+    lastUserActivityTime = 0;
+    userActivityPauseMs = 2000;
+    constructor(config) {
+        const extra = (config?.blockedKeys ?? []).map(normalizeShortcut);
+        this.blockedKeys = new Set([
+            ...DEFAULT_BLOCKED_KEYS.map(normalizeShortcut),
+            ...extra,
+        ]);
+        this.skippedWindows = [
+            ...DEFAULT_SKIPPED_WINDOWS,
+            ...(config?.skippedWindows ?? []),
+        ].map((p) => p.toLowerCase());
+        this.blockedUrls = [
+            ...DEFAULT_BLOCKED_URL_PATTERNS,
+            ...(config?.blockedUrls ?? []),
+        ].map((p) => p.toLowerCase());
+        this.allowUnsafeText = config?.allowUnsafeText ?? false;
+        this.rateLimitMs = config?.rateLimitMs ?? 100;
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Evaluate whether the proposed action should be allowed.
+     *
+     * @param action  The action type (e.g. "key", "click", "type", "screenshot").
+     * @param params  Arbitrary action parameters; expected keys depend on action.
+     *                - "key":         { keys: string[] }
+     *                - any action:    { windowTitle?: string }
+     */
+    checkAction(action, params = {}) {
+        // 1. Key blocklist -------------------------------------------------------
+        if (action === "key" || action === "press_key") {
+            const keys = params.keys;
+            if (keys && keys.length > 0) {
+                const normalized = normalizeShortcut(keys.join("+"));
+                if (this.blockedKeys.has(normalized)) {
+                    return {
+                        allowed: false,
+                        reason: `Blocked shortcut: ${keys.join("+")}`,
+                    };
+                }
+            }
+        }
+        // 2. Window skip ----------------------------------------------------------
+        const windowTitle = typeof params.windowTitle === "string" ? params.windowTitle : undefined;
+        if (windowTitle) {
+            const lower = windowTitle.toLowerCase();
+            for (const pattern of this.skippedWindows) {
+                if (lower.includes(pattern)) {
+                    return {
+                        allowed: false,
+                        reason: `Skipped sensitive window: "${windowTitle}"`,
+                    };
+                }
+            }
+        }
+        // 3. URL blocklist --------------------------------------------------------
+        const url = typeof params.url === "string" ? params.url : undefined;
+        if (url) {
+            const lower = url.toLowerCase();
+            for (const pattern of this.blockedUrls) {
+                if (lower.includes(pattern)) {
+                    return {
+                        allowed: false,
+                        reason: `Blocked sensitive URL: ${url}`,
+                    };
+                }
+            }
+        }
+        // 4. Text injection scan --------------------------------------------------
+        if (!this.allowUnsafeText && (action === "type" || action === "type_text" || action === "type_in_element" || action === "set_value")) {
+            const text = typeof params.text === "string"
+                ? params.text
+                : typeof params.value === "string"
+                    ? params.value
+                    : undefined;
+            if (text) {
+                for (const { pattern, reason } of DEFAULT_TEXT_INJECTION_PATTERNS) {
+                    if (pattern.test(text)) {
+                        return {
+                            allowed: false,
+                            reason: `Blocked suspicious typed text (${reason})`,
+                        };
+                    }
+                }
+            }
+        }
+        // 5. Rate limit -----------------------------------------------------------
+        const now = Date.now();
+        const elapsed = now - this.lastActionTime;
+        if (elapsed < this.rateLimitMs) {
+            return {
+                allowed: false,
+                reason: `Rate-limited: ${elapsed}ms since last action (min ${this.rateLimitMs}ms)`,
+            };
+        }
+        this.lastActionTime = now;
+        // 6. User activity pause --------------------------------------------------
+        if (this.isUserActivityPauseActive()) {
+            return {
+                allowed: false,
+                reason: `User activity detected — pausing automation for ${this.userActivityPauseMs}ms`,
+            };
+        }
+        return { allowed: true };
+    }
+    // -----------------------------------------------------------------------
+    // User Activity Monitoring
+    // -----------------------------------------------------------------------
+    /** Record that the user performed an activity (mouse/keyboard). */
+    recordUserActivity() {
+        this.lastUserActivityTime = Date.now();
+    }
+    /** Set the pause duration after user activity (default 2000ms). */
+    setUserActivityPauseMs(ms) {
+        this.userActivityPauseMs = ms;
+    }
+    /** Check if user activity pause is still active. */
+    isUserActivityPauseActive() {
+        if (this.userActivityPauseMs <= 0)
+            return false;
+        return Date.now() - this.lastUserActivityTime < this.userActivityPauseMs;
+    }
+}

package/dist/src/safety/permissions.d.ts

@@ -0,0 +1,17 @@
+export type PermissionType = "accessibility" | "screenRecording";
+export interface PermissionCheckResult {
+    granted: boolean;
+    missing: PermissionType[];
+}
+export interface PermissionDetail {
+    type: PermissionType;
+    granted: boolean;
+    instructions: string;
+}
+export declare function checkPermissions(): Promise<PermissionCheckResult>;
+export declare function checkPermission(type: "accessibility" | "screenRecording"): Promise<{
+    granted: boolean;
+    message?: string;
+}>;
+export declare function getPermissionInstructions(type: PermissionType): string;
+export declare function runPermissionDoctor(): Promise<PermissionDetail[]>;

package/dist/src/safety/permissions.js

@@ -0,0 +1,184 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Get the name of the terminal app that the user needs to authorize.
+ */
+function getTerminalAppName() {
+    // Walk up the process tree to find the terminal emulator
+    const ppid = process.ppid;
+    // Common terminal app names
+    const env = process.env.TERM_PROGRAM || "";
+    const nameMap = {
+        "Apple_Terminal": "Terminal.app",
+        "iTerm.app": "iTerm.app",
+        "vscode": "Visual Studio Code",
+        "alacritty": "Alacritty",
+        "kitty": "kitty",
+        "wezterm": "WezTerm",
+        "ghostty": "Ghostty",
+        "warp": "Warp",
+        "hyper": "Hyper",
+    };
+    return nameMap[env] || env || "your terminal app";
+}
+/**
+ * Open the macOS System Settings page for a permission.
+ */
+async function openPermissionSettings(type) {
+    const url = type === "accessibility"
+        ? "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+        : "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture";
+    try {
+        await execFileAsync("/usr/bin/open", [url], { timeout: 3000 });
+    }
+    catch {
+        // Non-critical — best effort
+    }
+}
+/**
+ * Request accessibility permission by triggering the macOS system dialog.
+ * Uses AXIsProcessTrustedWithOptions with kAXTrustedCheckOptionPrompt=true
+ * which shows the system authorization prompt.
+ */
+async function requestAccessibilityWithPrompt() {
+    try {
+        const script = `
+      ObjC.import('CoreServices');
+      var opts = $.NSDictionary.dictionaryWithObjectForObject(
+        $(true), $("kAXTrustedCheckOptionPrompt")
+      );
+      $.AXIsProcessTrustedWithOptions(opts);
+    `;
+        const { stdout } = await execFileAsync("/usr/bin/osascript", [
+            "-l", "JavaScript", "-e", script,
+        ], { timeout: 10000 });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check accessibility by trying to use System Events via osascript.
+ * macOS grants the PARENT process the TCC entry — we check via
+ * a simple AXAPI call that returns the current process's status.
+ *
+ * NOTE: When running via `node`, the TCC entry is for "Terminal.app"
+ * (or whichever terminal hosts node). The osascript subprocess
+ * inherits the parent's TCC for accessibility because it runs
+ * under the same application context via the shell.
+ */
+async function checkAccessibility() {
+    if (process.platform !== "darwin")
+        return true;
+    try {
+        const script = `
+      tell application "System Events"
+        return (count of processes) as text
+      end tell
+    `;
+        const { stdout } = await execFileAsync("/usr/bin/osascript", ["-e", script], {
+            timeout: 5000,
+        });
+        const count = parseInt(stdout.trim(), 10);
+        return !isNaN(count) && count > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check screen recording by attempting a minimal screenshot.
+ * screencapture respects TCC — it fails with a specific error
+ * if the calling process doesn't have Screen Recording permission.
+ */
+async function checkScreenRecording() {
+    if (process.platform !== "darwin")
+        return true;
+    try {
+        await execFileAsync("/usr/sbin/screencapture", [
+            "-x", "-R", "0,0,1,1", "/dev/null",
+        ], { timeout: 5000 });
+        return true;
+    }
+    catch (e) {
+        const msg = (e.stderr || e.message || "").toLowerCase();
+        // screencapture returns error when no permission
+        if (msg.includes("not authorized") || msg.includes("denied") || msg.includes("permission")) {
+            return false;
+        }
+        // Other errors (file system) — permission is likely granted
+        return true;
+    }
+}
+export async function checkPermissions() {
+    if (process.platform !== "darwin") {
+        return { granted: true, missing: [] };
+    }
+    const [hasAccessibility, hasScreenRecording] = await Promise.all([
+        checkAccessibility(),
+        checkScreenRecording(),
+    ]);
+    const missing = [];
+    if (!hasAccessibility)
+        missing.push("accessibility");
+    if (!hasScreenRecording)
+        missing.push("screenRecording");
+    return { granted: missing.length === 0, missing };
+}
+export async function checkPermission(type) {
+    if (process.platform !== "darwin") {
+        return { granted: true };
+    }
+    const appName = getTerminalAppName();
+    if (type === "accessibility") {
+        const granted = await checkAccessibility();
+        if (!granted) {
+            // Trigger the macOS system prompt for Accessibility
+            await requestAccessibilityWithPrompt();
+            // Also open System Settings as a fallback
+            await openPermissionSettings("accessibility");
+            return {
+                granted: false,
+                message: `macOS Accessibility permission required for ${appName}. A system dialog should have appeared requesting authorization — please approve it. If no dialog appeared, open System Settings > Privacy & Security > Accessibility and manually enable ${appName}. Then restart ucu-mcp.`,
+            };
+        }
+        return { granted: true };
+    }
+    const granted = await checkScreenRecording();
+    if (!granted) {
+        // Open System Settings for Screen Recording
+        await openPermissionSettings("screenRecording");
+        return {
+            granted: false,
+            message: `macOS Screen Recording permission required for ${appName}. Opening System Settings now — please navigate to Privacy & Security > Screen Recording and enable ${appName}. Then restart ucu-mcp.`,
+        };
+    }
+    return { granted: true };
+}
+export function getPermissionInstructions(type) {
+    const instructions = {
+        accessibility: "Open System Settings > Privacy & Security > Accessibility. Add and enable your terminal application (e.g. Terminal.app, iTerm2, Alacritty). Restart ucu-mcp after granting.",
+        screenRecording: "Open System Settings > Privacy & Security > Screen Recording. Add and enable your terminal application. Restart ucu-mcp after granting.",
+    };
+    return instructions[type];
+}
+export async function runPermissionDoctor() {
+    const details = [];
+    const [accessibility, screenRecording] = await Promise.all([
+        checkAccessibility(),
+        checkScreenRecording(),
+    ]);
+    details.push({
+        type: "accessibility",
+        granted: accessibility,
+        instructions: getPermissionInstructions("accessibility"),
+    });
+    details.push({
+        type: "screenRecording",
+        granted: screenRecording,
+        instructions: getPermissionInstructions("screenRecording"),
+    });
+    return details;
+}

package/dist/src/util/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Error taxonomy for UCU-MCP.
+ *
+ * All errors inherit from UcuError and are categorized by:
+ *   - code: machine-readable error code
+ *   - retryable: whether the operation can be retried
+ */
+export declare class UcuError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(message: string, code?: string, retryable?: boolean);
+}
+/**
+ * Native API call failed (permissions, OS error, timeout).
+ */
+export declare class PlatformError extends UcuError {
+    constructor(message: string, retryable?: boolean);
+}
+/**
+ * Action blocked by safety guard.
+ */
+export declare class SafetyError extends UcuError {
+    constructor(message: string);
+}
+/**
+ * Missing OS accessibility/screen-recording permissions.
+ */
+export declare class PermissionError extends UcuError {
+    constructor(permission: string, platform: string);
+}
+/**
+ * Requested window ID no longer exists.
+ */
+export declare class WindowNotFoundError extends UcuError {
+    constructor(windowId: string);
+}
+/**
+ * Click/scroll target is outside screen bounds.
+ */
+export declare class CoordinateError extends UcuError {
+    constructor(x: number, y: number, bounds: {
+        width: number;
+        height: number;
+    });
+}
+/**
+ * Keystroke or mouse event injection failed.
+ */
+export declare class InputSynthesisError extends UcuError {
+    constructor(message: string);
+}
+/**
+ * The request is well-formed JSON, but asks for a parameter combination this
+ * implementation does not support.
+ */
+export declare class UnsupportedParameterError extends UcuError {
+    constructor(message: string);
+}
+/**
+ * Screenshot or window-state capture failed.
+ */
+export declare class CaptureError extends UcuError {
+    constructor(message: string);
+}