mcp-web-inspector 0.5.3 → 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>
@@ -911,11 +910,11 @@ Quick check if an element exists on the page. Ultra-lightweight alternative to q
 
 ### Navigation
 
-#### `go_back`
-Navigate back in browser history
+#### `go_history`
+Navigate browser history (back/forward). Returns: 'Navigated <direction> in browser history', a quick network-idle note if available, 'URL: <current>', and 'Title: <current>' when set. If console errors occur after the navigation, returns an error like 'Console error after history navigation: <message>' including Title when available.
 
-#### `go_forward`
-Navigate forward in browser history
+- Parameters:
+  - direction (string, required): History direction to navigate
 
 #### `navigate`
 Navigate to a URL. Browser sessions (cookies, localStorage, sessionStorage) are automatically saved in ./.mcp-web-inspector/user-data directory and persist across restarts. To clear saved sessions, delete the directory.
@@ -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`
@@ -1048,7 +1045,7 @@ Clears captured console logs and returns the number of entries cleared.
 Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
-  - type (string, optional): Type of logs to retrieve (all, error, warning, log, info, debug, exception)
+  - type (string, optional): Type filter (all, error, warning, log, info, debug, exception). Note: 'error' also includes 'exception' entries for convenience.
   - search (string, optional): Text to search for in logs (handles text with square brackets)
   - limit (number, optional): Maximum entries to return (groups when grouped, lines when raw). Default: 20
   - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'
@@ -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
  */
@@ -79,6 +83,10 @@ export declare function getConsoleLogs(): string[];
  * Get console logs captured after the last navigation
  */
 export declare function getConsoleLogsSinceLastNavigation(): string[];
+/**
+ * Get console logs captured after the last interaction
+ */
+export declare function getConsoleLogsSinceLastInteraction(): string[];
 /**
  * Get screenshots
  */

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,21 +78,36 @@ 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;
 }
 async function applyColorScheme(targetPage) {
-    if (!targetPage) {
+    if (!targetPage)
         return;
-    }
+    const scheme = getColorSchemeValue();
     try {
-        const scheme = getColorSchemeValue();
-        await targetPage.emulateMedia({ colorScheme: scheme ?? null });
+        // Some test environments or mocks may not implement emulateMedia
+        const anyPage = targetPage;
+        if (typeof anyPage.emulateMedia === 'function') {
+            await anyPage.emulateMedia({ colorScheme: scheme ?? null });
+            return;
+        }
+        // Fallback: if emulateMedia is unavailable, do a best-effort hint via CSS.
+        // This won't fully emulate prefers-color-scheme but avoids throwing in tests.
+        if (scheme) {
+            const css = scheme === 'dark' ? ':root{color-scheme: dark;}'
+                : scheme === 'light' ? ':root{color-scheme: light;}'
+                    : ':root{color-scheme: light dark;}';
+            if (typeof anyPage.addStyleTag === 'function') {
+                await anyPage.addStyleTag({ content: css });
+            }
+        }
     }
     catch (error) {
-        console.error("Failed to apply color scheme:", error);
+        // Swallow errors to keep color scheme application non-fatal
+        console.warn("Failed to apply color scheme (non-fatal):", error);
     }
 }
 export async function setColorSchemeOverride(scheme) {
@@ -258,13 +285,13 @@ async function getScreenSize() {
         await tempBrowser.close();
         // Validate the screen size values
         if (!screenSize || typeof screenSize.width !== 'number' || typeof screenSize.height !== 'number') {
-            console.error('Invalid screen size detected, using defaults');
+            console.warn('Invalid screen size detected, using defaults');
             return { width: 1280, height: 720 };
         }
         return screenSize;
     }
     catch (error) {
-        console.error('Failed to detect screen size, using defaults:', error);
+        console.warn('Failed to detect screen size, using defaults:', error);
         return { width: 1280, height: 720 };
     }
 }
@@ -279,13 +306,14 @@ export async function ensureBrowser(browserSettings) {
             const browserCheck = checkBrowsersInstalled();
             if (!browserCheck.installed) {
                 // Try to install browsers automatically
-                console.error('🎭 Playwright browsers not found. Installing automatically...');
-                console.error('⏳ This will download ~1GB of browser binaries. Please wait...');
+                console.warn('🎭 Playwright browsers not found. Installing automatically...');
+                console.warn('⏳ This will download ~1GB of browser binaries. Please wait...');
                 try {
                     const { execSync } = await import('child_process');
                     execSync('npx playwright install chromium firefox webkit', {
                         stdio: 'inherit',
-                        encoding: 'utf8'
+                        encoding: 'utf8',
+                        cwd: PACKAGE_ROOT,
                     });
                     console.error('✅ Browsers installed successfully! Starting browser...');
                     // Note: browser variable is still undefined here, which is correct.
@@ -300,7 +328,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if browser exists but is disconnected
         if (browser && !browser.isConnected()) {
-            console.error("Browser exists but is disconnected. Cleaning up...");
+            console.warn("Browser exists but is disconnected. Cleaning up...");
             try {
                 await browser.close().catch(err => console.error("Error closing disconnected browser:", err));
             }
@@ -312,7 +340,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if device preset has changed (requires browser restart)
         if (browser && browserSettings?.device && browserSettings.device !== currentDevice) {
-            console.error(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
+            console.warn(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
             try {
                 await browser.close().catch(err => console.error("Error closing browser on device change:", err));
             }
@@ -360,14 +388,14 @@ export async function ensureBrowser(browserSettings) {
                     currentDevice = device;
                 }
                 else {
-                    console.error(`Warning: Device preset ${playwrightDeviceName} not found`);
+                    console.warn(`Warning: Device preset ${playwrightDeviceName} not found`);
                     currentDevice = undefined;
                 }
             }
             else {
                 currentDevice = undefined;
             }
-            console.error(`Launching new ${browserType} browser instance...`);
+            console.warn(`Launching new ${browserType} browser instance...`);
             // Use the appropriate browser engine
             let browserInstance;
             switch (browserType) {
@@ -421,14 +449,14 @@ export async function ensureBrowser(browserSettings) {
             }
             // Use persistent context if session saving is enabled
             if (sessionConfig.saveSession) {
-                console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
+                console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
                 const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, contextOptions);
                 // Get the browser instance from the context
                 browser = context.browser();
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -444,7 +472,7 @@ export async function ensureBrowser(browserSettings) {
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -473,7 +501,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Verify page is still valid
         if (!page || page.isClosed()) {
-            console.error("Page is closed or invalid. Creating new page...");
+            console.warn("Page is closed or invalid. Creating new page...");
             // Create a new page if the current one is invalid
             const context = browser.contexts()[0] || await browser.newContext();
             page = await context.newPage();
@@ -565,12 +593,12 @@ export async function ensureBrowser(browserSettings) {
         }
         // Use persistent context if session saving is enabled
         if (sessionConfig.saveSession) {
-            console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
+            console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
             const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, retryContextOptions);
             browser = context.browser();
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -584,7 +612,7 @@ export async function ensureBrowser(browserSettings) {
             });
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -650,7 +678,7 @@ export async function handleToolCall(name, args, server) {
         const requiresBrowser = isBrowserTool(name);
         // Check if we have a disconnected browser that needs cleanup
         if (browser && !browser.isConnected() && requiresBrowser) {
-            console.error("Detected disconnected browser before tool execution, cleaning up...");
+            console.warn("Detected disconnected browser before tool execution, cleaning up...");
             try {
                 await browser.close().catch(() => { }); // Ignore errors
             }
@@ -739,6 +767,16 @@ export function getConsoleLogsSinceLastNavigation() {
         return [];
     return consoleLogsTool.getLogsSinceLastNavigation();
 }
+/**
+ * Get console logs captured after the last interaction
+ */
+export function getConsoleLogsSinceLastInteraction() {
+    const consoleLogsTool = getToolInstance("get_console_logs", null);
+    if (!consoleLogsTool)
+        return [];
+    // Expose a compact accessor mirroring navigation-based retrieval
+    return consoleLogsTool.getLogsSinceLastInteraction?.() ?? [];
+}
 /**
  * Get screenshots
  */

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

@@ -121,4 +121,10 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * @param totalCount Total number of matches
      */
     protected buildNthSelectorHint(selector: string, totalCount: number): string;
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    protected describeMatchedElements(locator: any, originalSelector: string, count: number): Promise<string>;
 }

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();
         });
     }
     /**
@@ -233,8 +249,8 @@ export class BrowserToolBase {
         // Check for multiple elements with errorOnMultiple flag
         if (options?.errorOnMultiple && count > 1) {
             const selector = options.originalSelector || 'selector';
-            const nthHint = this.buildNthSelectorHint(selector, count).trimEnd();
-            const warning = this.getDuplicateTestIdWarning(selector, count).trimEnd();
+            const nthHint = ''.trimEnd();
+            const warning = ''.trimEnd();
             let message = `Selector "${selector}" matched ${count} elements. Please use a more specific selector.`;
             if (nthHint) {
                 message += `\n${nthHint}`;
@@ -242,7 +258,15 @@ export class BrowserToolBase {
             if (warning) {
                 message += `\n${warning}`;
             }
-            throw new Error(message);
+            {
+                const guidance = [
+                    `1) Preferred: add a unique data-testid and select it directly (e.g., testid:submit).`,
+                    `2) If you cannot change markup: append \`>> nth=<index>\` to target a specific match.`,
+                ];
+                const matchesDetails = await this.describeMatchedElements(locator, selector, count);
+                message += `\n${guidance.join('\n')}\n\nMatches:\n${matchesDetails}`;
+                throw new Error(message);
+            }
         }
         // Handle explicit element index (1-based)
         if (options?.elementIndex !== undefined) {
@@ -358,4 +382,68 @@ export class BrowserToolBase {
             `Note: nth selectors are brittle and may break with layout/content changes.\n` +
             `Prefer unique data-testid attributes for long-term stability.`);
     }
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    async describeMatchedElements(locator, originalSelector, count) {
+        const maxItems = Math.min(count, 5);
+        const lines = [];
+        for (let i = 0; i < maxItems; i++) {
+            const nth = locator.nth(i);
+            try {
+                const info = await nth.evaluate((el) => {
+                    const tag = (el.tagName || '').toLowerCase();
+                    let text = el.innerText || el.textContent || '';
+                    text = (text || '').replace(/\s+/g, ' ').trim();
+                    const testid = el.getAttribute?.('data-testid') || el.getAttribute?.('data-test') || el.getAttribute?.('data-cy') || null;
+                    const id = el.id || null;
+                    let parentLabel = null;
+                    let p = el.parentElement;
+                    while (p && !parentLabel) {
+                        const ptid = p.getAttribute?.('data-testid');
+                        const ptest = p.getAttribute?.('data-test');
+                        const pcy = p.getAttribute?.('data-cy');
+                        const pid = p.id || null;
+                        if (ptid)
+                            parentLabel = `[data-testid="${ptid}"]`;
+                        else if (ptest)
+                            parentLabel = `[data-test="${ptest}"]`;
+                        else if (pcy)
+                            parentLabel = `[data-cy="${pcy}"]`;
+                        else if (pid)
+                            parentLabel = `#${pid}`;
+                        p = p.parentElement;
+                    }
+                    return { tag, text, testid, id, parentLabel };
+                });
+                const truncatedText = info.text && info.text.length > 80 ? `${info.text.slice(0, 77)}...` : info.text;
+                let selectorSuggestion = `${originalSelector} >> nth=${i}`;
+                let altSuggestion;
+                if (info?.testid) {
+                    selectorSuggestion = `testid:${info.testid}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                else if (info?.id) {
+                    selectorSuggestion = `id=${info.id}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                const parts = [
+                    `[${i}] <${info.tag}>${truncatedText ? ` "${truncatedText}"` : ''}`,
+                    info.parentLabel ? `    parent: ${info.parentLabel}` : undefined,
+                    `    selector: ${selectorSuggestion}`,
+                    altSuggestion ? `    alt: ${altSuggestion}` : undefined,
+                ].filter(Boolean);
+                lines.push(parts.join('\n'));
+            }
+            catch {
+                lines.push(`[${i}] (element)\n    selector: ${originalSelector} >> nth=${i}`);
+            }
+        }
+        if (count > maxItems) {
+            lines.push(`… and ${count - maxItems} more matches (use >> nth=<index> to target).`);
+        }
+        return lines.join('\n');
+    }
 }

package/dist/tools/browser/common/postAction.d.ts

@@ -0,0 +1,7 @@
+import type { Page } from 'playwright';
+export declare function gatherConsoleErrorsSince(since: 'navigation' | 'interaction'): Promise<string[]>;
+export declare function quickNetworkIdleNote(page: Page): Promise<string>;
+export declare function titleUrlChangeLines(page: Page, initial?: {
+    url?: string;
+    title?: string;
+}): Promise<string[]>;

package/dist/tools/browser/common/postAction.js

@@ -0,0 +1,46 @@
+// Gather console error/exception logs since a baseline event
+export async function gatherConsoleErrorsSince(since) {
+    const { getConsoleLogsSinceLastNavigation, getConsoleLogsSinceLastInteraction } = await import('../../../toolHandler.js');
+    const logs = since === 'navigation'
+        ? getConsoleLogsSinceLastNavigation()
+        : getConsoleLogsSinceLastInteraction();
+    return logs.filter(l => l.startsWith('[error]') || l.startsWith('[exception]'));
+}
+// Provide a compact, best-effort network idle note
+export async function quickNetworkIdleNote(page) {
+    try {
+        const start = Date.now();
+        const anyPage = page;
+        const wait = anyPage?.waitForLoadState?.bind(page);
+        if (typeof wait === 'function') {
+            await wait('networkidle', { timeout: 500 });
+            const ms = Date.now() - start;
+            return `✓ Network idle after ${ms}ms, 0 pending requests`;
+        }
+    }
+    catch {
+        // fall through to no-activity note
+    }
+    return 'No new network activity detected (quick check)';
+}
+// Compute concise lines for title/URL when changed
+export async function titleUrlChangeLines(page, initial = {}) {
+    const lines = [];
+    let newUrl = '';
+    let newTitle = '';
+    try {
+        newUrl = page.url();
+    }
+    catch { }
+    try {
+        newTitle = await page.title();
+    }
+    catch { }
+    if (initial.url && newUrl && initial.url !== newUrl) {
+        lines.push(`URL changed: ${newUrl}`);
+    }
+    if (initial.title && newTitle && initial.title !== newTitle) {
+        lines.push(`Title changed: ${newTitle}`);
+    }
+    return lines;
+}

package/dist/tools/browser/console/__tests__/console.test.js

@@ -237,4 +237,13 @@ describe('GetConsoleLogsTool', () => {
         // Should include one of the first 20 grouped messages
         expect(fullText).toContain('GROUP-LONG-0');
     });
+    test('type: error should include exception entries', async () => {
+        consoleLogsTool.registerConsoleMessage('exception', 'Hook failed');
+        consoleLogsTool.registerConsoleMessage('error', 'Console error');
+        const result = await consoleLogsTool.execute({ type: 'error' }, mockContext);
+        expect(result.isError).toBe(false);
+        const text = result.content.map(c => c.text).join('\n');
+        expect(text).toContain('[exception] Hook failed');
+        expect(text).toContain('[error] Console error');
+    });
 });