mcp-web-inspector 0.6.0 → 0.8.0

package/README.md

@@ -319,6 +319,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)
+- **`--expose-sensitive-network-data`** - Loosen redaction for sensitive network headers (e.g., show truncated auth/cookie values). Disabled by default for safety.
 
 **Example usage:**
 ```json
@@ -350,7 +351,7 @@ Customize server behavior with command line flags:
   "mcpServers": {
     "web-inspector": {
       "command": "npx",
-      "args": ["-y", "mcp-web-inspector", "--headless", "--no-save-session"]
+      "args": ["-y", "mcp-web-inspector", "--headless", "--no-save-session", "--user-data-dir", "./.mcp-web-inspector"]
     }
   }
 }
@@ -495,7 +496,6 @@ RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use com
   - includeHidden (boolean, optional): Include hidden elements in results (default: false)
   - maxChildren (number, optional): Maximum number of children to show (default: 20)
   - maxDepth (number, optional): Maximum depth to drill through non-semantic wrapper elements when looking for semantic children (default: 5). Increase for extremely deeply nested components, decrease to 1 to see only immediate children without drilling.
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
 
 - Output Format:
   - Optional selection header when multiple matches (with chosen index).
@@ -542,7 +542,6 @@ DEBUG LAYOUT CONSTRAINTS: Walk up the DOM tree to find where width constraints,
 - Parameters:
   - selector (string, required): CSS selector or testid shorthand for the element to start from (e.g., 'testid:header', '#main')
   - limit (number, optional): Maximum number of ancestors to traverse (default: 10, max: 15). Increase for deeply nested component frameworks.
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
 
 - Output Format:
   - Header showing selected element index when selector matched multiple.
@@ -634,7 +633,6 @@ INSPECT CSS PROPERTIES: Get computed CSS values for specific properties (display
 - Parameters:
   - selector (string, required): CSS selector, text selector, or testid shorthand (e.g., 'testid:submit-button', '#main')
   - properties (string, optional): Comma-separated list of CSS properties to retrieve (e.g., 'display,width,color'). If not specified, returns common layout properties: display, position, width, height, opacity, visibility, z-index, overflow, margin, padding, font-size, font-weight, color, background-color
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
 
 - Output Format:
   - Optional selection header when multiple elements matched.
@@ -648,7 +646,10 @@ INSPECT CSS PROPERTIES: Get computed CSS values for specific properties (display
 
 - Example Output (get_computed_styles({ selector: 'testid:login-form' })):
 ```
-⚠ Warning: Selector matched 2 elements, showing 1 (use elementIndex to target a specific one)
+⚠ Found 2 elements matching "testid:login-form", using element 1 (first visible)
+💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.
+   Primary fix: add data-testid and target it (e.g., testid:submit).
+   Workaround: use '>> nth=<index>' only when you can't add test IDs.
 
 Computed Styles: <form data-testid="login-form">
 
@@ -679,7 +680,6 @@ Check if an element is visible to the user. CRITICAL for debugging click/interac
 
 - Parameters:
   - selector (string, required): CSS selector, text selector, or testid shorthand (e.g., 'testid:login-button', '#submit', 'text=Click here')
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
 
 - Output Format:
   - Header: Visibility: <tag id/class/testid>
@@ -692,7 +692,7 @@ Check if an element is visible to the user. CRITICAL for debugging click/interac
 
 - Examples:
 - check_visibility({ selector: 'testid:submit' })
-- check_visibility({ selector: '#login button', elementIndex: 2 })
+- check_visibility({ selector: '#login button' })
 
 - Example Output (check_visibility({ selector: 'testid:submit' })):
 ```
@@ -808,7 +808,6 @@ data-cy (2):
 
 - Parameters:
   - selector (string, required): CSS selector or testid shorthand (e.g., 'testid:submit', '#login-button')
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
 
 - Output Format:
   - Header: Element: <tag id/class/testid>
@@ -1001,16 +1000,14 @@ Upload a file to an input[type='file'] element on the page
 
 - Parameters:
   - selector (string, optional): 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'
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
   - clean (boolean, optional): Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `get_text`
-⚠️ 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.
+⚠️ 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. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts.
 
 - Parameters:
   - selector (string, optional): 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'
-  - elementIndex (number, optional): When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element.
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `visual_screenshot_for_humans`
@@ -1078,7 +1075,7 @@ Retrieve console logs with filtering and token‑efficient output. Defaults: sin
 ### Network
 
 #### `get_request_details`
-Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. Essential for debugging API responses and investigating failed requests.
+Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. If a request or response body exceeds 500 chars, includes a preview and a one-time confirm_output token that, when called, saves the full body to disk under ./.mcp-web-inspector/network-bodies/ and returns the file path(s). Essential for debugging API responses and investigating failed requests.
 
 - Parameters:
   - index (number, required): Index of the request from list_network_requests output (e.g., [0], [1], etc.)

package/dist/index.js

@@ -10,6 +10,12 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 // Get package.json version
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+// Expose package root for tools that need to spawn child processes (e.g., npx playwright)
+// Tests and non-CLI environments can override or ignore this.
+if (!process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT) {
+    process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT = PACKAGE_ROOT;
+}
 const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 const VERSION = packageJson.version;
 // Parse command line arguments
@@ -19,6 +25,10 @@ const { values } = parseArgs({
             type: 'boolean',
             default: false,
         },
+        'expose-sensitive-network-data': {
+            type: 'boolean',
+            default: false,
+        },
         'user-data-dir': {
             type: 'string',
             default: './.mcp-web-inspector',
@@ -45,6 +55,7 @@ const sessionConfig = {
     userDataDir: `${baseDir}/user-data`,
     screenshotsDir: `${baseDir}/screenshots`,
     headlessDefault: Boolean(values['headless']),
+    exposeSensitiveNetworkData: Boolean(values['expose-sensitive-network-data']),
 };
 setSessionConfig(sessionConfig);
 async function runServer() {
@@ -74,7 +85,7 @@ async function runServer() {
     setupRequestHandlers(server, TOOLS);
     // Graceful shutdown logic
     function shutdown() {
-        console.log('Shutdown signal received');
+        console.error('Shutdown signal received');
         process.exit(0);
     }
     process.on('SIGINT', shutdown);

package/dist/toolHandler.d.ts

@@ -24,6 +24,10 @@ type ColorSchemeOverride = 'light' | 'dark' | 'no-preference';
  * Sets the session configuration
  */
 export declare function setSessionConfig(config: Partial<SessionConfig>): void;
+/**
+ * Gets the current session configuration
+ */
+export declare function getSessionConfig(): SessionConfig;
 /**
  * Gets the screenshots directory
  */

package/dist/toolHandler.js

@@ -12,14 +12,25 @@ let sessionConfig = {
     userDataDir: './.mcp-web-inspector/user-data',
     screenshotsDir: './.mcp-web-inspector/screenshots',
     headlessDefault: false,
+    exposeSensitiveNetworkData: false,
 };
 let colorSchemeOverride = null;
+// Resolve package root for child processes (like npx). Entry point sets
+// MCP_WEB_INSPECTOR_PACKAGE_ROOT using import.meta.url; tests and other
+// environments fall back to process.cwd().
+const PACKAGE_ROOT = process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT || process.cwd();
 /**
  * Sets the session configuration
  */
 export function setSessionConfig(config) {
     sessionConfig = { ...sessionConfig, ...config };
 }
+/**
+ * Gets the current session configuration
+ */
+export function getSessionConfig() {
+    return sessionConfig;
+}
 /**
  * Gets the screenshots directory
  */
@@ -42,6 +53,7 @@ export function resetBrowserState() {
     currentBrowserType = 'chromium';
     currentDevice = undefined;
     networkLog = [];
+    clearConsoleLogs();
 }
 /**
  * Gets the network log
@@ -66,7 +78,7 @@ export async function setGlobalPage(newPage) {
     await registerNetworkListeners(page);
     await applyColorScheme(page);
     page.bringToFront(); // Bring the new tab to the front
-    console.log("Global page has been updated with listeners registered.");
+    console.error("Global page has been updated with listeners registered.");
 }
 function getColorSchemeValue() {
     return colorSchemeOverride;
@@ -300,9 +312,10 @@ export async function ensureBrowser(browserSettings) {
                     const { execSync } = await import('child_process');
                     execSync('npx playwright install chromium firefox webkit', {
                         stdio: 'inherit',
-                        encoding: 'utf8'
+                        encoding: 'utf8',
+                        cwd: PACKAGE_ROOT,
                     });
-                    console.log('✅ Browsers installed successfully! Starting browser...');
+                    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.
                 }
@@ -346,7 +359,7 @@ export async function ensureBrowser(browserSettings) {
                 const targetHeight = height ?? currentViewport?.height ?? 720;
                 // Check if viewport size actually changed
                 if (!currentViewport || currentViewport.width !== targetWidth || currentViewport.height !== targetHeight) {
-                    console.log(`Resizing viewport to ${targetWidth}x${targetHeight}`);
+                    console.error(`Resizing viewport to ${targetWidth}x${targetHeight}`);
                     await page.setViewportSize({ width: targetWidth, height: targetHeight });
                 }
             }
@@ -371,7 +384,7 @@ export async function ensureBrowser(browserSettings) {
                 // Check custom configs first, then Playwright's built-in devices
                 deviceConfig = CUSTOM_DEVICE_CONFIGS[playwrightDeviceName] || devices[playwrightDeviceName];
                 if (deviceConfig) {
-                    console.log(`Using device preset: ${device} (${playwrightDeviceName})`);
+                    console.error(`Using device preset: ${device} (${playwrightDeviceName})`);
                     currentDevice = device;
                 }
                 else {
@@ -412,7 +425,7 @@ export async function ensureBrowser(browserSettings) {
                 viewportWidth = screenSize?.width ?? 1280;
                 viewportHeight = screenSize?.height ?? 720;
                 if (screenSize && screenSize.width > 0 && screenSize.height > 0) {
-                    console.log(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
+                    console.error(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
                 }
             }
             // Prepare context options

package/dist/tools/browser/base.js

@@ -20,6 +20,10 @@ export class BrowserToolBase {
      * @returns Normalized selector
      */
     normalizeSelector(selector) {
+        const raw = selector.trim();
+        if (!raw) {
+            return '';
+        }
         const prefixMap = {
             'testid:': 'data-testid',
             'data-test:': 'data-test',
@@ -27,12 +31,23 @@ export class BrowserToolBase {
         };
         // Handle testid shortcuts first
         for (const [prefix, attr] of Object.entries(prefixMap)) {
-            if (selector.startsWith(prefix)) {
-                const value = selector.slice(prefix.length);
-                return `[${attr}="${value}"]`;
+            if (raw.startsWith(prefix)) {
+                const rest = raw.slice(prefix.length);
+                // Allow combined selectors like:
+                //   "testid:chat-buttons button:first-child"
+                //   "testid:chat-buttons\n  button:first-child"
+                // We treat the portion immediately after the prefix up to the first
+                // whitespace or combinator as the attribute value, and append the tail.
+                const splitIndex = rest.search(/[\s>+~,]/);
+                if (splitIndex === -1) {
+                    return `[${attr}="${rest}"]`;
+                }
+                const attrValue = rest.slice(0, splitIndex);
+                const tail = rest.slice(splitIndex);
+                return `[${attr}="${attrValue}"]${tail}`;
             }
         }
-        const trimmed = selector.trim();
+        const trimmed = raw;
         // Helper: unescape simple backslash-escapes used inside IDs (e.g., \:, \[, \])
         const unescapeCssIdentifier = (s) => {
             // Collapse multiple backslashes before a single char to the char itself
@@ -158,8 +173,9 @@ export class BrowserToolBase {
      * Record that a navigation occurred (for console log filtering)
      */
     recordNavigation() {
-        import('../../toolHandler.js').then(({ updateLastNavigationTimestamp }) => {
+        import('../../toolHandler.js').then(({ updateLastNavigationTimestamp, updateLastInteractionTimestamp }) => {
             updateLastNavigationTimestamp();
+            updateLastInteractionTimestamp();
         });
     }
     /**

package/dist/tools/browser/content/get_html.js

@@ -16,10 +16,6 @@ export class GetHtmlTool extends BrowserToolBase {
                         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'"
                     },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
-                    },
                     clean: {
                         type: "boolean",
                         description: "Remove noise from HTML: false (default) = remove scripts only, true = remove scripts + styles + comments + meta tags for minimal markup"
@@ -59,7 +55,6 @@ export class GetHtmlTool extends BrowserToolBase {
                     const normalizedSelector = this.normalizeSelector(args.selector);
                     const locator = page.locator(normalizedSelector);
                     const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
-                        elementIndex: args.elementIndex,
                         originalSelector: args.selector,
                     });
                     selectionWarning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount, true);

package/dist/tools/browser/content/get_text.js

@@ -1,5 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for getting visible text from the page
  */
@@ -7,7 +8,7 @@ export class GetTextTool extends BrowserToolBase {
     static getMetadata(sessionConfig) {
         return {
             name: "get_text",
-            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.",
+            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. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -15,10 +16,6 @@ export class GetTextTool extends BrowserToolBase {
                         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'"
                     },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
-                    },
                     maxLength: {
                         type: "number",
                         description: "Maximum number of characters to return (default: 20000)"
@@ -32,6 +29,7 @@ export class GetTextTool extends BrowserToolBase {
         const requestedMaxLength = typeof args.maxLength === 'number' && Number.isFinite(args.maxLength) && args.maxLength > 0
             ? Math.floor(args.maxLength)
             : 20000;
+        const PREVIEW_THRESHOLD = 2000;
         if (!context.page) {
             return createErrorResponse('Page is not available');
         }
@@ -52,7 +50,6 @@ export class GetTextTool extends BrowserToolBase {
                     const normalizedSelector = this.normalizeSelector(args.selector);
                     const locator = page.locator(normalizedSelector);
                     const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
-                        elementIndex: args.elementIndex,
                         originalSelector: args.selector,
                     });
                     selectionWarning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount, true);
@@ -73,8 +70,35 @@ export class GetTextTool extends BrowserToolBase {
                 if (selectionWarning) {
                     lines.push(selectionWarning.trimEnd());
                 }
-                lines.push('');
                 const safeMaxLength = requestedMaxLength > 0 ? requestedMaxLength : 20000;
+                const totalLength = textContent.length;
+                // Large-output guard: return preview + confirm_output token when text is big
+                if (totalLength >= PREVIEW_THRESHOLD) {
+                    const preview = makeConfirmPreview(() => textContent, {
+                        counts: {
+                            totalLength,
+                            shownLength: Math.min(500, totalLength),
+                            truncated: true,
+                        },
+                        previewLines: [
+                            'Preview (first 500 chars):',
+                            textContent.slice(0, 500),
+                            ...(totalLength > 500 ? ['...'] : []),
+                            '',
+                            '⚠️ Full text not returned to save tokens',
+                            '',
+                            '💡 RECOMMENDED: Use token-efficient alternatives:',
+                            '   • inspect_dom() - structured view with positions and layout',
+                            '   • find_by_text() - locate specific text with context',
+                            '   • query_selector() - inspect specific elements',
+                        ],
+                    });
+                    lines.push(`Text size: ${totalLength.toLocaleString()} characters (exceeds ${PREVIEW_THRESHOLD} char threshold)`);
+                    lines.push('');
+                    lines.push(...preview.lines);
+                    return createSuccessResponse(lines.join('\n'));
+                }
+                lines.push('');
                 let displayText = textContent;
                 const truncated = displayText.length > safeMaxLength;
                 if (truncated) {

package/dist/tools/browser/evaluation/evaluate.js

@@ -1,6 +1,7 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
 import { makeConfirmPreview } from '../../common/confirm_output.js';
+import { gatherConsoleErrorsSince, quickNetworkIdleNote } from '../common/postAction.js';
 /**
  * Tool for executing JavaScript in the browser
  */
@@ -113,6 +114,21 @@ export class EvaluateTool extends BrowserToolBase {
                 '   Why: Playwright auto-scrolls before interactions, but these tools help with\n' +
                 '        testing scroll behavior, lazy-loading, and scroll-triggered content');
         }
+        // Pattern: Navigation (top-level or SPA routing)
+        // Detect common navigation attempts: window.location / document.location assignments,
+        // location.assign|replace, history.pushState|replaceState, and href changes.
+        if (scriptLower.match(/\blocation\s*\./) ||
+            scriptLower.match(/window\s*\.\s*location/) ||
+            scriptLower.match(/document\s*\.\s*location/) ||
+            scriptLower.match(/history\s*\.\s*pushstate|history\s*\.\s*replacestate/) ||
+            scriptLower.match(/location\s*=(?!\s*location)/) ||
+            scriptLower.match(/location\s*\.\s*href\s*=|location\s*\.\s*assign|location\s*\.\s*replace/)) {
+            suggestions.push('🌐 Navigation\n' +
+                '   • navigate({ url: "..." }) — full document navigation with proper waits\n' +
+                '   • SPA-only: click a router link or evaluate history.pushState(...), then wait_for_element\n' +
+                '   • go_history for back/forward\n' +
+                '   Note: setting window.location.href causes a reload; prefer navigate for reliability');
+        }
         return suggestions;
     }
     async execute(args, context) {
@@ -267,6 +283,43 @@ export class EvaluateTool extends BrowserToolBase {
                     resultStr = String(evalReturn);
                 }
             }
+            // Detect navigation patterns in the script for post-action waits
+            const scriptLower = (args.script || '').toLowerCase();
+            const navDetected = (/\blocation\s*\./.test(scriptLower) ||
+                /window\s*\.\s*location/.test(scriptLower) ||
+                /document\s*\.\s*location/.test(scriptLower) ||
+                /history\s*\.\s*pushstate|history\s*\.\s*replacestate/.test(scriptLower) ||
+                /location\s*=(?!\s*location)/.test(scriptLower) ||
+                /location\s*\.\s*href\s*=|location\s*\.\s*assign|location\s*\.\s*replace/.test(scriptLower));
+            // Optional quick network-idle note when navigation is detected
+            let netIdleNote = null;
+            if (navDetected) {
+                try {
+                    const note = await quickNetworkIdleNote(page);
+                    if (note)
+                        netIdleNote = note;
+                }
+                catch {
+                    // ignore
+                }
+            }
+            // After script execution (and any quick wait), surface console errors since this interaction
+            try {
+                const errs = await gatherConsoleErrorsSince('interaction');
+                if (errs.length > 0) {
+                    let titleInfo = '';
+                    try {
+                        const t = await page.title();
+                        if (t)
+                            titleInfo = `\nTitle: ${t}`;
+                    }
+                    catch { }
+                    return createErrorResponse(`Console error after evaluate: ${errs[0]}${titleInfo}`);
+                }
+            }
+            catch {
+                // Best-effort; continue on failure
+            }
             // Guard for large outputs: preview + confirm
             const totalLength = resultStr.length;
             const lines = [];
@@ -285,6 +338,10 @@ export class EvaluateTool extends BrowserToolBase {
                     extraTips: ['Tip: Prefer specialized tools or narrow the script when possible.'],
                 });
                 lines.push(...previewBlock.lines);
+                if (netIdleNote) {
+                    lines.push('');
+                    lines.push(netIdleNote);
+                }
                 if (suggestions.length > 0) {
                     lines.push('');
                     lines.push('💡 Consider specialized tools:');
@@ -293,6 +350,10 @@ export class EvaluateTool extends BrowserToolBase {
                 return createSuccessResponse(lines);
             }
             const messages = [`✓ JavaScript execution result:`, resultStr];
+            if (netIdleNote) {
+                messages.push('');
+                messages.push(netIdleNote);
+            }
             // Detect if specialized tools would be better
             if (suggestions.length > 0) {
                 messages.push('');

package/dist/tools/browser/inspection/check_visibility.js

@@ -21,7 +21,7 @@ export class CheckVisibilityTool extends BrowserToolBase {
             ],
             examples: [
                 "check_visibility({ selector: 'testid:submit' })",
-                "check_visibility({ selector: '#login button', elementIndex: 2 })",
+                "check_visibility({ selector: '#login button' })",
             ],
             exampleOutputs: [
                 {
@@ -39,10 +39,6 @@ export class CheckVisibilityTool extends BrowserToolBase {
                     selector: {
                         type: "string",
                         description: "CSS selector, text selector, or testid shorthand (e.g., 'testid:login-button', '#submit', 'text=Click here')"
-                    },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
                     }
                 },
                 required: ["selector"],
@@ -59,7 +55,6 @@ export class CheckVisibilityTool extends BrowserToolBase {
             try {
                 // Use standard element selection with visibility preference
                 const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
-                    elementIndex: args.elementIndex,
                     originalSelector: args.selector,
                 });
                 // Format selection warning if multiple elements matched

package/dist/tools/browser/inspection/get_computed_styles.d.ts

@@ -1,13 +1,11 @@
 import { ToolHandler, ToolMetadata, SessionConfig } from '../../common/types.js';
 import { BrowserToolBase } from '../base.js';
 import type { ToolContext, ToolResponse } from '../../common/types.js';
-export interface GetComputedStylesArgs {
-    selector: string;
-    properties?: string;
-    elementIndex?: number;
-}
 export declare class GetComputedStylesTool extends BrowserToolBase implements ToolHandler {
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     private readonly DEFAULT_PROPERTIES;
-    execute(args: GetComputedStylesArgs, context: ToolContext): Promise<ToolResponse>;
+    execute(args: {
+        selector: string;
+        properties?: string;
+    }, context: ToolContext): Promise<ToolResponse>;
 }

package/dist/tools/browser/inspection/get_computed_styles.js

@@ -27,7 +27,7 @@ export class GetComputedStylesTool extends BrowserToolBase {
             exampleOutputs: [
                 {
                     call: "get_computed_styles({ selector: 'testid:login-form' })",
-                    output: `⚠ Warning: Selector matched 2 elements, showing 1 (use elementIndex to target a specific one)\n\nComputed Styles: <form data-testid=\"login-form\">\n\nLayout:\n  display: block\n  position: static\n  width: 560px\n  height: 480px\n\nVisibility:\n  opacity: 1\n  visibility: visible\n  z-index: auto\n  overflow: visible\n\nSpacing:\n  margin: 0px\n  padding: 24px\n\nTypography:\n  font-size: 16px\n  font-weight: 400\n  color: rgb(33, 37, 41)`
+                    output: `⚠ Found 2 elements matching \"testid:login-form\", using element 1 (first visible)\n💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n   Primary fix: add data-testid and target it (e.g., testid:submit).\n   Workaround: use '>> nth=<index>' only when you can't add test IDs.\n\nComputed Styles: <form data-testid=\"login-form\">\n\nLayout:\n  display: block\n  position: static\n  width: 560px\n  height: 480px\n\nVisibility:\n  opacity: 1\n  visibility: visible\n  z-index: auto\n  overflow: visible\n\nSpacing:\n  margin: 0px\n  padding: 24px\n\nTypography:\n  font-size: 16px\n  font-weight: 400\n  color: rgb(33, 37, 41)`
                 }
             ],
             inputSchema: {
@@ -40,10 +40,6 @@ export class GetComputedStylesTool extends BrowserToolBase {
                     properties: {
                         type: "string",
                         description: "Comma-separated list of CSS properties to retrieve (e.g., 'display,width,color'). If not specified, returns common layout properties: display, position, width, height, opacity, visibility, z-index, overflow, margin, padding, font-size, font-weight, color, background-color"
-                    },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
                     }
                 },
                 required: ["selector"],
@@ -60,7 +56,6 @@ export class GetComputedStylesTool extends BrowserToolBase {
             // Use standard element selection with visibility preference
             const locator = page.locator(normalizedSelector);
             const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
-                elementIndex: args.elementIndex,
                 originalSelector: args.selector,
             });
             // Format selection warning if multiple elements matched

package/dist/tools/browser/inspection/inspect_ancestors.js

@@ -42,10 +42,6 @@ export class InspectAncestorsTool extends BrowserToolBase {
                     limit: {
                         type: "number",
                         description: "Maximum number of ancestors to traverse (default: 10, max: 15). Increase for deeply nested component frameworks."
-                    },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
                     }
                 },
                 required: ["selector"],

package/dist/tools/browser/inspection/inspect_dom.js

@@ -83,10 +83,6 @@ RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use com
                     maxDepth: {
                         type: "number",
                         description: "Maximum depth to drill through non-semantic wrapper elements when looking for semantic children (default: 5). Increase for extremely deeply nested components, decrease to 1 to see only immediate children without drilling."
-                    },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
                     }
                 },
                 required: [],

package/dist/tools/browser/inspection/measure_element.d.ts

@@ -1,11 +1,9 @@
 import { ToolHandler, ToolMetadata, SessionConfig } from '../../common/types.js';
 import { BrowserToolBase } from '../base.js';
 import type { ToolContext, ToolResponse } from '../../common/types.js';
-export interface MeasureElementArgs {
-    selector: string;
-    elementIndex?: number;
-}
 export declare class MeasureElementTool extends BrowserToolBase implements ToolHandler {
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
-    execute(args: MeasureElementArgs, context: ToolContext): Promise<ToolResponse>;
+    execute(args: {
+        selector: string;
+    }, context: ToolContext): Promise<ToolResponse>;
 }

package/dist/tools/browser/inspection/measure_element.js

@@ -28,10 +28,6 @@ export class MeasureElementTool extends BrowserToolBase {
                     selector: {
                         type: "string",
                         description: "CSS selector or testid shorthand (e.g., 'testid:submit', '#login-button')"
-                    },
-                    elementIndex: {
-                        type: "number",
-                        description: "When selector matches multiple elements, use this 1-based index to select a specific one (e.g., 2 = second element). Default: first visible element."
                     }
                 },
                 required: ["selector"],
@@ -44,7 +40,6 @@ export class MeasureElementTool extends BrowserToolBase {
             // Use standard element selection with visibility preference
             const locator = page.locator(normalizedSelector);
             const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
-                elementIndex: args.elementIndex,
                 originalSelector: args.selector,
             });
             // Format selection warning if multiple elements matched

package/dist/tools/browser/network/get_request_details.js

@@ -1,9 +1,12 @@
+import fs from 'node:fs';
+import * as path from 'node:path';
 import { BrowserToolBase } from '../base.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 export class GetRequestDetailsTool extends BrowserToolBase {
     static getMetadata(sessionConfig) {
         return {
             name: "get_request_details",
-            description: "Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. Essential for debugging API responses and investigating failed requests.",
+            description: "Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. If a request or response body exceeds 500 chars, includes a preview and a one-time confirm_output token that, when called, saves the full body to disk under ./.mcp-web-inspector/network-bodies/ and returns the file path(s). Essential for debugging API responses and investigating failed requests.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -19,8 +22,10 @@ export class GetRequestDetailsTool extends BrowserToolBase {
     async execute(args, context) {
         return this.safeExecute(context, async () => {
             const { index } = args;
-            const { getNetworkLog } = await import('../../../toolHandler.js');
+            const { getNetworkLog, getSessionConfig } = await import('../../../toolHandler.js');
             const networkLog = getNetworkLog();
+            const sessionConfig = getSessionConfig();
+            const exposeSensitive = Boolean(sessionConfig?.exposeSensitiveNetworkData);
             if (index < 0 || index >= networkLog.length) {
                 return {
                     content: [{
@@ -31,6 +36,15 @@ export class GetRequestDetailsTool extends BrowserToolBase {
                 };
             }
             const req = networkLog[index];
+            // Helper to look up headers case-insensitively
+            const getHeader = (headers, key) => {
+                if (!headers)
+                    return undefined;
+                const found = Object.entries(headers).find(([k]) => k.toLowerCase() === key.toLowerCase());
+                return found ? String(found[1]) : undefined;
+            };
+            const reqContentType = getHeader(req.requestData.headers, 'content-type') || '';
+            const respContentType = getHeader(req.responseData?.headers || {}, 'content-type') || '';
             // Build compact text response
             const lines = [];
             lines.push(`Request Details [${index}]:\n`);
@@ -55,11 +69,10 @@ export class GetRequestDetailsTool extends BrowserToolBase {
                     return `${bytes} bytes`;
                 return `${(bytes / 1024).toFixed(1)}KB`;
             };
-            if (responseSize > 0) {
-                lines.push(`Size: ${formatBytes(requestSize)} → ${formatBytes(responseSize)}`);
-            }
-            else if (requestSize > 0) {
-                lines.push(`Size: ${formatBytes(requestSize)} →`);
+            if (responseSize > 0 || requestSize > 0) {
+                const reqPart = requestSize > 0 ? formatBytes(requestSize) : '0 bytes';
+                const respPart = responseSize > 0 ? formatBytes(responseSize) : '0 bytes';
+                lines.push(`Size: requestBody=${reqPart}, responseBody≈${respPart}`);
             }
             // Request headers (show important ones)
             const importantRequestHeaders = ['content-type', 'authorization', 'cookie', 'user-agent', 'accept'];
@@ -67,13 +80,36 @@ export class GetRequestDetailsTool extends BrowserToolBase {
                 .filter(([key]) => importantRequestHeaders.includes(key.toLowerCase()));
             if (reqHeaders.length > 0) {
                 lines.push('\nRequest Headers:');
-                reqHeaders.forEach(([key, value]) => {
-                    // Truncate sensitive values
-                    if (key.toLowerCase() === 'authorization' || key.toLowerCase() === 'cookie') {
-                        const truncated = value.length > 20
-                            ? value.substring(0, 17) + '...'
-                            : value;
-                        lines.push(`  ${key}: ${truncated}`);
+                const order = (name) => {
+                    const idx = importantRequestHeaders.indexOf(name.toLowerCase());
+                    return idx === -1 ? importantRequestHeaders.length : idx;
+                };
+                reqHeaders
+                    .sort(([a], [b]) => {
+                    const oa = order(a);
+                    const ob = order(b);
+                    if (oa !== ob)
+                        return oa - ob;
+                    return a.localeCompare(b);
+                })
+                    .forEach(([key, value]) => {
+                    const keyLower = key.toLowerCase();
+                    if (keyLower === 'authorization' || keyLower === 'cookie') {
+                        if (!exposeSensitive) {
+                            if (keyLower === 'authorization') {
+                                const scheme = value.split(' ')[0] || '';
+                                lines.push(`  ${key}: ${scheme ? `${scheme} <redacted>` : '<redacted>'}`);
+                            }
+                            else {
+                                lines.push(`  ${key}: <redacted>`);
+                            }
+                        }
+                        else {
+                            const truncated = value.length > 60
+                                ? value.substring(0, 57) + '...'
+                                : value;
+                            lines.push(`  ${key}: ${truncated}`);
+                        }
                     }
                     else {
                         lines.push(`  ${key}: ${value}`);
@@ -91,15 +127,21 @@ export class GetRequestDetailsTool extends BrowserToolBase {
                         parsed.password = '***';
                     if (parsed.pass)
                         parsed.pass = '***';
-                    displayData = JSON.stringify(parsed);
+                    const compact = JSON.stringify(parsed);
+                    const pretty = JSON.stringify(parsed, null, 2);
+                    // Pretty-print small JSON bodies for readability; keep large ones compact
+                    displayData = pretty.length <= 500 ? pretty : compact;
                 }
                 catch (e) {
                     // Not JSON, use as is
                 }
                 // Truncate at 500 chars
                 if (displayData.length > 500) {
-                    lines.push(`  ${displayData.substring(0, 500)}`);
-                    lines.push(`  ... [${displayData.length - 500} more chars]`);
+                    const shown = 500;
+                    const remaining = displayData.length - shown;
+                    const coverage = Math.round((shown / displayData.length) * 1000) / 10;
+                    lines.push(`  ${displayData.substring(0, shown)}`);
+                    lines.push(`  ... [${remaining} more chars] (previewCoverage≈${coverage}%)`);
                 }
                 else {
                     lines.push(`  ${displayData}`);
@@ -113,13 +155,30 @@ export class GetRequestDetailsTool extends BrowserToolBase {
                 : [];
             if (respHeaders.length > 0) {
                 lines.push('\nResponse Headers:');
-                respHeaders.forEach(([key, value]) => {
-                    // Truncate cookies
-                    if (key.toLowerCase() === 'set-cookie') {
-                        const truncated = value.length > 60
-                            ? value.substring(0, 57) + '...'
-                            : value;
-                        lines.push(`  ${key}: ${truncated}`);
+                const order = (name) => {
+                    const idx = importantResponseHeaders.indexOf(name.toLowerCase());
+                    return idx === -1 ? importantResponseHeaders.length : idx;
+                };
+                respHeaders
+                    .sort(([a], [b]) => {
+                    const oa = order(a);
+                    const ob = order(b);
+                    if (oa !== ob)
+                        return oa - ob;
+                    return a.localeCompare(b);
+                })
+                    .forEach(([key, value]) => {
+                    const keyLower = key.toLowerCase();
+                    if (keyLower === 'set-cookie') {
+                        if (!exposeSensitive) {
+                            lines.push(`  ${key}: <redacted>`);
+                        }
+                        else {
+                            const truncated = value.length > 60
+                                ? value.substring(0, 57) + '...'
+                                : value;
+                            lines.push(`  ${key}: ${truncated}`);
+                        }
                     }
                     else {
                         lines.push(`  ${key}: ${value}`);
@@ -129,18 +188,104 @@ export class GetRequestDetailsTool extends BrowserToolBase {
             // Response body
             if (req.responseData?.body) {
                 lines.push('\nResponse Body (truncated at 500 chars):');
-                const body = req.responseData.body;
-                if (body.length > 500) {
-                    lines.push(`  ${body.substring(0, 500)}`);
-                    lines.push(`  ... [${body.length - 500} more chars]`);
+                const rawBody = req.responseData.body;
+                let displayBody = rawBody;
+                // Pretty-print small JSON responses for readability; keep large ones compact
+                if (respContentType.toLowerCase().includes('application/json')) {
+                    try {
+                        const parsed = JSON.parse(rawBody);
+                        const compact = JSON.stringify(parsed);
+                        const pretty = JSON.stringify(parsed, null, 2);
+                        displayBody = pretty.length <= 500 ? pretty : compact;
+                    }
+                    catch {
+                        // Not valid JSON, fall back to raw body
+                    }
+                }
+                if (displayBody.length > 500) {
+                    const shown = 500;
+                    const remaining = displayBody.length - shown;
+                    const coverage = Math.round((shown / displayBody.length) * 1000) / 10;
+                    lines.push(`  ${displayBody.substring(0, shown)}`);
+                    lines.push(`  ... [${remaining} more chars] (previewCoverage≈${coverage}%)`);
                 }
                 else {
-                    lines.push(`  ${body}`);
+                    lines.push(`  ${displayBody}`);
                 }
             }
             else if (req.status) {
                 lines.push('\nResponse Body: (none or binary data)');
             }
+            // If either request or response body was truncated, provide a confirm_output token
+            const reqBody = req.requestData.postData || '';
+            const respBody = req.responseData?.body || '';
+            const reqTruncated = typeof reqBody === 'string' && reqBody.length > 500;
+            const respTruncated = typeof respBody === 'string' && respBody.length > 500;
+            if (reqTruncated || respTruncated) {
+                const inferExt = (ct) => {
+                    const c = (ct || '').toLowerCase();
+                    if (c.includes('application/json'))
+                        return 'json';
+                    if (c.includes('text/html'))
+                        return 'html';
+                    if (c.startsWith('text/'))
+                        return 'txt';
+                    if (c.includes('xml'))
+                        return 'xml';
+                    return 'txt';
+                };
+                const { getScreenshotsDir } = await import('../../../toolHandler.js');
+                const baseInspectorDir = path.dirname(getScreenshotsDir());
+                const outDir = path.join(baseInspectorDir, 'network-bodies');
+                const makeSafe = (s) => s.replace(/[^a-zA-Z0-9._-]/g, '-');
+                const urlObj = (() => { try {
+                    return new URL(req.url);
+                }
+                catch {
+                    return null;
+                } })();
+                const host = urlObj?.hostname ? makeSafe(urlObj.hostname) : 'unknown-host';
+                const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                const thunk = async () => {
+                    if (!fs.existsSync(outDir)) {
+                        fs.mkdirSync(outDir, { recursive: true });
+                    }
+                    const messages = [];
+                    if (respTruncated) {
+                        const ext = inferExt(respContentType);
+                        const respFile = path.join(outDir, `${ts}-${index}-${makeSafe(req.method)}-${host}.response.${ext}`);
+                        fs.writeFileSync(respFile, respBody, 'utf8');
+                        messages.push(`✓ Saved full response body to: ${path.relative(process.cwd(), respFile)} (${respBody.length} bytes${respContentType ? `, content-type: ${respContentType}` : ''})`);
+                    }
+                    if (reqTruncated) {
+                        const ext = inferExt(reqContentType);
+                        const reqFile = path.join(outDir, `${ts}-${index}-${makeSafe(req.method)}-${host}.request.${ext}`);
+                        fs.writeFileSync(reqFile, reqBody, 'utf8');
+                        messages.push(`✓ Saved full request body to: ${path.relative(process.cwd(), reqFile)} (${reqBody.length} bytes${reqContentType ? `, content-type: ${reqContentType}` : ''})`);
+                    }
+                    if (messages.length === 0) {
+                        messages.push('Nothing to save (no truncated text bodies).');
+                    }
+                    else {
+                        messages.push('');
+                        messages.push(`Paths above are relative to the current working directory: ${process.cwd()}`);
+                    }
+                    messages.push('');
+                    messages.push('Note: .mcp-web-inspector/ is recommended in .gitignore to avoid committing sensitive data.');
+                    return messages.join('\n');
+                };
+                const totalLen = (respTruncated ? respBody.length : 0) + (reqTruncated ? reqBody.length : 0);
+                const preview = makeConfirmPreview(thunk, {
+                    counts: { totalLength: totalLen, shownLength: 500, truncated: true },
+                    previewLines: [
+                        'Large network body detected — preview shown above.',
+                        'Confirm to save full body to disk (token-efficient).',
+                        `Output directory: ${path.relative(process.cwd(), outDir)}`,
+                    ],
+                });
+                lines.push('');
+                lines.push(...preview.lines);
+            }
             return {
                 content: [{
                         type: "text",

package/dist/tools/browser/network/list_network_requests.js

@@ -81,7 +81,7 @@ export class ListNetworkRequestsTool extends BrowserToolBase {
                     parts.push('|', cached);
                 lines.push(parts.join(' '));
             });
-            lines.push('\nUse get_request_details(index) for full info');
+            lines.push('\nUse get_request_details(index) for full info (indices are 0-based from this list)');
             return {
                 content: [{
                         type: "text",

package/dist/tools/common/types.d.ts

@@ -5,6 +5,7 @@ export interface SessionConfig {
     userDataDir: string;
     screenshotsDir: string;
     headlessDefault: boolean;
+    exposeSensitiveNetworkData?: boolean;
 }
 export interface ToolContext {
     page?: Page;

package/dist/utils/browserCheck.js

@@ -1,6 +1,10 @@
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { join } from 'path';
+// Resolve package root so npx uses this package's Playwright.
+// Entry point sets MCP_WEB_INSPECTOR_PACKAGE_ROOT using import.meta.url;
+// tests and other environments fall back to process.cwd().
+const PACKAGE_ROOT = process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT || process.cwd();
 /**
  * Check if Playwright browsers are installed
  * Returns true if browsers are available, false otherwise
@@ -10,7 +14,8 @@ export function checkBrowsersInstalled() {
         // Check if playwright is available
         const result = execSync('npx playwright --version', {
             encoding: 'utf8',
-            stdio: 'pipe'
+            stdio: 'pipe',
+            cwd: PACKAGE_ROOT,
         });
         // If we got here, playwright CLI is available
         // Now check if browsers are actually installed

package/package.json

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