npm - mcp-web-inspector - Versions diffs - 0.1.2 → 0.1.3 - Mend

mcp-web-inspector 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +129 -0
package/dist/toolHandler.js +110 -9
package/dist/tools/browser/ancestorInspection.d.ts +16 -0
package/dist/tools/browser/ancestorInspection.js +242 -0
package/dist/tools/browser/compareElementAlignment.js +9 -0
package/dist/tools/browser/elementVisibility.js +5 -0
package/dist/tools/browser/inspectDom.js +6 -0
package/dist/tools/browser/interaction.d.ts +4 -0
package/dist/tools/browser/interaction.js +60 -3
package/dist/tools/browser/measureElement.js +8 -0
package/dist/tools/browser/screenshot.js +13 -1
package/dist/tools.d.ts +19 -2
package/dist/tools.js +21 -2
package/dist/utils/browserCheck.d.ts +12 -0
package/dist/utils/browserCheck.js +67 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -10,6 +10,7 @@ Modern web applications are complex. Elements are hidden, layouts break, selecto
 - 🔍 **Understand any page structure** - Progressive DOM inspection that drills through wrapper divs to find semantic elements
 - 🎯 **Debug visibility issues** - Detailed diagnostics showing exactly why clicks fail (clipped, covered, scrolled out of view)
+- 🔼 **Trace layout constraints** - Walk up the DOM tree to find where unexpected margins, width limits, and overflow clipping come from
 - 📐 **Validate layouts** - Compare element positions to ensure consistent alignment and spacing
 - 🧪 **Test selector reliability** - See all matching elements with their visibility status before writing tests
 - 🎨 **Inspect styles** - Get computed CSS to understand why elements behave unexpectedly
@@ -139,6 +140,17 @@ code-insiders --add-mcp '{"name":"web-inspector","command":"npx","args":["mcp-we
 4. MCP only works in **Agent mode** - switch to agent mode in the chat interface
 5. Open the `mcp.json` file and click the **"Start"** button next to the server
+### First-Time Browser Setup
+When you first use the server with `npx`, Playwright browsers will be **automatically installed** on first tool use if not already present. The installation happens once and browsers are stored in your home directory, shared across all projects.
+If automatic installation doesn't work (firewall, permissions, etc.), you'll see clear instructions to run:
+```bash
+npx playwright install chromium firefox webkit
+```
+Then restart VS Code to use the server.
 ### Note about Embedded Browser
 GitHub Copilot and VS Code may have an embedded browser feature. If you experience conflicts or prefer using Web Inspector MCP for all web inspection tasks, you may want to disable the built-in browser:
@@ -458,6 +470,32 @@ Compare positions and alignment of two elements. Validates if elements are align
 - Validating grid layouts
 - Checking responsive design consistency
+#### `inspect_ancestors` ⭐ **DEBUG LAYOUT CONSTRAINTS**
+Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Shows position, size, and layout-critical CSS for each ancestor up to `<body>`.
+**Key Features:**
+- Default depth: 10 levels (reaches `<body>` in most React apps)
+- Only shows non-default values (omits `border:none`, `overflow:visible`)
+- Auto-detects overflow:hidden clipping, width constraints, auto-margin centering
+- Token-efficient compact text format with diagnostic annotations (🎯⚠️)
+**Use Cases:**
+- Finding where unexpected margins come from (auto-centering)
+- Discovering parent max-width constraints
+- Locating overflow:hidden containers that clip elements
+- Understanding why elements have constrained widths
+- Debugging deeply nested component library layouts (Material-UI, Chakra, Ant Design)
+**Example:**
+```
+inspect_ancestors({ selector: "testid:header" })
+→ Shows: [0] header (896px, margins: 160px)
+         [1] div (1216px, max-w constraint)
+         [2] body (1920px, overflow-x: hidden)
+   🎯 WIDTH CONSTRAINT found at parent
+   ⚠ Auto margins centering (160px each side)
+```
 ### 🎨 Style & Content Inspection
 #### `get_computed_styles`
@@ -785,6 +823,32 @@ These step-by-step recipes show how to chain tools together for common testing a
 **Why this works**: Progressive inspection + precise measurements reveal layout problems.
+### Recipe 2a: Finding Where Unexpected Margins Come From
+```
+1. navigate({ url: "https://app.example.com" })
+2. inspect_dom({ selector: "main" })
+   → Shows header element with test ID
+3. measure_element({ selector: "testid:event-mode-header" })
+   → @ (160,0) 896x56px
+   → Margin: ←160px →160px (unexpected!)
+   💡 Unexpected spacing detected. Check parent constraints
+4. inspect_ancestors({ selector: "testid:event-mode-header" })
+   → [0] <header testid:event-mode-header>
+       @ (160,0) 896x56px | w:896px max-w:896px m:0 160px
+       border-bottom: 1px solid #e5e7eb
+       ⚠ Auto margins centering (160px each side)
+   → [1] <div>
+       @ (0,0) 1216x56px | w:1216px
+   → [2] <div> flex max-w-[1600px]
+       @ (352,60) 1216x900px
+       max-width: 1600px
+       🎯 WIDTH CONSTRAINT
+5. Solution: Remove mx-auto from header (centering already handled by parent)
+```
+**Why this works**: `inspect_ancestors` traces the layout constraint chain to find the root cause of unexpected spacing in deeply nested React components.
 ### Recipe 3: API Response Testing
 ```
@@ -953,6 +1017,71 @@ These step-by-step recipes show how to chain tools together for common testing a
 **Why this works**: DOM inspection + attribute queries reveal accessibility issues.
+## Troubleshooting
+### Browser Installation Issues
+**Symptom**: Error message about Playwright browsers not being installed, or browser fails to launch.
+**How it works**: Browsers are **automatically installed on first use** when you run any navigation tool. The installation happens once (~1GB download) and browsers are stored in your home directory, shared across all projects.
+**What you'll see on first use**:
+```
+🎭 Playwright browsers not found. Installing automatically...
+⏳ This will download ~1GB of browser binaries. Please wait...
+[Installation progress...]
+✅ Browsers installed successfully! Starting browser...
+```
+**If automatic installation fails** (firewall, permissions, etc.):
+```bash
+# Manual installation - run this command:
+npx playwright install chromium firefox webkit
+# With system dependencies (requires admin/sudo):
+npx playwright install --with-deps chromium firefox webkit
+```
+**For GitHub Copilot / VS Code users**:
+- First tool use will auto-install browsers (1-2 minute wait)
+- Subsequent uses are instant
+- Installation happens in the background with progress messages
+- If manual installation is needed, restart your IDE after running the command
+### Server Not Loading
+**Symptom**: Tools from web-inspector are not available in your AI assistant.
+**Solutions**:
+1. Verify the configuration file is correct (see AI Tool Setup section above)
+2. Restart your AI tool completely (not just reload window)
+3. Check server logs (location depends on your AI tool)
+4. Try removing and re-adding the server configuration
+### Permission Issues
+**Symptom**: Permission denied errors when installing browsers.
+**Solutions**:
+```bash
+# If using global installation, you may need sudo (Linux/macOS)
+sudo npm install -g mcp-web-inspector
+# Or use npx without global installation (recommended)
+# Just configure with "npx -y mcp-web-inspector" as shown in setup
+```
+### Browser Crashes or Disconnects
+**Symptom**: Browser becomes unresponsive or disconnects during use.
+**The MCP server automatically handles this**:
+- Detects disconnected browsers
+- Resets state and provides clear error messages
+- Instructs you to retry the navigation/action
+- No manual intervention needed - just retry your command
 ## Development
 ### Testing

package/dist/toolHandler.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { chromium, firefox, webkit, devices } from 'playwright';
 import { BROWSER_TOOLS } from './tools.js';
+import { checkBrowsersInstalled, getInstallationInstructions } from './utils/browserCheck.js';
 import { ScreenshotTool, NavigationTool, CloseBrowserTool, ConsoleLogsTool } from './tools/browser/index.js';
 import { ClickTool, FillTool, SelectTool, HoverTool, EvaluateTool, UploadFileTool } from './tools/browser/interaction.js';
 import { VisibleTextTool, VisibleHtmlTool } from './tools/browser/visiblePage.js';
@@ -12,6 +13,7 @@ import { GetComputedStylesTool } from './tools/browser/computedStyles.js';
 import { MeasureElementTool } from './tools/browser/measureElement.js';
 import { ElementExistsTool } from './tools/browser/elementExists.js';
 import { CompareElementAlignmentTool } from './tools/browser/compareElementAlignment.js';
+import { InspectAncestorsTool } from './tools/browser/ancestorInspection.js';
 import { GoBackTool, GoForwardTool } from './tools/browser/navigation.js';
 import { DragTool, PressKeyTool } from './tools/browser/interaction.js';
 import { WaitForElementTool } from './tools/browser/waitForElement.js';
@@ -97,6 +99,7 @@ let getComputedStylesTool;
 let measureElementTool;
 let elementExistsTool;
 let compareElementAlignmentTool;
+let inspectAncestorsTool;
 let waitForElementTool;
 let waitForNetworkIdleTool;
 let listNetworkRequestsTool;
@@ -162,13 +165,21 @@ async function registerConsoleMessage(page) {
     page.on("console", (msg) => {
         if (consoleLogsTool) {
             const type = msg.type();
-            const text = msg.text();
+            let text = msg.text();
             // "Unhandled Rejection In Promise" we injected
             if (text.startsWith("[Playwright]")) {
                 const payload = text.replace("[Playwright]", "");
                 consoleLogsTool.registerConsoleMessage("exception", payload);
             }
             else {
+                // Truncate stack traces for error messages to keep output compact
+                if (type === 'error' && text.includes('\n')) {
+                    const lines = text.split('\n');
+                    // Keep first line (error message) and up to 3 stack trace lines
+                    if (lines.length > 4) {
+                        text = lines.slice(0, 4).join('\n') + '\n  ...[stack trace truncated]';
+                    }
+                }
                 consoleLogsTool.registerConsoleMessage(type, text);
             }
         }
@@ -200,11 +211,66 @@ async function registerConsoleMessage(page) {
         });
     });
 }
+// Track if we've checked browser installation
+let browserInstallationChecked = false;
+/**
+ * Gets the screen size using Playwright's API
+ */
+async function getScreenSize() {
+    try {
+        // Launch a temporary browser to get screen size
+        const tempBrowser = await chromium.launch({ headless: true });
+        const tempContext = await tempBrowser.newContext();
+        const tempPage = await tempContext.newPage();
+        const screenSize = await tempPage.evaluate(() => {
+            return {
+                width: window.screen.width,
+                height: window.screen.height
+            };
+        });
+        await tempBrowser.close();
+        // Validate the screen size values
+        if (!screenSize || typeof screenSize.width !== 'number' || typeof screenSize.height !== 'number') {
+            console.error('Invalid screen size detected, using defaults');
+            return { width: 1280, height: 720 };
+        }
+        return screenSize;
+    }
+    catch (error) {
+        console.error('Failed to detect screen size, using defaults:', error);
+        return { width: 1280, height: 720 };
+    }
+}
 /**
  * Ensures a browser is launched and returns the page
  */
 export async function ensureBrowser(browserSettings) {
     try {
+        // Check if browsers are installed on first launch (only once)
+        if (!browser && !browserInstallationChecked) {
+            browserInstallationChecked = true;
+            const browserCheck = checkBrowsersInstalled();
+            if (!browserCheck.installed) {
+                // Try to install browsers automatically
+                console.error('🎭 Playwright browsers not found. Installing automatically...');
+                console.error('⏳ This will download ~1GB of browser binaries. Please wait...');
+                try {
+                    const { execSync } = await import('child_process');
+                    execSync('npx playwright install chromium firefox webkit', {
+                        stdio: 'inherit',
+                        encoding: 'utf8'
+                    });
+                    console.error('✅ Browsers installed successfully! Starting browser...');
+                    // Note: browser variable is still undefined here, which is correct.
+                    // The code below (line 342) will launch the browser after installation.
+                }
+                catch (installError) {
+                    // If auto-install fails, show instructions
+                    const instructions = getInstallationInstructions();
+                    throw new Error(`Playwright browsers not installed.\n\n${instructions}`);
+                }
+            }
+        }
         // Check if browser exists but is disconnected
         if (browser && !browser.isConnected()) {
             console.error("Browser exists but is disconnected. Cleaning up...");
@@ -273,6 +339,23 @@ export async function ensureBrowser(browserSettings) {
                     break;
             }
             const executablePath = process.env.CHROME_EXECUTABLE_PATH;
+            // Determine viewport size
+            let viewportWidth;
+            let viewportHeight;
+            if (viewport?.width !== undefined || viewport?.height !== undefined) {
+                // If any viewport dimension is specified, use specified values or defaults
+                viewportWidth = viewport?.width ?? 1280;
+                viewportHeight = viewport?.height ?? 720;
+            }
+            else {
+                // If no viewport specified, detect screen size
+                const screenSize = await getScreenSize();
+                viewportWidth = screenSize?.width ?? 1280;
+                viewportHeight = screenSize?.height ?? 720;
+                if (screenSize && screenSize.width > 0 && screenSize.height > 0) {
+                    console.error(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
+                }
+            }
             // Prepare context options
             const contextOptions = {
                 headless,
@@ -287,8 +370,8 @@ export async function ensureBrowser(browserSettings) {
                     contextOptions.userAgent = userAgent;
                 }
                 contextOptions.viewport = {
-                    width: viewport?.width ?? 1280,
-                    height: viewport?.height ?? 720,
+                    width: viewportWidth,
+                    height: viewportHeight,
                 };
                 contextOptions.deviceScaleFactor = 1;
             }
@@ -331,8 +414,8 @@ export async function ensureBrowser(browserSettings) {
                         newContextOptions.userAgent = userAgent;
                     }
                     newContextOptions.viewport = {
-                        width: viewport?.width ?? 1280,
-                        height: viewport?.height ?? 720,
+                        width: viewportWidth,
+                        height: viewportHeight,
                     };
                     newContextOptions.deviceScaleFactor = 1;
                 }
@@ -390,6 +473,20 @@ export async function ensureBrowser(browserSettings) {
                 break;
         }
         const executablePath = process.env.CHROME_EXECUTABLE_PATH;
+        // Determine viewport size for retry
+        let retryViewportWidth;
+        let retryViewportHeight;
+        if (viewport?.width !== undefined || viewport?.height !== undefined) {
+            // If any viewport dimension is specified, use specified values or defaults
+            retryViewportWidth = viewport?.width ?? 1280;
+            retryViewportHeight = viewport?.height ?? 720;
+        }
+        else {
+            // If no viewport specified, detect screen size
+            const screenSize = await getScreenSize();
+            retryViewportWidth = screenSize?.width ?? 1280;
+            retryViewportHeight = screenSize?.height ?? 720;
+        }
         // Prepare context options
         const retryContextOptions = {
             headless,
@@ -404,8 +501,8 @@ export async function ensureBrowser(browserSettings) {
                 retryContextOptions.userAgent = userAgent;
             }
             retryContextOptions.viewport = {
-                width: viewport?.width ?? 1280,
-                height: viewport?.height ?? 720,
+                width: retryViewportWidth,
+                height: retryViewportHeight,
             };
             retryContextOptions.deviceScaleFactor = 1;
         }
@@ -444,8 +541,8 @@ export async function ensureBrowser(browserSettings) {
                     retryNewContextOptions.userAgent = userAgent;
                 }
                 retryNewContextOptions.viewport = {
-                    width: viewport?.width ?? 1280,
-                    height: viewport?.height ?? 720,
+                    width: retryViewportWidth,
+                    height: retryViewportHeight,
                 };
                 retryNewContextOptions.deviceScaleFactor = 1;
             }
@@ -512,6 +609,8 @@ function initializeTools(server) {
         elementExistsTool = new ElementExistsTool(server);
     if (!compareElementAlignmentTool)
         compareElementAlignmentTool = new CompareElementAlignmentTool(server);
+    if (!inspectAncestorsTool)
+        inspectAncestorsTool = new InspectAncestorsTool(server);
     if (!waitForElementTool)
         waitForElementTool = new WaitForElementTool(server);
     if (!waitForNetworkIdleTool)
@@ -653,6 +752,8 @@ export async function handleToolCall(name, args, server) {
                 return await elementExistsTool.execute(args, context);
             case "compare_element_alignment":
                 return await compareElementAlignmentTool.execute(args, context);
+            case "inspect_ancestors":
+                return await inspectAncestorsTool.execute(args, context);
             case "wait_for_element":
                 return await waitForElementTool.execute(args, context);
             case "wait_for_network_idle":

package/dist/tools/browser/ancestorInspection.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { BrowserToolBase } from "./base.js";
+import type { ToolResponse, ToolContext } from "../common/types.js";
+/**
+ * Tool to inspect ancestor chain of an element
+ * Shows parent elements up the DOM tree with layout-critical CSS properties
+ */
+export declare class InspectAncestorsTool extends BrowserToolBase {
+    execute(args: {
+        selector: string;
+        limit?: number;
+    }, context: ToolContext): Promise<ToolResponse>;
+    private formatAncestorChain;
+    private formatBorder;
+    private formatOverflow;
+    private generateDiagnostics;
+}

package/dist/tools/browser/ancestorInspection.js ADDED Viewed

@@ -0,0 +1,242 @@
+import { BrowserToolBase } from "./base.js";
+/**
+ * Tool to inspect ancestor chain of an element
+ * Shows parent elements up the DOM tree with layout-critical CSS properties
+ */
+export class InspectAncestorsTool extends BrowserToolBase {
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const limit = Math.min(args.limit ?? 10, 15); // Default 10, max 15
+            const normalizedSelector = this.normalizeSelector(args.selector);
+            const ancestors = await page.evaluate(({ sel, lim }) => {
+                const element = document.querySelector(sel);
+                if (!element) {
+                    return null;
+                }
+                const chain = [];
+                let current = element;
+                for (let i = 0; i < lim && current; i++) {
+                    const rect = current.getBoundingClientRect();
+                    const computed = window.getComputedStyle(current);
+                    chain.push({
+                        tagName: current.tagName.toLowerCase(),
+                        testId: current.getAttribute("data-testid"),
+                        classes: current.className,
+                        rect: {
+                            x: Math.round(rect.x),
+                            y: Math.round(rect.y),
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height),
+                        },
+                        // Layout-critical properties
+                        width: computed.width,
+                        maxWidth: computed.maxWidth,
+                        minWidth: computed.minWidth,
+                        margin: computed.margin,
+                        padding: computed.padding,
+                        display: computed.display,
+                        overflow: computed.overflow,
+                        overflowX: computed.overflowX,
+                        overflowY: computed.overflowY,
+                        border: computed.border,
+                        borderTop: computed.borderTop,
+                        borderRight: computed.borderRight,
+                        borderBottom: computed.borderBottom,
+                        borderLeft: computed.borderLeft,
+                        // Flexbox
+                        flexDirection: computed.flexDirection,
+                        justifyContent: computed.justifyContent,
+                        alignItems: computed.alignItems,
+                        // Conditional
+                        position: computed.position !== "static" ? computed.position : undefined,
+                        zIndex: computed.zIndex !== "auto" ? computed.zIndex : undefined,
+                        transform: computed.transform !== "none" ? computed.transform : undefined,
+                    });
+                    current = current.parentElement;
+                }
+                return chain;
+            }, { sel: normalizedSelector, lim: limit });
+            if (!ancestors) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: Element not found with selector "${args.selector}"`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: this.formatAncestorChain(ancestors, args.selector),
+                    },
+                ],
+                isError: false,
+            };
+        });
+    }
+    formatAncestorChain(ancestors, originalSelector) {
+        const lines = [`Ancestor Chain: ${originalSelector}\n`];
+        ancestors.forEach((ancestor, index) => {
+            const parts = [];
+            // Tag and identifier
+            let identifier = `[${index}] <${ancestor.tagName}>`;
+            if (ancestor.testId) {
+                identifier += ` | testid:${ancestor.testId}`;
+            }
+            else if (ancestor.classes) {
+                // Show first few classes for context
+                const classes = ancestor.classes.trim().split(/\s+/).slice(0, 3);
+                if (classes.length > 0 && classes[0]) {
+                    identifier += ` | ${classes.join(" ")}`;
+                }
+            }
+            parts.push(identifier);
+            // Position and size (always show)
+            const layoutInfo = [];
+            parts.push(`\n    @ (${ancestor.rect.x},${ancestor.rect.y}) ${ancestor.rect.width}x${ancestor.rect.height}px`);
+            // Width info (always show)
+            layoutInfo.push(`w:${ancestor.width}`);
+            // Display (only if not block)
+            if (ancestor.display !== "block") {
+                layoutInfo.push(`display:${ancestor.display}`);
+                if (ancestor.flexDirection && ancestor.flexDirection !== "row") {
+                    layoutInfo.push(ancestor.flexDirection);
+                }
+            }
+            // Only show non-default values
+            if (ancestor.margin !== "0px") {
+                layoutInfo.push(`m:${ancestor.margin}`);
+            }
+            if (ancestor.padding !== "0px") {
+                layoutInfo.push(`p:${ancestor.padding}`);
+            }
+            if (ancestor.maxWidth !== "none") {
+                layoutInfo.push(`max-w:${ancestor.maxWidth}`);
+            }
+            if (ancestor.minWidth !== "0px") {
+                layoutInfo.push(`min-w:${ancestor.minWidth}`);
+            }
+            if (layoutInfo.length > 0) {
+                parts.push(` | ${layoutInfo.join(" ")}`);
+            }
+            // Border - only if set
+            const borderInfo = this.formatBorder(ancestor);
+            if (borderInfo) {
+                parts.push(`\n    ${borderInfo}`);
+            }
+            // Overflow - only if not visible
+            const overflowInfo = this.formatOverflow(ancestor);
+            if (overflowInfo) {
+                parts.push(`\n    ${overflowInfo}`);
+            }
+            // Position, z-index, transform (only if set)
+            const extraInfo = [];
+            if (ancestor.position) {
+                extraInfo.push(`position:${ancestor.position}`);
+            }
+            if (ancestor.zIndex) {
+                extraInfo.push(`z-index:${ancestor.zIndex}`);
+            }
+            if (ancestor.transform) {
+                extraInfo.push(`transform:${ancestor.transform}`);
+            }
+            if (extraInfo.length > 0) {
+                parts.push(`\n    ${extraInfo.join(", ")}`);
+            }
+            // Add diagnostics
+            const diagnostics = this.generateDiagnostics(ancestor, index);
+            if (diagnostics) {
+                parts.push(`\n    ${diagnostics}`);
+            }
+            lines.push(parts.join(""));
+        });
+        return lines.join("\n\n");
+    }
+    formatBorder(ancestor) {
+        // Check if main border is set
+        if (ancestor.border &&
+            ancestor.border !== "none" &&
+            ancestor.border !== "0px none" &&
+            !ancestor.border.startsWith("0px")) {
+            return `border: ${ancestor.border}`;
+        }
+        // Check directional borders
+        const borders = [];
+        if (ancestor.borderTop &&
+            ancestor.borderTop !== "none" &&
+            !ancestor.borderTop.startsWith("0px")) {
+            borders.push(`top:${ancestor.borderTop}`);
+        }
+        if (ancestor.borderRight &&
+            ancestor.borderRight !== "none" &&
+            !ancestor.borderRight.startsWith("0px")) {
+            borders.push(`right:${ancestor.borderRight}`);
+        }
+        if (ancestor.borderBottom &&
+            ancestor.borderBottom !== "none" &&
+            !ancestor.borderBottom.startsWith("0px")) {
+            borders.push(`bottom:${ancestor.borderBottom}`);
+        }
+        if (ancestor.borderLeft &&
+            ancestor.borderLeft !== "none" &&
+            !ancestor.borderLeft.startsWith("0px")) {
+            borders.push(`left:${ancestor.borderLeft}`);
+        }
+        if (borders.length > 0) {
+            return `border: ${borders.join(", ")}`;
+        }
+        return null;
+    }
+    formatOverflow(ancestor) {
+        const parts = [];
+        // Handle uniform overflow
+        if (ancestor.overflow !== "visible" &&
+            ancestor.overflowX === ancestor.overflow &&
+            ancestor.overflowY === ancestor.overflow) {
+            const icon = ancestor.overflow === "hidden"
+                ? "🔒"
+                : ancestor.overflow === "auto" || ancestor.overflow === "scroll"
+                    ? "↕️"
+                    : "";
+            return `overflow: ${icon} ${ancestor.overflow}`;
+        }
+        // Handle different overflow-x/y
+        if (ancestor.overflowX !== "visible" ||
+            ancestor.overflowY !== "visible") {
+            const xIcon = ancestor.overflowX === "hidden"
+                ? "🔒"
+                : ancestor.overflowX === "auto" || ancestor.overflowX === "scroll"
+                    ? "↔️"
+                    : "";
+            const yIcon = ancestor.overflowY === "hidden"
+                ? "🔒"
+                : ancestor.overflowY === "auto" || ancestor.overflowY === "scroll"
+                    ? "↕️"
+                    : "";
+            parts.push(`overflow-x: ${xIcon} ${ancestor.overflowX}, overflow-y: ${yIcon} ${ancestor.overflowY}`);
+            return parts.join(", ");
+        }
+        return null;
+    }
+    generateDiagnostics(ancestor, index) {
+        const diagnostics = [];
+        // Overflow hidden warning
+        if (ancestor.overflow === "hidden" || ancestor.overflowY === "hidden") {
+            diagnostics.push("🎯 CLIPPING POINT - May clip overflowing children");
+        }
+        // Width constraint detection
+        if (ancestor.maxWidth !== "none" && index > 0) {
+            diagnostics.push("🎯 WIDTH CONSTRAINT");
+        }
+        // Large margins (potential centering)
+        const marginMatch = ancestor.margin.match(/0px (\d+)px/);
+        if (marginMatch && parseInt(marginMatch[1]) > 100) {
+            diagnostics.push(`⚠ Auto margins centering (${marginMatch[1]}px each side)`);
+        }
+        return diagnostics.length > 0 ? diagnostics.join("\n    ") : null;
+    }
+}

package/dist/tools/browser/compareElementAlignment.js CHANGED Viewed

@@ -161,6 +161,15 @@ export class CompareElementAlignmentTool extends BrowserToolBase {
                     `  Width:  ${formatDimension(widthSame, width1, width2, widthDiff)}`,
                     `  Height: ${formatDimension(heightSame, height1, height2, heightDiff)}`
                 ];
+                // Suggest inspect_ancestors if alignment is off and differences are significant
+                const hasSignificantDifference = Math.abs(topDiff) > 5 || Math.abs(leftDiff) > 5 || Math.abs(rightDiff) > 5;
+                const isNotAligned = !topAligned && !leftAligned && !rightAligned && !bottomAligned;
+                if (isNotAligned && hasSignificantDifference) {
+                    lines.push('');
+                    lines.push('💡 Alignment issue detected. Check if parent layout affects positioning:');
+                    lines.push(`   inspect_ancestors({ selector: "${args.selector1}" })`);
+                    lines.push(`   inspect_ancestors({ selector: "${args.selector2}" })`);
+                }
                 return createSuccessResponse(lines.filter(l => l !== undefined).join('\n'));
             }
             catch (error) {

package/dist/tools/browser/elementVisibility.js CHANGED Viewed

@@ -214,6 +214,11 @@ export class ElementVisibilityTool extends BrowserToolBase {
                 if (suggestions.length > 0) {
                     output += '\n' + suggestions.join('\n');
                 }
+                // Suggest inspect_ancestors if element is clipped
+                if (visibilityData.isClipped) {
+                    output += '\n\n💡 Element clipped by parent. Find the clipping container:';
+                    output += `\n   inspect_ancestors({ selector: "${args.selector}" })`;
+                }
                 return createSuccessResponse(output.trim());
             }
             catch (error) {

package/dist/tools/browser/inspectDom.js CHANGED Viewed

@@ -443,6 +443,12 @@ export class InspectDomTool extends BrowserToolBase {
                         lines.push(`💡 Tip: Some elements found, but ${stats.skippedWrappers} wrapper divs were skipped.`);
                         lines.push('   Consider adding test IDs to key elements for easier selection.');
                     }
+                    // Suggest inspect_ancestors when drilling through many wrappers
+                    if (stats.skippedWrappers >= 3) {
+                        lines.push('');
+                        lines.push(`💡 Drilled through ${stats.skippedWrappers} wrapper levels. To see parent constraints:`);
+                        lines.push(`   inspect_ancestors({ selector: "${args.selector || 'body'}" })`);
+                    }
                 }
                 return createSuccessResponse(lines.join('\n'));
             }

package/dist/tools/browser/interaction.d.ts CHANGED Viewed

@@ -76,6 +76,10 @@ export declare class UploadFileTool extends BrowserToolBase {
  * Tool for executing JavaScript in the browser
  */
 export declare class EvaluateTool extends BrowserToolBase {
+    /**
+     * Detect common patterns and suggest better tools
+     */
+    private detectBetterToolSuggestions;
     /**
      * Execute the evaluate tool
      */

package/dist/tools/browser/interaction.js CHANGED Viewed

@@ -160,6 +160,52 @@ export class UploadFileTool extends BrowserToolBase {
  * Tool for executing JavaScript in the browser
  */
 export class EvaluateTool extends BrowserToolBase {
+    /**
+     * Detect common patterns and suggest better tools
+     */
+    detectBetterToolSuggestions(script) {
+        const suggestions = [];
+        const scriptLower = script.toLowerCase();
+        // Pattern: DOM inspection/querying
+        if (scriptLower.match(/queryselector|getelementby|getelement|innerhtml|outerhtml|children|childnodes/)) {
+            suggestions.push('📍 DOM Inspection - Use inspect_dom({ selector: "..." }) for page structure');
+        }
+        // Pattern: Getting text content
+        if (scriptLower.match(/textcontent|innertext/)) {
+            suggestions.push('📝 Text Content - Use get_visible_text() or find_by_text({ text: "..." })');
+        }
+        // Pattern: Getting element position/size/layout
+        if (scriptLower.match(/getboundingclientrect|offsetwidth|offsetheight|offsetleft|offsettop|clientwidth|clientheight/)) {
+            suggestions.push('📏 Element Measurements - Use measure_element({ selector: "..." })');
+        }
+        // Pattern: Walking up DOM tree / checking parents
+        if (scriptLower.match(/parentelement|parentnode|offsetparent|closest/) ||
+            (scriptLower.match(/while.*parent/) && scriptLower.match(/getcomputedstyle/))) {
+            suggestions.push('🔼 Parent Chain - Use inspect_ancestors({ selector: "..." }) to see parent constraints');
+        }
+        // Pattern: Checking visibility
+        if (scriptLower.match(/offsetparent|visibility|display.*none|opacity/)) {
+            suggestions.push('👁️  Visibility Check - Use element_visibility({ selector: "..." })');
+        }
+        // Pattern: Getting computed styles
+        if (scriptLower.match(/getcomputedstyle|style\.|currentstyle/)) {
+            suggestions.push('🎨 CSS Styles - Use get_computed_styles({ selector: "..." })');
+        }
+        // Pattern: Checking element existence
+        if (scriptLower.match(/\!=\s*null|\!==\s*null/) && scriptLower.match(/queryselector/)) {
+            suggestions.push('✓ Element Existence - Use element_exists({ selector: "..." })');
+        }
+        // Pattern: Finding test IDs
+        if (scriptLower.match(/data-testid|data-test|data-cy/)) {
+            suggestions.push('🔍 Test IDs - Use get_test_ids() to discover all test identifiers');
+        }
+        // Pattern: Comparing positions/alignment
+        if (scriptLower.match(/getboundingclientrect.*getboundingclientrect/) ||
+            (scriptLower.match(/\.left|\.top|\.right|\.bottom/) && scriptLower.match(/===|==|!==|!=/))) {
+            suggestions.push('⚖️  Position Comparison - Use compare_positions({ selector1: "...", selector2: "..." })');
+        }
+        return suggestions;
+    }
     /**
      * Execute the evaluate tool
      */
@@ -175,12 +221,23 @@ export class EvaluateTool extends BrowserToolBase {
             catch (error) {
                 resultStr = String(result);
             }
-            return createSuccessResponse([
-                `Executed JavaScript:`,
+            const messages = [
+                `✓ Executed JavaScript:`,
                 `${args.script}`,
+                ``,
                 `Result:`,
                 `${resultStr}`
-            ]);
+            ];
+            // Detect if specialized tools would be better
+            const suggestions = this.detectBetterToolSuggestions(args.script);
+            if (suggestions.length > 0) {
+                messages.push('');
+                messages.push('💡 Consider using specialized tools instead:');
+                suggestions.forEach(suggestion => messages.push(`   ${suggestion}`));
+                messages.push('');
+                messages.push('ℹ️  Specialized tools are more reliable and token-efficient than evaluate()');
+            }
+            return createSuccessResponse(messages);
         });
     }
 }

package/dist/tools/browser/measureElement.js CHANGED Viewed

@@ -125,6 +125,14 @@ export class MeasureElementTool extends BrowserToolBase {
             sections.push(`  Margin:  ${formatSpacing(measurements.marginTop, measurements.marginRight, measurements.marginBottom, measurements.marginLeft)}`);
             sections.push('');
             sections.push(`Total Space: ${totalWidth}x${totalHeight}px (with margin)`);
+            // Detect unusual spacing and suggest inspect_ancestors
+            const hasUnusualMargins = measurements.marginLeft > 100 || measurements.marginRight > 100;
+            const isWidthConstrained = boxWidth < 800 && (measurements.marginLeft + measurements.marginRight) > 200;
+            if (hasUnusualMargins || isWidthConstrained) {
+                sections.push('');
+                sections.push('💡 Unexpected spacing/width detected. Check parent constraints:');
+                sections.push(`   inspect_ancestors({ selector: "${args.selector}" })`);
+            }
             return {
                 content: [
                     {

package/dist/tools/browser/screenshot.js CHANGED Viewed

@@ -49,7 +49,7 @@ export class ScreenshotTool extends BrowserToolBase {
             screenshotOptions.path = outputPath;
             const screenshot = await page.screenshot(screenshotOptions);
             const base64Screenshot = screenshot.toString('base64');
-            const messages = [`Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
+            const messages = [`✓ Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
             // Handle base64 storage
             if (args.storeBase64 !== false) {
                 this.screenshots.set(args.name || 'screenshot', base64Screenshot);
@@ -58,6 +58,18 @@ export class ScreenshotTool extends BrowserToolBase {
                 });
                 messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
             }
+            // Add actionable guidance based on screenshot context
+            messages.push('');
+            messages.push('💡 To debug layout issues in this screenshot:');
+            if (args.selector) {
+                messages.push(`   inspect_ancestors({ selector: "${args.selector}" })`);
+                messages.push('   → See parent constraints (width, margins, overflow, borders)');
+            }
+            else {
+                messages.push('   1. Find the element: inspect_dom({}) or get_test_ids()');
+                messages.push('   2. Check parent constraints: inspect_ancestors({ selector: "..." })');
+                messages.push('   3. Compare alignment: compare_element_alignment({ selector1: "...", selector2: "..." })');
+            }
             return createSuccessResponse(messages);
         });
     }

package/dist/tools.d.ts CHANGED Viewed

@@ -25,11 +25,11 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
             };
             readonly width: {
                 readonly type: "number";
-                readonly description: "Viewport width in pixels (default: 1280). Ignored if device is specified.";
+                readonly description: "Viewport width in pixels. If not specified, automatically matches screen width. Ignored if device is specified.";
             };
             readonly height: {
                 readonly type: "number";
-                readonly description: "Viewport height in pixels (default: 720). Ignored if device is specified.";
+                readonly description: "Viewport height in pixels. If not specified, automatically matches screen height. Ignored if device is specified.";
             };
             readonly timeout: {
                 readonly type: "number";
@@ -468,6 +468,23 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
         };
         readonly required: readonly ["selector1", "selector2"];
     };
+}, {
+    readonly name: "inspect_ancestors";
+    readonly description: "DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Essential when elements have unexpected centering (large auto margins), constrained width (max-width from parent), or are clipped (overflow:hidden ancestor). Shows position, size, and layout-critical CSS for each ancestor. Default depth: 10 levels (reaches <body> in most React apps). Use after inspect_dom() when you need to understand parent layout flow.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly description: "CSS selector or testid shorthand for the element to start from (e.g., 'testid:header', '#main')";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of ancestors to traverse (default: 10, max: 15). Increase for deeply nested component frameworks.";
+            };
+        };
+        readonly required: readonly ["selector"];
+    };
 }, {
     readonly name: "wait_for_element";
     readonly description: "Wait for an element to reach a specific state (visible, hidden, attached, detached). Better than sleep() for waiting on dynamic content. Returns duration and current element status. Supports testid shortcuts (e.g., 'testid:submit-button').";

package/dist/tools.js CHANGED Viewed

@@ -20,8 +20,8 @@ export function createToolDefinitions(sessionConfig) {
                         description: "Mobile device preset to emulate. Uses Playwright's built-in device configurations for viewport, user agent, and device scale factor. When specified, overrides width/height parameters.",
                         enum: ["iphone-se", "iphone-14", "iphone-14-pro", "pixel-5", "ipad", "samsung-s21"]
                     },
-                    width: { type: "number", description: "Viewport width in pixels (default: 1280). Ignored if device is specified." },
-                    height: { type: "number", description: "Viewport height in pixels (default: 720). Ignored if device is specified." },
+                    width: { type: "number", description: "Viewport width in pixels. If not specified, automatically matches screen width. Ignored if device is specified." },
+                    height: { type: "number", description: "Viewport height in pixels. If not specified, automatically matches screen height. Ignored if device is specified." },
                     timeout: { type: "number", description: "Navigation timeout in milliseconds" },
                     waitUntil: { type: "string", description: "Navigation wait condition" },
                     headless: { type: "boolean", description: "Run browser in headless mode (default: false)" }
@@ -437,6 +437,24 @@ More efficient than get_html() or evaluate(). Supports testid shortcuts.`,
                 required: ["selector1", "selector2"],
             },
         },
+        {
+            name: "inspect_ancestors",
+            description: "DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Essential when elements have unexpected centering (large auto margins), constrained width (max-width from parent), or are clipped (overflow:hidden ancestor). Shows position, size, and layout-critical CSS for each ancestor. Default depth: 10 levels (reaches <body> in most React apps). Use after inspect_dom() when you need to understand parent layout flow.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector or testid shorthand for the element to start from (e.g., 'testid:header', '#main')"
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of ancestors to traverse (default: 10, max: 15). Increase for deeply nested component frameworks."
+                    }
+                },
+                required: ["selector"],
+            },
+        },
         {
             name: "wait_for_element",
             description: "Wait for an element to reach a specific state (visible, hidden, attached, detached). Better than sleep() for waiting on dynamic content. Returns duration and current element status. Supports testid shortcuts (e.g., 'testid:submit-button').",
@@ -523,6 +541,7 @@ export const BROWSER_TOOLS = [
     // Visibility & Position
     "check_visibility",
     "compare_element_alignment",
+    "inspect_ancestors",
     "element_exists",
     "wait_for_element",
     "wait_for_network_idle",

package/dist/utils/browserCheck.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/**
+ * Check if Playwright browsers are installed
+ * Returns true if browsers are available, false otherwise
+ */
+export declare function checkBrowsersInstalled(): {
+    installed: boolean;
+    message?: string;
+};
+/**
+ * Get installation instructions for the current context
+ */
+export declare function getInstallationInstructions(): string;

package/dist/utils/browserCheck.js ADDED Viewed

@@ -0,0 +1,67 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+/**
+ * Check if Playwright browsers are installed
+ * Returns true if browsers are available, false otherwise
+ */
+export function checkBrowsersInstalled() {
+    try {
+        // Check if playwright is available
+        const result = execSync('npx playwright --version', {
+            encoding: 'utf8',
+            stdio: 'pipe'
+        });
+        // If we got here, playwright CLI is available
+        // Now check if browsers are actually installed
+        // Playwright stores browsers in a cache directory
+        const homeDir = process.env.HOME || process.env.USERPROFILE;
+        if (!homeDir) {
+            return {
+                installed: false,
+                message: 'Could not determine home directory to check for browsers'
+            };
+        }
+        // Common browser cache locations
+        const possibleCacheDirs = [
+            join(homeDir, '.cache', 'ms-playwright'), // Linux
+            join(homeDir, 'Library', 'Caches', 'ms-playwright'), // macOS
+            join(homeDir, 'AppData', 'Local', 'ms-playwright'), // Windows
+        ];
+        const cacheExists = possibleCacheDirs.some(dir => existsSync(dir));
+        if (!cacheExists) {
+            return {
+                installed: false,
+                message: 'Playwright browsers not found in cache directories'
+            };
+        }
+        return { installed: true };
+    }
+    catch (error) {
+        return {
+            installed: false,
+            message: `Playwright check failed: ${error.message}`
+        };
+    }
+}
+/**
+ * Get installation instructions for the current context
+ */
+export function getInstallationInstructions() {
+    return `
+Playwright browsers are not installed. To fix this, run one of the following commands:
+1. In your project directory:
+   npx playwright install chromium firefox webkit
+2. If you installed mcp-web-inspector globally:
+   cd $(npm root -g)/mcp-web-inspector && npx playwright install chromium firefox webkit
+3. Or install system-wide with dependencies (requires admin/sudo):
+   npx playwright install --with-deps chromium firefox webkit
+For GitHub Copilot or VS Code users, you may need to:
+- Close and reopen your IDE after installation
+- Or run: npx playwright install chromium
+`.trim();
+}

package/package.json CHANGED Viewed

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