chrometools-mcp 3.1.7 → 3.2.6

package/server/tool-definitions.js

@@ -28,7 +28,7 @@ export const toolDefinitions = [
       },
       {
         name: "click",
-        description: "PRIMARY tool for clicking elements. PREFERRED: Use APOM ID (e.g., id: 'button_45') from analyzePage for reliable element targeting. ALTERNATIVE: CSS selector for ad-hoc usage. Works correctly with React/Vue/Angular synthetic events. DO NOT use executeScript for clicks - use this tool instead. Waits for animations and navigation.",
+        description: "Click element by APOM ID (preferred) or CSS selector. Handles React/Vue/Angular events, waits for navigation.",
         inputSchema: {
           type: "object",
           properties: {
@@ -42,29 +42,19 @@ export const toolDefinitions = [
       },
       {
         name: "type",
-        description: "PRIMARY tool for filling input fields. PREFERRED: Use APOM ID (e.g., id: 'input_20') from analyzePage for reliable element targeting. ALTERNATIVE: CSS selector for ad-hoc usage. Works correctly with React/Vue/Angular state management. DO NOT use executeScript for typing - use this tool instead. Automatically updates framework state (React hooks, Vue reactive data).",
+        description: "Type text into input by APOM ID (preferred) or CSS selector. Updates React/Vue/Angular state automatically.",
         inputSchema: {
           type: "object",
           properties: {
             id: { type: "string", description: "APOM element ID from analyzePage (e.g., 'input_20'). Either id or selector required." },
             selector: { type: "string", description: "CSS selector (e.g., '#email'). Either id or selector required." },
             text: { type: "string", description: "Text to type" },
-            delay: { type: "number", description: "Keystroke delay ms (default: 0)" },
+            delay: { type: "number", description: "Keystroke delay ms (default: 30)" },
             clearFirst: { type: "boolean", description: "Clear first (default: true)" },
           },
           required: ["text"],
         },
       },
-      {
-        name: "getElement",
-        description: "Get HTML markup of element. Prefer analyzePage for better efficiency.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            selector: { type: "string", description: "CSS selector (default: body)" },
-          },
-        },
-      },
       {
         name: "getComputedCss",
         description: "Get computed CSS styles for element. For layout debugging and responsive design.",
@@ -102,7 +92,7 @@ export const toolDefinitions = [
       },
       {
         name: "screenshot",
-        description: "Capture element image (15-25k tokens). For visual comparison. Use analyzePage for form data/validation (2-5k tokens).",
+        description: "Capture element image (15-25k tokens). Use analyzePage for form data/validation (8-10k tokens).",
         inputSchema: {
           type: "object",
           properties: {
@@ -223,7 +213,7 @@ export const toolDefinitions = [
       },
       {
         name: "hover",
-        description: "Hover over element. PREFERRED: Use APOM ID from analyzePage. ALTERNATIVE: CSS selector. For testing hover effects, tooltips, and CSS :hover states.",
+        description: "Hover over element by APOM ID or CSS selector. For hover effects, tooltips, :hover states.",
         inputSchema: {
           type: "object",
           properties: {
@@ -234,7 +224,7 @@ export const toolDefinitions = [
       },
       {
         name: "selectOption",
-        description: "Select option in dropdown. PREFERRED: Use APOM ID from analyzePage. ALTERNATIVE: CSS selector. Works with HTML select elements. Specify value, text, or index to choose option.",
+        description: "Select dropdown option by APOM ID or CSS selector. Specify value, text, or index.",
         inputSchema: {
           type: "object",
           properties: {
@@ -248,7 +238,7 @@ export const toolDefinitions = [
       },
       {
         name: "drag",
-        description: "Drag element by mouse (click-hold-move-release). Simulates real mouse drag in any direction. Works with interactive maps, Gantt charts, SVG diagrams, canvas, sliders. Does NOT work with standard overflow scrollbars - use scrollTo/scrollHorizontal instead.",
+        description: "Drag element in any direction. For maps, charts, SVG, canvas, sliders. Use scrollHorizontal for scrollbars.",
         inputSchema: {
           type: "object",
           properties: {
@@ -262,7 +252,7 @@ export const toolDefinitions = [
       },
       {
         name: "scrollHorizontal",
-        description: "Scroll element horizontally. For tables, carousels, and horizontally scrollable containers. Can scroll by pixels or to the end.",
+        description: "Scroll element horizontally by pixels or to end. For tables, carousels, scrollable containers.",
         inputSchema: {
           type: "object",
           properties: {
@@ -487,12 +477,12 @@ export const toolDefinitions = [
       },
       {
         name: "analyzePage",
-        description: "PRIMARY tool for reading page state. Returns APOM (Agent Page Object Model) format by default with unique element IDs. Use element IDs with click/type tools instead of CSS selectors. Use refresh:true after clicks/submissions to see updated state. Efficient: 2-5k tokens vs screenshot 15-25k. Set useLegacyFormat:true for old format.",
+        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k.",
         inputSchema: {
           type: "object",
           properties: {
             refresh: { type: "boolean", description: "Refresh cache (default: false)" },
-            includeAll: { type: "boolean", description: "Include all elements on page, not just interactive ones (default: false)" },
+            includeAll: { type: "boolean", description: "Include all elements with selectors - full debug format (default: false for compact format)" },
             useLegacyFormat: { type: "boolean", description: "Return legacy format instead of APOM (default: false - APOM is now default)" },
             registerElements: { type: "boolean", description: "Auto-register elements in selector resolver (default: true)" },
             groupBy: { type: "string", description: "Group elements: 'type' or 'flat' (default: 'type')", enum: ["type", "flat"] },
@@ -500,26 +490,19 @@ export const toolDefinitions = [
         },
       },
       {
-        name: "getElementByApomId",
-        description: "Get detailed information about element by its APOM ID from analyzePage. Returns full element details including bounds, position, attributes, computed styles. Use this to inspect specific elements without re-analyzing entire page.",
+        name: "getElementDetails",
+        description: "Get detailed information about element by its APOM ID. Returns full element details including bounds, CSS selector, position, attributes, and computed styles. Can also analyze children elements tree structure. Use this when analyzePage output was simplified and you need complete information about specific element or analyze specific sections in detail.",
         inputSchema: {
           type: "object",
           properties: {
             id: { type: "string", description: "APOM element ID (e.g., 'input_20', 'button_45') from analyzePage result" },
+            analyzeChildren: { type: "boolean", description: "Analyze children elements tree structure (default: false)" },
+            includeAll: { type: "boolean", description: "When analyzing children, include all elements, not just interactive ones (default: false)" },
+            refresh: { type: "boolean", description: "Force refresh of cached analysis (default: false)" },
           },
           required: ["id"],
         },
       },
-      {
-        name: "getAllInteractiveElements",
-        description: "Get all interactive elements with selectors. For understanding available actions.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            includeHidden: { type: "boolean", description: "Include hidden (default: false)" },
-          },
-        },
-      },
       {
         name: "findElementsByText",
         description: "Find elements by visible text content and get their selectors. Use this INSTEAD of executeScript when you need to find elements. Returns working selectors that can be used with click/type tools. Can optionally perform actions directly.",
@@ -564,7 +547,7 @@ export const toolDefinitions = [
       },
       {
         name: "enableRecorder",
-        description: "Check ChromeTools Extension connection status for scenario recording. Recording is now handled via Chrome Extension popup (click CT icon in Chrome toolbar). Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/.",
+        description: "Check ChromeTools Extension connection for scenario recording. Use Chrome Extension popup (CT icon) for recording.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -572,7 +555,7 @@ export const toolDefinitions = [
       },
       {
         name: "startRecording",
-        description: "Start recording user actions into a scenario. Recording follows the active tab automatically. Use stopRecording to finish and save the scenario.",
+        description: "Start recording user actions. Follows active tab automatically. Use stopRecording to finish.",
         inputSchema: {
           type: "object",
           properties: {
@@ -641,7 +624,7 @@ export const toolDefinitions = [
       },
       {
         name: "executeScenario",
-        description: "Execute recorded scenario by name. Runs actions with dependency resolution. Scenarios are organized by domain in ~/.config/chrometools-mcp/projects/{domain}/scenarios/. If multiple scenarios have the same name across different domains, specify projectId to disambiguate.",
+        description: "Execute scenario by name with dependency resolution. Use projectId to disambiguate duplicate names.",
         inputSchema: {
           type: "object",
           properties: {
@@ -655,7 +638,7 @@ export const toolDefinitions = [
       },
       {
         name: "listScenarios",
-        description: "List all scenarios with metadata. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "List all scenarios with metadata.",
         inputSchema: {
           type: "object",
           properties: {
@@ -665,7 +648,7 @@ export const toolDefinitions = [
       },
       {
         name: "searchScenarios",
-        description: "Search scenarios by text or tags. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Search scenarios by text or tags.",
         inputSchema: {
           type: "object",
           properties: {
@@ -677,7 +660,7 @@ export const toolDefinitions = [
       },
       {
         name: "getScenarioInfo",
-        description: "Get scenario details: actions, parameters, dependencies. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Get scenario details: actions, parameters, dependencies.",
         inputSchema: {
           type: "object",
           properties: {
@@ -689,7 +672,7 @@ export const toolDefinitions = [
       },
       {
         name: "deleteScenario",
-        description: "Delete scenario and secrets. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Delete scenario and secrets.",
         inputSchema: {
           type: "object",
           properties: {
@@ -700,7 +683,7 @@ export const toolDefinitions = [
       },
       {
         name: "exportScenarioAsCode",
-        description: "Export recorded scenario as executable test code for creating a NEW test file. Automatically cleans unstable selectors (CSS modules, styled-components). 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. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Export scenario as test code for NEW file. Cleans unstable selectors, optionally generates Page Object. Use appendScenarioToFile for existing files.",
         inputSchema: {
           type: "object",
           properties: {
@@ -735,7 +718,7 @@ export const toolDefinitions = [
       },
       {
         name: "appendScenarioToFile",
-        description: "Append recorded scenario as test code to an EXISTING test file. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class. Returns JSON with test code and target file - Claude Code will append to the file without overwriting existing tests. To create NEW test files, use 'exportScenarioAsCode' instead. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Append scenario as test code to EXISTING file. Cleans unstable selectors, optionally generates Page Object. Use exportScenarioAsCode for new files.",
         inputSchema: {
           type: "object",
           properties: {

package/server/tool-groups.js

@@ -24,7 +24,6 @@ export const toolGroups = {
     'getViewport',
     'smartFindElement',
     'analyzePage',
-    'getAllInteractiveElements',
     'findElementsByText'
   ],
 

package/server/tool-schemas.js

@@ -29,16 +29,12 @@ export const TypeSchema = z.object({
   id: z.string().optional().describe("APOM element ID from analyzePage (e.g., 'input_20', 'input_33'). Mutually exclusive with selector."),
   selector: z.string().optional().describe("CSS selector for input element. Mutually exclusive with id."),
   text: z.string().describe("Text to type"),
-  delay: z.number().optional().describe("Delay between keystrokes in ms (default: 0)"),
+  delay: z.number().optional().describe("Delay between keystrokes in ms (default: 30)"),
   clearFirst: z.boolean().optional().describe("Clear field before typing (default: true)"),
 }).refine(data => (data.id && !data.selector) || (!data.id && data.selector), {
   message: "Either 'id' or 'selector' must be provided, but not both"
 });
 
-export const GetElementSchema = z.object({
-  selector: z.string().optional().describe("CSS selector (optional, defaults to body)"),
-});
-
 export const HoverSchema = z.object({
   id: z.string().optional().describe("APOM element ID from analyzePage. Mutually exclusive with selector."),
   selector: z.string().optional().describe("CSS selector for element to hover. Mutually exclusive with id."),
@@ -260,18 +256,17 @@ export const SmartFindElementSchema = z.object({
 
 export const AnalyzePageSchema = z.object({
   refresh: z.boolean().optional().describe("Force refresh of cached analysis (default: false)"),
-  includeAll: z.boolean().optional().describe("Include all elements on page, not just interactive ones (default: false). Useful for layout work and finding non-interactive elements to style."),
+  includeAll: z.boolean().optional().describe("Include all elements on page, not just interactive ones (default: false). When false (default), returns compact format: containers as \"tag_id\":[children], interactive elements without selectors. When true, returns full format with selectors for debugging."),
   useLegacyFormat: z.boolean().optional().describe("Return legacy format instead of APOM (default: false - APOM is now the default format)"),
   registerElements: z.boolean().optional().describe("Automatically register elements in selector resolver (default: true)"),
   groupBy: z.enum(['type', 'flat']).optional().describe("Group elements by type or return flat structure (default: 'type')"),
 });
 
-export const GetElementByApomIdSchema = z.object({
+export const GetElementDetailsSchema = z.object({
   id: z.string().describe("APOM element ID (e.g., 'input_20', 'button_45') from analyzePage result"),
-});
-
-export const GetAllInteractiveElementsSchema = z.object({
-  includeHidden: z.boolean().optional().describe("Include hidden elements (default: false)"),
+  analyzeChildren: z.boolean().optional().describe("Analyze children elements tree structure (default: false)"),
+  includeAll: z.boolean().optional().describe("When analyzing children, include all elements, not just interactive ones (default: false)"),
+  refresh: z.boolean().optional().describe("Force refresh of cached analysis (default: false)"),
 });
 
 export const FindElementsByTextSchema = z.object({

package/test-interactivity.html

@@ -0,0 +1,178 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Interactivity Detection Test</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            padding: 20px;
+            max-width: 800px;
+            margin: 0 auto;
+        }
+        .section {
+            margin: 30px 0;
+            padding: 20px;
+            border: 1px solid #ccc;
+            border-radius: 8px;
+        }
+        h2 {
+            margin-top: 0;
+            color: #333;
+        }
+        .test-item {
+            margin: 10px 0;
+            padding: 10px;
+            background: #f0f0f0;
+            border-radius: 4px;
+        }
+        .clickable-div {
+            cursor: pointer;
+            padding: 10px;
+            background: #4CAF50;
+            color: white;
+            border-radius: 4px;
+            display: inline-block;
+        }
+        .hover-div {
+            padding: 10px;
+            background: #2196F3;
+            color: white;
+            border-radius: 4px;
+            display: inline-block;
+        }
+        .hover-div:hover {
+            background: #0b7dda;
+        }
+    </style>
+</head>
+<body>
+    <h1>🧪 Interactivity Detection Test Suite</h1>
+
+    <!-- 1. Standard Interactive Elements -->
+    <div class="section">
+        <h2>1️⃣ Standard Interactive Elements</h2>
+        <div class="test-item">
+            <button id="standard-button">Standard Button</button>
+        </div>
+        <div class="test-item">
+            <a href="#test" id="standard-link">Standard Link</a>
+        </div>
+        <div class="test-item">
+            <input type="text" id="standard-input" placeholder="Standard Input">
+        </div>
+        <div class="test-item">
+            <select id="standard-select">
+                <option>Option 1</option>
+                <option>Option 2</option>
+            </select>
+        </div>
+    </div>
+
+    <!-- 2. JavaScript Event Listeners -->
+    <div class="section">
+        <h2>2️⃣ Elements with JS Event Listeners</h2>
+        <div class="test-item">
+            <div id="click-listener" class="clickable-div">DIV with Click Listener</div>
+        </div>
+        <div class="test-item">
+            <span id="mousedown-listener" class="clickable-div">SPAN with Mousedown Listener</span>
+        </div>
+        <div class="test-item">
+            <p id="multiple-listeners" class="clickable-div">P with Multiple Listeners (click, mousedown, mouseup)</p>
+        </div>
+    </div>
+
+    <!-- 3. React-style Synthetic Events (inline onclick) -->
+    <div class="section">
+        <h2>3️⃣ Inline Event Handlers</h2>
+        <div class="test-item">
+            <div onclick="alert('Clicked!')" class="clickable-div">DIV with onclick attribute</div>
+        </div>
+        <div class="test-item">
+            <span onmousedown="console.log('mousedown')" class="clickable-div">SPAN with onmousedown attribute</span>
+        </div>
+    </div>
+
+    <!-- 4. Pointer Cursor Elements -->
+    <div class="section">
+        <h2>4️⃣ Elements with cursor: pointer</h2>
+        <div class="test-item">
+            <div class="clickable-div" style="cursor: pointer;">DIV with cursor:pointer (no JS)</div>
+        </div>
+        <div class="test-item">
+            <span style="cursor: pointer; padding: 5px; background: #FF9800; color: white; border-radius: 4px;">
+                SPAN with cursor:pointer (no JS)
+            </span>
+        </div>
+    </div>
+
+    <!-- 5. Hover Effects (CSS only) -->
+    <div class="section">
+        <h2>5️⃣ Elements with CSS :hover Effects</h2>
+        <div class="test-item">
+            <div class="hover-div">DIV with :hover CSS (no JS)</div>
+        </div>
+    </div>
+
+    <!-- 6. Contenteditable -->
+    <div class="section">
+        <h2>6️⃣ Contenteditable Elements</h2>
+        <div class="test-item">
+            <div contenteditable="true" style="border: 1px solid #999; padding: 10px; min-height: 50px;">
+                Editable DIV - type here!
+            </div>
+        </div>
+    </div>
+
+    <!-- 7. Complex Nested Interactive Elements -->
+    <div class="section">
+        <h2>7️⃣ Nested Interactive Elements</h2>
+        <div class="test-item">
+            <div id="parent-clickable" class="clickable-div">
+                Parent DIV with click listener
+                <button id="nested-button" style="margin-left: 10px;">Nested Button</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- 8. False Positives Check -->
+    <div class="section">
+        <h2>8️⃣ Non-Interactive Elements (Should NOT be detected)</h2>
+        <div class="test-item">
+            <p>Regular paragraph - not interactive</p>
+        </div>
+        <div class="test-item">
+            <div style="padding: 10px; background: #ddd;">Regular DIV - not interactive</div>
+        </div>
+        <div class="test-item">
+            <span>Regular SPAN - not interactive</span>
+        </div>
+    </div>
+
+    <script>
+        // Add event listeners to test elements
+        document.getElementById('click-listener').addEventListener('click', function() {
+            console.log('Click listener triggered');
+        });
+
+        document.getElementById('mousedown-listener').addEventListener('mousedown', function() {
+            console.log('Mousedown listener triggered');
+        });
+
+        const multiListener = document.getElementById('multiple-listeners');
+        multiListener.addEventListener('click', () => console.log('click'));
+        multiListener.addEventListener('mousedown', () => console.log('mousedown'));
+        multiListener.addEventListener('mouseup', () => console.log('mouseup'));
+
+        document.getElementById('parent-clickable').addEventListener('click', function(e) {
+            if (e.target === this) {
+                console.log('Parent clicked');
+            }
+        });
+
+        console.log('✅ Test page loaded successfully');
+    </script>
+</body>
+</html>