@wdio/mcp 3.4.0 → 3.4.1

package/lib/server.js

@@ -46,7 +46,7 @@ var package_default = {
     type: "git",
     url: "git://github.com/webdriverio/mcp.git"
   },
-  version: "3.3.0",
+  version: "3.4.0",
   description: "MCP server with WebdriverIO for browser and mobile app automation (iOS/Android via Appium)",
   main: "./lib/server.js",
   module: "./lib/server.js",
@@ -173,7 +173,8 @@ init_state();
 import { z } from "zod";
 var navigateToolDefinition = {
   name: "navigate",
-  description: "Loads a URL in the current tab and waits for the page load event. Resets page state (DOM, JS runtime). Use instead of clicking links to go directly to a known URL.",
+  description: "Loads a URL in the current tab and waits for the page load event. Resets page state \u2014 DOM, JS runtime, timers, and frame context are destroyed. Use instead of clicking links when the target URL is known.",
+  annotations: { title: "Navigate to URL", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     url: z.string().min(1).describe("The URL to navigate to")
   }
@@ -214,7 +215,8 @@ var coerceBoolean = z2.preprocess((val) => {
 var defaultTimeout = 3e3;
 var clickToolDefinition = {
   name: "click_element",
-  description: "Waits for an element to exist, scrolls it into view, and calls element.click(). For browser sessions. On iOS, element.click() is sometimes ignored \u2014 use tap_element (which calls element.tap()) instead.",
+  description: "Waits for an element, scrolls it into view, and fires element.click(). May trigger navigation, form submission, or modals. Browser sessions only \u2014 on iOS element.click() is silently ignored; use tap_element instead. Default timeout: 3000ms.",
+  annotations: { title: "Click Element", destructiveHint: false },
   inputSchema: {
     selector: z3.string().describe(`Value for the selector, in the form of css selector or xpath ("button.my-class" or "//button[@class='my-class']" or "button=Exact text with spaces" or "a*=Link containing text")`),
     scrollToView: coerceBoolean.optional().describe("Whether to scroll the element into view before clicking").default(true),
@@ -247,7 +249,8 @@ import { z as z4 } from "zod";
 var defaultTimeout2 = 3e3;
 var setValueToolDefinition = {
   name: "set_value",
-  description: "Clears an input or textarea and types the given text. Always replaces existing content. Fails if the element is not found or not interactable within the timeout.",
+  description: "Clears an input or textarea then types the given text character by character. Always replaces existing content \u2014 clearValue() runs first. Triggers input, change, and key events which may fire validation or autocomplete. Scrolls into view by default.",
+  annotations: { title: "Set Input Value", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     selector: z4.string().describe(`Value for the selector, in the form of css selector or xpath ("button.my-class" or "//button[@class='my-class']")`),
     value: z4.string().describe("Text to enter into the element"),
@@ -281,7 +284,8 @@ init_state();
 import { z as z5 } from "zod";
 var scrollToolDefinition = {
   name: "scroll",
-  description: "scrolls the page by specified pixels (browser only). For mobile, use the swipe tool.",
+  description: "Scrolls the page vertically by a pixel amount. Browser-only \u2014 for mobile scrolling use swipe. Only supports up/down; no horizontal scrolling.",
+  annotations: { title: "Scroll Page", destructiveHint: false },
   inputSchema: {
     direction: z5.enum(["up", "down"]).describe("Scroll direction"),
     pixels: z5.number().optional().default(500).describe("Number of pixels to scroll")
@@ -316,7 +320,8 @@ var scrollTool = async ({ direction, pixels = 500 }) => scrollAction(direction,
 import { z as z6 } from "zod";
 var setCookieToolDefinition = {
   name: "set_cookie",
-  description: "Sets a browser cookie for the active session. The browser must already be on the target domain \u2014 cookies cannot be set cross-domain. Use to inject session tokens or feature flags without going through login flows.",
+  description: "Sets a browser cookie on the active session. The browser must already be on the target domain \u2014 cookies cannot be set cross-domain. Use to inject session tokens or feature flags without login flows.",
+  annotations: { title: "Set Cookie", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     name: z6.string().describe("Cookie name"),
     value: z6.string().describe("Cookie value"),
@@ -355,7 +360,8 @@ var setCookieTool = async ({
 };
 var deleteCookiesToolDefinition = {
   name: "delete_cookies",
-  description: "deletes all cookies or a specific cookie by name",
+  description: "Deletes all cookies or a single cookie by name from the current browser session. Irreversible \u2014 deleted cookies cannot be recovered.",
+  annotations: { title: "Delete Cookies", destructiveHint: true, idempotentHint: true },
   inputSchema: {
     name: z6.string().optional().describe("Optional cookie name to delete a specific cookie. If not provided, deletes all cookies")
   }
@@ -387,7 +393,8 @@ init_state();
 import { z as z7 } from "zod";
 var tapElementToolDefinition = {
   name: "tap_element",
-  description: "Calls element.tap() on a matched element or taps at absolute screen coordinates. Use on iOS when element.click() (click_element) is ignored \u2014 tap is the native gesture iOS responds to. Mobile-only.",
+  description: "Taps a matched element via element.tap() or at absolute screen coordinates (x, y). No scroll-into-view or wait \u2014 element must already be visible on screen. Use instead of click_element on iOS where element.click() is ignored. Provide selector OR both x and y. Mobile-only.",
+  annotations: { title: "Tap Element", destructiveHint: false },
   inputSchema: {
     selector: z7.string().optional().describe("Element selector (CSS, XPath, accessibility ID, or UiAutomator)"),
     x: z7.number().optional().describe("X coordinate for screen tap (if no selector provided)"),
@@ -424,7 +431,8 @@ var tapAction = async (args) => {
 var tapElementTool = async (args) => tapAction(args);
 var swipeToolDefinition = {
   name: "swipe",
-  description: 'Performs a full-screen swipe gesture on mobile. Direction is content movement (e.g. "up" scrolls a list upward, not the finger direction). Use to scroll past visible bounds; for moving a specific element use drag_and_drop. Mobile-only \u2014 use scroll for browsers.',
+  description: 'Performs a full-screen swipe gesture. Direction is content movement \u2014 "up" scrolls content upward (finger moves down). For browser scrolling use scroll; for dragging a specific element use drag_and_drop. No error if content cannot scroll further. Mobile-only.',
+  annotations: { title: "Swipe Screen", destructiveHint: false },
   inputSchema: {
     direction: z7.enum(["up", "down", "left", "right"]).describe("Swipe direction"),
     duration: z7.number().min(100).max(5e3).optional().describe("Swipe duration in milliseconds (default: 500)"),
@@ -460,7 +468,8 @@ var swipeAction = async (args) => {
 var swipeTool = async (args) => swipeAction(args);
 var dragAndDropToolDefinition = {
   name: "drag_and_drop",
-  description: "drags an element to another element or coordinates (mobile)",
+  description: "Drags an element to another element or to relative x/y offsets. x and y are offsets from the source element, not absolute screen coordinates (unlike tap_element). Provide targetSelector OR both x and y. Mobile-only.",
+  annotations: { title: "Drag and Drop", destructiveHint: false },
   inputSchema: {
     sourceSelector: z7.string().describe("Source element selector to drag"),
     targetSelector: z7.string().optional().describe("Target element selector to drop onto"),
@@ -504,7 +513,8 @@ init_state();
 import { z as z8 } from "zod";
 var switchContextToolDefinition = {
   name: "switch_context",
-  description: "Switches between native and webview automation contexts in a hybrid mobile app. Required before using CSS/XPath selectors inside an embedded webview \u2014 switch to WEBVIEW_* first, then switch back to NATIVE_APP for native elements. List available contexts using get_contexts tool or wdio://session/current/contexts resource.",
+  description: "Switches between native and webview automation contexts in a hybrid mobile app. In NATIVE_APP context, use accessibility IDs; in WEBVIEW_* context, use CSS/XPath. Changes persist for all subsequent commands. Accepts context name or 1-based index. Use get_contexts to discover available targets. Mobile-only.",
+  annotations: { title: "Switch Context", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     context: z8.string().describe(
       'Context name to switch to (e.g., "NATIVE_APP", "WEBVIEW_com.example.app", or use index from wdio://session/current/contexts resource)'
@@ -542,19 +552,22 @@ init_state();
 import { z as z9 } from "zod";
 var hideKeyboardToolDefinition = {
   name: "hide_keyboard",
-  description: "Dismisses the software keyboard on mobile. Call after text entry when the keyboard obscures elements you need to interact with next. No-op if already hidden. Mobile-only.",
+  description: "Dismisses the on-screen keyboard on mobile. Call after text entry when the keyboard obscures elements. No-op if already hidden. Mobile-only.",
+  annotations: { title: "Hide Keyboard", destructiveHint: false, idempotentHint: true },
   inputSchema: {}
 };
 var rotateDeviceToolDefinition = {
   name: "rotate_device",
-  description: "Rotates a mobile device to portrait or landscape and waits for the OS rotation to complete. Use to test orientation-dependent layouts. Mobile-only; no effect in browser sessions.",
+  description: "Rotates a mobile device to portrait or landscape orientation. Waits for the OS rotation animation to complete. Use to test orientation-dependent layouts. Mobile-only; no effect in browser sessions.",
+  annotations: { title: "Rotate Device", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     orientation: z9.enum(["PORTRAIT", "LANDSCAPE"]).describe("Device orientation")
   }
 };
 var setGeolocationToolDefinition = {
   name: "set_geolocation",
-  description: "Overrides the device GPS coordinates for the session. Affects navigator.geolocation on web and location services on mobile. Location permissions must be granted to the app before calling this.",
+  description: "Overrides GPS coordinates for the session. Affects navigator.geolocation in browsers and location services on mobile. Location permissions must already be granted to the app.",
+  annotations: { title: "Set Geolocation", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     latitude: z9.number().min(-90).max(90).describe("Latitude coordinate"),
     longitude: z9.number().min(-180).max(180).describe("Longitude coordinate"),
@@ -619,21 +632,8 @@ init_state();
 import { z as z10 } from "zod";
 var executeScriptToolDefinition = {
   name: "execute_script",
-  description: `Executes JavaScript in browser or mobile commands via Appium.
-
-**Option B for browser interaction** \u2014 prefer get_visible_elements or click_element/set_value with a selector instead. Use execute_script only when no dedicated tool covers the action (e.g. reading computed values, triggering custom events, scrolling to a position).
-
-**Browser:** Runs JavaScript in page context. Use 'return' to get values back.
-  - Example: execute_script({ script: "return document.title" })
-  - Example: execute_script({ script: "return window.scrollY" })
-  - Example: execute_script({ script: "arguments[0].click()", args: ["#myButton"] })
-
-**Mobile (Appium):** Executes mobile-specific commands using 'mobile: <command>' syntax.
-  - Press key (Android): execute_script({ script: "mobile: pressKey", args: [{ keycode: 4 }] }) // BACK=4, HOME=3
-  - Activate app: execute_script({ script: "mobile: activateApp", args: [{ appId: "com.example" }] })
-  - Terminate app: execute_script({ script: "mobile: terminateApp", args: [{ appId: "com.example" }] })
-  - Deep link: execute_script({ script: "mobile: deepLink", args: [{ url: "myapp://screen", package: "com.example" }] })
-  - Shell command (Android): execute_script({ script: "mobile: shell", args: [{ command: "dumpsys", args: ["battery"] }] })`,
+  description: `Executes arbitrary JavaScript in browser page context or Appium mobile: commands. Can read/modify DOM, trigger events, terminate apps, or run Android shell commands \u2014 use only when no dedicated tool covers the action. Browser: pass JS in script, use 'return' for values, string args matching selectors auto-resolve to elements. Mobile: use 'mobile: <command>' syntax in script with args array (e.g. "mobile: pressKey", "mobile: activateApp"). Prefer click_element/set_value/get_elements for standard interactions.`,
+  annotations: { title: "Execute Script", destructiveHint: false },
   inputSchema: {
     script: z10.string().describe('JavaScript code (browser) or mobile command string like "mobile: pressKey" (Appium)'),
     args: z10.array(z10.any()).optional().describe("Arguments to pass to the script. For browser: element selectors or values. For mobile commands: command-specific parameters as objects.")
@@ -1839,7 +1839,8 @@ async function getElements(browser, params) {
 import { encode } from "@toon-format/toon";
 var getElementsToolDefinition = {
   name: "get_elements",
-  description: "Get interactable elements on the current page. Use when wdio://session/current/elements does not return the desired elements.",
+  description: "Returns interactable elements on the current page with selectors, text, and bounding boxes. Supports filtering by element type, viewport visibility, and pagination. Use when the wdio://session/current/elements resource does not return desired elements.",
+  annotations: { title: "Get Visible Elements", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
     inViewportOnly: coerceBoolean.optional().default(false).describe("Only return elements visible in the current viewport (default: false)."),
     includeContainers: coerceBoolean.optional().default(false).describe("Include container elements like divs and sections (default: false)"),
@@ -1874,19 +1875,8 @@ import { z as z12 } from "zod";
 var USER_DATA_DIR = join(tmpdir(), "chrome-debug");
 var launchChromeToolDefinition = {
   name: "launch_chrome",
-  description: `Prepares and launches Chrome with remote debugging enabled so attach_browser() can connect.
-
-Two modes:
-
-  newInstance (default): Opens a Chrome window alongside your existing one using a separate
-    profile dir. Your current Chrome session is untouched.
-
-  freshSession: Launches Chrome with an empty profile (no cookies, no logins).
-
-Use copyProfileFiles: true to carry over your cookies and logins into the debug session.
-Note: changes made during the session won't sync back to your main profile.
-
-After this tool succeeds, call attach_browser() to connect.`,
+  description: 'Launches Chrome with remote debugging enabled. Wipes and recreates a temporary profile directory on each call. Mode "newInstance" (default) runs alongside existing Chrome; "freshSession" starts with an empty profile. Set copyProfileFiles to copy cookies/logins from your Default profile \u2014 changes do not sync back. After launch, call start_session with attach: true to connect. Spawns a detached Chrome process that persists if the server exits.',
+  annotations: { title: "Launch Chrome", destructiveHint: false },
   inputSchema: {
     port: z12.number().default(9222).describe("Remote debugging port (default: 9222)"),
     mode: z12.enum(["newInstance", "freshSession"]).default("newInstance").describe(
@@ -1990,14 +1980,8 @@ import { z as z13 } from "zod";
 var restoreFunctions = /* @__PURE__ */ new Map();
 var emulateDeviceToolDefinition = {
   name: "emulate_device",
-  description: `Emulate a mobile or tablet device in the current browser session (sets viewport, DPR, user-agent, touch events).
-
-Requires a BiDi-enabled session: start_browser({ capabilities: { webSocketUrl: true } })
-
-Usage:
-  emulate_device()                    \u2014 list available device presets
-  emulate_device({ device: "iPhone 15" })  \u2014 activate emulation
-  emulate_device({ device: "reset" }) \u2014 restore desktop defaults`,
+  description: 'Emulates a mobile or tablet device in the current browser session by setting viewport, DPR, user-agent, and touch events. Requires a BiDi-enabled session (start_session with capabilities: { webSocketUrl: true }). Omit device to list available presets. Pass "reset" to restore desktop defaults. Changes persist for all subsequent tool calls until reset or session close. Browser-only.',
+  annotations: { title: "Emulate Device", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     device: z13.string().optional().describe(
       'Device preset name (e.g. "iPhone 15", "Pixel 7"). Omit to list available presets. Pass "reset" to restore desktop defaults.'
@@ -3502,7 +3486,8 @@ var browserEnum = z14.enum(["chrome", "firefox", "edge", "safari"]);
 var automationEnum = z14.enum(["XCUITest", "UiAutomator2"]);
 var startSessionToolDefinition = {
   name: "start_session",
-  description: 'Starts a new browser or mobile automation session. Only one active session at a time \u2014 starting a new one closes the existing one. Use platform "browser" with a browser name, or "ios"/"android" with a deviceName. Use attach mode to connect to an already-running Chrome instance via CDP.',
+  description: 'Starts a browser or mobile automation session. Only one active session at a time \u2014 starting a new one closes the existing session first. Use platform "browser" with a browser name, or "ios"/"android" with deviceName. Set attach: true to connect to a running Chrome via CDP instead of launching a new browser.',
+  annotations: { title: "Start Session", destructiveHint: false },
   inputSchema: {
     provider: z14.enum(["local", "browserstack"]).optional().default("local").describe("Session provider (default: local)"),
     platform: platformEnum.describe("Session platform type"),
@@ -3549,7 +3534,8 @@ var startSessionToolDefinition = {
 };
 var closeSessionToolDefinition = {
   name: "close_session",
-  description: "Closes or detaches from the current session. Detach disconnects without terminating the process, preserving app state on the Appium server. Sessions started with noReset: true auto-detach by default.",
+  description: "Closes the current session or detaches without terminating. Detach preserves app state on the Appium server \u2014 sessions with noReset: true auto-detach by default. Closing a browser attach session terminates chromedriver but the Chrome process spawned by launch_chrome remains running.",
+  annotations: { title: "Close Session", destructiveHint: true },
   inputSchema: {
     detach: coerceBoolean.optional().describe("If true, disconnect without terminating (preserves app state). Default: false")
   }
@@ -3799,7 +3785,8 @@ init_state();
 import { z as z15 } from "zod";
 var switchTabToolDefinition = {
   name: "switch_tab",
-  description: "Focuses a browser tab by window handle or 0-based index. All subsequent tool calls operate on the newly active tab. Get handles from get_tabs tool or wdio://session/current/tabs resource. Browser-only \u2014 use switch_context for mobile webviews.",
+  description: "Focuses a browser tab by window handle or 0-based index. All subsequent tool calls operate on the active tab. Provide handle OR index \u2014 use get_tabs to find them. Browser-only; use switch_context for mobile webviews.",
+  annotations: { title: "Switch Browser Tab", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     handle: z15.string().optional().describe("Window handle to switch to"),
     index: z15.number().int().min(0).optional().describe("0-based tab index to switch to")
@@ -3830,7 +3817,8 @@ init_state();
 import { z as z16 } from "zod";
 var switchFrameToolDefinition = {
   name: "switch_frame",
-  description: "Switches into an iframe by CSS or XPath selector, or back to the top-level frame if no selector is given. Required before interacting with elements inside iframes \u2014 click, set_value, and get_elements only see the current frame context. Browser-only.",
+  description: "Switches WebDriver frame context into an iframe by CSS/XPath selector, or back to top-level if selector is omitted. Changes persist \u2014 all subsequent click_element, set_value, get_elements calls operate within the switched frame until you switch back. Waits up to 5s for the iframe. Browser-only.",
+  annotations: { title: "Switch Frame", destructiveHint: false, idempotentHint: true },
   inputSchema: {
     selector: z16.string().optional().describe(
       "CSS/XPath selector for the iframe element. Omit to switch back to the top-level frame."
@@ -3875,6 +3863,7 @@ function formatAppList(apps) {
 var listAppsToolDefinition = {
   name: "list_apps",
   description: "List apps uploaded to BrowserStack App Automate. Reads BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY from environment.",
+  annotations: { title: "List BrowserStack Apps", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
     sortBy: z17.enum(["app_name", "uploaded_at"]).optional().default("uploaded_at").describe("Sort order for results"),
     organizationWide: coerceBoolean.optional().default(false).describe("List apps uploaded by all users in the organization (uses recent_group_apps endpoint). Defaults to false (own uploads only)."),
@@ -3907,6 +3896,7 @@ var listAppsTool = async ({ sortBy = "uploaded_at", organizationWide = false, li
 var uploadAppToolDefinition = {
   name: "upload_app",
   description: "Upload a local .apk or .ipa to BrowserStack App Automate. Returns a bs:// URL for use in start_session.",
+  annotations: { title: "Upload App to BrowserStack", destructiveHint: false },
   inputSchema: {
     path: z17.string().describe("Absolute path to the .apk or .ipa file"),
     customId: z17.string().optional().describe("Optional custom ID for the app (used to reference it later)")
@@ -3951,6 +3941,7 @@ Use this URL as the "app" parameter in start_session with provider: "browserstac
 var screenshotToolDefinition = {
   name: "get_screenshot",
   description: "Takes a screenshot of the current page or screen and returns a base64-encoded image, resized and compressed for model context limits.",
+  annotations: { title: "Get Screenshot", readOnlyHint: true, idempotentHint: true },
   inputSchema: {}
 };
 var screenshotTool = async () => {
@@ -3966,6 +3957,7 @@ import { z as z18 } from "zod";
 var accessibilityToolDefinition = {
   name: "get_accessibility_tree",
   description: "Returns the page accessibility tree with roles, names, and selectors. Browser-only. Supports filtering by ARIA roles and pagination via limit/offset.",
+  annotations: { title: "Get Accessibility Tree", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
     limit: z18.number().optional().default(0).describe("Maximum number of nodes to return (0 = no limit)"),
     offset: z18.number().optional().default(0).describe("Number of nodes to skip for pagination"),
@@ -3984,6 +3976,7 @@ var accessibilityTool = async ({ limit = 0, offset = 0, roles }) => {
 var getTabsToolDefinition = {
   name: "get_tabs",
   description: "Lists all browser tabs with handle, title, URL, and which is active. Use before switch_tab to find the target handle or index. Browser-only.",
+  annotations: { title: "Get Browser Tabs", readOnlyHint: true, idempotentHint: true },
   inputSchema: {}
 };
 var getTabsTool = async () => {
@@ -3998,6 +3991,7 @@ var getTabsTool = async () => {
 var getContextsToolDefinition = {
   name: "get_contexts",
   description: "Returns available automation contexts and the currently active one. Use before switch_context to discover NATIVE_APP and WEBVIEW_* targets. Mobile-only.",
+  annotations: { title: "Get Automation Contexts", readOnlyHint: true, idempotentHint: true },
   inputSchema: {}
 };
 var getContextsTool = async () => {
@@ -4020,6 +4014,7 @@ import { z as z19 } from "zod";
 var appStateToolDefinition = {
   name: "get_app_state",
   description: "Returns the current state of a mobile app: not installed, not running, background, or foreground. Mobile-only.",
+  annotations: { title: "Get App State", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
     bundleId: z19.string().describe('App bundle ID (iOS) or package name (Android), e.g. "com.example.app"')
   }
@@ -4037,6 +4032,7 @@ import { z as z20 } from "zod";
 var getCookiesToolDefinition = {
   name: "get_cookies",
   description: "Returns all cookies for the current session, or a single cookie by name. Use to verify auth state, session tokens, or feature flags after login flows.",
+  annotations: { title: "Get Cookies", readOnlyHint: true, idempotentHint: true },
   inputSchema: {
     name: z20.string().optional().describe("Cookie name to retrieve a specific cookie. If omitted, returns all cookies.")
   }
@@ -4070,7 +4066,8 @@ function createServer() {
   });
   const registerTool = (definition, callback) => server.registerTool(definition.name, {
     description: definition.description,
-    inputSchema: definition.inputSchema
+    inputSchema: definition.inputSchema,
+    ...definition.annotations && { annotations: definition.annotations }
   }, callback);
   const registerResource = (definition) => {
     if ("uri" in definition) {