ucu-mcp 0.3.9 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.4.0] - 2026-06-11
+
+### Fixed
+
+- **JXA return values fixed (P0)**: Three JXA scripts (`click_element`, `type_in_element`, `set_value`) called `JSON.stringify({success:…})` as a bare statement — the result was computed but discarded, so the osascript output was empty and `JSON.parse(out)` would fail or return undefined. Now each script assigns to `_result` and calls `JSON.stringify(_result)` once at the end.
+- **Rate-limit timestamp ordering (P0)**: `lastActionTime` was updated before the user-activity pause check. If the pause blocked the action, the rate-limit window was consumed anyway, causing subsequent retries to also be rate-limited. Now `lastActionTime` is set only after both checks pass.
+- **Window cache concurrency guard (P0)**: `listWindows` could be called concurrently (e.g. `validateActiveTarget` + `list_windows` tool). Two overlapping calls could write `windowCache` at the same time, producing torn reads. Added `windowCacheInFlight` flag — concurrent callers return stale data instead of racing.
+- **`validateActiveTarget` checks pid (P1)**: Previously only checked windowId, missing the case where an app restarts and the OS reuses the same window ID. Now also checks pid match.
+- **`focusApp` failure clears stale target (P1)**: When `focusApp` threw `WindowNotFoundError`, the old `activeTarget` was retained. Subsequent AX tools would try to use the dead target. Now `activeTarget` is cleared on failure.
+- **`get_screen_size` goes through `withSafety` (P1)**: Was the only tool that bypassed the safety/permission/retry pipeline. Now wrapped in `withSafety` for consistent error handling and rate limiting.
+
+### Tests
+
+- 225 unit tests pass (13 test files).
+- MCP stdio smoke: `doctor`, `list_windows`, `list_apps`, `get_screen_size` all return valid responses.
+- All 3 JXA scripts now produce valid JSON output (verified via stdio pipe test).
+
+
 ## [0.3.8] - 2026-06-08
 
 ### Fixed

package/dist/src/mcp/tools.js

@@ -208,7 +208,13 @@ async function withSafety(sa) {
     }
     if (sa.dryRun)
         return `[DRY-RUN] ${await sa.dryRun()}`;
-    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);
+    // Focus management is disabled by default: CGEvent input injection works
+    // at the HID level without requiring the target app to be frontmost, and
+    // AX operations target processes by name/PID via System Events. The user
+    // should remain in their current app while the agent works in the background.
+    // Re-enable saveFocus/restoreFocus only if a specific AX operation truly
+    // requires the target app to be frontmost (rare).
+    const shouldManageFocus = false;
     if (shouldManageFocus)
         await platform.saveFocus?.();
     const start = Date.now();
@@ -634,7 +640,8 @@ export function registerTools(server) {
     registerTool("get_screen_size", "Get screen dimensions and scale factor", {
         display: z.number().optional().describe("Display index"),
     }, async (params) => {
-        return { content: [{ type: "text", text: JSON.stringify(getPlatform().getScreenSize(params.display), null, 2) }] };
+        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) }] };
     });
     registry.register("get_screen_size");
     registerTool("ocr", "Perform OCR on screen region", {

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

@@ -15,6 +15,7 @@ export declare class MacOSPlatform implements Platform {
     private readonly elementCacheMaxSize;
     private readonly windowCacheTtlMs;
     private windowCache;
+    private windowCacheInFlight;
     private activeTarget;
     private savedFocus;
     constructor(options?: MacOSPlatformOptions);

package/dist/src/platform/macos.js

@@ -69,6 +69,7 @@ export class MacOSPlatform {
     elementCacheMaxSize = 100;
     windowCacheTtlMs = 300;
     windowCache;
+    windowCacheInFlight = false;
     activeTarget;
     savedFocus;
     constructor(options) {
@@ -114,8 +115,12 @@ export class MacOSPlatform {
             return;
         this.windowCache = undefined; // Bypass cache — stale detection must use fresh data
         const windows = await this.listWindows(true);
-        const stillExists = windows.some(w => w.id === this.activeTarget.windowId);
-        if (!stillExists) {
+        const match = windows.find(w => w.id === this.activeTarget.windowId);
+        if (!match) {
+            throw new TargetStaleError(this.activeTarget.windowId);
+        }
+        // Also invalidate if pid changed (app restarted)
+        if (match.pid !== this.activeTarget.pid) {
             throw new TargetStaleError(this.activeTarget.windowId);
         }
     }
@@ -239,13 +244,14 @@ export class MacOSPlatform {
     async focusApp(app) {
         const escapedApp = app.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
         this.windowCache = undefined;
-        try {
-            execFileSync("osascript", ["-e", `tell application "${escapedApp}" to activate`], { timeout: 5000 });
-        }
-        catch {
-            // Some app names are process labels rather than AppleScript application names.
-            // Continue with the AX window lookup below so existing callers still work.
-        }
+        // NOTE: We intentionally do NOT call AppleScript "activate" here.
+        // focus_app sets the internal target context so subsequent operations
+        // know which app/window to target. It does NOT bring the app to the
+        // foreground — the user should remain in their current app (terminal,
+        // Codex, etc.) while the agent works in the background.
+        // CGEvent input injection works at the HID level and doesn't require
+        // the target app to be frontmost. AX operations target processes by
+        // name/PID via System Events, also without needing frontmost status.
         let target;
         const deadline = Date.now() + 3000;
         do {
@@ -262,6 +268,7 @@ export class MacOSPlatform {
             // app name so the tool handler can surface a remediation hint. The
             // bare WindowNotFoundError("CC Switch") was indistinguishable from
             // "the app is not running", which led models to retry forever.
+            this.activeTarget = undefined; // Clear stale target on focus failure
             const err = new WindowNotFoundError(app);
             err.hint =
                 "list_windows returned no match for this app. If the app is running, " +
@@ -343,6 +350,12 @@ export class MacOSPlatform {
                 bounds: { ...window.bounds },
             }));
         }
+        // P0 #3: Prevent concurrent cache refreshes
+        if (this.windowCacheInFlight) {
+            // Another call is already refreshing; return stale or empty
+            return this.windowCache?.windows.map(w => ({ ...w, bounds: { ...w.bounds } })) ?? [];
+        }
+        this.windowCacheInFlight = true;
         try {
             // Try native Swift helper first (CGWindowListCopyWindowInfo, ~1ms).
             // Falls back to JXA System Events if the helper is not available.
@@ -370,6 +383,9 @@ export class MacOSPlatform {
             // Fallback: return empty list if both methods fail
             return [];
         }
+        finally {
+            this.windowCacheInFlight = false;
+        }
     }
     listWindowsNative() {
         try {
@@ -1177,6 +1193,7 @@ export class MacOSPlatform {
         const cachedJson = JSON.stringify(this.elementCache.get(elementId) ?? null);
         const jxaScript = `
       var se = Application('System Events');
+      var _result = null;
       function childElements(elem) {
         try { return elem.uiElements(); } catch(e1) {
           try { return elem.elements(); } catch(e2) { return []; }
@@ -1354,11 +1371,11 @@ export class MacOSPlatform {
       }
 
       if (!elem) {
-        JSON.stringify({success: false, error: "Element not found: " + elemPath});
+        _result = {success: false, error: "Element not found: " + elemPath};
       } else {
         try {
           elem.actions.AXPress.perform();
-          JSON.stringify({success: true});
+          _result = {success: true};
         } catch(e) {
           try {
             var pos = elem.position();
@@ -1372,12 +1389,13 @@ export class MacOSPlatform {
             $.CGEventPost($.kCGHIDEventTap, down);
             var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
             $.CGEventPost($.kCGHIDEventTap, up);
-            JSON.stringify({success: true});
+            _result = {success: true};
           } catch(e2) {
-            JSON.stringify({success: false, error: "Could not click element: " + String(e2.message || e2)});
+            _result = {success: false, error: "Could not click element: " + String(e2.message || e2)};
           }
         }
       }
+      JSON.stringify(_result);
     `;
         try {
             const out = execFileSync("osascript", [
@@ -1408,6 +1426,7 @@ export class MacOSPlatform {
         const cachedJson = JSON.stringify(this.elementCache.get(elementId) ?? null);
         const jxaScript = `
       var se = Application('System Events');
+      var _result = null;
       function childElements(elem) {
         try { return elem.uiElements(); } catch(e1) {
           try { return elem.elements(); } catch(e2) { return []; }
@@ -1587,7 +1606,7 @@ export class MacOSPlatform {
       }
 
       if (!elem) {
-        JSON.stringify({success: false, error: "Element not found: " + elemPath});
+        _result = {success: false, error: "Element not found: " + elemPath};
       } else {
         try {
           elem.focused = true;
@@ -1614,13 +1633,15 @@ export class MacOSPlatform {
         if (!didSet) {
           try {
             se.keystroke(textToType);
+            _result = {success: true};
           } catch(e) {
-            JSON.stringify({success: false, error: "Could not type into element: " + String(e.message || e)});
+            _result = {success: false, error: "Could not type into element: " + String(e.message || e)};
           }
+        } else {
+          _result = {success: true};
         }
-
-        JSON.stringify({success: true});
       }
+      JSON.stringify(_result);
     `;
         try {
             const out = execFileSync("osascript", [
@@ -1669,6 +1690,7 @@ export class MacOSPlatform {
         const cachedJson = JSON.stringify(this.elementCache.get(elementId) ?? null);
         const jxaScript = `
       var se = Application('System Events');
+      var _result = null;
       function childElements(elem) {
         try { return elem.uiElements(); } catch(e1) {
           try { return elem.elements(); } catch(e2) { return []; }
@@ -1842,15 +1864,16 @@ export class MacOSPlatform {
       }
 
       if (!elem) {
-        JSON.stringify({success: false, error: "Element not found: " + elemPath});
+        _result = {success: false, error: "Element not found: " + elemPath};
       } else {
         try {
           elem.value = valueToSet;
-          JSON.stringify({success: true});
+          _result = {success: true};
         } catch(e) {
-          JSON.stringify({success: false, error: "Could not set AX value: " + String(e.message || e)});
+          _result = {success: false, error: "Could not set AX value: " + String(e.message || e)};
         }
       }
+      JSON.stringify(_result);
     `;
         try {
             const out = execFileSync("osascript", [

package/dist/src/safety/guard.js

@@ -233,7 +233,6 @@ export class SafetyGuard {
                 reason: `Rate-limited: ${elapsed}ms since last action (min ${this.rateLimitMs}ms)`,
             };
         }
-        this.lastActionTime = now;
         // 6. User activity pause (skipped for observe-class actions) -----------------
         if (!options.skipUserActivityPause && this.isUserActivityPauseActive()) {
             return {
@@ -241,6 +240,7 @@ export class SafetyGuard {
                 reason: `User activity detected — pausing automation for ${this.userActivityPauseMs}ms`,
             };
         }
+        this.lastActionTime = now;
         return { allowed: true };
     }
     // -----------------------------------------------------------------------

package/package.json

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