mcp-web-inspector 0.3.0 → 0.4.1

package/dist/toolHandler.d.ts

@@ -19,6 +19,7 @@ export interface NetworkRequest {
         body: string | null;
     };
 }
+type ColorSchemeOverride = 'light' | 'dark' | 'no-preference';
 /**
  * Sets the session configuration
  */
@@ -49,6 +50,8 @@ export declare function clearNetworkLog(): void;
  * @param newPage The Page object to set as the global page
  */
 export declare function setGlobalPage(newPage: Page): Promise<void>;
+export declare function setColorSchemeOverride(scheme: ColorSchemeOverride | null): Promise<void>;
+export declare function getColorSchemeOverride(): ColorSchemeOverride | null;
 interface BrowserSettings {
     viewport?: {
         width?: number;

package/dist/toolHandler.js

@@ -5,6 +5,7 @@ import { getToolInstance, isBrowserTool, executeTool } from './tools/common/regi
 let browser;
 let page;
 let currentBrowserType = 'chromium';
+let currentDevice;
 let networkLog = [];
 let sessionConfig = {
     saveSession: false,
@@ -12,6 +13,7 @@ let sessionConfig = {
     screenshotsDir: './.mcp-web-inspector/screenshots',
     headlessDefault: false,
 };
+let colorSchemeOverride = null;
 /**
  * Sets the session configuration
  */
@@ -38,6 +40,7 @@ export function resetBrowserState() {
     browser = undefined;
     page = undefined;
     currentBrowserType = 'chromium';
+    currentDevice = undefined;
     networkLog = [];
 }
 /**
@@ -61,9 +64,34 @@ export async function setGlobalPage(newPage) {
     // Register console message handlers and network listeners for the new page
     await registerConsoleMessage(page);
     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.");
 }
+function getColorSchemeValue() {
+    return colorSchemeOverride;
+}
+async function applyColorScheme(targetPage) {
+    if (!targetPage) {
+        return;
+    }
+    try {
+        const scheme = getColorSchemeValue();
+        await targetPage.emulateMedia({ colorScheme: scheme ?? null });
+    }
+    catch (error) {
+        console.error("Failed to apply color scheme:", error);
+    }
+}
+export async function setColorSchemeOverride(scheme) {
+    colorSchemeOverride = scheme;
+    if (page && !page.isClosed()) {
+        await applyColorScheme(page);
+    }
+}
+export function getColorSchemeOverride() {
+    return colorSchemeOverride;
+}
 /**
  * Device preset mapping to Playwright device descriptors
  */
@@ -282,6 +310,17 @@ export async function ensureBrowser(browserSettings) {
             // Reset browser and page references
             resetBrowserState();
         }
+        // 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...`);
+            try {
+                await browser.close().catch(err => console.error("Error closing browser on device change:", err));
+            }
+            catch (e) {
+                // Ignore errors when closing browser
+            }
+            resetBrowserState();
+        }
         // If browser exists and viewport settings changed, resize the viewport
         if (browser && page && !page.isClosed() && browserSettings?.viewport) {
             const { width, height } = browserSettings.viewport;
@@ -318,11 +357,16 @@ export async function ensureBrowser(browserSettings) {
                 deviceConfig = CUSTOM_DEVICE_CONFIGS[playwrightDeviceName] || devices[playwrightDeviceName];
                 if (deviceConfig) {
                     console.error(`Using device preset: ${device} (${playwrightDeviceName})`);
+                    currentDevice = device;
                 }
                 else {
                     console.error(`Warning: Device preset ${playwrightDeviceName} not found`);
+                    currentDevice = undefined;
                 }
             }
+            else {
+                currentDevice = undefined;
+            }
             console.error(`Launching new ${browserType} browser instance...`);
             // Use the appropriate browser engine
             let browserInstance;
@@ -425,6 +469,7 @@ export async function ensureBrowser(browserSettings) {
             // Register console message handler and network listeners
             await registerConsoleMessage(page);
             await registerNetworkListeners(page);
+            await applyColorScheme(page);
         }
         // Verify page is still valid
         if (!page || page.isClosed()) {
@@ -435,7 +480,9 @@ export async function ensureBrowser(browserSettings) {
             // Re-register console message handler and network listeners
             await registerConsoleMessage(page);
             await registerNetworkListeners(page);
+            await applyColorScheme(page);
         }
+        await applyColorScheme(page);
         return page;
     }
     catch (error) {
@@ -458,6 +505,15 @@ export async function ensureBrowser(browserSettings) {
             const playwrightDeviceName = DEVICE_PRESETS[device];
             // Check custom configs first, then Playwright's built-in devices
             deviceConfig = CUSTOM_DEVICE_CONFIGS[playwrightDeviceName] || devices[playwrightDeviceName];
+            if (deviceConfig) {
+                currentDevice = device;
+            }
+            else {
+                currentDevice = undefined;
+            }
+        }
+        else {
+            currentDevice = undefined;
         }
         // Use the appropriate browser engine
         let browserInstance;
@@ -552,6 +608,7 @@ export async function ensureBrowser(browserSettings) {
         }
         await registerConsoleMessage(page);
         await registerNetworkListeners(page);
+        await applyColorScheme(page);
         return page;
     }
 }

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

@@ -12,11 +12,14 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      */
     abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
     /**
-     * Normalize selector shortcuts to full Playwright selectors
+     * 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']"
-     * - Everything else → pass through
+     * - 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)
      * @param selector The selector string
      * @returns Normalized selector
      */

package/dist/tools/browser/base.js

@@ -8,11 +8,14 @@ export class BrowserToolBase {
         this.server = server;
     }
     /**
-     * Normalize selector shortcuts to full Playwright selectors
+     * 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']"
-     * - Everything else → pass through
+     * - 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)
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -22,13 +25,22 @@ export class BrowserToolBase {
             'data-test:': 'data-test',
             'data-cy:': 'data-cy',
         };
+        // 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}"]`;
             }
         }
-        return selector; // CSS, text=, etc. pass through
+        // Clean up common escaping mistakes that LLMs make in CSS selectors
+        // These characters don't need to be escaped in CSS selectors: [ ] :
+        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, ':');
+        return cleaned;
     }
     /**
      * Ensures a page is available and returns it
@@ -140,7 +152,36 @@ export class BrowserToolBase {
      * @returns Object with { element: Locator, elementIndex: number, totalCount: number }
      */
     async selectPreferredLocator(locator, options) {
-        const count = await locator.count();
+        let count;
+        try {
+            count = await locator.count();
+        }
+        catch (error) {
+            // Catch selector syntax errors and provide helpful guidance
+            const errorMsg = error.message;
+            const selector = options?.originalSelector || 'selector';
+            if (errorMsg.includes('Unexpected token') ||
+                errorMsg.includes('Invalid selector') ||
+                errorMsg.includes('SyntaxError') ||
+                errorMsg.includes('selector')) {
+                throw new Error(`Invalid CSS selector: "${selector}"\n\n` +
+                    `Selector syntax error: ${errorMsg}\n\n` +
+                    `💡 Tips:\n` +
+                    `  • CSS selectors don't need backslash escapes for [ ] or :\n` +
+                    `  • Use .class-name or #id without escaping\n` +
+                    `  • For data attributes, use [data-attr="value"]\n` +
+                    `  • For testid shortcuts, use testid:name\n\n` +
+                    `Examples:\n` +
+                    `  ✓ .dark:bg-gray-700\n` +
+                    `  ✓ .top-[36px]\n` +
+                    `  ✓ testid:submit-button\n` +
+                    `  ✓ #login-form\n` +
+                    `  ✗ .dark\\:bg-gray-700 (unnecessary escape)\n` +
+                    `  ✗ .top-\\[36px\\] (unnecessary escape)`);
+            }
+            // Re-throw other errors as-is
+            throw error;
+        }
         if (count === 0) {
             throw new Error('No elements found');
         }

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

@@ -300,10 +300,11 @@ describe('GetHtmlTool', () => {
         expect(result.isError).toBe(false);
         expect(result.content[0].text).toContain('HTML content');
     });
-    test('should respect maxLength parameter', async () => {
+    test('should respect maxLength parameter for small HTML', async () => {
         const args = { maxLength: 50 };
-        const longHtml = '<div>' + 'A'.repeat(100) + '</div>';
-        mockEvaluate.mockImplementationOnce(() => Promise.resolve(longHtml));
+        // Small HTML that won't trigger preview threshold
+        const smallHtml = '<div>' + 'A'.repeat(100) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(smallHtml));
         const result = await visibleHtmlTool.execute(args, mockContext);
         expect(result.isError).toBe(false);
         expect(result.content[0].text).toContain('Output truncated due to size limits');
@@ -378,4 +379,107 @@ describe('GetHtmlTool', () => {
         expect(result.content[0].text).toContain('Failed to get visible HTML content');
         expect(result.content[0].text).toContain('Content retrieval failed');
     });
+    test('should return preview with token for large HTML (≥2000 chars)', async () => {
+        const args = {};
+        // Large HTML that exceeds preview threshold
+        const largeHtml = '<div>' + 'X'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(largeHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain('HTML size:');
+        expect(result.content[0].text).toContain('exceeds 2000 char threshold');
+        expect(result.content[0].text).toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toContain('⚠️ Full HTML not returned to save tokens');
+        expect(result.content[0].text).toContain('💡 RECOMMENDED: Use token-efficient alternatives');
+        expect(result.content[0].text).toContain('inspect_dom()');
+        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+    });
+    test('should return full HTML with valid confirmToken', async () => {
+        const args = {};
+        // Large HTML
+        const largeHtml = '<div>' + 'Y'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get preview and token
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        expect(previewResult.isError).toBe(false);
+        // Extract token from preview
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        expect(tokenMatch).toBeTruthy();
+        const token = tokenMatch[1];
+        // Second call - with token
+        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        expect(fullResult.content[0].text).not.toContain('Preview (first 500 chars)');
+        expect(fullResult.content[0].text).toContain('💡 TIP: If you need structured inspection');
+    });
+    test('should generate new token for invalid confirmToken', async () => {
+        const args = { confirmToken: 'invalid123' };
+        // Large HTML
+        const largeHtml = '<div>' + 'Z'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(largeHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain('HTML size:');
+        expect(result.content[0].text).toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+        // Should not return full HTML
+        expect(result.content[0].text).not.toContain('Z'.repeat(3000));
+    });
+    test('should return small HTML directly without token requirement', async () => {
+        const args = {};
+        // Small HTML below threshold
+        const smallHtml = '<div>Small content with 1500 chars: ' + 'A'.repeat(1400) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(smallHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain(smallHtml);
+        expect(result.content[0].text).not.toContain('confirmToken:');
+        expect(result.content[0].text).not.toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toContain('💡 TIP: If you need structured inspection');
+    });
+    test('should consume token only once (one-time use)', async () => {
+        const args = {};
+        // Large HTML
+        const largeHtml = '<div>' + 'M'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get token
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const token = tokenMatch[1];
+        // Second call - use token (should work)
+        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        // Third call - try to reuse same token (should fail, get new preview)
+        const retryResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(retryResult.isError).toBe(false);
+        expect(retryResult.content[0].text).toContain('Preview (first 500 chars)');
+        expect(retryResult.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+        // Should have different token
+        const newTokenMatch = retryResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        expect(newTokenMatch[1]).not.toBe(token);
+    });
+    test('should handle large HTML with selector and confirmToken', async () => {
+        const largeHtml = '<section>' + 'S'.repeat(3000) + '</section>';
+        const args = { selector: 'testid:large-section' };
+        mockLocator.mockImplementation(() => ({}));
+        const mockElement = {
+            evaluate: jest.fn(async () => largeHtml),
+        };
+        const selectSpy = jest
+            .spyOn(visibleHtmlTool, 'selectPreferredLocator')
+            .mockResolvedValue({ element: mockElement, elementIndex: 0, totalCount: 1 });
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get preview
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        expect(previewResult.content[0].text).toContain('(from "testid:large-section")');
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const token = tokenMatch[1];
+        // Second call - with token
+        const fullResult = await visibleHtmlTool.execute({ selector: 'testid:large-section', confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        selectSpy.mockRestore();
+    });
 });

package/dist/tools/browser/content/get_html.d.ts

@@ -4,6 +4,7 @@ import { ToolContext, ToolResponse, ToolMetadata, SessionConfig } from '../../co
  * Tool for getting HTML from the page
  */
 export declare class GetHtmlTool extends BrowserToolBase {
+    private confirmTokens;
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     execute(args: any, context: ToolContext): Promise<ToolResponse>;
 }

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

@@ -4,10 +4,14 @@ import { createSuccessResponse, createErrorResponse, } from '../../common/types.
  * Tool for getting HTML from the page
  */
 export class GetHtmlTool extends BrowserToolBase {
+    constructor() {
+        super(...arguments);
+        this.confirmTokens = new Map(); // Stores tokens for two-step confirmation
+    }
     static getMetadata(sessionConfig) {
         return {
             name: "get_html",
-            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Returns HTML up to 20000 chars (truncated if longer), scripts removed by default for security/size. Supports testid shortcuts.",
+            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements), shows preview with token-based confirmation if larger. Scripts removed by default for security/size. Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -26,6 +30,10 @@ export class GetHtmlTool extends BrowserToolBase {
                     maxLength: {
                         type: "number",
                         description: "Maximum number of characters to return (default: 20000)"
+                    },
+                    confirmToken: {
+                        type: "string",
+                        description: "Confirmation token from preview response (required to retrieve large HTML). Get this token by calling without confirmToken first - the preview will include the token to use."
                     }
                 },
                 required: [],
@@ -37,6 +45,8 @@ export class GetHtmlTool extends BrowserToolBase {
             ? Math.floor(args.maxLength)
             : 20000;
         const clean = args.clean ?? false;
+        const confirmToken = args.confirmToken;
+        const PREVIEW_THRESHOLD = 2000;
         if (!context.page) {
             return createErrorResponse('Page is not available');
         }
@@ -58,6 +68,7 @@ export class GetHtmlTool extends BrowserToolBase {
                     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);
                     rawHtml = await element.evaluate((target) => {
@@ -99,6 +110,40 @@ export class GetHtmlTool extends BrowserToolBase {
                 const safeMaxLength = requestedMaxLength > 0 ? requestedMaxLength : 20000;
                 const processedHtml = sanitizedHtml ?? '';
                 const originalLength = processedHtml.length;
+                // Generate key for this HTML request
+                const tokenKey = `${args.selector || 'page'}:${originalLength}`;
+                // Check if HTML is too large
+                if (originalLength >= PREVIEW_THRESHOLD) {
+                    // Verify if confirmToken matches
+                    const expectedToken = this.confirmTokens.get(tokenKey);
+                    if (confirmToken && expectedToken && confirmToken === expectedToken) {
+                        // Valid token - delete it (one-time use) and proceed to return HTML
+                        this.confirmTokens.delete(tokenKey);
+                    }
+                    else {
+                        // No token or invalid token - show preview and generate new token
+                        const newToken = Math.random().toString(36).substring(2, 10);
+                        this.confirmTokens.set(tokenKey, newToken);
+                        lines.push(`HTML size: ${originalLength.toLocaleString()} characters (exceeds ${PREVIEW_THRESHOLD} char threshold)`);
+                        lines.push('');
+                        lines.push('Preview (first 500 chars):');
+                        lines.push(processedHtml.slice(0, 500));
+                        if (originalLength > 500) {
+                            lines.push('...');
+                        }
+                        lines.push('');
+                        lines.push('⚠️ Full HTML not returned to save tokens (~' + Math.round(originalLength / 3) + ' tokens)');
+                        lines.push('');
+                        lines.push('💡 RECOMMENDED: Use token-efficient alternatives:');
+                        lines.push('   • inspect_dom() - structured view with positions and layout');
+                        lines.push('   • query_selector_all() - find specific elements');
+                        lines.push('   • get_computed_styles() - CSS values for debugging');
+                        lines.push('');
+                        lines.push(`To get full HTML anyway, call again with: confirmToken: "${newToken}"`);
+                        return createSuccessResponse(lines.join('\n'));
+                    }
+                }
+                // Return full HTML (either small or explicitly requested)
                 let displayHtml = processedHtml;
                 const truncated = displayHtml.length > safeMaxLength;
                 if (truncated) {

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

@@ -53,6 +53,7 @@ export class GetTextTool extends BrowserToolBase {
                     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);
                     textContent = await element.evaluate((target) => {

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

@@ -14,7 +14,7 @@ export class ScreenshotTool extends BrowserToolBase {
         const screenshotsDir = sessionConfig?.screenshotsDir || './.mcp-web-inspector/screenshots';
         return {
             name: "screenshot",
-            description: `⚠️ RARELY NEEDED: Screenshots are NOT useful for LLMs to analyze layouts, margins, or alignment issues. Use inspect_dom(), compare_positions(), or measure_element() instead - they provide precise numerical data. Only take screenshots for: (1) sharing with humans for visual confirmation, (2) documenting test results, or (3) verifying colors/images. Screenshots are saved to ${screenshotsDir}. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`,
+            description: `📸 VISUAL OUTPUT TOOL - Captures page/element appearance and saves to file. Essential for: visual regression testing, sharing with humans, confirming UI appearance (colors/fonts/images). ⚠️ NOT for layout debugging (positions/sizes/alignment/margins) - use inspect_dom/compare_positions/inspect_ancestors/get_computed_styles instead (structural data is token-efficient, screenshots require ~1,500 tokens to read). Screenshots saved to ${screenshotsDir}. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -82,9 +82,13 @@ export class ScreenshotTool extends BrowserToolBase {
                 });
                 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 - only use Read tool if visual analysis is essential');
             // Add actionable guidance based on screenshot context
             messages.push('');
-            messages.push('💡 To debug layout issues in this screenshot:');
+            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)');

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

@@ -36,6 +36,7 @@ export class CheckVisibilityTool extends BrowserToolBase {
                 // 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
                 const multipleMatchWarning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount);

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

@@ -44,6 +44,7 @@ export class GetComputedStylesTool extends BrowserToolBase {
             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
             const warning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount);

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

@@ -46,7 +46,9 @@ export class InspectAncestorsTool extends BrowserToolBase {
                     isError: true,
                 };
             }
-            const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator);
+            const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
+                originalSelector: args.selector,
+            });
             // Use the selected element for ancestor traversal
             const ancestors = await element.evaluate((el, lim) => {
                 const chain = [];

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

@@ -78,7 +78,9 @@ More efficient than get_html() or evaluate(). Supports testid shortcuts.`,
                 if (count === 0) {
                     return createErrorResponse(`Element not found: ${args.selector || 'body'}`);
                 }
-                const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator);
+                const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
+                    originalSelector: args.selector || 'body',
+                });
                 // Get the target element and its semantic children
                 const inspectionData = await element.evaluate((target, { hidden, max, maxDepth }) => {
                     // Helper to check if element is visible

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

@@ -27,6 +27,7 @@ export class MeasureElementTool extends BrowserToolBase {
             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
             const warning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount);

package/dist/tools/browser/lifecycle/index.d.ts

@@ -1 +1,2 @@
 export { CloseTool } from './close.js';
+export { SetColorSchemeTool } from './set_color_scheme.js';

package/dist/tools/browser/lifecycle/index.js

@@ -1 +1,2 @@
 export { CloseTool } from './close.js';
+export { SetColorSchemeTool } from './set_color_scheme.js';

package/dist/tools/browser/lifecycle/set_color_scheme.d.ts

@@ -0,0 +1,9 @@
+import { BrowserToolBase } from '../base.js';
+import { ToolContext, ToolMetadata, ToolResponse, SessionConfig } from '../../common/types.js';
+/**
+ * Tool for setting prefers-color-scheme emulation
+ */
+export declare class SetColorSchemeTool extends BrowserToolBase {
+    static getMetadata(_sessionConfig?: SessionConfig): ToolMetadata;
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/lifecycle/set_color_scheme.js

@@ -0,0 +1,52 @@
+import { BrowserToolBase } from '../base.js';
+import { createErrorResponse, createSuccessResponse, } from '../../common/types.js';
+function normalizeScheme(rawValue) {
+    if (typeof rawValue !== 'string') {
+        return null;
+    }
+    const normalized = rawValue.trim().toLowerCase();
+    if (normalized === 'dark' ||
+        normalized === 'light' ||
+        normalized === 'system' ||
+        normalized === 'no-preference') {
+        return normalized;
+    }
+    return null;
+}
+/**
+ * Tool for setting prefers-color-scheme emulation
+ */
+export class SetColorSchemeTool extends BrowserToolBase {
+    static getMetadata(_sessionConfig) {
+        return {
+            name: "set_color_scheme",
+            description: "Set the browser color scheme that controls CSS prefers-color-scheme. Defaults to system appearance. Use before inspecting colors or taking screenshots. Options: system (clear override to follow OS/browser setting), dark, light, no-preference (simulate agents with no declared preference). Returns confirmation of the active scheme.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    scheme: {
+                        type: "string",
+                        description: "Color scheme to emulate: 'system', 'dark', 'light', or 'no-preference'. Example: { scheme: 'dark' }",
+                    },
+                },
+                required: ["scheme"],
+            },
+        };
+    }
+    async execute(args, context) {
+        const schemeInput = normalizeScheme(args.scheme);
+        if (!schemeInput) {
+            return createErrorResponse(`Invalid scheme "${args.scheme}". Use one of: system, dark, light, no-preference.`);
+        }
+        return this.safeExecute(context, async () => {
+            const { setColorSchemeOverride, getColorSchemeOverride } = await import('../../../toolHandler.js');
+            const override = schemeInput === 'system'
+                ? null
+                : schemeInput;
+            await setColorSchemeOverride(override);
+            const active = getColorSchemeOverride();
+            const label = active ?? 'system';
+            return createSuccessResponse(`Color scheme set to ${label}.`);
+        });
+    }
+}

package/dist/tools/browser/register.js

@@ -6,6 +6,7 @@ import { ScrollToElementTool } from './navigation/scroll_to_element.js';
 import { ScrollByTool } from './navigation/scroll_by.js';
 // Lifecycle
 import { CloseTool } from './lifecycle/close.js';
+import { SetColorSchemeTool } from './lifecycle/set_color_scheme.js';
 // Interaction
 import { ClickTool } from './interaction/click.js';
 import { FillTool } from './interaction/fill.js';
@@ -40,13 +41,15 @@ import { GetRequestDetailsTool } from './network/get_request_details.js';
 import { WaitForElementTool } from './waiting/wait_for_element.js';
 import { WaitForNetworkIdleTool } from './waiting/wait_for_network_idle.js';
 export const BROWSER_TOOL_CLASSES = [
-    // Navigation (6)
+    // Navigation (5)
     NavigateTool,
     GoBackTool,
     GoForwardTool,
     ScrollToElementTool,
     ScrollByTool,
+    // Lifecycle (2)
     CloseTool,
+    SetColorSchemeTool,
     // Interaction (7)
     ClickTool,
     FillTool,

package/package.json

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