ucu-mcp 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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

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');
@@ -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.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.2",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {