mcp-web-inspector 0.5.0 → 0.5.3

package/README.md

@@ -595,7 +595,7 @@ COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in on
   - selector2 (string, required): CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')
 
 - Output Format:
-  - Optional warnings when a selector matched multiple elements (using first).
+  - Optional warnings when a selector matched multiple elements (uses first visible; suggests adding unique data-testid).
   - Header: Alignment: <elem1> vs <elem2>
   - Two lines with each element's position and size: @ (x,y) w×h px
   - Edges block: Top/Left/Right/Bottom with ✓/✗ and diffs
@@ -1031,8 +1031,6 @@ Upload a file to an input[type='file'] element on the page
 
 ⚠️ Token cost: ~1,500 tokens to read. Structural tools: <100 tokens.
 
-Admin control (optional): set env MCP_SCREENSHOT_GUARD=strict to block execution (prevents misuse by default). Unset to allow visuals for human review.
-
 Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }
 
 - Parameters:

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

@@ -12,14 +12,14 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      */
     abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
+     * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
+     *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -28,7 +28,7 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * Sanitize verbose Playwright selector engine messages by removing stack traces and
      * keeping only the essential syntax error information.
      */
-    private sanitizeSelectorEngineMessage;
+    protected sanitizeSelectorEngineMessage(msg: string): string;
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page

package/dist/tools/browser/base.js

@@ -8,14 +8,14 @@ export class BrowserToolBase {
         this.server = server;
     }
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
+     * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
+     *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -32,14 +32,33 @@ export class BrowserToolBase {
                 return `[${attr}="${value}"]`;
             }
         }
-        // Clean up common escaping mistakes that LLMs make in CSS selectors
-        // These characters don't need to be escaped in many selector contexts: [ ] :
-        let cleaned = selector;
-        // Remove backslash escapes before brackets and colons
-        // Handle both single escapes (\[) and double escapes (\\[)
-        cleaned = cleaned.replace(/\\+\[/g, '[');
-        cleaned = cleaned.replace(/\\+\]/g, ']');
-        cleaned = cleaned.replace(/\\+:/g, ':');
+        const trimmed = selector.trim();
+        // Helper: unescape simple backslash-escapes used inside IDs (e.g., \:, \[, \])
+        const unescapeCssIdentifier = (s) => {
+            // Collapse multiple backslashes before a single char to the char itself
+            return s
+                .replace(/\\+:/g, ':')
+                .replace(/\\+\[/g, '[')
+                .replace(/\\+\]/g, ']');
+        };
+        // If this looks like a simple, standalone ID selector (no combinators or descendants),
+        // switch to Playwright's id engine. This avoids CSS escaping pitfalls with colons.
+        if (/^#[^\s>+~]+$/.test(trimmed)) {
+            const idToken = trimmed.slice(1);
+            // Only switch to id= engine if ID contains characters that commonly break CSS (#... with colons or escapes)
+            if (idToken.includes('\\') || idToken.includes(':') || idToken.includes('[') || idToken.includes(']')) {
+                const idValue = unescapeCssIdentifier(idToken);
+                return `id=${idValue}`;
+            }
+            // Otherwise, keep simple IDs as-is
+            return trimmed;
+        }
+        // For general CSS selectors, preserve required escapes for special chars.
+        // Collapse over-escaping (e.g., \\\\[ → \\[, but keep a single backslash before [ ] :)
+        let cleaned = trimmed;
+        cleaned = cleaned.replace(/\\{2,}(?=\[)/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=\])/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=:)/g, '\\');
         return cleaned;
     }
     /**
@@ -274,12 +293,19 @@ export class BrowserToolBase {
      * @returns Formatted string or empty if only one element
      */
     formatElementSelectionInfo(selector, elementIndex, totalCount, preferredVisible = true) {
+        const usesNth = selector.includes('>> nth=');
         if (totalCount <= 1) {
+            // Even when a single element is ultimately targeted, discourage nth usage
+            // because it is brittle across layout/content changes.
+            if (usesNth) {
+                return "💡 Tip: Selector uses '>> nth='. Prefer adding a unique data-testid for robust selection.";
+            }
             return '';
         }
         const duplicateWarning = this.getDuplicateTestIdWarning(selector, totalCount).trimEnd();
         const nthHint = this.buildNthSelectorHint(selector, totalCount).trimEnd();
-        const extraHints = [duplicateWarning, nthHint].filter(Boolean).join('\n');
+        const avoidNth = usesNth ? "💡 Tip: Avoid relying on '>> nth='; add a unique data-testid instead." : '';
+        const extraHints = [duplicateWarning, nthHint, avoidNth].filter(Boolean).join('\n');
         const baseMessage = preferredVisible
             ? `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1} (first visible)`
             : `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1}`;
@@ -302,10 +328,14 @@ export class BrowserToolBase {
             selector.startsWith('data-cy:') ||
             selector.match(/^\[data-(testid|test|cy)=/);
         if (isTestIdSelector) {
-            return `💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n\n`;
+            return (`💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n` +
+                `   Primary fix: assign a unique data-testid to the intended element.\n` +
+                `   Workaround: if you cannot change markup, you may use '>> nth=<index>' temporarily.\n\n`);
         }
         // Suggest testid for non-testid selectors
-        return `💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n\n`;
+        return (`💡 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\n`);
     }
     /**
      * Provide a hint for using >> nth= when multiple elements match a selector
@@ -321,6 +351,11 @@ export class BrowserToolBase {
         const firstExample = `${trimmed} >> nth=0`;
         const lastIndex = Math.max(totalCount - 1, 1);
         const lastExample = `${trimmed} >> nth=${lastIndex}`;
-        return `💡 Hint: Append ">> nth=<index>" to target a specific match.\n   Example: ${firstExample} (first match)\n   Or: ${lastExample} (last match)`;
+        return (`Primary fix: add a unique data-testid to the intended element and select it directly.\n` +
+            `Workaround: Append ">> nth=<index>" to target a specific match when you cannot change markup.\n` +
+            `   Example: ${firstExample} (first match)\n` +
+            `   Or: ${lastExample} (last match)\n` +
+            `Note: nth selectors are brittle and may break with layout/content changes.\n` +
+            `Prefer unique data-testid attributes for long-term stability.`);
     }
 }

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

@@ -195,4 +195,46 @@ describe('GetConsoleLogsTool', () => {
         // (The truncation happens in toolHandler.ts before calling registerConsoleMessage)
         expect(logsText).toContain(longStackError);
     });
+    test('raw format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate enough long logs to exceed preview threshold
+        for (let i = 0; i < 40; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `RAW-LONG-${i} ` + 'X'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({ format: 'raw' }, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        // Should include confirm_output token reference
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        // Confirm to retrieve full payload
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // By default limit=20 → header should reflect 20 lines
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // And include one of our long messages
+        expect(fullText).toContain('RAW-LONG-39');
+    });
+    test('grouped format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate 30 unique messages to form distinct groups and exceed threshold
+        for (let i = 0; i < 30; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `GROUP-LONG-${i} ` + 'G'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({}, mockContext); // grouped is default
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // Header reflects number of groups shown (limit default 20)
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // Should include one of the first 20 grouped messages
+        expect(fullText).toContain('GROUP-LONG-0');
+    });
 });

package/dist/tools/browser/console/get_console_logs.js

@@ -1,6 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse } from '../../common/types.js';
-import { makeConfirmPreview } from '../../common/confirmHelpers.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for retrieving and filtering console logs from the browser
  */
@@ -122,7 +122,7 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                     `Matched ${logs.length} log(s). Showing ${Math.min(messages.length, 10)} line(s) preview.`,
                     ...messages.slice(0, Math.min(messages.length, 10)),
                 ];
-                const preview = makeConfirmPreview(textPayload, {
+                const preview = makeConfirmPreview(() => textPayload, {
                     counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: logs.length, shownCount: Math.min(messages.length, 10), truncated: true },
                     previewLines,
                     extraTips: ['Tip: refine with search/type/since/limit or prefer grouped format.'],
@@ -163,7 +163,7 @@ export class GetConsoleLogsTool extends BrowserToolBase {
                 `Matched ${groups.size} group(s). Showing ${limitedGroups.length}.`,
                 ...lines.slice(0, Math.min(lines.length, 12)),
             ];
-            const preview = makeConfirmPreview(textPayload, {
+            const preview = makeConfirmPreview(() => textPayload, {
                 counts: { totalLength: textPayload.length, shownLength: previewLines.join('\n').length, totalMatched: groups.size, shownCount: limitedGroups.length, truncated: true },
                 previewLines,
                 extraTips: ['Tip: refine with search/type/since/limit.'],

package/dist/tools/browser/content/__tests__/screenshot.test.js

@@ -52,47 +52,65 @@ describe('ScreenshotTool', () => {
     afterEach(() => {
         jest.restoreAllMocks();
     });
-    test('should take a full page screenshot', async () => {
+    test('should take a full page screenshot (via confirm_output)', async () => {
         const args = {
             name: 'test-screenshot',
             fullPage: true
         };
-        // Return a buffer for the screenshot
+        // First call returns preview with confirm token; no screenshot yet
+        const previewResult = await screenshotTool.execute(args, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const text = previewResult.content.map(c => c.text).join('\n');
+        expect(text).toMatch(/confirm_output\(\{ token: \"[\w\d]+\" \}\)/);
+        // Extract token and confirm
+        const tokenMatch = text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        expect(tokenMatch).not.toBeNull();
+        const token = tokenMatch[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
         const screenshotBuffer = Buffer.from('mock-screenshot');
         mockScreenshot.mockImplementationOnce(() => Promise.resolve(screenshotBuffer));
-        const result = await screenshotTool.execute(args, mockContext);
-        // Check if screenshot was called with correct options
-        expect(mockScreenshot).toHaveBeenCalledWith(expect.objectContaining({
-            fullPage: true,
-            type: 'png'
-        }));
-        // Check that the result contains success message
-        expect(result.isError).toBe(false);
-        expect(result.content[0].text).toContain('Screenshot saved to');
+        const finalResult = await confirmTool.execute({ token }, mockContext);
+        expect(finalResult.isError).toBe(false);
+        expect(finalResult.content[0].text).toContain('Screenshot saved to');
+        expect(mockScreenshot).toHaveBeenCalledWith(expect.objectContaining({ fullPage: true, type: 'png' }));
     });
-    test('should handle element screenshot', async () => {
+    test('should handle element screenshot (via confirm_output)', async () => {
         const args = {
             name: 'test-element-screenshot',
             selector: '#test-element'
         };
-        // Return a buffer for the screenshot
+        const previewResult = await screenshotTool.execute(args, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const text = previewResult.content.map(c => c.text).join('\n');
+        const tokenMatch = text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        expect(tokenMatch).not.toBeNull();
+        const token = tokenMatch[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
         const screenshotBuffer = Buffer.from('mock-element-screenshot');
         mockLocatorScreenshot.mockImplementationOnce(() => Promise.resolve(screenshotBuffer));
-        const result = await screenshotTool.execute(args, mockContext);
-        // Check that the result contains success message
-        expect(result.isError).toBe(false);
-        expect(result.content[0].text).toContain('Screenshot saved to');
+        const finalResult = await confirmTool.execute({ token }, mockContext);
+        expect(finalResult.isError).toBe(false);
+        expect(finalResult.content[0].text).toContain('Screenshot saved to');
     });
-    test('should handle screenshot errors', async () => {
+    test('should handle screenshot errors (on confirm)', async () => {
         const args = {
             name: 'test-screenshot'
         };
-        // Mock a screenshot error
+        const previewResult = await screenshotTool.execute(args, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const text = previewResult.content.map(c => c.text).join('\n');
+        const tokenMatch = text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        expect(tokenMatch).not.toBeNull();
+        const token = tokenMatch[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        // Mock a screenshot error on confirmation
         mockScreenshot.mockImplementationOnce(() => Promise.reject(new Error('Screenshot failed')));
-        const result = await screenshotTool.execute(args, mockContext);
-        expect(mockScreenshot).toHaveBeenCalled();
-        expect(result.isError).toBe(true);
-        expect(result.content[0].text).toContain('Operation failed');
+        const finalResult = await confirmTool.execute({ token }, mockContext);
+        expect(finalResult.isError).toBe(true);
+        expect(finalResult.content[0].text).toContain('Screenshot failed');
     });
     test('should handle missing page', async () => {
         const args = {
@@ -108,60 +126,60 @@ describe('ScreenshotTool', () => {
         expect(result.isError).toBe(true);
         expect(result.content[0].text).toContain('Browser page not initialized');
     });
-    test('should store screenshots in a map', async () => {
+    test('should store screenshots in a map (after confirm)', async () => {
         const args = {
             name: 'test-screenshot',
             storeBase64: true
         };
-        // Return a buffer for the screenshot
-        const screenshotBuffer = Buffer.from('mock-screenshot');
-        mockScreenshot.mockImplementationOnce(() => Promise.resolve(screenshotBuffer));
-        await screenshotTool.execute(args, mockContext);
+        const preview = await screenshotTool.execute(args, mockContext);
+        const token = (preview.content.map(c => c.text).join('\n').match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        mockScreenshot.mockImplementationOnce(() => Promise.resolve(Buffer.from('mock-screenshot')));
+        await confirmTool.execute({ token }, mockContext);
         // Check that the screenshot was stored in the map
         const screenshots = screenshotTool.getScreenshots();
         expect(screenshots.has('test-screenshot')).toBe(true);
     });
-    test('should take a screenshot with specific browser type', async () => {
+    test('should take a screenshot with specific browser type (via confirm_output)', async () => {
         const args = {
             name: 'browser-type-test',
             browserType: 'firefox'
         };
-        // Execute with browser type
-        const result = await screenshotTool.execute(args, mockContext);
+        const preview = await screenshotTool.execute(args, mockContext);
+        const text = preview.content.map(c => c.text).join('\n');
+        const token = (text.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        mockScreenshot.mockImplementationOnce(() => Promise.resolve(Buffer.from('mock-screenshot')));
+        const result = await confirmTool.execute({ token }, mockContext);
         expect(mockScreenshot).toHaveBeenCalled();
         expect(result.isError).toBe(false);
         expect(result.content[0].text).toContain('Screenshot saved to');
     });
-    test('should include actionable guidance for full-page screenshots', async () => {
+    test('preview should suggest alternative tools', async () => {
         const args = {
             name: 'test-screenshot',
             fullPage: true
         };
-        const screenshotBuffer = Buffer.from('mock-screenshot');
-        mockScreenshot.mockImplementationOnce(() => Promise.resolve(screenshotBuffer));
         const result = await screenshotTool.execute(args, mockContext);
         expect(result.isError).toBe(false);
-        // Concatenate all content items to check the full response
         const fullResponseText = result.content.map(c => c.text).join('\n');
-        // Verify guidance is included (updated to match new cross-tool advertising)
-        expect(fullResponseText).toContain('💡 To debug layout issues');
+        expect(fullResponseText).toContain('Screenshot requested');
         expect(fullResponseText).toContain('inspect_dom');
-        expect(fullResponseText).toContain('get_test_ids');
+        expect(fullResponseText).toContain('compare_element_alignment');
+        expect(fullResponseText).toContain('get_computed_styles');
         expect(fullResponseText).toContain('inspect_ancestors');
     });
-    test('should NOT include guidance for element-specific screenshots', async () => {
+    test('preview should also suggest alternatives for element screenshots', async () => {
         const args = {
             name: 'test-element-screenshot',
             selector: '#test-element'
         };
-        const screenshotBuffer = Buffer.from('mock-element-screenshot');
-        mockLocatorScreenshot.mockImplementationOnce(() => Promise.resolve(screenshotBuffer));
         const result = await screenshotTool.execute(args, mockContext);
         expect(result.isError).toBe(false);
-        // Concatenate all content items to check the full response
         const fullResponseText = result.content.map(c => c.text).join('\n');
-        // Verify guidance is NOT included for element screenshots
-        expect(fullResponseText).not.toContain('💡 Next steps to analyze this page:');
-        expect(fullResponseText).not.toContain('inspect_dom');
+        expect(fullResponseText).toContain('Screenshot requested');
+        expect(fullResponseText).toContain('inspect_dom');
     });
 });

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

@@ -1,6 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
-import { makeConfirmPreview } from '../../common/confirmHelpers.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for getting HTML from the page
  */
@@ -105,7 +105,7 @@ export class GetHtmlTool extends BrowserToolBase {
                 // Generate key for this HTML request
                 // Check if HTML is too large => return preview + token for confirm_output
                 if (originalLength >= PREVIEW_THRESHOLD) {
-                    const preview = makeConfirmPreview(processedHtml, {
+                    const preview = makeConfirmPreview(() => processedHtml, {
                         counts: { totalLength: originalLength, shownLength: Math.min(500, originalLength), truncated: true },
                         previewLines: [
                             'Preview (first 500 chars):',

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

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import * as path from 'node:path';
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse } from '../../common/types.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for taking screenshots of pages or elements
  */
@@ -30,8 +31,6 @@ export class ScreenshotTool extends BrowserToolBase {
             '',
             '⚠️ Token cost: ~1,500 tokens to read. Structural tools: <100 tokens.',
             '',
-            'Admin control (optional): set env MCP_SCREENSHOT_GUARD=strict to block execution (prevents misuse by default). Unset to allow visuals for human review.',
-            '',
             `Screenshots saved to ${screenshotsDir}. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`
         ].join('\n');
         return {
@@ -63,81 +62,64 @@ export class ScreenshotTool extends BrowserToolBase {
     }
     async execute(args, context) {
         return this.safeExecute(context, async (page) => {
-            // Optional guardrail to reduce unreasonable calls by LLMs.
-            // If MCP_SCREENSHOT_GUARD is set to 'strict', block execution.
-            const guard = (process.env.MCP_SCREENSHOT_GUARD || '').toLowerCase();
-            const strictGuard = guard === '1' || guard === 'true' || guard === 'strict';
-            if (strictGuard) {
-                const lines = [];
-                lines.push('🚫 Screenshot blocked by admin guard (MCP_SCREENSHOT_GUARD=strict).');
-                lines.push('');
-                lines.push('Use structural tools for programmatic debugging:');
-                lines.push('  - inspect_dom()               → hierarchy, positions, visibility');
-                lines.push('  - compare_element_alignment() → alignment and pixel diffs');
-                lines.push('  - get_computed_styles()       → CSS values');
-                lines.push('  - inspect_ancestors()         → parent constraints and overflow');
-                lines.push('');
-                lines.push('If a human needs to review visuals, ask an admin to unset MCP_SCREENSHOT_GUARD.');
-                return createSuccessResponse(lines.join('\n'));
-            }
-            const screenshotOptions = {
-                type: args.type || "png",
-                fullPage: !!args.fullPage
-            };
-            if (args.selector) {
-                // Normalize selector (support testid: shorthand)
-                const selector = this.normalizeSelector(args.selector);
-                const element = await page.$(selector);
-                if (!element) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: `Element not found: ${selector}`,
-                            }],
-                        isError: true
-                    };
+            // Defer the screenshot capture until confirmation via confirm_output
+            const thunk = async () => {
+                const screenshotOptions = {
+                    type: args.type || "png",
+                    fullPage: !!args.fullPage
+                };
+                if (args.selector) {
+                    const selector = this.normalizeSelector(args.selector);
+                    const element = await page.$(selector);
+                    if (!element) {
+                        throw new Error(`Element not found: ${selector}`);
+                    }
+                    screenshotOptions.element = element;
                 }
-                screenshotOptions.element = element;
-            }
-            const { getScreenshotsDir } = await import('../../../toolHandler.js');
-            // Generate output path
-            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-            const filename = `${args.name || 'screenshot'}-${timestamp}.png`;
-            // Use screenshots directory from config, fall back to downloadsDir arg, then default Downloads
-            const downloadsDir = args.downloadsDir || getScreenshotsDir();
-            if (!fs.existsSync(downloadsDir)) {
-                fs.mkdirSync(downloadsDir, { recursive: true });
-            }
-            const outputPath = path.join(downloadsDir, filename);
-            screenshotOptions.path = outputPath;
-            const screenshot = await page.screenshot(screenshotOptions);
-            const base64Screenshot = screenshot.toString('base64');
-            const messages = [`✓ Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
-            // Handle base64 storage
-            if (args.storeBase64 !== false) {
-                this.screenshots.set(args.name || 'screenshot', base64Screenshot);
-                context.server.notification({
-                    method: "notifications/resources/list_changed",
-                });
-                messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
-            }
-            // Add token cost warning
-            messages.push('');
-            messages.push('📸 Open the file in your IDE to view the screenshot');
-            messages.push('⚠️ Reading the image file consumes ~1,500 tokens — use structural tools for layout debugging');
-            // Add actionable guidance based on screenshot context
-            messages.push('');
-            messages.push('💡 To debug layout issues without reading the screenshot:');
-            if (args.selector) {
-                messages.push(`   inspect_ancestors({ selector: "${args.selector}" })`);
-                messages.push('   → See parent constraints (width, margins, overflow, borders)');
-            }
-            else {
-                messages.push('   1) Find the element: inspect_dom({}) or get_test_ids()');
-                messages.push('   2) Check parent constraints: inspect_ancestors({ selector: "..." })');
-                messages.push('   3) Compare alignment: compare_element_alignment({ selector1: "...", selector2: "..." })');
-            }
-            return createSuccessResponse(messages);
+                const { getScreenshotsDir } = await import('../../../toolHandler.js');
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+                const filename = `${args.name || 'screenshot'}-${timestamp}.png`;
+                const downloadsDir = args.downloadsDir || getScreenshotsDir();
+                if (!fs.existsSync(downloadsDir)) {
+                    fs.mkdirSync(downloadsDir, { recursive: true });
+                }
+                const outputPath = path.join(downloadsDir, filename);
+                screenshotOptions.path = outputPath;
+                const screenshot = await page.screenshot(screenshotOptions);
+                const base64Screenshot = screenshot.toString('base64');
+                const messages = [`✓ Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
+                if (args.storeBase64 !== false) {
+                    this.screenshots.set(args.name || 'screenshot', base64Screenshot);
+                    context.server.notification({ method: "notifications/resources/list_changed" });
+                    messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
+                }
+                messages.push('');
+                messages.push('📸 Open the file in your IDE to view the screenshot');
+                messages.push('⚠️ Reading the image file consumes ~1,500 tokens — use structural tools for layout debugging');
+                messages.push('');
+                messages.push('💡 To debug layout issues without reading the screenshot:');
+                if (args.selector) {
+                    messages.push(`   inspect_ancestors({ selector: "${args.selector}" })`);
+                    messages.push('   → See parent constraints (width, margins, overflow, borders)');
+                }
+                else {
+                    messages.push('   1) Find the element: inspect_dom({}) or get_test_ids()');
+                    messages.push('   2) Check parent constraints: inspect_ancestors({ selector: "..." })');
+                    messages.push('   3) Compare alignment: compare_element_alignment({ selector1: "...", selector2: "..." })');
+                }
+                return messages.join('\n');
+            };
+            // Return a minimal preview that suggests better alternatives
+            const preview = makeConfirmPreview(thunk, {
+                previewLines: [
+                    'Screenshot requested. For debugging, prefer:',
+                    '  • inspect_dom() - structure, positions, visibility',
+                    '  • compare_element_alignment() - alignment with pixel diffs',
+                    '  • get_computed_styles() - CSS values',
+                    '  • inspect_ancestors() - constraints and overflow',
+                ],
+            });
+            return createSuccessResponse(preview.lines.join('\n'));
         });
     }
     /**

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

@@ -1,6 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { createSuccessResponse, createErrorResponse, } from '../../common/types.js';
-import { makeConfirmPreview } from '../../common/confirmHelpers.js';
+import { makeConfirmPreview } from '../../common/confirm_output.js';
 /**
  * Tool for executing JavaScript in the browser
  */
@@ -274,7 +274,7 @@ export class EvaluateTool extends BrowserToolBase {
             if (totalLength >= PREVIEW_THRESHOLD) {
                 const previewLen = Math.min(500, totalLength);
                 const preview = resultStr.slice(0, previewLen);
-                const previewBlock = makeConfirmPreview(resultStr, {
+                const previewBlock = makeConfirmPreview(() => resultStr, {
                     headerLine: '✓ JavaScript execution result (preview):',
                     counts: { totalLength, shownLength: previewLen, truncated: true },
                     previewLines: [

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

@@ -9,7 +9,7 @@ export class CompareElementAlignmentTool extends BrowserToolBase {
             name: "compare_element_alignment",
             description: "COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in one call. Shows edge alignment (top, left, right, bottom), center alignment (horizontal, vertical), and dimensions (width, height). Perfect for debugging 'are these headers aligned?' or 'do these panels match?'. Returns all alignment info with ✓/✗ symbols and pixel differences. For parent-child centering, use inspect_dom() instead (automatically shows if children are centered in parent). More efficient than evaluate() with manual getBoundingClientRect() calculations.",
             outputs: [
-                "Optional warnings when a selector matched multiple elements (using first).",
+                "Optional warnings when a selector matched multiple elements (uses first visible; suggests adding unique data-testid).",
                 "Header: Alignment: <elem1> vs <elem2>",
                 "Two lines with each element's position and size: @ (x,y) w×h px",
                 "Edges block: Top/Left/Right/Bottom with ✓/✗ and diffs",
@@ -52,10 +52,10 @@ export class CompareElementAlignmentTool extends BrowserToolBase {
             const selector1 = this.normalizeSelector(args.selector1);
             const selector2 = this.normalizeSelector(args.selector2);
             try {
-                // Get locators for both elements
+                // Build locators for both elements
                 const locator1 = page.locator(selector1);
                 const locator2 = page.locator(selector2);
-                // Check if both elements exist
+                // Check existence first to preserve legacy error messages expected by tests
                 const count1 = await locator1.count();
                 const count2 = await locator2.count();
                 if (count1 === 0) {
@@ -64,19 +64,43 @@ export class CompareElementAlignmentTool extends BrowserToolBase {
                 if (count2 === 0) {
                     return createErrorResponse(`Second element not found: ${args.selector2}`);
                 }
-                // Handle multiple matches by using first() - show warning
-                const targetLocator1 = count1 > 1 ? locator1.first() : locator1;
-                const targetLocator2 = count2 > 1 ? locator2.first() : locator2;
-                let warnings = '';
+                // Prefer first visible element and produce clear selection info
+                let selectionWarning1 = '';
+                let selectionWarning2 = '';
+                let targetLocator1 = locator1.first();
+                let targetLocator2 = locator2.first();
+                try {
+                    const sel1 = await this.selectPreferredLocator(locator1, {
+                        originalSelector: args.selector1,
+                    });
+                    selectionWarning1 = this.formatElementSelectionInfo(args.selector1, sel1.elementIndex, sel1.totalCount);
+                    targetLocator1 = sel1.element;
+                }
+                catch {
+                    // Fallback to first() when visibility checks are unavailable (tests/mocks)
+                    selectionWarning1 = this.formatElementSelectionInfo(args.selector1, 0, count1);
+                }
+                try {
+                    const sel2 = await this.selectPreferredLocator(locator2, {
+                        originalSelector: args.selector2,
+                    });
+                    selectionWarning2 = this.formatElementSelectionInfo(args.selector2, sel2.elementIndex, sel2.totalCount);
+                    targetLocator2 = sel2.element;
+                }
+                catch {
+                    selectionWarning2 = this.formatElementSelectionInfo(args.selector2, 0, count2);
+                }
+                // Maintain legacy warning format for multiple matches, then append richer hints
+                let legacyWarnings = '';
                 if (count1 > 1) {
-                    warnings += `⚠ Warning: First selector matched ${count1} elements, using first\n`;
+                    legacyWarnings += `⚠ Warning: First selector matched ${count1} elements, using first\n`;
                 }
                 if (count2 > 1) {
-                    warnings += `⚠ Warning: Second selector matched ${count2} elements, using first\n`;
-                }
-                if (warnings) {
-                    warnings += '\n';
+                    legacyWarnings += `⚠ Warning: Second selector matched ${count2} elements, using first\n`;
                 }
+                const warnings = [legacyWarnings.trimEnd(), selectionWarning1, selectionWarning2]
+                    .filter(Boolean)
+                    .join('\n');
                 // Get bounding boxes
                 const box1 = await targetLocator1.boundingBox();
                 const box2 = await targetLocator2.boundingBox();
@@ -182,7 +206,7 @@ export class CompareElementAlignmentTool extends BrowserToolBase {
                 };
                 // Build output
                 const lines = [
-                    warnings,
+                    warnings ? `${warnings}\n` : '',
                     `Alignment: ${descriptor1} vs ${descriptor2}`,
                     `  ${name1}: @ (${left1},${top1}) ${width1}×${height1}px`,
                     `  ${name2}: @ (${left2},${top2}) ${width2}×${height2}px`,

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

@@ -104,11 +104,8 @@ RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use com
             const maxDepth = args.maxDepth ?? 5;
             try {
                 // Use consistent element selection (Playwright's visibility detection)
+                // Delegate count + selector error handling to selectPreferredLocator()
                 const locator = page.locator(selector);
-                const count = await locator.count();
-                if (count === 0) {
-                    return createErrorResponse(`Element not found: ${args.selector || 'body'}`);
-                }
                 const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
                     originalSelector: args.selector || 'body',
                 });
@@ -716,7 +713,14 @@ RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use com
                 return createSuccessResponse(lines.join('\n'));
             }
             catch (error) {
-                return createErrorResponse(`Failed to inspect DOM: ${error.message}`);
+                const msg = error.message || '';
+                // Map common not-found message to a user-friendly line
+                if (msg === 'No elements found') {
+                    return createErrorResponse(`Element not found: ${args.selector || 'body'}`);
+                }
+                // Sanitize verbose selector engine traces and return concise message
+                const concise = this.sanitizeSelectorEngineMessage(msg) || msg;
+                return createErrorResponse(`Failed to inspect DOM: ${concise}`);
             }
         });
     }

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

@@ -243,7 +243,9 @@ export class QuerySelectorTool extends BrowserToolBase {
                 return createSuccessResponse(lines.join('\n'));
             }
             catch (error) {
-                return createErrorResponse(`Failed to query selector: ${error.message}`);
+                const msg = error.message || '';
+                const concise = this.sanitizeSelectorEngineMessage(msg) || msg;
+                return createErrorResponse(`Failed to query selector: ${concise}`);
             }
         });
     }

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

@@ -1,7 +1,33 @@
 import type { ToolHandler, ToolContext, ToolResponse, ToolMetadata, SessionConfig } from './types.js';
+type PayloadThunk = () => Promise<string> | string;
+export declare function registerPayloadThunk(thunk: PayloadThunk, ttlMs?: number): string;
+export declare function consumeThunk(token: string): {
+    ok: true;
+    thunk: PayloadThunk;
+} | {
+    ok: false;
+    error: string;
+};
+export interface PreviewCounts {
+    totalLength?: number;
+    shownLength?: number;
+    totalMatched?: number;
+    shownCount?: number;
+    truncated?: boolean;
+}
+export declare function makeConfirmPreview(payloadOrThunk: string | PayloadThunk, options: {
+    headerLine?: string;
+    previewLines: string[];
+    counts?: PreviewCounts;
+    extraTips?: string[];
+}): {
+    token: string;
+    lines: string[];
+};
 export declare class ConfirmOutputTool implements ToolHandler {
     private server;
     constructor(server: any);
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     execute(args: any, context: ToolContext): Promise<ToolResponse>;
 }
+export {};

package/dist/tools/common/confirm_output.js

@@ -1,5 +1,73 @@
 import { createSuccessResponse, createErrorResponse } from './types.js';
-import { consumePayload } from './confirmStore.js';
+const STORE = new Map();
+function now() {
+    return Date.now();
+}
+function purgeExpired() {
+    const t = now();
+    for (const [k, v] of STORE.entries()) {
+        if (v.expiresAt <= t)
+            STORE.delete(k);
+    }
+}
+function genToken(len = 12) {
+    return Math.random().toString(36).slice(2, 2 + len);
+}
+export function registerPayloadThunk(thunk, ttlMs = 120000) {
+    purgeExpired();
+    const token = genToken();
+    const expiresAt = now() + Math.max(1000, ttlMs);
+    STORE.set(token, { thunk, expiresAt });
+    return token;
+}
+export function consumeThunk(token) {
+    purgeExpired();
+    const entry = STORE.get(token);
+    if (!entry)
+        return { ok: false, error: 'Invalid or expired token' };
+    STORE.delete(token);
+    if (entry.expiresAt <= now())
+        return { ok: false, error: 'Invalid or expired token' };
+    return { ok: true, thunk: entry.thunk };
+}
+export function makeConfirmPreview(payloadOrThunk, options) {
+    const thunk = typeof payloadOrThunk === 'function' ? payloadOrThunk : () => payloadOrThunk;
+    const token = registerPayloadThunk(thunk);
+    const lines = [];
+    if (options.headerLine) {
+        lines.push(options.headerLine);
+    }
+    const parts = [];
+    const c = options.counts || {};
+    if (typeof c.totalLength === 'number')
+        parts.push(`totalLength=${c.totalLength}`);
+    if (typeof c.shownLength === 'number')
+        parts.push(`shownLength=${c.shownLength}`);
+    if (typeof c.totalMatched === 'number')
+        parts.push(`totalMatched=${c.totalMatched}`);
+    if (typeof c.shownCount === 'number')
+        parts.push(`shownCount=${c.shownCount}`);
+    if (typeof c.truncated === 'boolean')
+        parts.push(`truncated=${c.truncated}`);
+    if (parts.length) {
+        lines.push(`counts: ${parts.join(', ')}`);
+    }
+    if (lines.length)
+        lines.push('');
+    // Caller provides preview content lines (e.g., label + excerpt or list)
+    for (const l of options.previewLines)
+        lines.push(l);
+    if (options.previewLines.length)
+        lines.push('');
+    const baseLen = typeof c.totalLength === 'number' ? c.totalLength : (typeof payloadOrThunk === 'string' ? payloadOrThunk.length : 0);
+    const estTokens = Math.round(baseLen / 3);
+    lines.push(`Output is large (~${estTokens} tokens). To fetch full content without resending parameters, call confirm_output({ token: "${token}" }).`);
+    if (options.extraTips && options.extraTips.length) {
+        for (const tip of options.extraTips)
+            lines.push(tip);
+    }
+    return { token, lines };
+}
 export class ConfirmOutputTool {
     constructor(server) {
         this.server = server;
@@ -30,11 +98,17 @@ export class ConfirmOutputTool {
         const token = typeof args.token === 'string' ? args.token : '';
         if (!token)
             return createErrorResponse('Token is required');
-        const res = consumePayload(token);
+        const res = consumeThunk(token);
         if (!res.ok) {
             const err = res.error;
             return createErrorResponse(err);
         }
-        return createSuccessResponse(res.payload);
+        try {
+            const out = await res.thunk();
+            return createSuccessResponse(out);
+        }
+        catch (e) {
+            return createErrorResponse(e.message || 'Failed to produce output');
+        }
     }
 }

package/dist/tools/common/types.js

@@ -1,9 +1,34 @@
 // Helper functions for creating responses
+// Global error message sanitizer: removes stack traces and noisy engine frames
+function sanitizeErrorMessage(message) {
+    if (!message)
+        return '';
+    // If message already contains helpful guidance (e.g., Tips), avoid truncation.
+    const hasGuidance = /\bTips?:\b|💡/.test(message);
+    // Trim to concise selector phrase only when there is no guidance to preserve.
+    if (!hasGuidance) {
+        const cutoffPhrases = [
+            'is not a valid selector.',
+            'is not a valid selector',
+        ];
+        for (const phrase of cutoffPhrases) {
+            const idx = message.indexOf(phrase);
+            if (idx !== -1) {
+                return message.slice(0, idx + phrase.length).trim();
+            }
+        }
+    }
+    // Remove typical stack lines (e.g., " at query (...)" or " at ... (<anonymous>:x:y)")
+    const lines = message.split(/\r?\n/);
+    const filtered = lines.filter(l => !/^\s*at\b/.test(l) && !/<anonymous>:\d+:\d+/.test(l));
+    return filtered.join('\n').trim();
+}
 export function createErrorResponse(message) {
+    const sanitized = sanitizeErrorMessage(message);
     return {
         content: [{
                 type: "text",
-                text: message
+                text: sanitized
             }],
         isError: true
     };

package/package.json

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