ucu-mcp 0.3.1 → 0.3.4

package/CHANGELOG.md

@@ -5,6 +5,60 @@ 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.4] - 2026-06-06
+
+### Re-publish of 0.3.3
+
+0.3.3 was published with a syntax error in the source test file
+(`tests/unit/tools-layer.test.ts:355` was a continuation of a `//`
+comment block that lost its `//` prefix on a hard line break, so
+tsc parsed the second line as a bare identifier). The published
+npm tarball was functionally correct (`dist/` was unaffected), but
+the broken test file would fail to compile for any consumer
+running `npm test` against the source. The fix (a single-character
+comment prefix) was applied, but npm disallows re-publishing the
+same version, so the fixed source ships as 0.3.4 with the same
+contents and CHANGELOG entry as 0.3.3 plus this note.
+
+### Yanked
+
+`ucu-mcp@0.3.3` was unpublished (yanked) shortly after release due to
+the test file compile error. Users on `@latest` are now on 0.3.4.
+
+## [0.3.3] - 2026-06-06
+
+### Tests
+
+- `tools-layer`: three new test cases cover `wait_for_element` value+textMode combinations (contains, exact, regex). They confirm the response surfaces the matched value unchanged so the model can branch on it. (Completes Singer Item 4)
+
+### Refactor
+
+- JXA `textMatches` and `valueMatches` consolidated through a shared `matchesValue(filter, value, mode)` helper. No behavior change; the three branches (contains / exact / regex) now live in one place. (Completes Singer Item 8)
+
+## [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

package/dist/src/mcp/tools.js

@@ -547,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');
@@ -852,45 +863,37 @@ export class MacOSPlatform {
         }
       }
 
-      function textMatches(elemName, elemValue, elemDesc) {
-        if (textFilter === null) return true;
-        var sources = [elemName, elemValue, elemDesc];
-        if (textMode === "exact") {
-          var t = textFilter.toLowerCase();
-          for (var i = 0; i < sources.length; i++) {
-            if (sources[i].toLowerCase() === t) return true;
-          }
-          return false;
-        } else if (textMode === "regex") {
+      // Shared filter helper. textMatches and valueMatches used to be near
+      // copies of the same three-branch dispatch (contains / exact / regex);
+      // this consolidates the logic so the two callers only differ in which
+      // sources they iterate. Declared before textMatches/valueMatches
+      // because JXA function declarations are order-sensitive within a
+      // script. (Singer Nit)
+      function matchesValue(filter, value, mode) {
+        if (filter === null) return true;
+        if (mode === "exact") {
+          return value.toLowerCase() === filter.toLowerCase();
+        } else if (mode === "regex") {
           try {
-            var re = new RegExp(textFilter, "i");
-            for (var i = 0; i < sources.length; i++) {
-              if (re.test(sources[i])) return true;
-            }
-          } catch(e) {}
-          return false;
+            return new RegExp(filter, "i").test(value);
+          } catch(e) { return false; }
         } else {
           // contains (default)
-          var t = textFilter.toLowerCase();
-          for (var i = 0; i < sources.length; i++) {
-            if (sources[i].toLowerCase().indexOf(t) !== -1) return true;
-          }
-          return false;
+          return value.toLowerCase().indexOf(filter.toLowerCase()) !== -1;
         }
       }
 
-      function valueMatches(elemValue) {
-        if (valueFilter === null) return true;
-        if (textMode === "exact") {
-          return elemValue.toLowerCase() === valueFilter.toLowerCase();
-        } else if (textMode === "regex") {
-          try {
-            return new RegExp(valueFilter, "i").test(elemValue);
-          } catch(e) { return false; }
-        } else {
-          // contains (default)
-          return elemValue.toLowerCase().indexOf(valueFilter.toLowerCase()) !== -1;
+      function textMatches(elemName, elemValue, elemDesc) {
+        if (textFilter === null) return true;
+        var sources = [elemName, elemValue, elemDesc];
+        for (var i = 0; i < sources.length; i++) {
+          if (matchesValue(textFilter, sources[i], textMode)) return true;
         }
+        return false;
+      }
+
+      function valueMatches(elemValue) {
+        return matchesValue(valueFilter, elemValue, textMode);
       }
 
       function matches(elem) {
@@ -1024,6 +1027,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.js

@@ -16,6 +16,8 @@ export class UcuError extends Error {
     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;

package/package.json

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