ucu-mcp 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-06-06
+
+### Bug fixes
+
+- `find_element` with `textMode="regex"` now pre-validates the `value` field for invalid regex patterns and throws `PlatformError`, mirroring the existing `text`-field validation. Before, an invalid value regex was silently swallowed by the JXA-internal `try/catch` and surfaced as "no results" instead of a clear error. (Singer Minor)
+- `find_element` `near` sort now explicitly pushes elements without `bounds` to the end of the sorted result, instead of implicitly treating them as centered at (0,0). Improves semantics for elements without on-screen geometry. (Singer Nit)
+
+### Changed
+
+- `find_element.value` schema is now `z.string().min(1).optional()`. Empty strings are now rejected at the schema layer with a clear validation error rather than being silently coerced to "no filter". (Singer Minor)
+
+### Tests
+
+- `macos-platform`: the `index out of range` test now also pins `metrics.matchedCount` to the JXA return value, locking the semantic that out-of-range indexing does not change the underlying match count. (Singer Minor)
+
+### Tool description
+
+- `find_element` tool description expanded to mention `value` / `index` / `near` selector support, so the model sees the new selectors at the tool level rather than only on individual parameters. (Singer Minor)
+- `UcuError.defaultCode` lookup now has a JSDoc cross-reference explaining the relationship between the static class default and the per-instance `code` field. (Singer Minor)
+
+### Hygiene
+
+- Tracked 7 files removed from git tracking: `.codex/{config.toml,postmortem-interrupt-loop.md}`, `.claude/{settings.json,settings.local.json,.cozempic-init.lock}`, `docs/{.DS_Store,superpowers/.DS_Store}`. These were local-environment residue that predated the `.gitignore` rules; the ignore rules were already in place, just not enforced on the existing tracked entries. `claude-desktop-config.json` (the root-level sample for Claude Desktop MCP setup) was kept.
+
+## [0.3.1] - 2026-06-06
+
+### Bug fixes
+
+- `wait_for_element` `until="value_change"` mode no longer spins until timeout when the matched element's initial `value` is `undefined` (e.g. progress indicators / status text without an AX value). A separate `hasInitial` flag now tracks "first sample captured" so a captured `undefined` is preserved as the baseline. On timeout, `value_change` mode now reports `"never_appeared"` (no match ever found) vs `"value_unchanged"` (match found but value did not change) so the model can branch on the result. (Singer review Major fix)
+
+### Note
+
+Post-0.3.0 release changes already merged on `main` and folded into 0.3.1:
+
+- Scenario-based MCP `instructions` covering forms, menu bar, screen read, app switch, verify action, wait for UI, recover from `TARGET_STALE`, clipboard read/write. (47dbcff)
+- `find_element` multi-strategy: new `value` (textMode-aware), `index` (Nth match), `near` (distance-sorted) selectors. (47dbcff)
+- `wait_for_element` `until` parameter: new modes `appear` (default), `disappear`, `value_change`. (47dbcff)
+- `UcuError` class static `code` renamed to `defaultCode` to avoid clashing with the instance `code` field. (eec7afd)
+
 ## [0.3.0] - 2026-06-06
 
 

package/dist/src/mcp/tools.js

@@ -10,6 +10,7 @@ import { SafetyGuard, classifyAction } from "../safety/guard.js";
 import { checkPermission } from "../safety/permissions.js";
 import { retry } from "../util/retry.js";
 import { createLogger } from "../util/logger.js";
+import { metrics } from "../util/metrics.js";
 import { SafetyError, PermissionError, UnsupportedParameterError, UcuError, WindowNotFoundError } from "../util/errors.js";
 const log = createLogger("tools");
 let _platform;
@@ -184,12 +185,14 @@ async function withSafety(sa) {
     const shouldManageFocus = sa.requiresAccessibility && !["screenshot", "list_windows", "list_apps", "get_window_state", "get_cursor_position", "get_screen_size", "ocr", "doctor", "wait", "wait_for_element", "find_element", "focus_app"].includes(sa.action);
     if (shouldManageFocus)
         await platform.saveFocus?.();
+    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);
         if (shouldManageFocus)
             await platform.restoreFocus?.();
     }
@@ -450,6 +453,10 @@ export function registerTools(server) {
                 typedTextInjectionScan: true,
             },
             stdioCommand: "ucu-mcp",
+            metrics: {
+                global: metrics.stats(),
+                byTool: metrics.byTool(),
+            },
         };
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
     });
@@ -477,6 +484,7 @@ export function registerTools(server) {
         if (!granted)
             throw new PermissionError("accessibility", process.platform);
         let initialValue;
+        let hasInitial = false;
         while (Date.now() < deadline) {
             const response = await getPlatform().findElement(query);
             const matched = response.results[0];
@@ -489,10 +497,15 @@ export function registerTools(server) {
                     return { content: [{ type: "text", text: JSON.stringify({ found: true, reason: "disappeared" }, null, 2) }] };
             }
             else {
-                // value_change: capture the initial value of the first match, then wait for it to differ
+                // value_change: capture the initial value of the first match, then wait for it to differ.
+                // A separate `hasInitial` flag is required because the first match's `value` may itself be
+                // undefined; using `initialValue === undefined` to mean "not yet captured" would loop
+                // forever in that case. On timeout, distinguish "element never appeared" from "value stayed
+                // the same" so the model can branch on the result.
                 if (matched) {
-                    if (initialValue === undefined) {
+                    if (!hasInitial) {
                         initialValue = matched.value;
+                        hasInitial = true;
                     }
                     else if (matched.value !== initialValue) {
                         return { content: [{ type: "text", text: JSON.stringify({ found: true, oldValue: initialValue, newValue: matched.value }, null, 2) }] };
@@ -501,7 +514,8 @@ export function registerTools(server) {
             }
             await new Promise(r => setTimeout(r, interval));
         }
-        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason: "timeout" }, null, 2) }] };
+        const reason = until === "value_change" ? (hasInitial ? "value_unchanged" : "never_appeared") : "timeout";
+        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason }, null, 2) }] };
     });
     registry.register("wait_for_element");
     registerTool("get_cursor_position", "Get current cursor position", {}, async () => {
@@ -533,12 +547,12 @@ export function registerTools(server) {
         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);
     });
     registry.register("move");
-    registerTool("find_element", "Find accessibility elements by text, role, or app", {
+    registerTool("find_element", "Find accessibility elements by text, role, or value. Supports value/index/near selectors.", {
         text: z.string().optional().describe("Text to search"), role: z.string().optional().describe("AX role"), app: z.string().optional().describe("Target app"),
         depth: z.number().optional().describe("AX tree depth"), includeBounds: z.boolean().default(true).describe("Include bounds"), maxResults: z.number().min(1).max(200).default(50).describe("Max results"),
         textMode: z.enum(["contains", "exact", "regex"]).default("contains").describe("Text matching mode: contains (default), exact, or regex"),
         visibleOnly: z.boolean().default(false).describe("Only return elements with valid on-screen bounds"),
-        value: z.string().optional().describe("Filter by AX element value (respects textMode)"),
+        value: z.string().min(1).optional().describe("Filter by AX element value (text/regex/exact, see textMode). Empty string is treated as unset (omit the field instead)."),
         index: z.number().int().nonnegative().optional().describe("Return only the Nth match (0-based) after all other filtering and sorting"),
         near: z.object({ x: z.number(), y: z.number() }).optional().describe("Sort results by ascending distance to this point and return closest first"),
     }, async (params) => {

package/dist/src/platform/macos.js

@@ -820,6 +820,17 @@ export class MacOSPlatform {
                 throw new PlatformError(`Invalid regex pattern: ${text}`);
             }
         }
+        // Same pre-validation for value field when regex textMode is requested;
+        // otherwise JXA's valueMatches silently returns false on invalid regex,
+        // which surfaces as "no results" instead of a clear error.
+        if (value && textMode === "regex") {
+            try {
+                new RegExp(value);
+            }
+            catch {
+                throw new PlatformError(`Invalid regex pattern: ${value}`);
+            }
+        }
         const startTime = Date.now();
         const jxaScript = `
         var se = Application('System Events');
@@ -1024,6 +1035,17 @@ export class MacOSPlatform {
                 const nx = options.near.x;
                 const ny = options.near.y;
                 finalResults = [...finalResults].sort((a, b) => {
+                    // Elements without bounds cannot be meaningfully compared against
+                    // a near point. Push them to the end of the sorted result so they
+                    // don't pollute the "closest first" ordering. (Singer Nit)
+                    const aHasBounds = !!a.bounds;
+                    const bHasBounds = !!b.bounds;
+                    if (!aHasBounds && !bHasBounds)
+                        return 0;
+                    if (!aHasBounds)
+                        return 1;
+                    if (!bHasBounds)
+                        return -1;
                     const acx = (a.bounds?.x ?? 0) + (a.bounds?.width ?? 0) / 2;
                     const acy = (a.bounds?.y ?? 0) + (a.bounds?.height ?? 0) / 2;
                     const bcx = (b.bounds?.x ?? 0) + (b.bounds?.width ?? 0) / 2;

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

@@ -2,54 +2,70 @@
  * Error taxonomy for UCU-MCP.
  *
  * All errors inherit from UcuError and are categorized by:
- *   - code: machine-readable error code
+ *   - code: machine-readable error code (also exposed via toJSON)
  *   - retryable: whether the operation can be retried
  */
 export declare class UcuError extends Error {
+    /** Default error code for this class. Subclasses override. */
+    static readonly defaultCode: string;
     readonly code: string;
     readonly retryable: boolean;
     constructor(message: string, code?: string, retryable?: boolean);
+    /** Serialize for MCP response / JSON.stringify. */
+    toJSON(): {
+        name: string;
+        code: string;
+        retryable: boolean;
+        message: string;
+    };
 }
 /**
  * Native API call failed (permissions, OS error, timeout).
  */
 export declare class PlatformError extends UcuError {
+    static readonly defaultCode = "PLATFORM_ERROR";
     constructor(message: string, retryable?: boolean);
 }
 /**
  * Action blocked by safety guard.
  */
 export declare class SafetyError extends UcuError {
+    static readonly defaultCode = "SAFETY_BLOCKED";
     constructor(message: string);
 }
 /**
  * Missing OS accessibility/screen-recording permissions.
  */
 export declare class PermissionError extends UcuError {
+    static readonly defaultCode = "PERMISSION_DENIED";
     constructor(permission: string, platform: string);
 }
 /**
  * Requested window ID no longer exists.
  */
 export declare class WindowNotFoundError extends UcuError {
+    static readonly defaultCode = "WINDOW_NOT_FOUND";
     constructor(windowId: string);
 }
 /**
  * Active target window is no longer available.
  */
 export declare class TargetStaleError extends UcuError {
+    static readonly defaultCode = "TARGET_STALE";
     constructor(windowId: string);
 }
 /**
  * Requested accessibility element ID no longer resolves.
  */
 export declare class ElementNotFoundError extends UcuError {
+    static readonly defaultCode = "ELEMENT_NOT_FOUND";
     constructor(elementId: string);
 }
 /**
  * Click/scroll target is outside screen bounds.
  */
 export declare class CoordinateError extends UcuError {
+    static readonly defaultCode = "COORDINATE_OUT_OF_BOUNDS";
     constructor(x: number, y: number, bounds: {
         width: number;
         height: number;
@@ -59,6 +75,7 @@ export declare class CoordinateError extends UcuError {
  * Keystroke or mouse event injection failed.
  */
 export declare class InputSynthesisError extends UcuError {
+    static readonly defaultCode = "INPUT_FAILED";
     constructor(message: string);
 }
 /**
@@ -66,11 +83,13 @@ export declare class InputSynthesisError extends UcuError {
  * implementation does not support.
  */
 export declare class UnsupportedParameterError extends UcuError {
+    static readonly defaultCode = "UNSUPPORTED_PARAMETER";
     constructor(message: string);
 }
 /**
  * Screenshot or window-state capture failed.
  */
 export declare class CaptureError extends UcuError {
+    static readonly defaultCode = "CAPTURE_FAILED";
     constructor(message: string);
 }

package/dist/src/util/errors.js

@@ -2,21 +2,37 @@
  * Error taxonomy for UCU-MCP.
  *
  * All errors inherit from UcuError and are categorized by:
- *   - code: machine-readable error code
+ *   - code: machine-readable error code (also exposed via toJSON)
  *   - retryable: whether the operation can be retried
  */
 // ---------------------------------------------------------------------------
 // Base Error Class
 // ---------------------------------------------------------------------------
 export class UcuError extends Error {
+    /** Default error code for this class. Subclasses override. */
+    static defaultCode = "UCU_ERROR";
     code;
     retryable;
-    constructor(message, code = "UCU_ERROR", retryable = false) {
+    constructor(message, code, retryable = false) {
         super(message);
+        if (code === undefined) {
+            // The default code applied to instances of this class when no explicit code is passed to the constructor.
+            // See the static `defaultCode` declaration above for the per-class override mechanism.
+            code = this.constructor.defaultCode;
+        }
         this.name = this.constructor.name;
         this.code = code;
         this.retryable = retryable;
     }
+    /** Serialize for MCP response / JSON.stringify. */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            retryable: this.retryable,
+            message: this.message,
+        };
+    }
 }
 // ---------------------------------------------------------------------------
 // Platform Errors
@@ -25,8 +41,9 @@ export class UcuError extends Error {
  * Native API call failed (permissions, OS error, timeout).
  */
 export class PlatformError extends UcuError {
+    static defaultCode = "PLATFORM_ERROR";
     constructor(message, retryable = true) {
-        super(message, "PLATFORM_ERROR", retryable);
+        super(message, PlatformError.defaultCode, retryable);
     }
 }
 // ---------------------------------------------------------------------------
@@ -36,8 +53,9 @@ export class PlatformError extends UcuError {
  * Action blocked by safety guard.
  */
 export class SafetyError extends UcuError {
+    static defaultCode = "SAFETY_BLOCKED";
     constructor(message) {
-        super(message, "SAFETY_BLOCKED", false);
+        super(message, SafetyError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -47,8 +65,9 @@ export class SafetyError extends UcuError {
  * Missing OS accessibility/screen-recording permissions.
  */
 export class PermissionError extends UcuError {
+    static defaultCode = "PERMISSION_DENIED";
     constructor(permission, platform) {
-        super(getPermissionMessage(permission, platform), "PERMISSION_DENIED", false);
+        super(getPermissionMessage(permission, platform), PermissionError.defaultCode, false);
     }
 }
 function getPermissionMessage(permission, platform) {
@@ -64,24 +83,27 @@ function getPermissionMessage(permission, platform) {
  * Requested window ID no longer exists.
  */
 export class WindowNotFoundError extends UcuError {
+    static defaultCode = "WINDOW_NOT_FOUND";
     constructor(windowId) {
-        super(`Window ${windowId} not found. It may have been closed. Run list_windows to get fresh IDs.`, "WINDOW_NOT_FOUND", false);
+        super(`Window ${windowId} not found. It may have been closed. Run list_windows to get fresh IDs.`, WindowNotFoundError.defaultCode, false);
     }
 }
 /**
  * Active target window is no longer available.
  */
 export class TargetStaleError extends UcuError {
+    static defaultCode = "TARGET_STALE";
     constructor(windowId) {
-        super(`Active target window ${windowId} is no longer available. Run focus_app or list_windows to refresh.`, "TARGET_STALE", false);
+        super(`Active target window ${windowId} is no longer available. Run focus_app or list_windows to refresh.`, TargetStaleError.defaultCode, false);
     }
 }
 /**
  * Requested accessibility element ID no longer resolves.
  */
 export class ElementNotFoundError extends UcuError {
+    static defaultCode = "ELEMENT_NOT_FOUND";
     constructor(elementId) {
-        super(`Element ${elementId} not found. It may have been removed or invalidated. Run find_element to get a fresh ID.`, "ELEMENT_NOT_FOUND", false);
+        super(`Element ${elementId} not found. It may have been removed or invalidated. Run find_element to get a fresh ID.`, ElementNotFoundError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -91,16 +113,18 @@ export class ElementNotFoundError extends UcuError {
  * Click/scroll target is outside screen bounds.
  */
 export class CoordinateError extends UcuError {
+    static defaultCode = "COORDINATE_OUT_OF_BOUNDS";
     constructor(x, y, bounds) {
-        super(`Coordinate (${x}, ${y}) is outside screen bounds (0-${bounds.width}, 0-${bounds.height}).`, "COORDINATE_OUT_OF_BOUNDS", false);
+        super(`Coordinate (${x}, ${y}) is outside screen bounds (0-${bounds.width}, 0-${bounds.height}).`, CoordinateError.defaultCode, false);
     }
 }
 /**
  * Keystroke or mouse event injection failed.
  */
 export class InputSynthesisError extends UcuError {
+    static defaultCode = "INPUT_FAILED";
     constructor(message) {
-        super(message, "INPUT_FAILED", true);
+        super(message, InputSynthesisError.defaultCode, true);
     }
 }
 /**
@@ -108,8 +132,9 @@ export class InputSynthesisError extends UcuError {
  * implementation does not support.
  */
 export class UnsupportedParameterError extends UcuError {
+    static defaultCode = "UNSUPPORTED_PARAMETER";
     constructor(message) {
-        super(message, "UNSUPPORTED_PARAMETER", false);
+        super(message, UnsupportedParameterError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -119,7 +144,8 @@ export class UnsupportedParameterError extends UcuError {
  * Screenshot or window-state capture failed.
  */
 export class CaptureError extends UcuError {
+    static defaultCode = "CAPTURE_FAILED";
     constructor(message) {
-        super(message, "CAPTURE_FAILED", true);
+        super(message, CaptureError.defaultCode, true);
     }
 }

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

@@ -0,0 +1,37 @@
+/**
+ * Tool-call latency ring buffer for performance observability.
+ *
+ * Keeps the last 1000 durationMs samples per tool name and exposes
+ * p50/p95/max/mean stats through the `doctor` tool.
+ *
+ * Singleton instance: import `metrics` and call `record()` on every
+ * completed tool call. Tests that need isolation can construct their own
+ * Metrics instance.
+ */
+export interface MetricStats {
+    count: number;
+    p50: number;
+    p95: number;
+    max: number;
+    mean: number;
+}
+export declare class Metrics {
+    private buffers;
+    private order;
+    private writeIndex;
+    private totalWrites;
+    /** Record a durationMs sample for the named tool. */
+    record(toolName: string, durationMs: number): void;
+    /** Get stats for one tool, or aggregate across all tools. */
+    stats(toolName?: string): MetricStats;
+    /** Stats for every tracked tool. */
+    byTool(): Record<string, MetricStats>;
+    /** Clear all recorded samples. Mostly for tests. */
+    reset(): void;
+    private liveSamples;
+    private computeStats;
+    /** Nearest-rank percentile on a pre-sorted ascending array. */
+    private percentile;
+}
+/** Singleton shared across the process. */
+export declare const metrics: Metrics;

package/dist/src/util/metrics.js

@@ -0,0 +1,97 @@
+/**
+ * Tool-call latency ring buffer for performance observability.
+ *
+ * Keeps the last 1000 durationMs samples per tool name and exposes
+ * p50/p95/max/mean stats through the `doctor` tool.
+ *
+ * Singleton instance: import `metrics` and call `record()` on every
+ * completed tool call. Tests that need isolation can construct their own
+ * Metrics instance.
+ */
+const RING_SIZE = 1000;
+export class Metrics {
+    buffers = new Map();
+    order = [];
+    writeIndex = new Map();
+    totalWrites = new Map();
+    /** Record a durationMs sample for the named tool. */
+    record(toolName, durationMs) {
+        let buf = this.buffers.get(toolName);
+        if (!buf) {
+            buf = new Array(RING_SIZE).fill(0);
+            this.buffers.set(toolName, buf);
+            this.order.push(toolName);
+            this.writeIndex.set(toolName, 0);
+            this.totalWrites.set(toolName, 0);
+        }
+        const idx = this.writeIndex.get(toolName);
+        buf[idx] = durationMs;
+        this.writeIndex.set(toolName, (idx + 1) % RING_SIZE);
+        this.totalWrites.set(toolName, (this.totalWrites.get(toolName) ?? 0) + 1);
+    }
+    /** Get stats for one tool, or aggregate across all tools. */
+    stats(toolName) {
+        if (toolName !== undefined) {
+            return this.computeStats(this.liveSamples(toolName));
+        }
+        const all = [];
+        for (const name of this.order) {
+            all.push(...this.liveSamples(name));
+        }
+        return this.computeStats(all);
+    }
+    /** Stats for every tracked tool. */
+    byTool() {
+        const out = {};
+        for (const name of this.order) {
+            const samples = this.liveSamples(name);
+            if (samples.length > 0) {
+                out[name] = this.computeStats(samples);
+            }
+        }
+        return out;
+    }
+    /** Clear all recorded samples. Mostly for tests. */
+    reset() {
+        this.buffers.clear();
+        this.order.length = 0;
+        this.writeIndex.clear();
+        this.totalWrites.clear();
+    }
+    liveSamples(toolName) {
+        const buf = this.buffers.get(toolName);
+        if (!buf)
+            return [];
+        const total = this.totalWrites.get(toolName) ?? 0;
+        if (total < RING_SIZE) {
+            return buf.slice(0, total);
+        }
+        // Ring is full — all RING_SIZE slots contain the most recent samples.
+        return buf.slice();
+    }
+    computeStats(samples) {
+        if (samples.length === 0) {
+            return { count: 0, p50: 0, p95: 0, max: 0, mean: 0 };
+        }
+        const sorted = [...samples].sort((a, b) => a - b);
+        const sum = sorted.reduce((acc, v) => acc + v, 0);
+        const round = (n) => Math.round(n * 10) / 10;
+        return {
+            count: sorted.length,
+            p50: round(this.percentile(sorted, 0.5)),
+            p95: round(this.percentile(sorted, 0.95)),
+            max: round(sorted[sorted.length - 1]),
+            mean: round(sum / sorted.length),
+        };
+    }
+    /** Nearest-rank percentile on a pre-sorted ascending array. */
+    percentile(sorted, p) {
+        if (sorted.length === 1)
+            return sorted[0];
+        const rank = Math.ceil(p * sorted.length);
+        const idx = Math.max(0, Math.min(rank - 1, sorted.length - 1));
+        return sorted[idx];
+    }
+}
+/** Singleton shared across the process. */
+export const metrics = new Metrics();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {