mcp-web-inspector 0.1.3 → 0.1.4

package/README.md

@@ -289,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
@@ -302,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
@@ -395,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
 
@@ -570,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.

package/dist/index.js

@@ -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

@@ -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

@@ -29,6 +29,7 @@ let sessionConfig = {
     saveSession: false,
     userDataDir: './.mcp-web-inspector/user-data',
     screenshotsDir: './.mcp-web-inspector/screenshots',
+    headlessDefault: false,
 };
 /**
  * Sets the session configuration
@@ -42,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
@@ -68,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;
@@ -300,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 {
@@ -451,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]) {

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

@@ -12,5 +12,7 @@ export declare class InspectAncestorsTool extends BrowserToolBase {
     private formatAncestorChain;
     private formatBorder;
     private formatOverflow;
+    private formatLayoutContext;
+    private formatMarginDetails;
     private generateDiagnostics;
 }

package/dist/tools/browser/ancestorInspection.js

@@ -33,6 +33,10 @@ export class InspectAncestorsTool extends BrowserToolBase {
                         maxWidth: computed.maxWidth,
                         minWidth: computed.minWidth,
                         margin: computed.margin,
+                        marginTop: computed.marginTop,
+                        marginRight: computed.marginRight,
+                        marginBottom: computed.marginBottom,
+                        marginLeft: computed.marginLeft,
                         padding: computed.padding,
                         display: computed.display,
                         overflow: computed.overflow,
@@ -47,6 +51,10 @@ export class InspectAncestorsTool extends BrowserToolBase {
                         flexDirection: computed.flexDirection,
                         justifyContent: computed.justifyContent,
                         alignItems: computed.alignItems,
+                        gap: computed.gap,
+                        // Grid
+                        gridTemplateColumns: computed.gridTemplateColumns,
+                        gridTemplateRows: computed.gridTemplateRows,
                         // Conditional
                         position: computed.position !== "static" ? computed.position : undefined,
                         zIndex: computed.zIndex !== "auto" ? computed.zIndex : undefined,
@@ -103,9 +111,6 @@ export class InspectAncestorsTool extends BrowserToolBase {
             // 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") {
@@ -123,6 +128,16 @@ export class InspectAncestorsTool extends BrowserToolBase {
             if (layoutInfo.length > 0) {
                 parts.push(` | ${layoutInfo.join(" ")}`);
             }
+            // Flexbox/Grid context (on separate line for clarity)
+            const layoutContext = this.formatLayoutContext(ancestor);
+            if (layoutContext) {
+                parts.push(`\n    ${layoutContext}`);
+            }
+            // Margin details (only if non-zero or has auto)
+            const marginDetails = this.formatMarginDetails(ancestor);
+            if (marginDetails) {
+                parts.push(`\n    ${marginDetails}`);
+            }
             // Border - only if set
             const borderInfo = this.formatBorder(ancestor);
             if (borderInfo) {
@@ -222,6 +237,116 @@ export class InspectAncestorsTool extends BrowserToolBase {
         }
         return null;
     }
+    formatLayoutContext(ancestor) {
+        const parts = [];
+        // Flexbox
+        if (ancestor.display === "flex" || ancestor.display === "inline-flex") {
+            const flexParts = ["flex"];
+            if (ancestor.flexDirection && ancestor.flexDirection !== "row") {
+                flexParts.push(ancestor.flexDirection);
+            }
+            if (ancestor.justifyContent && ancestor.justifyContent !== "normal" && ancestor.justifyContent !== "flex-start") {
+                flexParts.push(`justify:${ancestor.justifyContent}`);
+            }
+            if (ancestor.alignItems && ancestor.alignItems !== "normal" && ancestor.alignItems !== "stretch") {
+                flexParts.push(`items:${ancestor.alignItems}`);
+            }
+            if (ancestor.gap && ancestor.gap !== "0px" && ancestor.gap !== "normal") {
+                flexParts.push(`gap:${ancestor.gap}`);
+            }
+            parts.push(flexParts.join(" "));
+        }
+        // Grid
+        if (ancestor.display === "grid" || ancestor.display === "inline-grid") {
+            const gridParts = ["grid"];
+            if (ancestor.gridTemplateColumns && ancestor.gridTemplateColumns !== "none") {
+                gridParts.push(`cols:${ancestor.gridTemplateColumns}`);
+            }
+            if (ancestor.gridTemplateRows && ancestor.gridTemplateRows !== "none") {
+                gridParts.push(`rows:${ancestor.gridTemplateRows}`);
+            }
+            if (ancestor.gap && ancestor.gap !== "0px" && ancestor.gap !== "normal") {
+                gridParts.push(`gap:${ancestor.gap}`);
+            }
+            parts.push(gridParts.join(" "));
+        }
+        return parts.length > 0 ? parts.join(" | ") : null;
+    }
+    formatMarginDetails(ancestor) {
+        // Check if any margin is "auto" (CSS value)
+        // Note: computed styles show actual values, not "auto"
+        const hasAuto = ancestor.margin.includes("auto") ||
+            ancestor.marginTop === "auto" ||
+            ancestor.marginRight === "auto" ||
+            ancestor.marginBottom === "auto" ||
+            ancestor.marginLeft === "auto";
+        // Check if margins are non-uniform (can't be represented by shorthand)
+        const isNonUniform = ancestor.marginTop !== ancestor.marginBottom ||
+            ancestor.marginLeft !== ancestor.marginRight ||
+            ancestor.marginTop !== ancestor.marginLeft;
+        // Parse margin values to detect large symmetric margins (likely auto-centered)
+        const parseMarginValue = (val) => {
+            const match = val.match(/^([\d.]+)px$/);
+            return match ? parseFloat(match[1]) : 0;
+        };
+        const marginLeftPx = parseMarginValue(ancestor.marginLeft);
+        const marginRightPx = parseMarginValue(ancestor.marginRight);
+        const marginTopPx = parseMarginValue(ancestor.marginTop);
+        const marginBottomPx = parseMarginValue(ancestor.marginBottom);
+        // Detect horizontal centering: large equal left/right margins, small top/bottom
+        const isHorizontallyCentered = marginLeftPx > 100 &&
+            marginRightPx > 100 &&
+            Math.abs(marginLeftPx - marginRightPx) < 2 && // Allow 1px rounding
+            marginTopPx === 0 &&
+            marginBottomPx === 0;
+        if (!hasAuto && !isHorizontallyCentered && ancestor.margin === "0px") {
+            return null; // All zeros, skip
+        }
+        // If has auto, always show detailed breakdown with arrows
+        if (hasAuto) {
+            const parts = [];
+            if (ancestor.marginTop !== "0px") {
+                parts.push(`↑${ancestor.marginTop}`);
+            }
+            if (ancestor.marginRight === "auto" || ancestor.marginRight !== "0px") {
+                parts.push(`→${ancestor.marginRight}`);
+            }
+            if (ancestor.marginBottom !== "0px") {
+                parts.push(`↓${ancestor.marginBottom}`);
+            }
+            if (ancestor.marginLeft === "auto" || ancestor.marginLeft !== "0px") {
+                parts.push(`←${ancestor.marginLeft}`);
+            }
+            const marginStr = `margin: ${parts.join(" ")}`;
+            // Add diagnostic if horizontally centered
+            if (ancestor.marginLeft === "auto" && ancestor.marginRight === "auto") {
+                return `${marginStr} ← Horizontally centered by auto margins`;
+            }
+            return marginStr;
+        }
+        // Show horizontal centering diagnostic
+        if (isHorizontallyCentered) {
+            return `margin: →${ancestor.marginRight} ←${ancestor.marginLeft} ← Horizontally centered (likely margin:0 auto)`;
+        }
+        // If non-uniform and non-zero, show with arrows
+        if (isNonUniform && ancestor.margin !== "0px") {
+            const parts = [];
+            if (ancestor.marginTop !== "0px") {
+                parts.push(`↑${ancestor.marginTop}`);
+            }
+            if (ancestor.marginRight !== "0px") {
+                parts.push(`→${ancestor.marginRight}`);
+            }
+            if (ancestor.marginBottom !== "0px") {
+                parts.push(`↓${ancestor.marginBottom}`);
+            }
+            if (ancestor.marginLeft !== "0px") {
+                parts.push(`←${ancestor.marginLeft}`);
+            }
+            return `margin: ${parts.join(" ")}`;
+        }
+        return null;
+    }
     generateDiagnostics(ancestor, index) {
         const diagnostics = [];
         // Overflow hidden warning
@@ -232,11 +357,6 @@ export class InspectAncestorsTool extends BrowserToolBase {
         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/interaction.js

@@ -36,11 +36,8 @@ export class ClickAndSwitchTabTool extends BrowserToolBase {
             ]);
             // Wait for the new page to load
             await newPage.waitForLoadState('domcontentloaded');
-            // Switch control to the new tab
-            setGlobalPage(newPage);
-            //page= newPage; // Update the current page to the new tab
-            //context.page = newPage;
-            //context.page.bringToFront(); // Bring the new tab to the front
+            // Switch control to the new tab and register listeners
+            await setGlobalPage(newPage);
             return createSuccessResponse(`Clicked link and switched to new tab: ${newPage.url()}`);
             //return createSuccessResponse(`Clicked link and switched to new tab: ${context.page.url()}`);
         });

package/dist/tools/browser/visiblePage.js

@@ -21,8 +21,25 @@ export class VisibleTextTool extends BrowserToolBase {
         }
         return this.safeExecute(context, async (page) => {
             try {
-                const visibleText = await page.evaluate(() => {
-                    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+                // Normalize selector (support testid: shorthand)
+                const selector = args.selector ? this.normalizeSelector(args.selector) : undefined;
+                // If selector provided, validate element exists
+                if (selector) {
+                    const element = await page.$(selector);
+                    if (!element) {
+                        return createErrorResponse(`Element with selector "${args.selector}" not found`);
+                    }
+                }
+                const visibleText = await page.evaluate((sel) => {
+                    // Find root element - either selected element or body
+                    let rootElement = document.body;
+                    if (sel) {
+                        const element = document.querySelector(sel);
+                        if (!element)
+                            return ""; // Should not happen due to earlier check, but be safe
+                        rootElement = element;
+                    }
+                    const walker = document.createTreeWalker(rootElement, NodeFilter.SHOW_TEXT, {
                         acceptNode: (node) => {
                             const style = window.getComputedStyle(node.parentElement);
                             return (style.display !== "none" && style.visibility !== "hidden")
@@ -39,7 +56,7 @@ export class VisibleTextTool extends BrowserToolBase {
                         }
                     }
                     return text.trim();
-                });
+                }, selector);
                 // Truncate logic
                 const maxLength = typeof args.maxLength === 'number' ? args.maxLength : 20000;
                 let output = visibleText;
@@ -48,7 +65,13 @@ export class VisibleTextTool extends BrowserToolBase {
                     output = output.slice(0, maxLength) + '\n[Output truncated due to size limits]';
                     truncated = true;
                 }
-                return createSuccessResponse(`Visible text content:\n${output}`);
+                // Add guidance footer
+                const scopeInfo = selector ? ` (from "${args.selector}")` : " (entire page)";
+                const guidance = `\n\n💡 TIP: If you need structured inspection rather than raw text:
+   • inspect_dom() - See page structure with positions and relationships
+   • find_by_text("text") - Locate specific text with element context
+   • query_selector("selector") - Find and inspect specific elements`;
+                return createSuccessResponse(`Visible text content${scopeInfo}:\n${output}${guidance}`);
             }
             catch (error) {
                 return createErrorResponse(`Failed to get visible text content: ${error.message}`);
@@ -76,91 +99,80 @@ export class VisibleHtmlTool extends BrowserToolBase {
         }
         return this.safeExecute(context, async (page) => {
             try {
-                const { removeComments, removeStyles, removeMeta, minify, cleanHtml } = args;
-                // Default removeScripts to true unless explicitly set to false
-                const removeScripts = args.removeScripts === false ? false : true;
                 // Normalize selector (support testid: shorthand)
                 const selector = args.selector ? this.normalizeSelector(args.selector) : undefined;
+                // If selector provided, validate element exists
+                if (selector) {
+                    const element = await page.$(selector);
+                    if (!element) {
+                        return createErrorResponse(`Element with selector "${args.selector}" not found`);
+                    }
+                }
                 // Get the HTML content
                 let htmlContent;
                 if (selector) {
                     // If a selector is provided, get only the HTML for that element
                     const element = await page.$(selector);
-                    if (!element) {
-                        return createErrorResponse(`Element with selector "${selector}" not found`);
-                    }
                     htmlContent = await page.evaluate((el) => el.outerHTML, element);
                 }
                 else {
                     // Otherwise get the full page HTML
                     htmlContent = await page.content();
                 }
-                // Determine if we need to apply filters
-                const shouldRemoveScripts = removeScripts || cleanHtml;
-                const shouldRemoveComments = removeComments || cleanHtml;
-                const shouldRemoveStyles = removeStyles || cleanHtml;
-                const shouldRemoveMeta = removeMeta || cleanHtml;
+                // Determine cleanup level
+                // Default: remove scripts only (security/size)
+                // clean=true: remove scripts + styles + comments + meta
+                const clean = args.clean === true;
                 // Apply filters in the browser context
-                if (shouldRemoveScripts || shouldRemoveComments || shouldRemoveStyles || shouldRemoveMeta || minify) {
-                    htmlContent = await page.evaluate(({ html, removeScripts, removeComments, removeStyles, removeMeta, minify }) => {
-                        // Create a DOM parser to work with the HTML
-                        const parser = new DOMParser();
-                        const doc = parser.parseFromString(html, 'text/html');
-                        // Remove script tags if requested
-                        if (removeScripts) {
-                            const scripts = doc.querySelectorAll('script');
-                            scripts.forEach(script => script.remove());
-                        }
-                        // Remove style tags if requested
-                        if (removeStyles) {
-                            const styles = doc.querySelectorAll('style');
-                            styles.forEach(style => style.remove());
-                        }
-                        // Remove meta tags if requested
-                        if (removeMeta) {
-                            const metaTags = doc.querySelectorAll('meta');
-                            metaTags.forEach(meta => meta.remove());
-                        }
-                        // Remove HTML comments if requested
-                        if (removeComments) {
-                            const removeComments = (node) => {
-                                const childNodes = node.childNodes;
-                                for (let i = childNodes.length - 1; i >= 0; i--) {
-                                    const child = childNodes[i];
-                                    if (child.nodeType === 8) { // 8 is for comment nodes
-                                        node.removeChild(child);
-                                    }
-                                    else if (child.nodeType === 1) { // 1 is for element nodes
-                                        removeComments(child);
-                                    }
+                htmlContent = await page.evaluate(({ html, clean }) => {
+                    // Create a DOM parser to work with the HTML
+                    const parser = new DOMParser();
+                    const doc = parser.parseFromString(html, 'text/html');
+                    // Always remove scripts (default behavior)
+                    const scripts = doc.querySelectorAll('script');
+                    scripts.forEach(script => script.remove());
+                    // If clean=true, remove additional noise
+                    if (clean) {
+                        // Remove style tags
+                        const styles = doc.querySelectorAll('style');
+                        styles.forEach(style => style.remove());
+                        // Remove meta tags
+                        const metaTags = doc.querySelectorAll('meta');
+                        metaTags.forEach(meta => meta.remove());
+                        // Remove HTML comments
+                        const removeCommentsRecursive = (node) => {
+                            const childNodes = node.childNodes;
+                            for (let i = childNodes.length - 1; i >= 0; i--) {
+                                const child = childNodes[i];
+                                if (child.nodeType === 8) { // 8 is for comment nodes
+                                    node.removeChild(child);
                                 }
-                            };
-                            removeComments(doc.documentElement);
-                        }
-                        // Get the processed HTML
-                        let result = doc.documentElement.outerHTML;
-                        // Minify if requested
-                        if (minify) {
-                            // Simple minification: remove extra whitespace
-                            result = result.replace(/>\s+</g, '><').trim();
-                        }
-                        return result;
-                    }, {
-                        html: htmlContent,
-                        removeScripts: shouldRemoveScripts,
-                        removeComments: shouldRemoveComments,
-                        removeStyles: shouldRemoveStyles,
-                        removeMeta: shouldRemoveMeta,
-                        minify
-                    });
-                }
+                                else if (child.nodeType === 1) { // 1 is for element nodes
+                                    removeCommentsRecursive(child);
+                                }
+                            }
+                        };
+                        removeCommentsRecursive(doc.documentElement);
+                    }
+                    // Get the processed HTML
+                    return doc.documentElement.outerHTML;
+                }, { html: htmlContent, clean });
                 // Truncate logic
                 const maxLength = typeof args.maxLength === 'number' ? args.maxLength : 20000;
                 let output = htmlContent;
+                let truncated = false;
                 if (output.length > maxLength) {
                     output = output.slice(0, maxLength) + '\n<!-- Output truncated due to size limits -->';
+                    truncated = true;
                 }
-                return createSuccessResponse(`HTML content:\n${output}`);
+                // Add guidance footer
+                const scopeInfo = selector ? ` (from "${args.selector}")` : " (entire page)";
+                const cleanInfo = clean ? ", clean mode" : ", scripts removed";
+                const guidance = `\n\n💡 TIP: If you need structured inspection rather than raw HTML:
+   • inspect_dom() - See page structure with positions and relationships
+   • query_selector("selector") - Find and inspect specific elements
+   • get_computed_styles("selector") - Get CSS values for elements`;
+                return createSuccessResponse(`HTML content${scopeInfo}${cleanInfo}:\n${output}${guidance}`);
             }
             catch (error) {
                 return createErrorResponse(`Failed to get visible HTML content: ${error.message}`);

package/dist/tools.d.ts

@@ -2,6 +2,7 @@ interface SessionConfig {
     saveSession: boolean;
     userDataDir: string;
     screenshotsDir: string;
+    headlessDefault: boolean;
 }
 export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     readonly name: "navigate";
@@ -41,7 +42,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
             };
             readonly headless: {
                 readonly type: "boolean";
-                readonly description: "Run browser in headless mode (default: false)";
+                readonly description: "Run browser in headless mode (default: true - no window shown)" | "Run browser in headless mode (default: false - browser window visible)";
             };
         };
         readonly required: readonly ["url"];
@@ -202,45 +203,34 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     readonly name: "get_text";
-    readonly description: "Get the visible text content of the current page";
+    readonly description: "⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Returns plain text up to 20000 chars (truncated if longer). Supports testid shortcuts.";
     readonly inputSchema: {
         readonly type: "object";
-        readonly properties: {};
+        readonly properties: {
+            readonly selector: {
+                readonly type: "string";
+                readonly description: "CSS selector, text selector, or testid shorthand to limit text extraction to a specific container. Omit to get text from entire page. Example: 'testid:article-body' or '#main-content'";
+            };
+            readonly maxLength: {
+                readonly type: "number";
+                readonly description: "Maximum number of characters to return (default: 20000)";
+            };
+        };
         readonly required: readonly [];
     };
 }, {
     readonly name: "get_html";
-    readonly description: "Get raw HTML content of the page or specific element. ⚠️ For understanding page structure, use inspect_dom() instead - it's more efficient and filters out noise. Use get_html() only when you need the actual HTML markup (e.g., to check specific attributes or element nesting).";
+    readonly description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Returns HTML up to 20000 chars (truncated if longer), scripts removed by default for security/size. Supports testid shortcuts.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
             readonly selector: {
                 readonly type: "string";
-                readonly description: "CSS selector to limit the HTML to a specific container";
-            };
-            readonly removeScripts: {
-                readonly type: "boolean";
-                readonly description: "Remove all script tags from the HTML (default: true)";
-            };
-            readonly removeComments: {
-                readonly type: "boolean";
-                readonly description: "Remove all HTML comments (default: false)";
-            };
-            readonly removeStyles: {
-                readonly type: "boolean";
-                readonly description: "Remove all style tags from the HTML (default: false)";
-            };
-            readonly removeMeta: {
-                readonly type: "boolean";
-                readonly description: "Remove all meta tags from the HTML (default: false)";
-            };
-            readonly cleanHtml: {
-                readonly type: "boolean";
-                readonly description: "Perform comprehensive HTML cleaning (default: false)";
+                readonly description: "CSS selector, text selector, or testid shorthand to limit HTML extraction to a specific container. Omit to get entire page HTML. Example: 'testid:main-content' or '#app'";
             };
-            readonly minify: {
+            readonly clean: {
                 readonly type: "boolean";
-                readonly description: "Minify the HTML output (default: false)";
+                readonly description: "Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup";
             };
             readonly maxLength: {
                 readonly type: "number";
@@ -470,7 +460,7 @@ export declare function createToolDefinitions(sessionConfig?: SessionConfig): [{
     };
 }, {
     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 description: "DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Shows for each ancestor: position/size, width constraints (w, max-w, min-w), margins with directional arrows (↑↓←→ format), padding, display type, borders (directional if non-uniform), overflow (🔒=hidden, ↕️=scroll), flexbox context (flex direction justify items gap), grid context (cols rows gap), position/z-index/transform when set. Automatically detects horizontal centering via auto margins and flags clipping points (🎯). Essential for debugging unexpected centering, constrained width, or clipped content. Default: 10 ancestors (reaches <body> in most React apps), max: 15. Use after inspect_dom() to understand parent layout constraints.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/dist/tools.js

@@ -3,6 +3,7 @@ export function createToolDefinitions(sessionConfig) {
     const sessionEnabled = sessionConfig?.saveSession ?? true;
     const userDataDir = sessionConfig?.userDataDir || './.mcp-web-inspector/user-data';
     const screenshotsDir = sessionConfig?.screenshotsDir || './.mcp-web-inspector/screenshots';
+    const headlessDefault = sessionConfig?.headlessDefault ?? false;
     const navigateDescription = sessionEnabled
         ? `Navigate to a URL. Browser sessions (cookies, localStorage, sessionStorage) are automatically saved in ${userDataDir} directory and persist across restarts. To clear saved sessions, delete the directory.`
         : "Navigate to a URL. Browser starts fresh each time with no persistent session state (started with --no-save-session flag).";
@@ -24,7 +25,7 @@ export function createToolDefinitions(sessionConfig) {
                     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)" }
+                    headless: { type: "boolean", description: `Run browser in headless mode (default: ${headlessDefault ? 'true - no window shown' : 'false - browser window visible'})` }
                 },
                 required: ["url"],
             },
@@ -167,27 +168,40 @@ export function createToolDefinitions(sessionConfig) {
         },
         {
             name: "get_text",
-            description: "Get the visible text content of the current page",
+            description: "⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Returns plain text up to 20000 chars (truncated if longer). Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
-                properties: {},
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector, text selector, or testid shorthand to limit text extraction to a specific container. Omit to get text from entire page. Example: 'testid:article-body' or '#main-content'"
+                    },
+                    maxLength: {
+                        type: "number",
+                        description: "Maximum number of characters to return (default: 20000)"
+                    }
+                },
                 required: [],
             },
         },
         {
             name: "get_html",
-            description: "Get raw HTML content of the page or specific element. ⚠️ For understanding page structure, use inspect_dom() instead - it's more efficient and filters out noise. Use get_html() only when you need the actual HTML markup (e.g., to check specific attributes or element nesting).",
+            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Returns HTML up to 20000 chars (truncated if longer), scripts removed by default for security/size. Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    selector: { type: "string", description: "CSS selector to limit the HTML to a specific container" },
-                    removeScripts: { type: "boolean", description: "Remove all script tags from the HTML (default: true)" },
-                    removeComments: { type: "boolean", description: "Remove all HTML comments (default: false)" },
-                    removeStyles: { type: "boolean", description: "Remove all style tags from the HTML (default: false)" },
-                    removeMeta: { type: "boolean", description: "Remove all meta tags from the HTML (default: false)" },
-                    cleanHtml: { type: "boolean", description: "Perform comprehensive HTML cleaning (default: false)" },
-                    minify: { type: "boolean", description: "Minify the HTML output (default: false)" },
-                    maxLength: { type: "number", description: "Maximum number of characters to return (default: 20000)" }
+                    selector: {
+                        type: "string",
+                        description: "CSS selector, text selector, or testid shorthand to limit HTML extraction to a specific container. Omit to get entire page HTML. Example: 'testid:main-content' or '#app'"
+                    },
+                    clean: {
+                        type: "boolean",
+                        description: "Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup"
+                    },
+                    maxLength: {
+                        type: "number",
+                        description: "Maximum number of characters to return (default: 20000)"
+                    }
                 },
                 required: [],
             },
@@ -439,7 +453,7 @@ More efficient than get_html() or evaluate(). Supports testid shortcuts.`,
         },
         {
             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.",
+            description: "DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints, margins, borders, and overflow clipping come from. Shows for each ancestor: position/size, width constraints (w, max-w, min-w), margins with directional arrows (↑↓←→ format), padding, display type, borders (directional if non-uniform), overflow (🔒=hidden, ↕️=scroll), flexbox context (flex direction justify items gap), grid context (cols rows gap), position/z-index/transform when set. Automatically detects horizontal centering via auto margins and flags clipping points (🎯). Essential for debugging unexpected centering, constrained width, or clipped content. Default: 10 ancestors (reaches <body> in most React apps), max: 15. Use after inspect_dom() to understand parent layout constraints.",
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

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