ucu-mcp 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.8] - 2026-06-08
+
+### Fixed
+
+- `focus_app` no longer trips the user-activity pause. It used to be classified as `"other"` (neither observe nor input) so a recent mouse movement could block `focus_app` for 2 s; it is now in `OBSERVE_ACTIONS`, matching the production `withSafety` default. Symptom: OpenCode could not switch the active target app (e.g. CC Switch) without retrying until the cursor had been still for 2 s.
+- `doctor` native-helper path resolution now checks `process.argv[1]` (npm / npx / global install), walks `import.meta.url` up to 4 levels, and falls back to `npm root -g`. Previously, when the MCP client launched `ucu-mcp` from a cwd other than the project root (the common case for `npx ucu-mcp`), the helper binaries would report as missing even though they were in the tarball. The new report includes `path` and a `tried[]` list so the model can see what was checked.
+- `doctor` recommendations now list each missing macOS permission on its own line, name the host terminal app (so the user knows which entry to grant in System Settings), and add an Electron AX hint for the common case where `list_windows` returns `[]` even with Accessibility granted.
+
+### Tests
+
+- `safety-guard`: `focus_app` is in `OBSERVE_ACTIONS`; `classifyAction("focus_app") === "observe"`; `withSafety`'s default `skipUserActivityPause` lets the call through even mid user-activity.
+- `errors`: `WindowNotFoundError` preserves an inline `hint` field set by the platform layer, surfaced in the MCP error response.
+- `macos-platform`: OCR JXA `"Failed to load screenshot image"` is re-thrown as `CaptureError` with a hint pointing at the missing Screen Recording permission (the typical cause is `screencapture` writing a 0-byte file when TCC denies Screen Recording, not the helper binary being absent).
+- `tools-layer`: `doctor` report carries `terminalApp` and the richer `nativeHelpers = { cgevent, ocr } = { ok, path, tried[] }` shape.
+
 ## [0.3.7] - 2026-06-07
 
 ### Fixed

package/dist/src/mcp/tools.js

@@ -94,13 +94,21 @@ function errorDetails(error) {
     const err = error instanceof Error ? error : new Error(String(error));
     const code = error instanceof UcuError ? error.code : "UNKNOWN_ERROR";
     const retryable = error instanceof UcuError ? error.retryable : false;
-    return {
+    // Some platform errors carry an inline `hint` field (added by macos.ts focusApp
+    // for the Electron AX case, etc.). Surface it under `hint` so the model can
+    // see remediation without parsing the message string.
+    const inlineHint = err.hint;
+    const details = {
         name: err.name,
         code,
         retryable,
         message: err.message,
         recovery: recoveryHint(code),
     };
+    if (typeof inlineHint === "string" && inlineHint.length > 0) {
+        details.hint = inlineHint;
+    }
+    return details;
 }
 let _actionCounter = 0;
 function nextActionId() {
@@ -281,7 +289,28 @@ export function registerTools(server) {
         includeMinimized: z.boolean().optional().describe("Include minimized windows"),
     }, async (params) => {
         const windows = await withSafety({ action: "list_windows", params: {}, requiresAccessibility: true, execute: () => getPlatform().listWindows(params.includeMinimized) });
-        return { content: [{ type: "text", text: JSON.stringify(windows, null, 2) }] };
+        // Attach a diagnostic hint when the result is empty so the model can
+        // tell the difference between "no windows are open" and "AX enumeration
+        // failed for the target app" (common with Electron apps like CC Switch,
+        // VS Code, Discord). The windows list itself is the source of truth; the
+        // hint is advisory only.
+        let diagnostics;
+        if (windows.length === 0) {
+            let accessibility = "unknown";
+            try {
+                const { checkPermission } = await import("../safety/permissions.js");
+                const { granted } = await checkPermission("accessibility");
+                accessibility = granted ? "granted" : "denied";
+            }
+            catch { /* keep unknown */ }
+            const axNote = accessibility === "denied"
+                ? "Accessibility is currently denied to this terminal — grant it via System Settings > Privacy & Security > Accessibility, then retry."
+                : accessibility === "granted"
+                    ? "Accessibility is granted. If you expected a specific app to appear here, it is likely an Electron app whose AX tree is not exposed to System Events; try modifying its config file or database directly rather than driving the UI."
+                    : "Accessibility status is unknown. Run `doctor` first to verify.";
+            diagnostics = { hint: `list_windows returned 0 windows. ${axNote}`, accessibility };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(diagnostics ? { windows, diagnostics } : windows, null, 2) }] };
     });
     registry.register("list_windows");
     registerTool("list_apps", "List all running applications", {}, async () => {
@@ -384,55 +413,98 @@ export function registerTools(server) {
     });
     registry.register("drag");
     registerTool("doctor", "Check system permissions, native helpers, and client readiness", {}, async () => {
-        const { checkPermissions } = await import("../safety/permissions.js");
+        const { checkPermissions, getPermissionInstructions, getTerminalAppName } = await import("../safety/permissions.js");
         const { MacOSPlatform: MacPlat } = await import("../platform/macos.js");
-        const { existsSync } = await import("node:fs");
-        const { join, dirname } = await import("node:path");
+        const { existsSync, statSync } = await import("node:fs");
+        const { join, dirname, resolve } = await import("node:path");
         const { fileURLToPath } = await import("node:url");
         const { execFileSync } = await import("node:child_process");
         const permissions = await checkPermissions();
         const screenLocked = process.platform === "darwin" ? new MacPlat().isScreenLocked?.() ?? false : false;
-        let nativeHelpers;
-        if (process.platform === "darwin") {
+        const termApp = process.platform === "darwin" ? getTerminalAppName() : undefined;
+        // Resolve native helper binaries across every install layout we have seen:
+        //  - dev: process.cwd() === project root
+        //  - npm install --prefix X: argv[1] is in X/node_modules/ucu-mcp/...
+        //  - global install via npm: argv[1] is in $(npm root -g)/ucu-mcp/...
+        //  - npx: argv[1] is in ~/.npm/_npx/.../node_modules/ucu-mcp/...
+        //  - bin/ucu-mcp.js is the entry; dist/src/*/tools.js is the module path
+        function resolveHelperPath(relParts) {
+            const tried = [];
+            const tryPaths = [];
             const moduleDir = dirname(fileURLToPath(import.meta.url));
-            const checkPaths = (subdirs) => {
-                const paths = [
-                    join(process.cwd(), ...subdirs),
-                    join(moduleDir, "..", ...subdirs),
-                    join(moduleDir, "..", "..", ...subdirs),
-                ];
-                return paths.some(p => { try {
-                    return existsSync(p);
+            const argv1 = process.argv[1] ? resolve(process.argv[1]) : "";
+            const argv1Dir = argv1 ? dirname(argv1) : "";
+            // (1) process.cwd() — dev invocation
+            tryPaths.push(join(process.cwd(), ...relParts));
+            // (2) argv[1] dir — npm / npx / global
+            if (argv1Dir) {
+                tryPaths.push(join(argv1Dir, ...relParts));
+                tryPaths.push(join(argv1Dir, "..", ...relParts));
+                tryPaths.push(join(argv1Dir, "..", "..", ...relParts));
+            }
+            // (3) module dir — dist/bin or dist/src/mcp; walk up to 4 levels
+            tryPaths.push(join(moduleDir, "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", "..", ...relParts));
+            tryPaths.push(join(moduleDir, "..", "..", "..", "..", ...relParts));
+            // (4) npm root -g for global install (best effort)
+            if (process.platform === "darwin") {
+                try {
+                    const npmRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8", timeout: 2000 }).trim();
+                    if (npmRoot) {
+                        tryPaths.push(join(npmRoot, "ucu-mcp", ...relParts));
+                    }
                 }
-                catch {
-                    return false;
-                } });
-            };
+                catch { /* npm not on PATH is fine */ }
+            }
+            for (const p of tryPaths) {
+                tried.push(p);
+                try {
+                    if (existsSync(p) && statSync(p).isFile())
+                        return { path: p, tried };
+                }
+                catch { /* skip */ }
+            }
+            return { path: null, tried };
+        }
+        let nativeHelpers;
+        if (process.platform === "darwin") {
+            const cgevent = resolveHelperPath(["native", "cgevent", "cgevent-helper"]);
+            const ocr = resolveHelperPath(["native", "ocr", "ocr-helper"]);
             nativeHelpers = {
-                cgevent: checkPaths(["native", "cgevent", "cgevent-helper"]),
-                ocr: checkPaths(["native", "ocr", "ocr-helper"]),
+                cgevent: { ok: cgevent.path !== null, path: cgevent.path, tried: cgevent.tried.slice(0, 3) },
+                ocr: { ok: ocr.path !== null, path: ocr.path, tried: ocr.tried.slice(0, 3) },
             };
         }
         let readiness = "ready";
         const issues = [];
         if (!permissions.granted) {
             readiness = "blocked";
-            issues.push("Missing macOS permissions: " + permissions.missing.join(", "));
+            for (const m of (permissions.missing ?? [])) {
+                issues.push(`Missing macOS permission: ${m}`);
+            }
         }
         if (screenLocked) {
             readiness = "blocked";
             issues.push("Screen is locked");
         }
         if (process.platform === "darwin" && nativeHelpers) {
-            if (!nativeHelpers.cgevent) {
+            if (!nativeHelpers.cgevent.ok) {
                 readiness = readiness === "ready" ? "degraded" : readiness;
-                issues.push("Native CGEvent helper not found (input synthesis may crash on macOS Sequoia+)");
+                issues.push("Native CGEvent helper not found (input synthesis may crash on macOS Sequoia+). Run `npm run build` to compile it, or reinstall ucu-mcp so the helper ships from the tarball.");
             }
-            if (!nativeHelpers.ocr) {
+            if (!nativeHelpers.ocr.ok) {
                 readiness = readiness === "ready" ? "degraded" : readiness;
-                issues.push("Native OCR helper not found (OCR may fail on macOS Sequoia+)");
+                issues.push("Native OCR helper not found (OCR may fail on macOS Sequoia+). Run `npm run build` to compile it, or reinstall ucu-mcp so the helper ships from the tarball.");
             }
         }
+        // Heuristic AX hint: if Accessibility is granted but list_windows consistently
+        // returns empty for the only app the model cared about, the model has likely
+        // hit the Electron AX limitation (Electron windows do not expose AX to System
+        // Events unless Accessibility is also granted to the Electron process itself,
+        // and the app has accessibility features enabled). This block is read-only —
+        // we never hit JXA here because the doctor must stay fast and side-effect free.
+        const electronHint = "If the target app is Electron (e.g. CC Switch, VS Code, Discord), list_windows may return [] even with Accessibility granted to your terminal. Grant Accessibility to the Electron app itself in System Settings > Privacy & Security > Accessibility, and restart the app. As a workaround, modify the app\'s config file or database directly rather than driving the UI.";
         const clients = {};
         for (const bin of ["claude", "codex", "opencode", "npx"]) {
             try {
@@ -445,16 +517,24 @@ export function registerTools(server) {
         }
         const recommendations = [];
         if (readiness === "blocked") {
-            recommendations.push("Grant missing permissions in System Settings > Privacy & Security, then restart the MCP client.");
+            for (const m of (permissions.missing ?? [])) {
+                const app = termApp ?? "your terminal app";
+                recommendations.push(`${m}: ${getPermissionInstructions(m)} (Grant to ${app}.)`);
+            }
+            if (screenLocked)
+                recommendations.push("Unlock the screen, then retry.");
         }
-        else if (readiness === "degraded") {
-            if (nativeHelpers && (!nativeHelpers.cgevent || !nativeHelpers.ocr)) {
-                recommendations.push("Run 'npm run build' to compile native Swift helpers.");
+        if (readiness !== "ready") {
+            if (process.platform === "darwin" && nativeHelpers && (!nativeHelpers.cgevent.ok || !nativeHelpers.ocr.ok)) {
+                recommendations.push("Run `npm run build` in the ucu-mcp project to compile native Swift helpers (cgevent-helper, ocr-helper).");
             }
         }
-        else {
+        if (readiness === "ready") {
             recommendations.push("All checks passed. MCP client can proceed with automation.");
         }
+        else if (process.platform === "darwin") {
+            recommendations.push(electronHint);
+        }
         const report = {
             readiness,
             issues: issues.length > 0 ? issues : undefined,
@@ -463,6 +543,7 @@ export function registerTools(server) {
             node: process.version,
             permissions,
             screenLocked,
+            terminalApp: termApp,
             nativeHelpers,
             clients,
             safety: {

package/dist/src/platform/macos.js

@@ -248,7 +248,21 @@ export class MacOSPlatform {
             await new Promise((resolve) => setTimeout(resolve, 150));
         } while (Date.now() < deadline);
         if (!target) {
-            throw new WindowNotFoundError(app);
+            // Wrap with a more diagnostic message: many real-world failures are
+            // Electron apps that do not expose their AX tree to System Events
+            // (CC Switch, VS Code, Discord, Slack). WindowNotFoundError carries the
+            // 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.
+            const err = new WindowNotFoundError(app);
+            err.hint =
+                "list_windows returned no match for this app. If the app is running, " +
+                    "the most likely cause is that it is an Electron app whose AX tree is " +
+                    "not exposed to System Events (System Settings > Privacy & Security > " +
+                    "Accessibility must be granted to the Electron process itself, not just " +
+                    "to the host terminal). As a workaround, modify the app's config file " +
+                    "or database directly.";
+            throw err;
         }
         this.activeTarget = {
             targetId: randomUUID(),
@@ -779,8 +793,18 @@ export class MacOSPlatform {
     `;
         const out = execFileSync("osascript", ["-l", "JavaScript", "-e", jxaScript], { encoding: "utf-8", timeout: 30000 }).trim();
         const parsed = JSON.parse(out);
-        if (parsed.error)
-            throw new CaptureError(`ocr failed: ${parsed.error}`);
+        if (parsed.error) {
+            // Distinguish permission-class failures from real Vision errors.
+            // screencapture writes a 0-byte file when Screen Recording is not granted,
+            // and the JXA NSImage init then fails with "Failed to load screenshot image".
+            // Surface that as a PermissionError hint so the model can suggest the right fix.
+            const hint = parsed.error === "Failed to load screenshot image"
+                ? " (the screenshot file is empty or unreadable — Screen Recording permission is most likely missing; run `doctor` and grant Screen Recording to the host terminal, then retry)"
+                : parsed.error === "Failed to get CGImage from screenshot"
+                    ? " (the screenshot could not be decoded — likely an empty capture; check Screen Recording permission)"
+                    : "";
+            throw new CaptureError(`ocr failed: ${parsed.error}${hint}`);
+        }
         const imgWidth = buf.readUInt32BE(16);
         const scaleFactorX = screenSize.width / (region ? region.width : (imgWidth / scaleFactor));
         const elements = parsed.elements.map((el) => ({

package/dist/src/safety/guard.js

@@ -100,6 +100,10 @@ export const OBSERVE_ACTIONS = new Set([
     "wait_for_element",
     "doctor",
     "clipboard_read",
+    // focus_app only sets the active target context via AppleScript activate
+    // and an AX window lookup — it does not synthesize mouse or keyboard input,
+    // so the user-activity pause must not block it. (OpenCode 0.3.7 follow-up)
+    "focus_app",
 ]);
 /** Actions that synthesize user input — need full user-activity protection. */
 export const INPUT_ACTIONS = new Set([

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

@@ -8,6 +8,10 @@ export interface PermissionDetail {
     granted: boolean;
     instructions: string;
 }
+/**
+ * Get the name of the terminal app that the user needs to authorize.
+ */
+export declare function getTerminalAppName(): string;
 export declare function checkPermissions(): Promise<PermissionCheckResult>;
 export declare function checkPermission(type: "accessibility" | "screenRecording"): Promise<{
     granted: boolean;

package/dist/src/safety/permissions.js

@@ -4,7 +4,7 @@ const execFileAsync = promisify(execFile);
 /**
  * Get the name of the terminal app that the user needs to authorize.
  */
-function getTerminalAppName() {
+export function getTerminalAppName() {
     // Walk up the process tree to find the terminal emulator
     const ppid = process.ppid;
     // Common terminal app names

package/package.json

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