chrometools-mcp 3.1.7 → 3.2.6

package/README.md

@@ -1,6 +1,29 @@
 # chrometools-mcp
 
-MCP server for Chrome automation using Puppeteer with persistent browser sessions.
+> 🌐 [Русская версия README](./README.ru.md)
+
+**AI-powered Chrome automation through natural language.** No more fighting with CSS selectors, XPath expressions, or brittle test scripts. Just tell your AI assistant what you want to do on a web page, and ChromeTools MCP makes it happen.
+
+## Why ChromeTools MCP?
+
+**For AI Agents & Developers:**
+- 🎯 **54 specialized tools** for browser automation - from simple clicks to Figma comparisons
+- 🧠 **APOM (Agent Page Object Model)** - AI-friendly page representation (~8-10k tokens vs 15-25k for screenshots)
+- 🔄 **Persistent browser sessions** - pages stay open between commands for iterative workflows
+- ⚡ **Framework-aware** - handles React, Vue, Angular events and state updates automatically
+- 📸 **Visual testing** - compare designs pixel-by-pixel with Figma integration
+- 🎬 **Scenario recording** - record browser actions, replay them, or export as Playwright/Selenium tests
+- 🌍 **Cross-platform** - works seamlessly on Windows, WSL, Linux, and macOS
+
+**Perfect for:**
+- 🤖 Building AI agents that interact with web applications
+- 🧪 Automated testing without writing code - let AI generate tests from scenarios
+- 🔍 Web scraping and data extraction with natural language instructions
+- 🎨 Design validation - compare implemented UI with Figma designs
+- 🚀 Rapid prototyping - test user flows by describing them to AI
+- 📊 Monitoring and health checks for web applications
+
+Stop writing brittle automation scripts. Start describing what you want in plain English.
 
 ## Installation
 
@@ -9,7 +32,7 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 The easiest way to install for Claude Code users:
 
 ```bash
-claude mcp add chrometools -- npx -y chrometools-mcp
+claude mcp add chrometools -- npx chrometools-mcp
 ```
 
 This command will automatically configure the MCP server in your Claude Code settings.
@@ -26,7 +49,7 @@ Add to your Claude Desktop configuration file:
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -47,7 +70,7 @@ Add to your Claude Desktop configuration file:
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -64,7 +87,7 @@ Add to your Claude Desktop configuration file:
     },
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -99,7 +122,7 @@ Add to your Claude Desktop configuration file:
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -118,7 +141,7 @@ For Cline, Continue, or other MCP-compatible clients, add to your MCP configurat
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -129,26 +152,85 @@ For Cline, Continue, or other MCP-compatible clients, add to your MCP configurat
 You can also run directly without configuration:
 
 ```bash
-npx -y chrometools-mcp
+npx chrometools-mcp
 ```
 
+### Chrome Extension Setup
+
+The Chrome Extension is **required** for scenario recording and other advanced features. Follow these steps to install it:
+
+**Important:** ChromeTools opens Chrome with a separate user profile, so you must install the extension **after** ChromeTools starts Chrome for the first time.
+
+**Step 1:** Start ChromeTools MCP server first
+- Make sure ChromeTools is running through your MCP client (Claude Desktop, Cursor, etc.)
+- Or run it manually: `npx chrometools-mcp`
+- This will launch Chrome with ChromeTools' isolated profile
+
+**Step 2:** Enable Developer Mode in Chrome
+- Open Chrome Extensions page: `chrome://extensions`
+- Toggle **Developer mode** (switch in top-right corner)
+
+![Developer Mode Screenshot](docs/extension-developer-mode.png)
+
+**Step 3:** Download and Extract the Extension
+
+**Option A - Download from GitHub (Recommended):**
+1. Download the extension archive: [chrome-extension.zip](https://github.com/docentovich/chrometools-mcp/raw/main/chrome-extension.zip)
+2. Extract the ZIP file to a folder on your computer
+3. Remember the extraction path (you'll need it in the next step)
+
+**Option B - Use from node_modules (if you know the path):**
+- **After npx install:** `~/.npm/_npx/.../node_modules/chrometools-mcp/extension`
+- **After global install:** `<npm-global-path>/node_modules/chrometools-mcp/extension`
+- **From source:** `<repo-path>/extension`
+
+**Step 4:** Load the Extension
+- Click **"Load unpacked"** button
+- Navigate to the extracted extension folder (from Step 3)
+- Select the folder and click **"Select Folder"**
+
+**Step 5:** Verify Installation
+- You should see "ChromeTools MCP" extension appear in your extensions list with:
+  - **Name:** ChromeTools MCP
+  - **Version:** (current version)
+  - **Description:** MCP server integration for Chrome automation
+  - **Status:** Toggle should be ON (blue)
+- Look for the ChromeTools icon (CT) in your Chrome toolbar
+- The extension is now ready to use for scenario recording
+
+![Installed Extension Screenshot](docs/extension-installed.png)
+
+> **Note:** After installation, the extension card will appear on the `chrome://extensions` page alongside other installed extensions. The extension should show as "Enabled" with a blue toggle switch.
+
+**Step 6:** Pin the Extension (Optional but Recommended)
+- Click the puzzle piece icon in Chrome toolbar
+- Find "ChromeTools MCP" in the list
+- Click the pin icon to keep it visible in toolbar
+
+**Troubleshooting:**
+- **Recommended:** Use Option A (download from GitHub) to avoid searching in node_modules
+- If using Option B and can't find the extension folder after `npx` install, run `npm list -g chrometools-mcp` to find the installation path
+- The extension only works with Chrome instances launched by ChromeTools
+- If Chrome closes and reopens, the extension should still be loaded (developer mode persists)
+- When ChromeTools first opens Chrome, it automatically shows a prompt with the extension path in node_modules
+
 ## Table of Contents
 
 - [Installation](#installation)
-- [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
-- [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
+  - [Chrome Extension Setup](#chrome-extension-setup)
+- [AI Optimization Features](#ai-optimization-features)- [Scenario Recorder](#scenario-recorder)  - Visual UI-based recording with smart optimization
 - [Available Tools](#available-tools) - **46+ Tools Total**
-  - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getElementByApomId, getAllInteractiveElements, findElementsByText
+  - [AI-Powered Tools](#ai-powered-tools)  - smartFindElement, analyzePage, getElementDetails, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
   - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - [Tab Management Tools](#5-tab-management-tools) ⭐ **NEW** - listTabs, switchTab
-  - [Recorder Tools](#7-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
+  - [Tab Management Tools](#5-tab-management-tools)  - listTabs, switchTab
+  - [Recorder Tools](#7-recorder-tools)  - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
-- [Multi-Instance Support](#multi-instance-support) ⭐ **NEW** - Run multiple MCP servers simultaneously
+- [Multi-Instance Support](#multi-instance-support)  - Run multiple MCP servers simultaneously
 - [WSL Setup Guide](#wsl-setup-guide) → [Full WSL Guide](WSL_SETUP.md)
 - [Development](#development)
 - [Features](#features)
@@ -156,7 +238,7 @@ npx -y chrometools-mcp
 
 ## AI Optimization Features
 
-⭐ **NEW**: Dramatically reduce AI agent request cycles with intelligent element finding and page analysis.
+: Dramatically reduce AI agent request cycles with intelligent element finding and page analysis.
 
 ### Why This Matters
 
@@ -179,7 +261,7 @@ AI: smartFindElement("login button")
 1. **`analyzePage`** - 🔥 **USE FREQUENTLY** - Get current page state after loads, clicks, submissions (cached, use refresh:true)
 2. **`smartFindElement`** - Natural language element search with multilingual support
 3. **AI Hints** - Automatic context in all tools (page type, available actions, suggestions)
-4. **Batch helpers** - `getAllInteractiveElements`, `findElementsByText`
+4. **Text search** - `findElementsByText` for finding elements by visible text
 
 **Performance:** 3-5x faster, 5-10x fewer requests
 
@@ -192,22 +274,17 @@ AI: smartFindElement("login button")
 
 ## Scenario Recorder
 
-⭐ **NEW**: Visual UI-based recorder for creating reusable test scenarios with automatic secret detection.
+: Visual UI-based recorder for creating reusable test scenarios with automatic secret detection.
 
 ### Features
 
 - **Visual Widget** - Floating recorder UI with compact mode (50x50px minimize button)
-- **Auto-Reinjection** - Recorder persists across page reloads/navigation automatically with duplicate prevention ⭐ **IMPROVED**
-- **Smart Click Detection** - Finds actual clickable parent elements with event listeners ⭐ **NEW**
-- **Smart Waiters** - 2s minimum + animation/network/DOM change detection after clicks ⭐ **NEW**
-- **Detailed Error Reports** - Comprehensive failure analysis with context and suggestions ⭐ **NEW**
-- **Smart Recording** - Captures clicks, typing, navigation with intelligent optimization
+- **Auto-Reinjection** - Recorder persists across page reloads/navigation automatically with duplicate prevention - **Smart Click Detection** - Finds actual clickable parent elements with event listeners- **Smart Waiters** - 2s minimum + animation/network/DOM change detection after clicks- **Detailed Error Reports** - Comprehensive failure analysis with context and suggestions- **Smart Recording** - Captures clicks, typing, navigation with intelligent optimization
 - **Secret Detection** - Auto-detects passwords/emails and stores them securely
 - **Action Optimization** - Combines sequential actions, removes duplicates
 - **Scenario Management** - Save, load, execute, search, and delete scenarios
 - **Dependencies** - Chain scenarios together with dependency resolution
-- **Multi-Instance Protection** - Prevents multiple recorder instances from interfering ⭐ **NEW**
-
+- **Multi-Instance Protection** - Prevents multiple recorder instances from interfering
 ### Quick Start
 
 ```javascript
@@ -258,8 +335,7 @@ executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })
 
 ### AI-Powered Tools
 
-#### smartFindElement ⭐
-Find elements using natural language descriptions instead of CSS selectors.
+#### smartFindElementFind elements using natural language descriptions instead of CSS selectors.
 - **Parameters**:
   - `description` (required): Natural language (e.g., "login button", "email field")
   - `maxResults` (optional): Max candidates to return (default: 5)
@@ -283,9 +359,22 @@ Find elements using natural language descriptions instead of CSS selectors.
   }
   ```
 
-#### analyzePage ⭐ **USE FREQUENTLY**
-Get current page state and structure. Returns complete map of forms (with values), inputs, buttons, links with selectors.
-- **When to use**:
+#### analyzePage Get current page state and structure. Returns complete map of forms (with values), inputs, buttons, links with selectors.
+
+**Interactivity Detection**:
+- Detects interactive elements via **8 different methods**:
+  1. Native HTML tags (`button`, `a`, `input`, `select`, `textarea`)
+  2. ARIA roles (`button`, `link`, `checkbox`, etc.)
+  3. `onclick` attribute
+  4. `onclick` property (set via JavaScript)
+  5. CSS `cursor: pointer`
+  6. JavaScript `addEventListener('click')`
+  7. `tabindex` attribute (except -1)
+  8. `contenteditable="true"`
+- **Captures DIV/SPAN with click handlers** - JavaScript-enabled elements are detected
+- Adds `interactivityReason` metadata showing detection method (e.g., `cursor-pointer`, `event-listener`)
+
+**When to use**:
   - After opening/navigating to page (initial analysis)
   - **After clicking buttons** (see what changed)
   - **After form submissions** (check results, errors)
@@ -295,18 +384,13 @@ Get current page state and structure. Returns complete map of forms (with values
 - **Parameters**:
   - `refresh` (optional): Force refresh cache to get CURRENT state after changes (default: false)
   - `includeAll` (optional): Include ALL page elements, not just interactive ones (default: false). Useful for layout work - find any element, get its selector, then use `getComputedCss` or `setStyles` on it.
-  - `useLegacyFormat` (optional): Return legacy format instead of APOM (default: false - **APOM is now the default**) 🔄 **BREAKING CHANGE**
-  - `registerElements` (optional): Auto-register elements for ID-based usage (default: true) ⭐ **APOM**
-  - `groupBy` (optional): 'type' or 'flat' - how to group elements (default: 'type') ⭐ **APOM**
-- **Why better than screenshot**:
+  - `useLegacyFormat` (optional): Return legacy format instead of APOM (default: false - APOM is the default)
+  - `registerElements` (optional): Auto-register elements for ID-based usage (default: true)   - `groupBy` (optional): 'type' or 'flat' - how to group elements (default: 'type') - **Why better than screenshot**:
   - Shows actual data (form values, validation errors) not just visual
   - Uses 2-5k tokens vs screenshot 15-25k tokens
   - Returns structured data with **unique element IDs** for easy interaction
-  - **Detects UI frameworks** (MUI, Ant Design, Chakra, Bootstrap, Vuetify, Semantic UI) ⭐
-  - **Extracts dropdown options** from both native `<select>` and custom UI components ⭐
-- **Returns**:
-  - **APOM format** (default): Tree-structured Page Object Model with unique IDs ⭐ **NOW DEFAULT**
-    - `tree` - Hierarchical tree of page elements (optimized: ~82% smaller than flat format)
+  - **Detects UI frameworks** (MUI, Ant Design, Chakra, Bootstrap, Vuetify, Semantic UI)  - **Extracts dropdown options** from both native `<select>` and custom UI components- **Returns**:
+  - **APOM format** (default): Tree-structured Page Object Model with unique IDs     - `tree` - Hierarchical tree of page elements (optimized: ~82% smaller than flat format)
       - Each node: `{ tag, id?, type?, sel, ch?, bounds?, meta? }`
       - Interactive elements have `bounds` and full metadata
       - Parent containers have minimal info (position only)
@@ -315,12 +399,10 @@ Get current page state and structure. Returns complete map of forms (with values
     - Elements automatically registered - use IDs with `click({ id: "..." })`, `type({ id: "..." })`, etc.
     - **Token-optimized**: Minified JSON, simplified parents, no redundant data
     - Example: `analyzePage()` returns APOM, then use `click({ id: "button_45" })` or `type({ id: "input_20", text: "..." })`
-  - **Use `getElementByApomId({ id: "input_20" })`** to get full details for any element
+  - **Use `getElementDetails({ id: "input_20" })`** to get full details for any element, or with `analyzeChildren: true` to get children tree structure
   - **Legacy format** (`useLegacyFormat: true`): Classic format for backward compatibility
     - Complete map of forms (with current values), inputs, buttons, links, navigation with selectors
-    - **Each element includes `uiFramework` info** (name, version, component type) ⭐
-    - **Select elements include `options` array** with value, text, index, selected, disabled, group ⭐
-    - With `includeAll: true`: Also includes `allElements` array with ALL visible page elements (divs, spans, headings, etc.) - each with selector, tag, text, classes, id
+    - **Each element includes `uiFramework` info** (name, version, component type)    - **Select elements include `options` array** with value, text, index, selected, disabled, group    - With `includeAll: true`: Also includes `allElements` array with ALL visible page elements (divs, spans, headings, etc.) - each with selector, tag, text, classes, id
 - **Example workflow**:
   1. `openBrowser({ url: "..." })`
   2. `analyzePage()` ← Initial analysis, returns elements with IDs
@@ -333,26 +415,31 @@ Get current page state and structure. Returns complete map of forms (with values
   3. `getComputedCss({ selector: "div.header" })` ← Get current styles
   4. `setStyles({ selector: "div.header", styles: [...] })` ← Apply new styles
 
-#### getElementByApomId ⭐ **NEW**
-Get detailed information about a specific element by its APOM ID from `analyzePage`. Use this to inspect elements without re-analyzing the entire page.
+#### getElementDetailsGet comprehensive details about a specific element by its APOM ID. Can optionally analyze children elements tree structure. Use when `analyzePage` output is simplified and you need complete element information or want to focus analysis on a specific section.
 - **Parameters**:
   - `id` (required): APOM element ID (e.g., `"input_20"`, `"button_45"`)
-- **Use case**: Get full details for a specific element (bounds, attributes, computed styles)
-- **Returns**: Element details including:
+  - `analyzeChildren` (optional): Analyze children elements tree structure (default: false)
+  - `includeAll` (optional): When analyzing children, include all elements, not just interactive ones (default: false)
+  - `refresh` (optional): Force refresh of cached analysis (default: false)
+- **Use case**:
+  - Get full details including bounds, CSS selector, attributes, computed styles
+  - Focus analysis on specific section (modal, form, sidebar, etc.) with `analyzeChildren: true`
+- **Returns**: Complete element details including:
   - `id`: Element APOM ID
-  - `selector`: CSS selector
+  - `selector`: CSS selector for the element
   - `tag`: HTML tag name
-  - `type`: Input type (for inputs)
+  - `type`: Element type (input, button, link, etc.)
   - `text`: Visible text content
-  - `bounds`: `{ x, y, width, height }` position and size
-  - `attributes`: All HTML attributes
-  - `computedStyles`: Key CSS properties (display, visibility, color, background, etc.)
-  - `isVisible`: Whether element is visible
-  - `isEnabled`: Whether element is enabled (not disabled)
+  - `bounds`: Position and size `{ x, y, width, height, top, right, bottom, left }`
+  - `attributes`: All HTML attributes (id, class, name, placeholder, href, etc.)
+  - `computed`: Key CSS properties (display, visibility, cursor, color, fontSize, etc.)
+  - `metadata`: Element metadata from APOM analysis
+  - `visible`: Whether element is visible
+  - `childrenTree` (optional): APOM tree structure of children elements when `analyzeChildren: true`
 - **Example**:
   ```javascript
-  // Get details for specific input field
-  getElementByApomId({ id: "input_20" })
+  // Get complete details for specific input field
+  getElementDetails({ id: "input_20" })
 
   // Returns:
   {
@@ -362,19 +449,17 @@ Get detailed information about a specific element by its APOM ID from `analyzePa
     "tag": "input",
     "type": "email",
     "text": "",
-    "bounds": { "x": 100, "y": 200, "width": 300, "height": 40 },
-    "attributes": { "name": "email", "placeholder": "Enter email" },
-    "computedStyles": { "display": "block", "visibility": "visible" },
-    "isVisible": true,
-    "isEnabled": true
+    "bounds": { "x": 100, "y": 200, "width": 300, "height": 40, "top": 200, "right": 400, "bottom": 240, "left": 100 },
+    "attributes": { "name": "email", "placeholder": "Enter email", "type": "email" },
+    "computed": { "display": "block", "visibility": "visible", "cursor": "text" },
+    "visible": true
   }
-  ```
 
-#### getAllInteractiveElements
-Get all clickable/fillable elements with their selectors.
-- **Parameters**:
-  - `includeHidden` (optional): Include hidden elements (default: false)
-- **Returns**: Array of all interactive elements with selectors and metadata
+  // Analyze modal contents after opening it
+  analyzePage() // Get initial page structure
+  click({ id: "button_45" }) // Open modal
+  getElementDetails({ id: "container_123", analyzeChildren: true, refresh: true }) // Analyze modal contents with children tree
+  ```
 
 #### findElementsByText
 Find elements by their visible text content.
@@ -471,8 +556,7 @@ Select option in dropdown (HTML select elements). **PREFERRED**: Use APOM ID fro
   selectOption({ selector: "select[name='country']", text: "United States" })
   ```
 
-#### selectFromGroup ⭐ **NEW**
-Select option(s) from radio or checkbox group by name attribute. Works at abstract group level instead of individual clicks.
+#### selectFromGroupSelect option(s) from radio or checkbox group by name attribute. Works at abstract group level instead of individual clicks.
 - **Parameters**:
   - `name` (required): Name attribute of the radio/checkbox group (e.g., 'size', 'toppings')
   - `value` (optional): Single value to select (for radio or single checkbox)
@@ -695,8 +779,7 @@ Navigate to different URL while keeping browser instance.
 - **Use case**: Moving between pages in workflow
 - **Returns**: New page title
 
-### 5. Tab Management Tools ⭐ NEW
-
+### 5. Tab Management Tools 
 Tools for managing multiple browser tabs. New tabs opened via `window.open()`, `target="_blank"`, or user actions are automatically detected and tracked.
 
 #### listTabs
@@ -737,12 +820,10 @@ switchTab({ tab: 0 })
 switchTab({ tab: "google.com" })
 ```
 
-### 6. Figma Tools ⭐ ENHANCED
-
+### 6. Figma Tools 
 Design-to-code validation, file browsing, design system extraction, and comparison tools with automatic 3 MB compression.
 
-#### parseFigmaUrl ⭐ NEW
-Parse Figma URL to extract fileKey and nodeId automatically.
+#### parseFigmaUrl Parse Figma URL to extract fileKey and nodeId automatically.
 - **Parameters**:
   - `url` (required): Full Figma URL or just fileKey
 - **Supported formats**:
@@ -752,8 +833,7 @@ Parse Figma URL to extract fileKey and nodeId automatically.
 - **Use case**: No need to manually extract fileKey and nodeId from URLs
 - **Returns**: `{ fileKey, nodeId }` object
 
-#### listFigmaPages ⭐ NEW
-Browse entire Figma file structure: all pages and frames with IDs.
+#### listFigmaPages Browse entire Figma file structure: all pages and frames with IDs.
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key or full URL
@@ -779,8 +859,7 @@ Browse entire Figma file structure: all pages and frames with IDs.
   }
   ```
 
-#### searchFigmaFrames ⭐ NEW
-Search frames/components by name across entire Figma file.
+#### searchFigmaFrames Search frames/components by name across entire Figma file.
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key or full URL
@@ -789,16 +868,14 @@ Search frames/components by name across entire Figma file.
 - **Returns**: All matching nodes with IDs, names, types, pages, dimensions
 - **Example**: Search for "login" returns all frames containing "login" in name
 
-#### getFigmaComponents ⭐ NEW
-Extract all components from Figma file (Design System).
+#### getFigmaComponents Extract all components from Figma file (Design System).
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key or full URL
 - **Use case**: Get complete list of design system components
 - **Returns**: All COMPONENT and COMPONENT_SET nodes with names, descriptions, dimensions
 
-#### getFigmaStyles ⭐ NEW
-Get all shared styles from Figma file (color, text, effect, grid styles).
+#### getFigmaStyles Get all shared styles from Figma file (color, text, effect, grid styles).
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key or full URL
@@ -809,8 +886,7 @@ Get all shared styles from Figma file (color, text, effect, grid styles).
   - Effect styles (shadows, blur)
   - Grid styles
 
-#### getFigmaColorPalette ⭐ NEW
-Extract complete color palette with usage statistics.
+#### getFigmaColorPalette Extract complete color palette with usage statistics.
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key or full URL
@@ -821,8 +897,7 @@ Extract complete color palette with usage statistics.
   - Usage examples (where the color is used)
   - Sorted by usage frequency
 
-#### convertFigmaToCode ⭐ NEW
-Convert Figma designs to React/Tailwind code with AI assistance.
+#### convertFigmaToCode Convert Figma designs to React/Tailwind code with AI assistance.
 - **Parameters**:
   - `figmaToken` (optional): Figma API token
   - `fileKey` (required): Figma file key
@@ -883,9 +958,8 @@ Extract detailed design specifications from Figma including text content, colors
   - **Dimensions**: Width, height, x, y coordinates
   - **Children**: Recursive tree with text extraction from all child elements
 
-### 7. Recorder Tools ⭐ NEW
-
-**URL-Based Storage (v2.1+)**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
+### 7. Recorder Tools 
+**URL-Based Storage**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
 
 **Automatic Domain Detection**: Project ID is extracted from the URL where recording starts:
 - `https://www.google.com` → `google`
@@ -1028,8 +1102,7 @@ Delete a scenario and its associated secrets. Searches all projects to find the
 - **Use case**: Clean up unused scenarios
 - **Returns**: Success confirmation
 
-#### exportScenarioAsCode ⭐ **NEW**
-Export recorded scenario as executable test code for creating a **NEW** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to **EXISTING** files, use `appendScenarioToFile` instead.
+#### exportScenarioAsCodeExport recorded scenario as executable test code for creating a **NEW** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to **EXISTING** files, use `appendScenarioToFile` instead.
 
 - **Parameters**:
   - `scenarioName` (required): Name of scenario to export
@@ -1097,7 +1170,7 @@ Export recorded scenario as executable test code for creating a **NEW** test fil
   - Hash suffixes: `component_a1b2c3d` → removed
   - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
 
-#### appendScenarioToFile ⭐ **NEW v2.3.0**
+#### appendScenarioToFile
 Append recorded scenario as test code to an **EXISTING** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with test code (without imports) - Claude Code will read the file, append the test, and write back. To create **NEW** test files, use `exportScenarioAsCode` instead.
 
 - **Parameters**:
@@ -1189,8 +1262,7 @@ Append recorded scenario as test code to an **EXISTING** test file. Automaticall
   }
   ```
 
-#### generatePageObject ⭐ **NEW**
-Generate Page Object Model (POM) class from current page structure. Analyzes page, extracts interactive elements, and generates framework-specific code with smart naming and helper methods.
+#### generatePageObjectGenerate Page Object Model (POM) class from current page structure. Analyzes page, extracts interactive elements, and generates framework-specific code with smart naming and helper methods.
 
 - **Parameters**:
   - `className` (optional): Page Object class name (auto-generated from page title/URL if not provided)
@@ -1303,7 +1375,7 @@ Add the MCP server to your MCP client configuration file:
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"]
+      "args": ["chrometools-mcp"]
     }
   }
 }
@@ -1317,7 +1389,7 @@ Add the MCP server to your MCP client configuration file:
     "chrometools": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"],
+      "args": ["chrometools-mcp"],
       "env": {}
     }
   }
@@ -1361,7 +1433,7 @@ By default, all tools are enabled. You can selectively enable only specific tool
 
 **Why filter tools?**
 
-Each tool definition is sent to the AI in every request, consuming context tokens. All 43 tools consume ~28k tokens (~14% of context window). By enabling only the groups you need, you can significantly reduce token usage:
+Each tool definition is sent to the AI in every request, consuming context tokens. Filtering tools can reduce token usage, improve focus, and lower API costs:
 
 - **Save tokens:** Fewer tools = less context consumed per request
 - **Reduce costs:** Lower token usage means lower API costs
@@ -1374,13 +1446,13 @@ Each tool definition is sent to the AI in every request, consuming context token
 |-------|-------------|---------------|
 | `core` | Basic tools | `ping`, `openBrowser` (2) |
 | `interaction` | User interaction | `click`, `type`, `scrollTo`, `waitForElement`, `hover` (5) |
-| `inspection` | Page inspection | `getElement`, `getComputedCss`, `getBoxModel`, `screenshot`, `saveScreenshot` (5) |
+| `inspection` | Page inspection | `getComputedCss`, `getBoxModel`, `screenshot`, `saveScreenshot` (4) |
 | `debug` | Debugging & network | `getConsoleLogs`, `listNetworkRequests`, `getNetworkRequest`, `filterNetworkRequests` (4) |
-| `advanced` | Advanced automation & AI | `executeScript`, `setStyles`, `setViewport`, `getViewport`, `navigateTo`, `smartFindElement`, `analyzePage`, `getAllInteractiveElements`, `findElementsByText` (9) |
+| `advanced` | Advanced automation & AI | `executeScript`, `setStyles`, `setViewport`, `getViewport`, `navigateTo`, `smartFindElement`, `analyzePage`, `findElementsByText` (8) |
 | `recorder` | Scenario recording | `enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`, `appendScenarioToFile`, `generatePageObject` (9) |
 | `figma` | Figma integration | `getFigmaFrame`, `compareFigmaToElement`, `getFigmaSpecs`, `parseFigmaUrl`, `listFigmaPages`, `searchFigmaFrames`, `getFigmaComponents`, `getFigmaStyles`, `getFigmaColorPalette`, `convertFigmaToCode` (10) |
 
-**Total:** 44 tools across 7 groups
+**Total:** 42 tools across 7 groups
 
 **Configuration:**
 
@@ -1391,7 +1463,7 @@ Each tool definition is sent to the AI in every request, consuming context token
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"],
+      "args": ["chrometools-mcp"],
       "env": {
         "ENABLED_TOOLS": "core,interaction,inspection"
       }
@@ -1408,7 +1480,7 @@ Each tool definition is sent to the AI in every request, consuming context token
     "chrometools": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"],
+      "args": ["chrometools-mcp"],
       "env": {
         "ENABLED_TOOLS": "core,interaction,advanced"
       }
@@ -1475,7 +1547,7 @@ To use Figma tools, you need to configure your Figma Personal Access Token.
   "mcpServers": {
     "chrometools": {
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"],
+      "args": ["chrometools-mcp"],
       "env": {
         "FIGMA_TOKEN": "your-figma-token-here"
       }
@@ -1492,7 +1564,7 @@ To use Figma tools, you need to configure your Figma Personal Access Token.
     "chrometools": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "chrometools-mcp"],
+      "args": ["chrometools-mcp"],
       "env": {
         "FIGMA_TOKEN": "your-figma-token-here"
       }
@@ -1543,30 +1615,24 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Features
 
-- **44+ Powerful Tools**: Complete toolkit for browser automation
+- **48+ Powerful Tools**: Complete toolkit for browser automation
   - Core: ping, openBrowser
   - Interaction: click, type, scrollTo, selectOption, selectFromGroup, drag, scrollHorizontal
   - Inspection: getElement, getComputedCss, getBoxModel, screenshot, saveScreenshot
   - Advanced: executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo, waitForElement
-  - AI-Powered: smartFindElement, analyzePage, getElementByApomId, getAllInteractiveElements, findElementsByText ⭐ **NEW**
-  - Recorder: enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
+  - AI-Powered: smartFindElement, analyzePage, getElementDetails (with children analysis), findElementsByText  - Recorder: enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
   - Figma: getFigmaFrame, compareFigmaToElement, getFigmaSpecs, parseFigmaUrl, listFigmaPages, searchFigmaFrames, getFigmaComponents, getFigmaStyles, getFigmaColorPalette, convertFigmaToCode
-- **UI Framework Detection**: Automatic detection of MUI, Ant Design, Chakra UI, Bootstrap, Vuetify, Semantic UI ⭐ **NEW**
-- **Smart Dropdown Handling**: Extracts options from both native `<select>` and custom UI framework components ⭐ **NEW**
-- **APOM (Agent Page Object Model)**: Automatic element ID assignment for reliable interaction ⭐ **NEW**
-  - `analyzePage()` returns elements with unique IDs (e.g., `input_20`, `button_45`)
+- **UI Framework Detection**: Automatic detection of MUI, Ant Design, Chakra UI, Bootstrap, Vuetify, Semantic UI- **Smart Dropdown Handling**: Extracts options from both native `<select>` and custom UI framework components- **APOM (Agent Page Object Model)**: Automatic element ID assignment for reliable interaction  - `analyzePage()` returns elements with unique IDs (e.g., `input_20`, `button_45`)
   - Use `id` parameter in click/type/hover/selectOption for stable targeting
-  - Use `getElementByApomId()` to get detailed element info
+  - Use `getElementDetails()` to get detailed element info
 - **Console Log Capture**: Automatic JavaScript console monitoring
 - **Network Request Monitoring**: Track all HTTP/API requests (XHR, Fetch, etc.)
 - **Persistent Browser Sessions**: Browser tabs remain open between requests
-- **Multi-Instance Support**: Run multiple MCP servers simultaneously with automatic discovery ⭐ **NEW**
-  - Dynamic port allocation (9223-9227)
+- **Multi-Instance Support**: Run multiple MCP servers simultaneously with automatic discovery  - Dynamic port allocation (9223-9227)
   - Chrome Extension port scanning every 20s
   - Broadcast pattern for parallel AI clients
   - Graceful handling of ungraceful shutdowns
-- **Auto-Sync Active Tab**: MCP server automatically syncs to user's currently active tab ⭐ **NEW**
-- **Visual Browser (GUI Mode)**: See automation in real-time
+- **Auto-Sync Active Tab**: MCP server automatically syncs to user's currently active tab- **Visual Browser (GUI Mode)**: See automation in real-time
 - **Cross-platform**: Works on Windows/WSL, Linux, macOS
 - **Simple Installation**: One command with npx
 - **CDP Integration**: Uses Chrome DevTools Protocol for precision
@@ -1575,7 +1641,7 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Multi-Instance Support
 
-⭐ **NEW**: Run up to 8 MCP servers simultaneously, connecting/disconnecting at any time without coordination.
+: Run up to 8 MCP servers simultaneously, connecting/disconnecting at any time without coordination.
 
 ### Overview