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

mcp-web-inspector 0.1.2 → 0.1.4

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 (19) hide show

package/README.md +166 -7
package/dist/index.js +5 -0
package/dist/toolHandler.d.ts +6 -1
package/dist/toolHandler.js +124 -13
package/dist/tools/browser/ancestorInspection.d.ts +18 -0
package/dist/tools/browser/ancestorInspection.js +362 -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 +62 -8
package/dist/tools/browser/measureElement.js +8 -0
package/dist/tools/browser/screenshot.js +13 -1
package/dist/tools/browser/visiblePage.js +80 -68
package/dist/tools.d.ts +36 -29
package/dist/tools.js +47 -14
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:
@@ -277,6 +289,7 @@ Customize server behavior with command line flags:
 - **`--no-save-session`** - Disable automatic session persistence (start with fresh browser state each time)
 - **`--user-data-dir <path>`** - Custom directory for session data (default: `./.mcp-web-inspector`)
+- **`--headless`** - Run browser in headless mode by default (no visible window)
 **Example usage:**
 ```json
@@ -290,6 +303,30 @@ Customize server behavior with command line flags:
 }
 ```
+**Run in headless mode for automation/CI:**
+```json
+{
+  "mcpServers": {
+    "web-inspector": {
+      "command": "npx",
+      "args": ["-y", "mcp-web-inspector", "--headless"]
+    }
+  }
+}
+```
+**Combine multiple flags:**
+```json
+{
+  "mcpServers": {
+    "web-inspector": {
+      "command": "npx",
+      "args": ["-y", "mcp-web-inspector", "--headless", "--no-save-session"]
+    }
+  }
+}
+```
 ---
 ## Session Persistence & Data Storage
@@ -383,8 +420,8 @@ rm -rf ./.mcp-web-inspector/screenshots    # Clear screenshots only
 - Session files can be large and bloat your git history
 **Best practices:**
-- Use `headless: true` for automation and CI/CD environments
-- Use `headless: false` only when debugging interactively
+- **Default is visible browser** (`headless: false`) for interactive debugging
+- Use `headless: true` explicitly for automation and CI/CD environments
 - Clear session data after testing sensitive applications
 - Use `--no-save-session` flag when testing on shared/public sites
@@ -458,6 +495,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`
@@ -532,11 +595,16 @@ Ultra-lightweight existence check. Returns simple ✓ exists or ✗ not found st
 Navigate to a URL with full browser configuration options.
 **Parameters:**
-- `browserType` - chromium, firefox, or webkit
-- `width`, `height` - Viewport dimensions
-- `headless` - Run in headless mode
-- `timeout` - Navigation timeout
-- `waitUntil` - Navigation wait condition
+- `browserType` - chromium, firefox, or webkit (default: chromium)
+- `width`, `height` - Viewport dimensions (default: auto-detected screen size)
+- `headless` - Run in headless mode (default: **false** - browser window visible)
+- `timeout` - Navigation timeout in ms (default: 30000)
+- `waitUntil` - Navigation wait condition (default: "load")
+**Default Behavior:**
+- Browser window is **visible by default** for interactive debugging
+- Use `headless: true` for automation, CI/CD, or when you don't need visual feedback
+- Use `headless: false` (or omit) when debugging interactively
 #### `go_back`
 Navigate back in browser history. Essential for testing navigation flows and multi-step forms.
@@ -785,6 +853,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 +1047,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/index.js CHANGED Viewed

@@ -16,6 +16,10 @@ const { values } = parseArgs({
             type: 'string',
             default: './.mcp-web-inspector',
         },
+        'headless': {
+            type: 'boolean',
+            default: false,
+        },
     },
     strict: false,
 });
@@ -25,6 +29,7 @@ const sessionConfig = {
     saveSession: !Boolean(values['no-save-session']),
     userDataDir: `${baseDir}/user-data`,
     screenshotsDir: `${baseDir}/screenshots`,
+    headlessDefault: Boolean(values['headless']),
 };
 setSessionConfig(sessionConfig);
 async function runServer() {

package/dist/toolHandler.d.ts CHANGED Viewed

@@ -22,6 +22,7 @@ interface SessionConfig {
     saveSession: boolean;
     userDataDir: string;
     screenshotsDir: string;
+    headlessDefault: boolean;
 }
 /**
  * Sets the session configuration
@@ -31,6 +32,10 @@ export declare function setSessionConfig(config: Partial<SessionConfig>): void;
  * Gets the screenshots directory
  */
 export declare function getScreenshotsDir(): string;
+/**
+ * Gets the default headless setting
+ */
+export declare function getHeadlessDefault(): boolean;
 /**
  * Resets browser and page variables
  * Used when browser is closed
@@ -48,7 +53,7 @@ export declare function clearNetworkLog(): void;
  * Sets the provided page to the global page variable
  * @param newPage The Page object to set as the global page
  */
-export declare function setGlobalPage(newPage: Page): void;
+export declare function setGlobalPage(newPage: Page): Promise<void>;
 interface BrowserSettings {
     viewport?: {
         width?: number;

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';
@@ -27,6 +29,7 @@ let sessionConfig = {
     saveSession: false,
     userDataDir: './.mcp-web-inspector/user-data',
     screenshotsDir: './.mcp-web-inspector/screenshots',
+    headlessDefault: false,
 };
 /**
  * Sets the session configuration
@@ -40,6 +43,12 @@ export function setSessionConfig(config) {
 export function getScreenshotsDir() {
     return sessionConfig.screenshotsDir;
 }
+/**
+ * Gets the default headless setting
+ */
+export function getHeadlessDefault() {
+    return sessionConfig.headlessDefault;
+}
 /**
  * Resets browser and page variables
  * Used when browser is closed
@@ -66,10 +75,13 @@ export function clearNetworkLog() {
  * Sets the provided page to the global page variable
  * @param newPage The Page object to set as the global page
  */
-export function setGlobalPage(newPage) {
+export async function setGlobalPage(newPage) {
     page = newPage;
+    // Register console message handlers and network listeners for the new page
+    await registerConsoleMessage(page);
+    await registerNetworkListeners(page);
     page.bringToFront(); // Bring the new tab to the front
-    console.log("Global page has been updated.");
+    console.log("Global page has been updated with listeners registered.");
 }
 // Tool instances
 let screenshotTool;
@@ -97,6 +109,7 @@ let getComputedStylesTool;
 let measureElementTool;
 let elementExistsTool;
 let compareElementAlignmentTool;
+let inspectAncestorsTool;
 let waitForElementTool;
 let waitForNetworkIdleTool;
 let listNetworkRequestsTool;
@@ -162,13 +175,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 +221,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...");
@@ -234,7 +310,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Launch new browser if needed
         if (!browser) {
-            const { viewport, userAgent, headless = false, browserType = 'chromium', device } = browserSettings ?? {};
+            const { viewport, userAgent, headless = sessionConfig.headlessDefault, browserType = 'chromium', device } = browserSettings ?? {};
             // If browser type is changing, force a new browser instance
             if (browser && currentBrowserType !== browserType) {
                 try {
@@ -273,6 +349,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 +380,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 +424,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;
                 }
@@ -368,7 +461,7 @@ export async function ensureBrowser(browserSettings) {
         }
         resetBrowserState();
         // Try one more time from scratch
-        const { viewport, userAgent, headless = false, browserType = 'chromium', device } = browserSettings ?? {};
+        const { viewport, userAgent, headless = sessionConfig.headlessDefault, browserType = 'chromium', device } = browserSettings ?? {};
         // Get device configuration if device preset is specified
         let deviceConfig = null;
         if (device && DEVICE_PRESETS[device]) {
@@ -390,6 +483,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 +511,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 +551,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 +619,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 +762,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,18 @@
+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 formatLayoutContext;
+    private formatMarginDetails;
+    private generateDiagnostics;
+}