fix(mcp): resolve bugs, add tool annotations, and new UIA tools

  Bug fixes:
  - Use top-level fs import instead of inline require() in appium-manager
  - Fix spawn race: replace setImmediate with child.once('spawn') (Node ≥15.1)
  - Fix CSS selector bug: use driver.findElement/findElements/findElementFromElement
    protocol calls directly; 'id' aliased to 'accessibility id' as documented
  - Fix appium:waitForAppLaunch capability (drop incorrect ms: infix)
  - Fix get_clipboard to pass { contentType } object, not bare string
  - Fix get_window_element to throw on unexpected response instead of String(result)
  - Fix get_attribute returning the string "null" for absent attributes (now "")
  - Remove dead ?? 1500 fallback (Zod default always fills the value)

  Quality:
  - Extract shared ELEMENT_KEY to lib/mcp/constants.ts
  - Return image content type from take_screenshot (MCP image rendering)
  - Move maximize/minimize/restore/close_window to window.ts (out of patterns.ts)
  - Add readOnlyHint/destructiveHint/idempotentHint annotations to all tools

  New tools: wait_for_element, get_toggle_state, focus_element, select_item

Author: y-schwab

lib/mcp/appium-manager.ts

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as path from 'node:path';
 import { spawn, type ChildProcess } from 'node:child_process';
@@ -52,7 +53,7 @@ function resolveAppiumBinary(configBinary?: string): string {
 
     // Prefer a local node_modules/.bin/appium (3 levels up from build/lib/mcp/)
     const localBin = path.resolve(__dirname, '..', '..', '..', 'node_modules', '.bin', 'appium');
-    if (require('node:fs').existsSync(localBin)) {return localBin;}
+    if (fs.existsSync(localBin)) {return localBin;}
 
     // Fall back to appium on the system PATH (global install: npm install -g appium)
     return 'appium';
@@ -86,7 +87,10 @@ export class AppiumManager {
             shell: process.platform === 'win32',
         });
 
-        // Attach error handler immediately to prevent unhandled error crash
+        // Wait for either a successful spawn or an early error.
+        // The 'spawn' event (Node ≥ 15.1) fires only after the OS has confirmed the
+        // process started; 'error' fires if it never starts (binary not found, etc.).
+        // Using setImmediate here would be a race — resolve could win before 'error' fires.
         await new Promise<void>((resolve, reject) => {
             child.once('error', (err) => {
                 reject(new Error(
@@ -95,8 +99,7 @@ export class AppiumManager {
                     `Or set APPIUM_BINARY to the full path of the appium executable.`
                 ));
             });
-            // If no error fires synchronously, we're past the spawn phase
-            setImmediate(resolve);
+            child.once('spawn', resolve);
         });
 
         this.process = child;

lib/mcp/constants.ts

@@ -0,0 +1,2 @@
+/** W3C WebDriver element reference key */
+export const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';

lib/mcp/session.ts

@@ -35,7 +35,7 @@ export class AppiumSession {
 
         if (params.appArguments !== undefined) {caps['appium:appArguments'] = params.appArguments;}
         if (params.appWorkingDir !== undefined) {caps['appium:appWorkingDir'] = params.appWorkingDir;}
-        if (params.waitForAppLaunch !== undefined) {caps['appium:ms:waitForAppLaunch'] = params.waitForAppLaunch;}
+        if (params.waitForAppLaunch !== undefined) {caps['appium:waitForAppLaunch'] = params.waitForAppLaunch;}
         if (params.shouldCloseApp !== undefined) {caps['appium:shouldCloseApp'] = params.shouldCloseApp;}
         if (params.delayAfterClick !== undefined) {caps['appium:delayAfterClick'] = params.delayAfterClick;}
         if (params.delayBeforeClick !== undefined) {caps['appium:delayBeforeClick'] = params.delayBeforeClick;}
@@ -48,7 +48,7 @@ export class AppiumSession {
             capabilities: caps as WebdriverIO.Capabilities,
         });
 
-        await this.driver.setTimeout({ implicit: params.implicitTimeout ?? 1500 });
+        await this.driver.setTimeout({ implicit: params.implicitTimeout });
         process.stderr.write('[MCP] Session created successfully\n');
     }
 

lib/mcp/tools/advanced.ts

@@ -10,6 +10,7 @@ export function registerAdvancedTools(server: McpServer, session: AppiumSession)
         'advanced_click',
         {
             description: 'Perform an advanced click with modifier keys, multiple clicks, or custom duration. Use this for right-click, Ctrl+click, double-click, etc.',
+            annotations: { destructiveHint: false },
             inputSchema: {
                 elementId: z.string().optional().describe('Element to click (its center). Provide either elementId or x+y.'),
                 x: z.number().int().optional().describe('Absolute screen x coordinate'),
@@ -36,6 +37,7 @@ export function registerAdvancedTools(server: McpServer, session: AppiumSession)
         'send_keys',
         {
             description: 'Send keyboard input. Each action can be a pause (ms delay), text to type, or a virtual key code press/release.',
+            annotations: { destructiveHint: false },
             inputSchema: {
                 actions: z.array(z.object({
                     pause: z.number().int().optional().describe('Pause in milliseconds'),

lib/mcp/tools/app.ts

@@ -7,14 +7,17 @@ export function registerAppTools(server: McpServer, session: AppiumSession): voi
         'get_window_element',
         {
             description: 'Get the root UI element of the current app window. Returns an element ID that represents the top-level window.',
+            annotations: { readOnlyHint: true },
         },
         async () => {
             try {
                 const driver = session.getDriver();
                 const result = await driver.executeScript('windows: getWindowElement', [{}]);
-                const elementId = (result as Record<string, string>)['element-6066-11e4-a52e-4f735466cecf']
-                    ?? (result as Record<string, string>).ELEMENT
-                    ?? String(result);
+                const ref = result as Record<string, string>;
+                const elementId = ref['element-6066-11e4-a52e-4f735466cecf'] ?? ref.ELEMENT;
+                if (!elementId) {
+                    throw new Error(`windows: getWindowElement returned unexpected value: ${JSON.stringify(result)}`);
+                }
                 return { content: [{ type: 'text' as const, text: elementId }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
@@ -26,6 +29,7 @@ export function registerAppTools(server: McpServer, session: AppiumSession): voi
         'launch_app',
         {
             description: 'Launch the application configured for this session (re-launch if it was closed).',
+            annotations: { destructiveHint: false },
         },
         async () => {
             try {
@@ -42,6 +46,7 @@ export function registerAppTools(server: McpServer, session: AppiumSession): voi
         'close_app',
         {
             description: 'Close the application under test without ending the session.',
+            annotations: { destructiveHint: true },
         },
         async () => {
             try {
@@ -58,6 +63,7 @@ export function registerAppTools(server: McpServer, session: AppiumSession): voi
         'get_device_time',
         {
             description: 'Get the current date/time on the Windows device.',
+            annotations: { readOnlyHint: true },
         },
         async () => {
             try {

lib/mcp/tools/clipboard.ts

@@ -13,11 +13,12 @@ export function registerClipboardTools(server: McpServer, session: AppiumSession
             inputSchema: {
                 contentType: contentTypeSchema.describe('"plaintext" for text, "image" for image content'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ contentType }) => {
             try {
                 const driver = session.getDriver();
-                const result = await driver.executeScript('windows: getClipboard', [contentType]);
+                const result = await driver.executeScript('windows: getClipboard', [{ contentType }]);
                 return { content: [{ type: 'text' as const, text: String(result) }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };

lib/mcp/tools/find.ts

@@ -2,21 +2,15 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { AppiumSession } from '../session.js';
 import { formatError } from '../errors.js';
+import { ELEMENT_KEY } from '../constants.js';
 
-const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
 const STRATEGIES = ['accessibility id', 'name', 'id', 'xpath', 'class name', 'tag name', '-windows uiautomation'] as const;
 type Strategy = typeof STRATEGIES[number];
 
-function buildSelector(strategy: Strategy, selector: string): string {
-    switch (strategy) {
-        case 'accessibility id': return `~${selector}`;
-        case 'xpath': return selector;
-        case 'tag name': return `//${selector}`;
-        case 'id': return `#${selector}`;
-        case 'class name': return `.${selector}`;
-        case 'name': return `*[name="${selector}"]`;
-        case '-windows uiautomation': return selector;
-    }
+// 'id' is documented as an alias for 'accessibility id' (UIA AutomationId).
+// All other strategies are forwarded verbatim to the Appium/WinAppDriver protocol.
+function resolveStrategy(strategy: Strategy): string {
+    return strategy === 'id' ? 'accessibility id' : strategy;
 }
 
 const STRATEGY_DESCRIPTIONS: Record<Strategy, string> = {
@@ -52,15 +46,13 @@ export function registerFindTools(server: McpServer, session: AppiumSession): vo
                 ),
                 selector: z.string().min(1).describe('The selector value for the chosen strategy'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ strategy, selector }) => {
             try {
                 const driver = session.getDriver();
-                const el = await driver.$(buildSelector(strategy as Strategy, selector));
-                if (!await el.isExisting()) {
-                    return { isError: true, content: [{ type: 'text' as const, text: `Element not found: ${strategy}="${selector}"` }] };
-                }
-                return { content: [{ type: 'text' as const, text: await el.elementId }] };
+                const rawEl = await driver.findElement(resolveStrategy(strategy as Strategy), selector);
+                return { content: [{ type: 'text' as const, text: rawEl[ELEMENT_KEY] }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
             }
@@ -78,15 +70,13 @@ export function registerFindTools(server: McpServer, session: AppiumSession): vo
                 ),
                 selector: z.string().min(1).describe('The selector value for the chosen strategy'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ strategy, selector }) => {
             try {
                 const driver = session.getDriver();
-                const els = await driver.$$(buildSelector(strategy as Strategy, selector));
-                const ids: string[] = [];
-                for (const el of els) {
-                    ids.push(await el.elementId);
-                }
+                const rawEls = await driver.findElements(resolveStrategy(strategy as Strategy), selector);
+                const ids = rawEls.map((el) => el[ELEMENT_KEY]);
                 return { content: [{ type: 'text' as const, text: JSON.stringify(ids) }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
@@ -106,19 +96,57 @@ export function registerFindTools(server: McpServer, session: AppiumSession): vo
                 ),
                 selector: z.string().min(1).describe('The selector value for the chosen strategy'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ parentElementId, strategy, selector }) => {
             try {
                 const driver = session.getDriver();
-                const parent = await driver.$({ [ELEMENT_KEY]: parentElementId });
-                const el = await parent.$(buildSelector(strategy as Strategy, selector));
-                if (!await el.isExisting()) {
-                    return { isError: true, content: [{ type: 'text' as const, text: `Child element not found: ${strategy}="${selector}"` }] };
-                }
-                return { content: [{ type: 'text' as const, text: await el.elementId }] };
+                const rawEl = await driver.findElementFromElement(
+                    parentElementId,
+                    resolveStrategy(strategy as Strategy),
+                    selector
+                );
+                return { content: [{ type: 'text' as const, text: rawEl[ELEMENT_KEY] }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
             }
         }
     );
+
+    server.registerTool(
+        'wait_for_element',
+        {
+            description: `Wait for a UI element to appear within a configurable timeout, then return its element ID. Useful after dialog opens, page transitions, or loading spinners disappear. ${FIND_STRATEGY_PRIORITY}`,
+            inputSchema: {
+                strategy: StrategyEnum.describe(
+                    'Locator strategy. ' +
+                    Object.entries(STRATEGY_DESCRIPTIONS).map(([k, v]) => `"${k}": ${v}`).join(' | ')
+                ),
+                selector: z.string().min(1).describe('The selector value for the chosen strategy'),
+                timeoutMs: z.number().int().min(0).default(5000).describe('Maximum time in milliseconds to wait for the element'),
+                pollIntervalMs: z.number().int().min(50).default(200).describe('How often to retry in milliseconds'),
+            },
+            annotations: { readOnlyHint: true },
+        },
+        async ({ strategy, selector, timeoutMs, pollIntervalMs }) => {
+            const driver = session.getDriver();
+            const effectiveStrategy = resolveStrategy(strategy as Strategy);
+            const deadline = Date.now() + timeoutMs;
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                try {
+                    const rawEl = await driver.findElement(effectiveStrategy, selector);
+                    return { content: [{ type: 'text' as const, text: rawEl[ELEMENT_KEY] }] };
+                } catch {
+                    if (Date.now() >= deadline) {
+                        return {
+                            isError: true,
+                            content: [{ type: 'text' as const, text: `Element not found within ${timeoutMs}ms: ${strategy}="${selector}"` }],
+                        };
+                    }
+                    await new Promise((r) => setTimeout(r, pollIntervalMs));
+                }
+            }
+        }
+    );
 }

lib/mcp/tools/inspect.ts

@@ -2,8 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { AppiumSession } from '../session.js';
 import { formatError } from '../errors.js';
-
-const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+import { ELEMENT_KEY } from '../constants.js';
 
 interface SuggestedSelector {
     strategy: string;
@@ -101,6 +100,7 @@ export function registerInspectTools(server: McpServer, session: AppiumSession):
             inputSchema: {
                 elementId: z.string().min(1).describe('Element ID returned by find_element'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ elementId }) => {
             try {

lib/mcp/tools/interact.ts

@@ -2,16 +2,17 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { AppiumSession } from '../session.js';
 import { formatError } from '../errors.js';
+import { ELEMENT_KEY } from '../constants.js';
 
 const elementIdSchema = z.string().min(1).describe('Element ID returned by find_element');
-const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
 
 export function registerInteractTools(server: McpServer, session: AppiumSession): void {
     server.registerTool(
         'click_element',
         {
             description: 'Click a UI element by its element ID.',
             inputSchema: { elementId: elementIdSchema },
+            annotations: { destructiveHint: false },
         },
         async ({ elementId }) => {
             try {
@@ -33,6 +34,7 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
                 elementId: elementIdSchema,
                 value: z.string().describe('The text value to set'),
             },
+            annotations: { destructiveHint: false },
         },
         async ({ elementId, value }) => {
             try {
@@ -51,6 +53,7 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
         {
             description: 'Clear the text content of an input element.',
             inputSchema: { elementId: elementIdSchema },
+            annotations: { destructiveHint: false },
         },
         async ({ elementId }) => {
             try {
@@ -69,6 +72,7 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
         {
             description: 'Get the visible text content of a UI element.',
             inputSchema: { elementId: elementIdSchema },
+            annotations: { readOnlyHint: true },
         },
         async ({ elementId }) => {
             try {
@@ -85,18 +89,19 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
     server.registerTool(
         'get_attribute',
         {
-            description: 'Get an attribute or property of a UI element. Common attributes: Name, AutomationId, ClassName, IsEnabled, IsOffscreen, ControlType, Value.Value.',
+            description: 'Get an attribute or property of a UI element. Common attributes: Name, AutomationId, ClassName, IsEnabled, IsOffscreen, ControlType, Value.Value. Returns an empty string when the attribute is absent.',
             inputSchema: {
                 elementId: elementIdSchema,
                 attribute: z.string().min(1).describe('Attribute name, e.g. "Name", "IsEnabled", "ControlType"'),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ elementId, attribute }) => {
             try {
                 const driver = session.getDriver();
                 const el = await driver.$({ [ELEMENT_KEY]: elementId });
                 const value = await el.getAttribute(attribute);
-                return { content: [{ type: 'text' as const, text: value ?? 'null' }] };
+                return { content: [{ type: 'text' as const, text: value ?? '' }] };
             } catch (err) {
                 return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
             }
@@ -108,6 +113,7 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
         {
             description: 'Check whether a UI element is visible on screen (not off-screen).',
             inputSchema: { elementId: elementIdSchema },
+            annotations: { readOnlyHint: true },
         },
         async ({ elementId }) => {
             try {
@@ -126,6 +132,7 @@ export function registerInteractTools(server: McpServer, session: AppiumSession)
         {
             description: 'Check whether a UI element is enabled and interactable.',
             inputSchema: { elementId: elementIdSchema },
+            annotations: { readOnlyHint: true },
         },
         async ({ elementId }) => {
             try {