ucu-mcp 0.1.0

package/dist/src/util/errors.js

@@ -0,0 +1,109 @@
+/**
+ * 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
+ */
+// ---------------------------------------------------------------------------
+// Base Error Class
+// ---------------------------------------------------------------------------
+export class UcuError extends Error {
+    code;
+    retryable;
+    constructor(message, code = "UCU_ERROR", retryable = false) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+// ---------------------------------------------------------------------------
+// Platform Errors
+// ---------------------------------------------------------------------------
+/**
+ * Native API call failed (permissions, OS error, timeout).
+ */
+export class PlatformError extends UcuError {
+    constructor(message, retryable = true) {
+        super(message, "PLATFORM_ERROR", retryable);
+    }
+}
+// ---------------------------------------------------------------------------
+// Safety Errors
+// ---------------------------------------------------------------------------
+/**
+ * Action blocked by safety guard.
+ */
+export class SafetyError extends UcuError {
+    constructor(message) {
+        super(message, "SAFETY_BLOCKED", false);
+    }
+}
+// ---------------------------------------------------------------------------
+// Permission Errors
+// ---------------------------------------------------------------------------
+/**
+ * Missing OS accessibility/screen-recording permissions.
+ */
+export class PermissionError extends UcuError {
+    constructor(permission, platform) {
+        super(getPermissionMessage(permission, platform), "PERMISSION_DENIED", false);
+    }
+}
+function getPermissionMessage(permission, platform) {
+    if (platform === "darwin") {
+        return `Missing ${permission} permission. Grant it in System Settings > Privacy & Security > ${permission}.`;
+    }
+    return `Missing ${permission} permission for this operation.`;
+}
+// ---------------------------------------------------------------------------
+// Window Errors
+// ---------------------------------------------------------------------------
+/**
+ * Requested window ID no longer exists.
+ */
+export class WindowNotFoundError extends UcuError {
+    constructor(windowId) {
+        super(`Window ${windowId} not found. It may have been closed. Run list_windows to get fresh IDs.`, "WINDOW_NOT_FOUND", false);
+    }
+}
+// ---------------------------------------------------------------------------
+// Input Errors
+// ---------------------------------------------------------------------------
+/**
+ * Click/scroll target is outside screen bounds.
+ */
+export class CoordinateError extends UcuError {
+    constructor(x, y, bounds) {
+        super(`Coordinate (${x}, ${y}) is outside screen bounds (0-${bounds.width}, 0-${bounds.height}).`, "COORDINATE_OUT_OF_BOUNDS", false);
+    }
+}
+/**
+ * Keystroke or mouse event injection failed.
+ */
+export class InputSynthesisError extends UcuError {
+    constructor(message) {
+        super(message, "INPUT_FAILED", true);
+    }
+}
+/**
+ * The request is well-formed JSON, but asks for a parameter combination this
+ * implementation does not support.
+ */
+export class UnsupportedParameterError extends UcuError {
+    constructor(message) {
+        super(message, "UNSUPPORTED_PARAMETER", false);
+    }
+}
+// ---------------------------------------------------------------------------
+// Capture Errors
+// ---------------------------------------------------------------------------
+/**
+ * Screenshot or window-state capture failed.
+ */
+export class CaptureError extends UcuError {
+    constructor(message) {
+        super(message, "CAPTURE_FAILED", true);
+    }
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Structured logging for UCU-MCP.
+ *
+ * Pino-compatible interface built on console — no external dependency.
+ * Each log entry is a JSON line with level, timestamp, name, and
+ * optional correlationId plus arbitrary structured fields.
+ *
+ * Usage:
+ *   import { createLogger } from "../util/logger.js";
+ *   const log = createLogger("tools");
+ *   log.info("Tool executed", { tool: "click", duration: 42 });
+ *   log.error("Tool failed", { error: "boom" });
+ *
+ * Correlation IDs are scoped per-logger via `withCorrelationId`:
+ *   const log = createLogger("safety").withCorrelationId("req-123");
+ *   log.info("check passed");  // → { ..., correlationId: "req-123" }
+ */
+interface LogFields {
+    [key: string]: unknown;
+}
+interface Logger {
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    debug(message: string, fields?: LogFields): void;
+    withCorrelationId(id: string): Logger;
+}
+/**
+ * Create a named logger instance.
+ *
+ * @param name - Module / subsystem name (included in every log entry)
+ * @returns Logger with info, warn, error, debug, and withCorrelationId
+ */
+declare function createLogger(name: string): Logger;
+/**
+ * Default root logger for backward compatibility.
+ * Prefer `createLogger("module")` for new code.
+ */
+declare const logger: Logger;
+export { createLogger, logger };
+export type { Logger, LogFields };

package/dist/src/util/logger.js

@@ -0,0 +1,92 @@
+/**
+ * Structured logging for UCU-MCP.
+ *
+ * Pino-compatible interface built on console — no external dependency.
+ * Each log entry is a JSON line with level, timestamp, name, and
+ * optional correlationId plus arbitrary structured fields.
+ *
+ * Usage:
+ *   import { createLogger } from "../util/logger.js";
+ *   const log = createLogger("tools");
+ *   log.info("Tool executed", { tool: "click", duration: 42 });
+ *   log.error("Tool failed", { error: "boom" });
+ *
+ * Correlation IDs are scoped per-logger via `withCorrelationId`:
+ *   const log = createLogger("safety").withCorrelationId("req-123");
+ *   log.info("check passed");  // → { ..., correlationId: "req-123" }
+ */
+// ── Level precedence ──────────────────────────────────────────────────────
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function resolveMinLevel() {
+    const env = process.env.UCU_LOG_LEVEL?.toLowerCase();
+    if (env && env in LEVEL_ORDER)
+        return env;
+    return "info";
+}
+const MIN_LEVEL = LEVEL_ORDER[resolveMinLevel()];
+// ── JSON formatting ───────────────────────────────────────────────────────
+function formatEntry(level, name, message, correlationId, fields) {
+    const entry = {
+        level,
+        time: Date.now(),
+        timestamp: new Date().toISOString(),
+        name,
+        msg: message,
+    };
+    if (correlationId)
+        entry.correlationId = correlationId;
+    if (fields)
+        Object.assign(entry, fields);
+    return JSON.stringify(entry);
+}
+// ── Logger implementation ─────────────────────────────────────────────────
+class ConsoleLogger {
+    _name;
+    _correlationId;
+    constructor(name, correlationId) {
+        this._name = name;
+        this._correlationId = correlationId;
+    }
+    emit(level, message, fields) {
+        if (LEVEL_ORDER[level] < MIN_LEVEL)
+            return;
+        // Write to stderr so stdout stays clean for MCP transport
+        console.error(formatEntry(level, this._name, message, this._correlationId, fields));
+    }
+    info(message, fields) {
+        this.emit("info", message, fields);
+    }
+    warn(message, fields) {
+        this.emit("warn", message, fields);
+    }
+    error(message, fields) {
+        this.emit("error", message, fields);
+    }
+    debug(message, fields) {
+        this.emit("debug", message, fields);
+    }
+    withCorrelationId(id) {
+        return new ConsoleLogger(this._name, id);
+    }
+}
+// ── Public API ────────────────────────────────────────────────────────────
+/**
+ * Create a named logger instance.
+ *
+ * @param name - Module / subsystem name (included in every log entry)
+ * @returns Logger with info, warn, error, debug, and withCorrelationId
+ */
+function createLogger(name) {
+    return new ConsoleLogger(name);
+}
+/**
+ * Default root logger for backward compatibility.
+ * Prefer `createLogger("module")` for new code.
+ */
+const logger = createLogger("ucu-mcp");
+export { createLogger, logger };

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

@@ -0,0 +1,30 @@
+/**
+ * Retry with exponential backoff for flaky platform calls.
+ *
+ * Only retries when the thrown error is a `UcuError` with `retryable === true`,
+ * unless a custom `shouldRetry` predicate overrides the decision.
+ */
+export interface RetryOptions {
+    /** Maximum number of retries (not including the initial attempt). Default: 3 */
+    maxRetries?: number;
+    /** Base delay in milliseconds for the first retry. Default: 100 */
+    baseDelay?: number;
+    /** Ceiling for the backoff delay in milliseconds. Default: 5000 */
+    maxDelay?: number;
+    /** Custom predicate to decide whether an error is retryable.
+     *  Defaults to `(err) => err instanceof UcuError && err.retryable === true`. */
+    shouldRetry?: (error: unknown) => boolean;
+}
+/**
+ * Execute `fn` and retry with exponential backoff on retryable errors.
+ *
+ * The delay for retry attempt *n* is `baseDelay * 2^(n-1)`, capped at
+ * `maxDelay`. Only errors that are `UcuError` with `retryable === true`
+ * (or that pass the custom `shouldRetry` predicate) trigger a retry.
+ * All other errors propagate immediately.
+ *
+ * @param fn      - The async function to execute.
+ * @param options - Retry configuration.
+ * @returns       The resolved value of `fn`.
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/src/util/retry.js

@@ -0,0 +1,53 @@
+/**
+ * Retry with exponential backoff for flaky platform calls.
+ *
+ * Only retries when the thrown error is a `UcuError` with `retryable === true`,
+ * unless a custom `shouldRetry` predicate overrides the decision.
+ */
+import { UcuError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY = 100;
+const DEFAULT_MAX_DELAY = 5000;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Execute `fn` and retry with exponential backoff on retryable errors.
+ *
+ * The delay for retry attempt *n* is `baseDelay * 2^(n-1)`, capped at
+ * `maxDelay`. Only errors that are `UcuError` with `retryable === true`
+ * (or that pass the custom `shouldRetry` predicate) trigger a retry.
+ * All other errors propagate immediately.
+ *
+ * @param fn      - The async function to execute.
+ * @param options - Retry configuration.
+ * @returns       The resolved value of `fn`.
+ */
+export async function retry(fn, options) {
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const baseDelay = options?.baseDelay ?? DEFAULT_BASE_DELAY;
+    const maxDelay = options?.maxDelay ?? DEFAULT_MAX_DELAY;
+    const shouldRetry = options?.shouldRetry ??
+        ((err) => err instanceof UcuError && err.retryable === true);
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // If we've exhausted all retries or the error is not retryable, throw.
+            if (attempt === maxRetries || !shouldRetry(error)) {
+                throw error;
+            }
+            // Exponential backoff: baseDelay * 2^attempt, capped at maxDelay.
+            const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // Unreachable — the loop either returns or throws.
+    throw lastError;
+}

package/dist/src/utils/input.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-platform input synthesis for UCU-MCP.
+ *
+ * macOS: Uses CGEvent API exclusively for BACKGROUND input injection.
+ * This does NOT activate windows or steal focus — the AI agent can
+ * control the desktop while the user continues working in another
+ * terminal/window without interruption.
+ *
+ * Windows: Uses SendInput (stub).
+ * Linux: Uses xdotool (stub).
+ */
+export declare function click(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string): Promise<void>;
+export declare function doubleClick(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string): Promise<void>;
+export declare function move(x: number, y: number, _platform?: string): Promise<void>;
+export declare function drag(fromX: number, fromY: number, toX: number, toY: number, button?: "left" | "right" | "middle", duration?: number, _platform?: string): Promise<void>;
+export declare function scroll(x: number, y: number, deltaX: number, deltaY: number, _platform?: string): Promise<void>;
+export declare function typeText(text: string, delay?: number, _platform?: string): Promise<void>;
+export declare function pressKey(key: string, modifiers?: string[], _platform?: string): Promise<void>;
+export declare function pressShortcut(keys: string[], _platform?: string): Promise<void>;
+export declare function getCursorPosition(_platform?: string): Promise<{
+    x: number;
+    y: number;
+}>;