ucu-mcp 0.4.3 → 0.5.1

package/dist/src/safety/guard.js

@@ -12,6 +12,8 @@
 const DEFAULT_BLOCKED_KEYS = [
     // macOS – app-level
     "cmd+q",
+    "cmd+shift+q", // log out（方向2 后字母 q 可解析，须显式拦截）
+    "cmd+option+q", // log out variant
     "cmd+w",
     "cmd+l", // lock screen
     // macOS – system-level
@@ -74,12 +76,22 @@ const DEFAULT_TEXT_INJECTION_PATTERNS = [
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Normalize a shortcut string to lowercase, trimmed, sorted modifiers. */
+/** Modifier alias → canonical name. MAC_MODIFIER_FLAGS accepts both forms
+ *  (cmd/command, option/alt, control/ctrl); normalize them so a blocklist
+ *  entry like "cmd+option+esc" also catches "cmd+alt+esc". */
+const MODIFIER_CANONICAL = {
+    alt: "option", ctrl: "control", cmd: "command",
+};
+/** Normalize a shortcut string to lowercase, trimmed, sorted modifiers with
+ *  modifier aliases canonicalized (alt→option, ctrl→control, cmd→command). */
 function normalizeShortcut(raw) {
     return raw
         .toLowerCase()
         .split("+")
-        .map((s) => s.trim())
+        .map((s) => {
+        const t = s.trim();
+        return MODIFIER_CANONICAL[t] ?? t;
+    })
         .sort()
         .join("+");
 }
@@ -104,6 +116,8 @@ export const OBSERVE_ACTIONS = new Set([
     // 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",
+    // describe_screen reads screen state (OCR + AX), no input synthesis.
+    "describe_screen",
 ]);
 /** Actions that synthesize user input — need full user-activity protection. */
 export const INPUT_ACTIONS = new Set([
@@ -117,6 +131,7 @@ export const INPUT_ACTIONS = new Set([
     "click_element",
     "type_in_element",
     "set_value",
+    "click_menu_bar_extra",
     "clipboard_write",
 ]);
 export function classifyAction(action) {

package/dist/src/utils/input.js

@@ -80,6 +80,20 @@ const MAC_MODIFIER_FLAGS = {
     option: 0x00080000, alt: 0x00080000,
     control: 0x00040000, ctrl: 0x00040000,
 };
+// 字母/数字 keyCode —— typeText 与 pressKey 共享的唯一数据源。
+// pressKey 在 MAC_KEY_CODES（特殊键）未命中时回退查这两个 map，让 Cmd+M / Cmd+W 等
+// 含字母的快捷键可用。注意 'a' 的 keyCode 是 0，查找时必须用 `in` 判定存在性，
+// 不能用 truthy（否则 0 会被当成未命中而穿透到 digit map）。
+const MAC_LETTER_KEY_CODES = {
+    a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
+    b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
+    o: 31, u: 32, i: 33, p: 34, l: 37, j: 38, k: 40,
+    n: 45, m: 46,
+};
+const MAC_DIGIT_KEY_CODES = {
+    "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
+    "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
+};
 // ── AppleScript string escaping ───────────────────────────────────────────
 function escapeAppleScriptString(str) {
     return str
@@ -288,23 +302,11 @@ export async function typeText(text, delay = 20, _platform = process.platform) {
     if (_platform === "darwin") {
         // Character -> { keyCode, shift? } map for CGEvent injection
         const CHAR_TO_KEY = {};
-        // Lowercase letters
-        const letterMap = {
-            a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
-            b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
-            o: 31, u: 32, i: 33, p: 34, l: 37, j: 38, k: 40,
-            n: 45, m: 46,
-        };
-        for (const [ch, code] of Object.entries(letterMap)) {
+        for (const [ch, code] of Object.entries(MAC_LETTER_KEY_CODES)) {
             CHAR_TO_KEY[ch] = { code };
             CHAR_TO_KEY[ch.toUpperCase()] = { code, shift: true };
         }
-        // Digits
-        const digitMap = {
-            "1": 18, "2": 19, "3": 20, "4": 21, "5": 23,
-            "6": 22, "7": 26, "8": 28, "9": 25, "0": 29,
-        };
-        for (const [ch, code] of Object.entries(digitMap)) {
+        for (const [ch, code] of Object.entries(MAC_DIGIT_KEY_CODES)) {
             CHAR_TO_KEY[ch] = { code };
         }
         // Unshifted symbols
@@ -422,9 +424,15 @@ export async function pressKey(key, modifiers = [], _platform = process.platform
         return;
     }
     if (_platform === "darwin") {
-        const keyCode = MAC_KEY_CODES[key.toLowerCase()];
+        const lookup = key.toLowerCase();
+        // 先查特殊键，未命中再回退查字母/数字（让 Cmd+M / Cmd+W 等含字母的快捷键可用）。
+        // 用 `in` 判定存在性——'a' 的 keyCode 是 0，truthy 判断会误穿透到 digit map。
+        const keyCode = lookup in MAC_KEY_CODES ? MAC_KEY_CODES[lookup] :
+            (key.length === 1 && lookup in MAC_LETTER_KEY_CODES) ? MAC_LETTER_KEY_CODES[lookup] :
+                (key.length === 1 && key in MAC_DIGIT_KEY_CODES) ? MAC_DIGIT_KEY_CODES[key] :
+                    undefined;
         if (keyCode === undefined) {
-            throw new Error(`Unknown key: ${key}. Supported keys: ${Object.keys(MAC_KEY_CODES).join(", ")}`);
+            throw new Error(`Unknown key: ${key}. Supported keys: special keys (${Object.keys(MAC_KEY_CODES).join(", ")}), single letters a-z, single digits 0-9`);
         }
         // Build modifier flags
         let flags = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "dist/src/",
     "dist/index.js",
     "dist/index.d.ts",
+    "skills/",
     "README.md",
     "CHANGELOG.md"
   ],

package/skills/ucu-mcp/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ucu-mcp
+description: >-
+  Guidance for using UCU-MCP, the macOS computer-use MCP server (screenshot,
+  click, type, OCR, AX element tools, menu-bar tray support). Use when an
+  agent needs to automate macOS desktop apps over MCP — establishing target
+  context, reading screen state, interacting with UI elements, operating
+  menu-bar/tray apps, or recovering from AX/permission errors. Covers Claude
+  Code CLI/Desktop, Codex, OpenCode, and other MCP clients.
+---
+
+# UCU-MCP
+
+UCU-MCP is a cross-client computer-use MCP server for macOS (Windows/Linux are
+explicit stubs). It exposes 26 tools that let an agent see the screen and drive
+native apps through a combination of Accessibility (AX) APIs, CGEvent input
+synthesis, Vision OCR, and ScreenCaptureKit screenshots.
+
+- npm package: `ucu-mcp`
+- Run: `npx -y ucu-mcp` (stdio MCP server) or install globally via `npm i -g ucu-mcp`
+
+## Core Workflow
+
+1. **Check readiness** → `doctor` verifies Accessibility + Screen Recording
+   permissions and native helpers. If anything is missing, follow its guidance
+   (see [troubleshooting](references/troubleshooting.md)).
+2. **Establish target context** → `list_apps` then `focus_app(name)` sets the
+   active window target. Subsequent AX tools operate against that target.
+3. **Prefer AX over coordinates** → `find_element(text/role/value)` →
+   `click_element` / `type_in_element` / `set_value`. AX is precise and survives
+   layout shifts; coordinates are a last resort.
+4. **When AX is opaque (Electron/Tauri/WebView)** → `screenshot` + `ocr` to
+   locate text by bounding box, then `click(x, y)` at the returned coordinates.
+5. **When image content is not visible to you** (relayed/downgraded to a URL) →
+   `screenshot(describe: true)` or the standalone `describe_screen` tool to get a
+   structured text view (OCR blocks + AX tree + foreground window).
+6. **Menu-bar/tray apps** (e.g. cc-switch) → `click_menu_bar_extra(app,
+   description/name/index)` opens the tray menu, then `find_element` inside it.
+7. **Verify actions** → pass `captureAfter: true` on action tools, or call
+   `screenshot` / `get_window_state` afterwards.
+8. **Recover from errors** → every error response carries a `hint` with the
+   next step. See the [error code table](references/troubleshooting.md).
+
+Full tool inventory with parameters: [tool-reference](references/tool-reference.md).
+Common task playbooks: [workflows](references/workflows.md).
+
+## Operating Rules
+
+- **AX-first.** Use `find_element` → `click_element` / `type_in_element` /
+  `set_value` whenever the AX tree exposes the target. Fall back to coordinates
+  only when AX returns nothing (Electron/WebView) or the control silently
+  swallows AX actions.
+- **Observe before acting.** Call `screenshot` / `get_window_state` /
+  `describe_screen` before destructive or hard-to-reverse actions so you act on
+  current state, not assumptions.
+- **TARGET_STALE is recoverable.** Re-run `focus_app` for the target app, then
+  retry — the element cache refetches equivalent AX nodes.
+- **Tray apps need `click_menu_bar_extra`.** `focus_app` alone cannot reach
+  pure menu-bar (LSUIElement) apps; their status item is hosted by
+  `SystemUIServer` and is not in any app window's AX tree.
+- **Dangerous actions are blocked.** Quit/logout/lock shortcuts (`cmd+q`,
+  `cmd+shift+q`, `cmd+l`, …), sensitive-window URLs, and suspicious injected
+  text are rejected by the safety guard. Choose a safer action or ask the user.
+- **Sensitive fields are masked in `describe_screen`.** Password fields
+  (`AXSecureTextField`, or names matching `/password|secret|token/i`) appear as
+  `[REDACTED]` — never try to read or exfiltrate them.
+- **macOS is locked → actions blocked.** The server refuses to synthesize input
+  while the screen is locked; wait for unlock or ask the user.
+
+## MCP Config
+
+Add UCU-MCP to your MCP client. Stdio transport, no arguments needed.
+
+**Codex / generic TOML:**
+
+```toml
+[mcp_servers.ucu-mcp]
+command = "npx"
+args = ["-y", "ucu-mcp"]
+```
+
+**Claude Code CLI / Desktop** — add via `claude mcp add`:
+
+```bash
+claude mcp add ucu-mcp -- npx -y ucu-mcp
+```
+
+Run `ucu-mcp doctor` once after first connect to verify macOS permissions
+(System Settings → Privacy & Security → Accessibility **and** Screen Recording
+must be granted to the launching terminal/client).
+
+## References
+
+- [tool-reference.md](references/tool-reference.md) — all 26 tools, parameters,
+  return shapes, and when to use each.
+- [workflows.md](references/workflows.md) — playbooks for common tasks: form
+  filling, tray apps, opaque Electron UIs, vision-degraded environments, stale
+  targets.
+- [troubleshooting.md](references/troubleshooting.md) — error code table with
+  recovery steps, permission issues, AX-opacity workarounds, OCR failures.

package/skills/ucu-mcp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UCU-MCP"
+  short_description: "Guide agents using UCU-MCP macOS computer-use"
+  default_prompt: "Use $ucu-mcp to automate macOS desktop apps through UCU-MCP."

package/skills/ucu-mcp/references/tool-reference.md

@@ -0,0 +1,255 @@
+# Tool Reference
+
+UCU-MCP exposes 26 tools across five categories. All action tools accept
+optional `captureAfter` / `captureMaxWidth` / `captureFormat` parameters that
+screenshot the result and append it to the response.
+
+Coordinate inputs are **screen-absolute** unless noted (window-relative only
+when a `windowId` is explicitly passed).
+
+---
+
+## Screen & Window
+
+### `screenshot`
+Capture the full screen, a region, or a specific window.
+
+| Param | Type | Default | Notes |
+|---|---|---|---|
+| `display` | number | 0 | Display index |
+| `windowId` | string | — | From `list_windows`; captures that window |
+| `region` | `{x,y,width,height}` | — | Mutually exclusive with `windowId` |
+| `format` | `"png"` \| `"jpeg"` | `"png"` | |
+| `maxWidth` | number | 1280 | Resize preserving aspect ratio |
+| `describe` | boolean | false | Append a text `ScreenDescription` block (OCR + AX) after the image |
+| `describeOptions` | object | — | `{axDepth=3, ocrBlocks=50, includeAx=true}` when `describe=true` |
+
+Returns one image content block (+ one text block if `describe=true`). Use
+`describe=true` when image content may not reach the model (relay/URL downgrade).
+
+### `list_windows`
+List visible windows. Returns `WindowInfo[]` (`{id, title, processName, pid,
+bounds, isMinimized, isOnScreen}`). When empty, includes a `diagnostics` hint
+distinguishing permission-denied vs Electron-opacity.
+
+| Param | Type | Default |
+|---|---|---|
+| `includeMinimized` | boolean | false |
+
+### `get_window_state`
+AX tree of a window. Returns `WindowState` = `{window, focusedElement?, tree?}`.
+The `tree` is a depth-limited `ElementInfo` (`{role, name, value, states,
+bounds?, children?}`).
+
+| Param | Type | Default |
+|---|---|---|
+| `windowId` | string | active target |
+| `depth` | number | 3 (capped at 10) |
+| `includeBounds` | boolean | false |
+
+### `get_screen_size`
+Returns `{width, height, scaleFactor, estimated?}`. Synchronous, low-cost.
+
+| Param | Type | Default |
+|---|---|---|
+| `display` | number | 0 |
+
+### `ocr`
+Run Vision OCR on the full screen or a region. Returns `{elements:
+OcrElement[], fullText}`. Each `OcrElement` = `{text, x, y, width, height,
+confidence}` in screen-absolute coordinates.
+
+| Param | Type | Default |
+|---|---|---|
+| `display` | number | 0 |
+| `region` | `{x,y,width,height}` | full screen |
+
+### `describe_screen`
+Structured text description of the screen — the **vision-degraded fallback**.
+Returns `ScreenDescription` = `{capturedAt, screen, foregroundWindow,
+ocr:{blocks, fullText, status}, ax:{elements?, status, windowId?}, errors[]}`.
+Each source is collected independently; failures land in `errors` (never thrown).
+Password fields are masked to `[REDACTED]`.
+
+| Param | Type | Default | Notes |
+|---|---|---|---|
+| `display` | number | 0 | |
+| `ocr` | boolean | true | Requires Screen Recording when true |
+| `includeAx` | boolean | true | Requires Accessibility when true |
+| `axDepth` | number | 3 | Capped at 10 |
+| `ocrBlocks` | number | 50 | Max OCR elements returned |
+| `windowId` | string | active target | AX traversal target |
+
+Use when: image content blocks are not visible to you; you need
+machine-readable layout; you want OCR + AX in one call with graceful failure.
+
+---
+
+## Mouse & Input
+
+All accept `captureAfter` / `captureMaxWidth` / `captureFormat`.
+
+### `click` / `double_click`
+Click at screen coordinates. `button` ∈ `left|right|middle`.
+
+| Param | Type |
+|---|---|
+| `x`, `y` | number |
+| `button` | `"left"` \| `"right"` \| `"middle"` |
+| `windowId` | string (optional, makes x/y window-relative) |
+
+### `scroll`
+| Param | Type | Notes |
+|---|---|---|
+| `x`, `y` | number | position |
+| `deltaX`, `deltaY` | number | negative deltaY = scroll up |
+
+### `drag`
+| Param | Type |
+|---|---|
+| `startX`, `startY`, `endX`, `endY` | number |
+| `button` | `"left"` \| `"right"` \| `"middle"` |
+| `duration` | number (ms) |
+
+### `move`
+Move cursor without clicking. Params: `x`, `y`.
+
+### `get_cursor_position`
+Returns `{x, y}`.
+
+---
+
+## Keyboard
+
+### `type_text`
+Type a string at the current cursor position (CGEvent background injection).
+
+| Param | Type |
+|---|---|
+| `text` | string |
+| `delay` | number (ms, optional) |
+
+### `press_key`
+Press a key combo. Supports special keys, single letters a–z, single digits 0–9.
+
+| Param | Type | Notes |
+|---|---|---|
+| `key` | string | e.g. `"enter"`, `"m"`, `"5"` |
+| `keys` | string[] | alternative to `key` for multi-tap |
+| `modifiers` | string[] | `cmd`, `shift`, `alt`/`option`, `ctrl`/`control`, `capslock` |
+
+Blocked combos: `cmd+q`, `cmd+shift+q`, `cmd+option+q`, `cmd+l`, `alt+f4`,
+`ctrl+alt+del` (logout/lock).
+
+---
+
+## AX Element Interaction
+
+These operate on the active target's window (set via `focus_app`). Prefer these
+over coordinate clicks.
+
+### `find_element`
+Find AX elements by text/role/value. Returns `{results: FindElementResult[],
+metrics}`. Each result has an `id` for use in the element tools below. When 0
+results, includes a hint guiding to `screenshot`+`ocr`+`click(x,y)` (Electron
+opacity).
+
+| Param | Type | Default | Notes |
+|---|---|---|---|
+| `text` | string | — | Match element name/description |
+| `role` | string | — | e.g. `AXButton`, `AXTextField` |
+| `value` | string | — | Match current value |
+| `textMode` | `"contains"` \| `"exact"` \| `"regex"` | `"contains"` | |
+| `app` | string | active target | |
+| `depth` | number | 5 | |
+| `index` | number | — | Return only the Nth match (0-based) |
+| `near` | `{x,y}` | — | Sort by ascending distance, closest first |
+| `visibleOnly` | boolean | false | |
+| `includeBounds` | boolean | false | |
+
+### `click_element`
+Click by element `id`. AXPress first; on AX failure falls back to coordinate
+click at the element's bounds center (handles Tauri/Electron silent swallows).
+
+| Param | Type |
+|---|---|
+| `elementId` | string |
+| `app` | string (optional) |
+
+### `set_value`
+Set an AX element's value directly (no key synthesis). Best for text fields,
+checkboxes, sliders.
+
+| Param | Type |
+|---|---|
+| `elementId` | string |
+| `value` | string |
+| `app` | string (optional) |
+
+### `type_in_element`
+Focus an element and type into it. Refetches an equivalent AX node if the
+original `elementId` is stale (UI tree changed).
+
+| Param | Type | Default |
+|---|---|---|
+| `elementId` | string | |
+| `text` | string | |
+| `clearFirst` | boolean | false |
+| `app` | string | active target |
+
+### `click_menu_bar_extra`
+Click a menu-bar status item (tray icon) — for menu-bar-only apps (e.g.
+cc-switch) that `focus_app` cannot target. After clicking, the menu opens; use
+`find_element` to locate menu items, or `screenshot` + `ocr` if the menu's AX
+tree is opaque.
+
+| Param | Type | Notes |
+|---|---|---|
+| `app` | string | Target app name |
+| `description` | string | Match by description/name substring |
+| `name` | string | Match by name/description substring |
+| `index` | number | 0-based among matched items |
+
+---
+
+## Runtime & Synchronization
+
+### `list_apps`
+Returns `AppInfo[]` = `{name, pid, isFrontmost, windowCount}`. Background-only
+processes are filtered.
+
+### `focus_app`
+Set the active target context. Establishes a window for AX tools; falls back to
+a tray target (`windowId: "tray"`) for menu-bar-only apps if
+`click_menu_bar_extra` status items are found.
+
+| Param | Type |
+|---|---|
+| `app` | string |
+
+### `wait`
+Pause execution.
+
+| Param | Type |
+|---|---|
+| `ms` | number (1–60000) |
+
+### `wait_for_element`
+Poll until an AX element matches. Returns the match or times out.
+
+| Param | Type | Default |
+|---|---|---|
+| `text` / `role` / `value` | string | — |
+| `app` | string | active target |
+| `until` | `"appear"` \| `"disappear"` \| `"value_change"` | `"appear"` |
+| `timeout` / `timeoutMs` | number (ms) | 5000 |
+| `interval` / `intervalMs` | number (ms) | 500 |
+
+### `doctor`
+Verify permissions, native helpers, and client readiness. Returns a JSON report
+with `platform`, `safety`, `nativeHelpers`, `clients`, and `recommendations`.
+Run this first when something is misbehaving.
+
+### `clipboard_read` / `clipboard_write`
+Read/write the system clipboard. `clipboard_write` text-injection patterns
+(e.g. shell-escape sequences) are blocked by the safety guard.

package/skills/ucu-mcp/references/troubleshooting.md

@@ -0,0 +1,142 @@
+# Troubleshooting
+
+## First Checks
+
+1. Run `doctor` — verifies Accessibility + Screen Recording permissions and
+   native helpers. Most failures are permission issues.
+2. Confirm the target app is running and not minimized to the point of having no
+   on-screen window: `list_apps` + `list_windows`.
+3. Check `errors[]` in `describe_screen` responses — it names which source
+   (ocr/ax/foreground/screen) failed and why.
+
+---
+
+## Error Code Table
+
+Every error response carries a `code` and a `hint`. The table below maps codes
+to recovery steps (mirrors the runtime `recoveryHint`).
+
+| Code | Meaning | Recovery |
+|---|---|---|
+| `WINDOW_NOT_FOUND` | The target window does not exist or is not on screen. | `list_windows` again, retry with a fresh `windowId`, or omit `windowId` for screen coordinates. |
+| `TARGET_STALE` | The active target window changed pid or closed. | `focus_app` for the target app again, then retry. `type_in_element` auto-refetches equivalent nodes. |
+| `ELEMENT_NOT_FOUND` | No AX element matched the selector. | `find_element` again with broader selectors (different `text`, `textMode:"contains"`, drop `role`). If still empty, the app may be Electron-opaque — see below. |
+| `PERMISSION_DENIED` | Accessibility or Screen Recording not granted. | Run `doctor`, then grant the missing permission in System Settings → Privacy & Security, and **restart the launching client** (changes do not apply to already-running processes). |
+| `SAFETY_BLOCKED` | Action rejected by the safety guard (dangerous shortcut, sensitive window, suspicious text). | Choose a less risky action, or ask the user to perform it manually. Blocked shortcuts include `cmd+q`, `cmd+shift+q`, `cmd+l`, `alt+f4`. |
+| `INPUT_FAILED` | Input synthesis (click/type/keypress) failed at the CGEvent layer. | Observe current state with `screenshot` or `get_window_state`, then retry only if safe. |
+| `CAPTURE_FAILED` | Screenshot/OCR failed (usually Screen Recording permission). | `doctor` → grant Screen Recording → restart client. |
+| `COORDINATE_OUT_OF_BOUNDS` | Click/drag coordinates are outside the active display/window. | `get_screen_size` or `list_windows`, retry with coordinates inside bounds. |
+| `UNSUPPORTED_PARAMETER` | A parameter combination is invalid (e.g. `screenshot` with both `windowId` and `region`). | Remove or replace the unsupported parameter; inspect `tools/list` for the schema. |
+
+---
+
+## Permission Issues
+
+macOS requires two permissions for full functionality:
+
+- **Accessibility** — needed for all AX tools (`find_element`,
+  `click_element`, `get_window_state`, `list_windows`, `click_menu_bar_extra`).
+- **Screen Recording** — needed for `screenshot`, `ocr`, and `describe_screen`
+  (with `ocr: true`).
+
+Grant via **System Settings → Privacy & Security → Accessibility / Screen
+Recording**, enabling the entry for the launching terminal/client app (Terminal,
+iTerm, Claude Code, Codex, etc.).
+
+**Critical:** permission changes do not apply to already-running processes.
+After granting, **quit and restart the client** that launches `ucu-mcp`.
+
+Run `ucu-mcp doctor` (or the `doctor` tool) to verify — it reports per-permission
+status and which process to authorize.
+
+---
+
+## Electron / Tauri / WebView AX Opacity
+
+**Symptom:** `find_element` returns 0 results, `get_window_state` returns a near-
+empty tree (just an `AXGroup`), `list_windows` shows the window but AX tools
+can't see into it.
+
+**Cause:** Electron/Tauri/WebView apps render their UI in a composited layer
+that macOS AX cannot introspect. The AX tree exposes only the window frame and
+traffic-light buttons.
+
+**Workaround — pixel path:**
+```
+screenshot({})
+ocr({})
+  → blocks[].text locates the target UI text with bounding box {x,y,width,height}
+click({ x: block.x + block.width/2, y: block.y + block.height/2 })
+```
+
+`find_element` and `list_windows` emit a `hint` describing this fallback when
+they detect the pattern. For one-shot planning, `describe_screen` gives OCR + AX
+together.
+
+---
+
+## Menu-Bar / Tray App Not Reachable
+
+**Symptom:** `focus_app("tray-app")` throws `WINDOW_NOT_FOUND`; the app has no
+window in `list_windows`.
+
+**Cause:** Pure menu-bar (LSUIElement) apps have no window; their status item is
+hosted by the `SystemUIServer` system process.
+
+**Workaround:**
+```
+click_menu_bar_extra({ app: "tray-app", name: "TrayApp" })   # opens tray menu
+find_element({ text: "Settings", app: "tray-app" })          # menu items are AX-visible
+click_element({ elementId })
+```
+
+`focus_app` automatically falls back to a tray target when `click_menu_bar_extra`
+finds a matching status item, so subsequent AX tools work against the menu.
+
+If the tray menu itself is Electron-opaque:
+```
+click_menu_bar_extra({ app: "tray-app" })
+screenshot({})
+ocr({}) → locate menu item by text → click(x, y)
+```
+
+---
+
+## OCR Failures
+
+**Symptom:** `ocr` or `describe_screen` reports OCR failure (`ocr.status:
+"failed"`), or native OCR helper not found in `doctor`.
+
+**Checks:**
+1. Screen Recording permission granted and client restarted.
+2. Native helper present — `doctor` reports `ocr` helper status. If missing, the
+   npm package may be corrupted; reinstall.
+3. Screen is not locked (OCR captures a black frame when locked).
+
+`describe_screen` degrades gracefully — OCR failure still returns AX state, so
+you can fall back to `get_window_state` / `find_element`.
+
+---
+
+## describe_screen Returns Empty / All-skipped
+
+**Symptom:** `describe_screen` returns `errors: []` but `ocr.status:
+"skipped"` and `ax.status: "skipped"`.
+
+**Cause:** you passed `ocr: false, includeAx: false`, or the params defaulted to
+that (note: in live MCP use the SDK applies `ocr: true, includeAx: true`
+defaults; if you see both skipped, the client stripped defaults).
+
+**Fix:** explicitly pass `ocr: true, includeAx: true`.
+
+---
+
+## Actions Blocked While macOS Is Locked
+
+**Symptom:** input actions (`click`, `type_text`, `press_key`, …) fail; observe
+actions (`screenshot`, `ocr`) return black/empty frames.
+
+**Cause:** the safety guard refuses to synthesize input while the screen is
+locked (the user is not present to supervise).
+
+**Fix:** wait for the user to unlock, or ask them to unlock. There is no bypass.