mcp-web-inspector 0.1.1 → 0.1.2

package/dist/toolHandler.js

@@ -11,7 +11,7 @@ import { FindByTextTool } from './tools/browser/findByText.js';
 import { GetComputedStylesTool } from './tools/browser/computedStyles.js';
 import { MeasureElementTool } from './tools/browser/measureElement.js';
 import { ElementExistsTool } from './tools/browser/elementExists.js';
-import { ComparePositionsTool } from './tools/browser/comparePositions.js';
+import { CompareElementAlignmentTool } from './tools/browser/compareElementAlignment.js';
 import { GoBackTool, GoForwardTool } from './tools/browser/navigation.js';
 import { DragTool, PressKeyTool } from './tools/browser/interaction.js';
 import { WaitForElementTool } from './tools/browser/waitForElement.js';
@@ -96,7 +96,7 @@ let findByTextTool;
 let getComputedStylesTool;
 let measureElementTool;
 let elementExistsTool;
-let comparePositionsTool;
+let compareElementAlignmentTool;
 let waitForElementTool;
 let waitForNetworkIdleTool;
 let listNetworkRequestsTool;
@@ -510,8 +510,8 @@ function initializeTools(server) {
         measureElementTool = new MeasureElementTool(server);
     if (!elementExistsTool)
         elementExistsTool = new ElementExistsTool(server);
-    if (!comparePositionsTool)
-        comparePositionsTool = new ComparePositionsTool(server);
+    if (!compareElementAlignmentTool)
+        compareElementAlignmentTool = new CompareElementAlignmentTool(server);
     if (!waitForElementTool)
         waitForElementTool = new WaitForElementTool(server);
     if (!waitForNetworkIdleTool)
@@ -651,8 +651,8 @@ export async function handleToolCall(name, args, server) {
                 return await measureElementTool.execute(args, context);
             case "element_exists":
                 return await elementExistsTool.execute(args, context);
-            case "compare_positions":
-                return await comparePositionsTool.execute(args, context);
+            case "compare_element_alignment":
+                return await compareElementAlignmentTool.execute(args, context);
             case "wait_for_element":
                 return await waitForElementTool.execute(args, context);
             case "wait_for_network_idle":

package/dist/tools/browser/compareElementAlignment.d.ts

@@ -0,0 +1,11 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for comparing alignment of two elements
+ */
+export declare class CompareElementAlignmentTool extends BrowserToolBase {
+    /**
+     * Execute the compare element alignment tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/compareElementAlignment.js

@@ -0,0 +1,171 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for comparing alignment of two elements
+ */
+export class CompareElementAlignmentTool extends BrowserToolBase {
+    /**
+     * Execute the compare element alignment tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector1 = this.normalizeSelector(args.selector1);
+            const selector2 = this.normalizeSelector(args.selector2);
+            try {
+                // Get locators for both elements
+                const locator1 = page.locator(selector1);
+                const locator2 = page.locator(selector2);
+                // Check if both elements exist
+                const count1 = await locator1.count();
+                const count2 = await locator2.count();
+                if (count1 === 0) {
+                    return createErrorResponse(`First element not found: ${args.selector1}`);
+                }
+                if (count2 === 0) {
+                    return createErrorResponse(`Second element not found: ${args.selector2}`);
+                }
+                // Handle multiple matches by using first() - show warning
+                const targetLocator1 = count1 > 1 ? locator1.first() : locator1;
+                const targetLocator2 = count2 > 1 ? locator2.first() : locator2;
+                let warnings = '';
+                if (count1 > 1) {
+                    warnings += `⚠ Warning: First selector matched ${count1} elements, using first\n`;
+                }
+                if (count2 > 1) {
+                    warnings += `⚠ Warning: Second selector matched ${count2} elements, using first\n`;
+                }
+                if (warnings) {
+                    warnings += '\n';
+                }
+                // Get bounding boxes
+                const box1 = await targetLocator1.boundingBox();
+                const box2 = await targetLocator2.boundingBox();
+                // Get element descriptors
+                const getDescriptor = async (locator) => {
+                    return await locator.evaluate((element) => {
+                        const tagName = element.tagName.toLowerCase();
+                        const testId = element.getAttribute('data-testid') || element.getAttribute('data-test') || element.getAttribute('data-cy');
+                        const id = element.id ? `#${element.id}` : '';
+                        const classes = element.className && typeof element.className === 'string'
+                            ? `.${element.className.split(' ').filter(c => c).join('.')}`
+                            : '';
+                        let descriptor = `<${tagName}`;
+                        if (testId)
+                            descriptor += ` data-testid="${testId}"`;
+                        else if (id)
+                            descriptor += id;
+                        else if (classes)
+                            descriptor += classes;
+                        descriptor += '>';
+                        return descriptor;
+                    });
+                };
+                const descriptor1 = await getDescriptor(targetLocator1);
+                const descriptor2 = await getDescriptor(targetLocator2);
+                // Handle hidden elements
+                if (!box1) {
+                    return createErrorResponse(`First element is hidden or has no dimensions: ${descriptor1}`);
+                }
+                if (!box2) {
+                    return createErrorResponse(`Second element is hidden or has no dimensions: ${descriptor2}`);
+                }
+                // Extract short name from descriptor for compact output
+                const getShortName = (descriptor, selector) => {
+                    const testIdMatch = descriptor.match(/data-testid="([^"]+)"/);
+                    if (testIdMatch)
+                        return testIdMatch[1];
+                    const idMatch = descriptor.match(/#([^>]+)/);
+                    if (idMatch)
+                        return idMatch[1];
+                    // Use original selector if available
+                    return selector;
+                };
+                const name1 = getShortName(descriptor1, args.selector1);
+                const name2 = getShortName(descriptor2, args.selector2);
+                // Calculate all alignment values
+                const tolerance = 2; // Allow 2px tolerance for rounding
+                // Edge positions
+                const top1 = Math.round(box1.y);
+                const top2 = Math.round(box2.y);
+                const topDiff = Math.abs(top1 - top2);
+                const topAligned = topDiff <= tolerance;
+                const left1 = Math.round(box1.x);
+                const left2 = Math.round(box2.x);
+                const leftDiff = Math.abs(left1 - left2);
+                const leftAligned = leftDiff <= tolerance;
+                const right1 = Math.round(box1.x + box1.width);
+                const right2 = Math.round(box2.x + box2.width);
+                const rightDiff = Math.abs(right1 - right2);
+                const rightAligned = rightDiff <= tolerance;
+                const bottom1 = Math.round(box1.y + box1.height);
+                const bottom2 = Math.round(box2.y + box2.height);
+                const bottomDiff = Math.abs(bottom1 - bottom2);
+                const bottomAligned = bottomDiff <= tolerance;
+                // Center positions
+                const centerH1 = Math.round(box1.x + box1.width / 2);
+                const centerH2 = Math.round(box2.x + box2.width / 2);
+                const centerHDiff = Math.abs(centerH1 - centerH2);
+                const centerHAligned = centerHDiff <= tolerance;
+                const centerV1 = Math.round(box1.y + box1.height / 2);
+                const centerV2 = Math.round(box2.y + box2.height / 2);
+                const centerVDiff = Math.abs(centerV1 - centerV2);
+                const centerVAligned = centerVDiff <= tolerance;
+                // Dimensions
+                const width1 = Math.round(box1.width);
+                const width2 = Math.round(box2.width);
+                const widthDiff = Math.abs(width1 - width2);
+                const widthSame = widthDiff <= tolerance;
+                const height1 = Math.round(box1.height);
+                const height2 = Math.round(box2.height);
+                const heightDiff = Math.abs(height1 - height2);
+                const heightSame = heightDiff <= tolerance;
+                // Format compact output
+                const formatAlignment = (aligned, val1, val2, diff, unit = 'px') => {
+                    const symbol = aligned ? '✓' : '✗';
+                    const status = aligned ? 'aligned' : 'not aligned';
+                    if (aligned) {
+                        return `${symbol} ${status} (both @ ${val1}${unit})`;
+                    }
+                    else {
+                        return `${symbol} ${status} (${val1}${unit} vs ${val2}${unit}, diff: ${diff}${unit})`;
+                    }
+                };
+                const formatDimension = (same, val1, val2, diff, unit = 'px') => {
+                    const symbol = same ? '✓' : '✗';
+                    const status = same ? 'same' : 'different';
+                    if (same) {
+                        return `${symbol} ${status} (${val1}${unit})`;
+                    }
+                    else {
+                        return `${symbol} ${status} (${val1}${unit} vs ${val2}${unit}, diff: ${diff}${unit})`;
+                    }
+                };
+                // Build output
+                const lines = [
+                    warnings,
+                    `Alignment: ${descriptor1} vs ${descriptor2}`,
+                    `  ${name1}: @ (${left1},${top1}) ${width1}×${height1}px`,
+                    `  ${name2}: @ (${left2},${top2}) ${width2}×${height2}px`,
+                    '',
+                    'Edges:',
+                    `  Top:    ${formatAlignment(topAligned, top1, top2, topDiff)}`,
+                    `  Left:   ${formatAlignment(leftAligned, left1, left2, leftDiff)}`,
+                    `  Right:  ${formatAlignment(rightAligned, right1, right2, rightDiff)}`,
+                    `  Bottom: ${formatAlignment(bottomAligned, bottom1, bottom2, bottomDiff)}`,
+                    '',
+                    'Centers:',
+                    `  Horizontal: ${formatAlignment(centerHAligned, centerH1, centerH2, centerHDiff)}`,
+                    `  Vertical:   ${formatAlignment(centerVAligned, centerV1, centerV2, centerVDiff)}`,
+                    '',
+                    'Dimensions:',
+                    `  Width:  ${formatDimension(widthSame, width1, width2, widthDiff)}`,
+                    `  Height: ${formatDimension(heightSame, height1, height2, heightDiff)}`
+                ];
+                return createSuccessResponse(lines.filter(l => l !== undefined).join('\n'));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to compare element alignment: ${error.message}`);
+            }
+        });
+    }
+}

package/dist/tools/browser/inspectDom.js

@@ -391,6 +391,13 @@ export class InspectDomTool extends BrowserToolBase {
                         lines.push(`${prefix} ${tag}${roleInfo}`);
                         // Position
                         lines.push(`    @ (${child.position.x},${child.position.y}) ${child.position.width}x${child.position.height}px`);
+                        // Calculate distances from all parent edges
+                        const fromLeft = child.position.x - target.position.x;
+                        const fromRight = (target.position.x + target.position.width) - (child.position.x + child.position.width);
+                        const fromTop = child.position.y - target.position.y;
+                        const fromBottom = (target.position.y + target.position.height) - (child.position.y + child.position.height);
+                        // Format edge distances (centering is obvious: equal left/right = horizontal center, equal top/bottom = vertical center)
+                        lines.push(`    from edges: ←${fromLeft}px →${fromRight}px ↑${fromTop}px ↓${fromBottom}px`);
                         // Calculate offset from previous sibling
                         if (index > 0) {
                             const prev = children[index - 1];

package/dist/tools.d.ts

@@ -314,7 +314,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "inspect_dom";
-    readonly description: "START HERE FOR LAYOUT DEBUGGING: Get page structure overview and identify elements. Progressive DOM inspection that skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.). Use without selector for full page overview, then drill down by calling with a child's selector. Returns compact text format with position, visibility, and layout patterns. More efficient than get_html() or evaluate() for understanding structure. Supports testid shortcuts.";
+    readonly description: "START HERE FOR LAYOUT DEBUGGING: Progressive DOM inspection that shows parent-child relationships, centering issues, and spacing gaps. Skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.).\n\nWORKFLOW: Call without selector for page overview, then drill down by calling with child's selector.\n\nDETECTS: Parent-relative positioning, vertical/horizontal centering, sibling spacing gaps, layout patterns.\n\nOUTPUT FORMAT:\n[0] <button data-testid=\"menu\">\n    @ (16,8) 40×40px                         ← Absolute viewport position (x,y) and size\n    from edges: ←16px →1144px ↑8px ↓8px      ← Distance from parent edges (↑8px = ↓8px means vertically centered)\n    \"Menu\"\n    ✓ visible, ⚡ interactive\n\n[1] <div data-testid=\"title\">\n    @ (260,2) 131×28px\n    from edges: ←244px →244px ↑2px ↓42px     ← Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered\n    gap from [0]: →16px                      ← Spacing between siblings\n    \"Title\"\n    ✓ visible, 2 children\n\nSYMBOLS: ✓=visible, ✗=hidden, ⚡=interactive, ←→=horizontal edges, ↑↓=vertical edges\nCENTERING: Equal left/right distances = horizontally centered, equal top/bottom = vertically centered\n\nRELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use compare_element_alignment(). For box model (padding/margin), use measure_element().\n\nMore efficient than get_html() or evaluate(). Supports testid shortcuts.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -427,7 +427,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "measure_element";
-    readonly description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). More readable than get_computed_styles() for box model debugging.";
+    readonly description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). For parent-child centering issues, use inspect_dom() first (shows if child is centered in parent). For comparing alignment between two elements, use compare_element_alignment(). More readable than get_computed_styles() for box model debugging.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -452,8 +452,8 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
         readonly required: readonly ["selector"];
     };
 }, {
-    readonly name: "compare_positions";
-    readonly description: "FIND ALIGNMENT GAPS: Check if two elements are properly aligned or have spacing issues. Perfect for debugging layout problems like 'element not aligned with header' or 'gap between panels'. Checks edge alignment (top, left, right, bottom) or dimension matching (width, height). Returns alignment status and gap size in pixels. More efficient than evaluate() with manual getBoundingClientRect() calculations.";
+    readonly name: "compare_element_alignment";
+    readonly description: "COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with ✓/✗ symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -465,13 +465,8 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
                 readonly type: "string";
                 readonly description: "CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')";
             };
-            readonly checkAlignment: {
-                readonly type: "string";
-                readonly description: "What to check: 'top', 'left', 'right', 'bottom' (edge alignment), or 'width', 'height' (dimension matching)";
-                readonly enum: readonly ["top", "left", "right", "bottom", "width", "height"];
-            };
         };
-        readonly required: readonly ["selector1", "selector2", "checkAlignment"];
+        readonly required: readonly ["selector1", "selector2"];
     };
 }, {
     readonly name: "wait_for_element";

package/dist/tools.js

@@ -250,7 +250,32 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "inspect_dom",
-            description: "START HERE FOR LAYOUT DEBUGGING: Get page structure overview and identify elements. Progressive DOM inspection that skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.). Use without selector for full page overview, then drill down by calling with a child's selector. Returns compact text format with position, visibility, and layout patterns. More efficient than get_html() or evaluate() for understanding structure. Supports testid shortcuts.",
+            description: `START HERE FOR LAYOUT DEBUGGING: Progressive DOM inspection that shows parent-child relationships, centering issues, and spacing gaps. Skips wrapper divs and shows only semantic elements (header, nav, main, form, button, elements with test IDs, ARIA roles, etc.).
+
+WORKFLOW: Call without selector for page overview, then drill down by calling with child's selector.
+
+DETECTS: Parent-relative positioning, vertical/horizontal centering, sibling spacing gaps, layout patterns.
+
+OUTPUT FORMAT:
+[0] <button data-testid="menu">
+    @ (16,8) 40×40px                         ← Absolute viewport position (x,y) and size
+    from edges: ←16px →1144px ↑8px ↓8px      ← Distance from parent edges (↑8px = ↓8px means vertically centered)
+    "Menu"
+    ✓ visible, ⚡ interactive
+
+[1] <div data-testid="title">
+    @ (260,2) 131×28px
+    from edges: ←244px →244px ↑2px ↓42px     ← Equal left/right (244px) = horizontally centered, unequal top/bottom = NOT vertically centered
+    gap from [0]: →16px                      ← Spacing between siblings
+    "Title"
+    ✓ visible, 2 children
+
+SYMBOLS: ✓=visible, ✗=hidden, ⚡=interactive, ←→=horizontal edges, ↑↓=vertical edges
+CENTERING: Equal left/right distances = horizontally centered, equal top/bottom = vertically centered
+
+RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use compare_element_alignment(). For box model (padding/margin), use measure_element().
+
+More efficient than get_html() or evaluate(). Supports testid shortcuts.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -368,7 +393,7 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "measure_element",
-            description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). More readable than get_computed_styles() for box model debugging.",
+            description: "DEBUG SPACING ISSUES: See padding, margin, and border measurements in visual box model format. Use when elements have unexpected spacing or size. Returns compact visual representation showing content → padding → border → margin with directional arrows (↑24px for top margin, etc.). For parent-child centering issues, use inspect_dom() first (shows if child is centered in parent). For comparing alignment between two elements, use compare_element_alignment(). More readable than get_computed_styles() for box model debugging.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -395,8 +420,8 @@ export function createToolDefinitions(sessionConfig) {
             },
         },
         {
-            name: "compare_positions",
-            description: "FIND ALIGNMENT GAPS: Check if two elements are properly aligned or have spacing issues. Perfect for debugging layout problems like 'element not aligned with header' or 'gap between panels'. Checks edge alignment (top, left, right, bottom) or dimension matching (width, height). Returns alignment status and gap size in pixels. More efficient than evaluate() with manual getBoundingClientRect() calculations.",
+            name: "compare_element_alignment",
+            description: "COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with ✓/✗ symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -407,14 +432,9 @@ export function createToolDefinitions(sessionConfig) {
                     selector2: {
                         type: "string",
                         description: "CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')"
-                    },
-                    checkAlignment: {
-                        type: "string",
-                        description: "What to check: 'top', 'left', 'right', 'bottom' (edge alignment), or 'width', 'height' (dimension matching)",
-                        enum: ["top", "left", "right", "bottom", "width", "height"]
                     }
                 },
-                required: ["selector1", "selector2", "checkAlignment"],
+                required: ["selector1", "selector2"],
             },
         },
         {
@@ -502,7 +522,7 @@ export const BROWSER_TOOLS = [
     "find_by_text",
     // Visibility & Position
     "check_visibility",
-    "compare_positions",
+    "compare_element_alignment",
     "element_exists",
     "wait_for_element",
     "wait_for_network_idle",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-web-inspector",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Web Inspector MCP: Give LLMs visual superpowers to see, debug, and test any web page.",
   "license": "MIT",
   "author": "Anton",