mcp-web-inspector 0.1.0

package/dist/tools/browser/comparePositions.js

@@ -0,0 +1,149 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for comparing positions and sizes of two elements
+ */
+export class ComparePositionsTool extends BrowserToolBase {
+    /**
+     * Execute the compare positions tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector1 = this.normalizeSelector(args.selector1);
+            const selector2 = this.normalizeSelector(args.selector2);
+            const checkAlignment = args.checkAlignment;
+            // Validate checkAlignment parameter
+            const validAlignments = ['top', 'left', 'right', 'bottom', 'width', 'height'];
+            if (!validAlignments.includes(checkAlignment)) {
+                return createErrorResponse(`Invalid checkAlignment value: "${checkAlignment}". Must be one of: ${validAlignments.join(', ')}`);
+            }
+            try {
+                // Get locators for both elements
+                const locator1 = page.locator(selector1);
+                const locator2 = page.locator(selector2);
+                // Check if both elements exist
+                const count1 = await locator1.count();
+                const count2 = await locator2.count();
+                if (count1 === 0) {
+                    return createErrorResponse(`First element not found: ${args.selector1}`);
+                }
+                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 = '';
+                if (count1 > 1) {
+                    warnings += `⚠ 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';
+                }
+                // Get bounding boxes
+                const box1 = await targetLocator1.boundingBox();
+                const box2 = await targetLocator2.boundingBox();
+                // Get element descriptors
+                const getDescriptor = async (locator) => {
+                    return await locator.evaluate((element) => {
+                        const tagName = element.tagName.toLowerCase();
+                        const testId = element.getAttribute('data-testid') || element.getAttribute('data-test') || element.getAttribute('data-cy');
+                        const id = element.id ? `#${element.id}` : '';
+                        const classes = element.className && typeof element.className === 'string'
+                            ? `.${element.className.split(' ').filter(c => c).join('.')}`
+                            : '';
+                        let descriptor = `<${tagName}`;
+                        if (testId)
+                            descriptor += ` data-testid="${testId}"`;
+                        else if (id)
+                            descriptor += id;
+                        else if (classes)
+                            descriptor += classes;
+                        descriptor += '>';
+                        return descriptor;
+                    });
+                };
+                const descriptor1 = await getDescriptor(targetLocator1);
+                const descriptor2 = await getDescriptor(targetLocator2);
+                // Handle hidden elements
+                if (!box1) {
+                    return createErrorResponse(`First element is hidden or has no dimensions: ${descriptor1}`);
+                }
+                if (!box2) {
+                    return createErrorResponse(`Second element is hidden or has no dimensions: ${descriptor2}`);
+                }
+                // Calculate values based on alignment type
+                let value1;
+                let value2;
+                let label;
+                let unit = 'px';
+                switch (checkAlignment) {
+                    case 'top':
+                        value1 = Math.round(box1.y);
+                        value2 = Math.round(box2.y);
+                        label = 'Top';
+                        break;
+                    case 'left':
+                        value1 = Math.round(box1.x);
+                        value2 = Math.round(box2.x);
+                        label = 'Left';
+                        break;
+                    case 'right':
+                        value1 = Math.round(box1.x + box1.width);
+                        value2 = Math.round(box2.x + box2.width);
+                        label = 'Right';
+                        break;
+                    case 'bottom':
+                        value1 = Math.round(box1.y + box1.height);
+                        value2 = Math.round(box2.y + box2.height);
+                        label = 'Bottom';
+                        break;
+                    case 'width':
+                        value1 = Math.round(box1.width);
+                        value2 = Math.round(box2.width);
+                        label = 'Width';
+                        break;
+                    case 'height':
+                        value1 = Math.round(box1.height);
+                        value2 = Math.round(box2.height);
+                        label = 'Height';
+                        break;
+                    default:
+                        return createErrorResponse(`Unexpected alignment type: ${checkAlignment}`);
+                }
+                const difference = Math.abs(value1 - value2);
+                const aligned = difference === 0;
+                const alignmentSymbol = aligned ? '✓' : '✗';
+                const alignmentStatus = aligned ? 'aligned' : 'not aligned';
+                // Extract short name from descriptor for compact output
+                const getShortName = (descriptor, selector) => {
+                    const testIdMatch = descriptor.match(/data-testid="([^"]+)"/);
+                    if (testIdMatch)
+                        return testIdMatch[1];
+                    const idMatch = descriptor.match(/#([^>]+)/);
+                    if (idMatch)
+                        return idMatch[1];
+                    // Use original selector if available
+                    return selector;
+                };
+                const name1 = getShortName(descriptor1, args.selector1);
+                const name2 = getShortName(descriptor2, args.selector2);
+                // Build compact text format
+                const output = warnings +
+                    `Alignment Check:\n` +
+                    `${descriptor1} vs ${descriptor2}\n\n` +
+                    `${label}: ${alignmentSymbol} ${alignmentStatus}\n` +
+                    `  ${name1}: ${value1}${unit}\n` +
+                    `  ${name2}: ${value2}${unit}\n` +
+                    `  Difference: ${difference}${unit}`;
+                return createSuccessResponse(output);
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to compare positions: ${error.message}`);
+            }
+        });
+    }
+}

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

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

package/dist/tools/browser/computedStyles.js

@@ -0,0 +1,128 @@
+import { BrowserToolBase } from './base.js';
+export class GetComputedStylesTool extends BrowserToolBase {
+    constructor() {
+        super(...arguments);
+        this.DEFAULT_PROPERTIES = [
+            'display', 'position', 'width', 'height',
+            'opacity', 'visibility', 'z-index', 'overflow',
+            'margin', 'padding',
+            'font-size', 'font-weight', 'color', 'background-color'
+        ];
+    }
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const normalizedSelector = this.normalizeSelector(args.selector);
+            // Parse properties parameter
+            const properties = args.properties
+                ? args.properties.split(',').map(p => p.trim())
+                : this.DEFAULT_PROPERTIES;
+            // Find the element
+            const locator = page.locator(normalizedSelector);
+            const count = await locator.count();
+            if (count === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✗ Element not found: ${args.selector}`
+                        }
+                    ],
+                    isError: true
+                };
+            }
+            // Handle multiple matches by using first() - show warning (consistent with compare_positions)
+            const targetLocator = count > 1 ? locator.first() : locator;
+            let warning = '';
+            if (count > 1) {
+                warning = `⚠ Warning: Selector matched ${count} elements, using first\n\n`;
+            }
+            // Get element tag and selector info
+            const elementInfo = await targetLocator.evaluate((el) => {
+                const attrs = [];
+                const tag = el.tagName.toLowerCase();
+                if (el.id)
+                    attrs.push(`#${el.id}`);
+                if (el.className && typeof el.className === 'string') {
+                    const classes = el.className.split(' ').filter(c => c).slice(0, 2);
+                    if (classes.length)
+                        attrs.push(`.${classes.join('.')}`);
+                }
+                const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('data-cy');
+                if (testId)
+                    attrs.push(`data-testid="${testId}"`);
+                return {
+                    tag,
+                    display: attrs.length ? `<${tag} ${attrs.join(' ')}>` : `<${tag}>`
+                };
+            });
+            // Get computed styles
+            const styles = await targetLocator.evaluate((el, props) => {
+                const computed = window.getComputedStyle(el);
+                const result = {};
+                props.forEach((prop) => {
+                    result[prop] = computed.getPropertyValue(prop);
+                });
+                return result;
+            }, properties);
+            // Group styles by category
+            const layout = [];
+            const visibility = [];
+            const spacing = [];
+            const typography = [];
+            const other = [];
+            const layoutProps = ['display', 'position', 'width', 'height', 'top', 'left', 'right', 'bottom'];
+            const visibilityProps = ['opacity', 'visibility', 'z-index', 'overflow', 'overflow-x', 'overflow-y'];
+            const spacingProps = ['margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+                'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left'];
+            const typographyProps = ['font-size', 'font-weight', 'font-family', 'color', 'line-height', 'text-align'];
+            Object.entries(styles).forEach(([prop, value]) => {
+                const line = `  ${prop}: ${value}`;
+                if (layoutProps.includes(prop)) {
+                    layout.push(line);
+                }
+                else if (visibilityProps.includes(prop)) {
+                    visibility.push(line);
+                }
+                else if (spacingProps.includes(prop)) {
+                    spacing.push(line);
+                }
+                else if (typographyProps.includes(prop)) {
+                    typography.push(line);
+                }
+                else {
+                    other.push(line);
+                }
+            });
+            // Build output
+            const sections = [];
+            if (warning) {
+                sections.push(warning.trim());
+            }
+            sections.push(`Computed Styles: ${elementInfo.display}\n`);
+            if (layout.length) {
+                sections.push('Layout:\n' + layout.join('\n'));
+            }
+            if (visibility.length) {
+                sections.push('Visibility:\n' + visibility.join('\n'));
+            }
+            if (spacing.length) {
+                sections.push('Spacing:\n' + spacing.join('\n'));
+            }
+            if (typography.length) {
+                sections.push('Typography:\n' + typography.join('\n'));
+            }
+            if (other.length) {
+                sections.push('Other:\n' + other.join('\n'));
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: sections.join('\n\n')
+                    }
+                ],
+                isError: false
+            };
+        });
+    }
+}

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

@@ -0,0 +1,37 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for retrieving and filtering console logs from the browser
+ */
+export declare class ConsoleLogsTool extends BrowserToolBase {
+    private consoleLogs;
+    private lastCallTimestamp;
+    private lastNavigationTimestamp;
+    private lastInteractionTimestamp;
+    /**
+     * Register a console message
+     * @param type The type of console message
+     * @param text The text content of the message
+     */
+    registerConsoleMessage(type: string, text: string): void;
+    /**
+     * Update the last navigation timestamp
+     */
+    updateLastNavigationTimestamp(): void;
+    /**
+     * Update the last interaction timestamp
+     */
+    updateLastInteractionTimestamp(): void;
+    /**
+     * Execute the console logs tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+    /**
+     * Get all console logs
+     */
+    getConsoleLogs(): string[];
+    /**
+     * Clear all console logs
+     */
+    clearConsoleLogs(): void;
+}

package/dist/tools/browser/console.js

@@ -0,0 +1,106 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse } from '../common/types.js';
+/**
+ * Tool for retrieving and filtering console logs from the browser
+ */
+export class ConsoleLogsTool extends BrowserToolBase {
+    constructor() {
+        super(...arguments);
+        this.consoleLogs = [];
+        this.lastCallTimestamp = 0;
+        this.lastNavigationTimestamp = 0;
+        this.lastInteractionTimestamp = 0;
+    }
+    /**
+     * Register a console message
+     * @param type The type of console message
+     * @param text The text content of the message
+     */
+    registerConsoleMessage(type, text) {
+        const logEntry = {
+            timestamp: Date.now(),
+            message: `[${type}] ${text}`
+        };
+        this.consoleLogs.push(logEntry);
+    }
+    /**
+     * Update the last navigation timestamp
+     */
+    updateLastNavigationTimestamp() {
+        this.lastNavigationTimestamp = Date.now();
+    }
+    /**
+     * Update the last interaction timestamp
+     */
+    updateLastInteractionTimestamp() {
+        this.lastInteractionTimestamp = Date.now();
+    }
+    /**
+     * Execute the console logs tool
+     */
+    async execute(args, context) {
+        // No need to use safeExecute here as we don't need to interact with the page
+        // We're just filtering and returning logs that are already stored
+        let logs = [...this.consoleLogs];
+        // Filter by timestamp if 'since' parameter is specified
+        if (args.since) {
+            let sinceTimestamp;
+            switch (args.since) {
+                case 'last-call':
+                    sinceTimestamp = this.lastCallTimestamp;
+                    break;
+                case 'last-navigation':
+                    sinceTimestamp = this.lastNavigationTimestamp;
+                    break;
+                case 'last-interaction':
+                    sinceTimestamp = this.lastInteractionTimestamp;
+                    break;
+                default:
+                    return createSuccessResponse(`Invalid 'since' value: ${args.since}. Must be one of: last-call, last-navigation, last-interaction`);
+            }
+            logs = logs.filter(log => log.timestamp > sinceTimestamp);
+        }
+        // Update last call timestamp
+        this.lastCallTimestamp = Date.now();
+        // Filter by type if specified
+        if (args.type && args.type !== 'all') {
+            logs = logs.filter(log => log.message.startsWith(`[${args.type}]`));
+        }
+        // Filter by search text if specified
+        if (args.search) {
+            logs = logs.filter(log => log.message.includes(args.search));
+        }
+        // Limit the number of logs if specified
+        if (args.limit && args.limit > 0) {
+            logs = logs.slice(-args.limit);
+        }
+        // Extract messages from log entries
+        const messages = logs.map(log => log.message);
+        // Clear logs if requested
+        if (args.clear) {
+            this.consoleLogs = [];
+        }
+        // Format the response
+        if (messages.length === 0) {
+            return createSuccessResponse("No console logs matching the criteria");
+        }
+        else {
+            return createSuccessResponse([
+                `Retrieved ${messages.length} console log(s):`,
+                ...messages
+            ]);
+        }
+    }
+    /**
+     * Get all console logs
+     */
+    getConsoleLogs() {
+        return this.consoleLogs.map(log => log.message);
+    }
+    /**
+     * Clear all console logs
+     */
+    clearConsoleLogs() {
+        this.consoleLogs = [];
+    }
+}

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

@@ -0,0 +1,9 @@
+import { ToolHandler } from '../common/types.js';
+import { BrowserToolBase } from './base.js';
+import type { ToolContext, ToolResponse } from '../common/types.js';
+export interface ElementExistsArgs {
+    selector: string;
+}
+export declare class ElementExistsTool extends BrowserToolBase implements ToolHandler {
+    execute(args: ElementExistsArgs, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/elementExists.js

@@ -0,0 +1,57 @@
+import { BrowserToolBase } from './base.js';
+export class ElementExistsTool extends BrowserToolBase {
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const normalizedSelector = this.normalizeSelector(args.selector);
+            const locator = page.locator(normalizedSelector);
+            const count = await locator.count();
+            if (count === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✗ not found: ${args.selector}`
+                        }
+                    ],
+                    isError: false
+                };
+            }
+            // Get element info for better output
+            const element = locator.first();
+            const elementInfo = await element.evaluate((el) => {
+                const tag = el.tagName.toLowerCase();
+                const parts = [tag];
+                if (el.id)
+                    parts.push(`#${el.id}`);
+                if (el.className && typeof el.className === 'string') {
+                    const classes = el.className.split(' ').filter(c => c).slice(0, 2);
+                    if (classes.length) {
+                        classes.forEach(c => parts.push(`.${c}`));
+                    }
+                }
+                return parts.join('');
+            }).catch(() => args.selector);
+            if (count === 1) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✓ exists: <${elementInfo}>`
+                        }
+                    ],
+                    isError: false
+                };
+            }
+            // Multiple matches
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✓ exists: <${elementInfo}> (${count} matches)`
+                    }
+                ],
+                isError: false
+            };
+        });
+    }
+}

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

@@ -0,0 +1,21 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for checking element visibility with detailed diagnostics
+ * Addresses the #1 debugging pain point: "Why won't it click?"
+ */
+export declare class ElementVisibilityTool extends BrowserToolBase {
+    /**
+     * Execute the element visibility tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for getting element position and size
+ */
+export declare class ElementPositionTool extends BrowserToolBase {
+    /**
+     * Execute the element position tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/elementInspection.js

@@ -0,0 +1,151 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for checking element visibility with detailed diagnostics
+ * Addresses the #1 debugging pain point: "Why won't it click?"
+ */
+export class ElementVisibilityTool extends BrowserToolBase {
+    /**
+     * Execute the element visibility tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector = this.normalizeSelector(args.selector);
+            const locator = page.locator(selector);
+            try {
+                // Check if element exists
+                const count = await locator.count();
+                if (count === 0) {
+                    return createErrorResponse(`Element not found: ${args.selector}`);
+                }
+                // Get basic visibility (Playwright's isVisible)
+                const isVisible = await locator.isVisible();
+                // Evaluate detailed visibility information in browser context
+                const visibilityData = await locator.evaluate((element) => {
+                    const rect = element.getBoundingClientRect();
+                    const viewportHeight = window.innerHeight;
+                    const viewportWidth = window.innerWidth;
+                    // Calculate viewport intersection ratio
+                    const visibleTop = Math.max(0, rect.top);
+                    const visibleBottom = Math.min(viewportHeight, rect.bottom);
+                    const visibleLeft = Math.max(0, rect.left);
+                    const visibleRight = Math.min(viewportWidth, rect.right);
+                    const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+                    const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+                    const visibleArea = visibleHeight * visibleWidth;
+                    const totalArea = rect.height * rect.width;
+                    const viewportRatio = totalArea > 0 ? visibleArea / totalArea : 0;
+                    // Check if element is in viewport
+                    const isInViewport = viewportRatio > 0;
+                    // Get computed styles
+                    const styles = window.getComputedStyle(element);
+                    const opacity = parseFloat(styles.opacity);
+                    const display = styles.display;
+                    const visibility = styles.visibility;
+                    // Check if clipped by overflow:hidden
+                    let isClipped = false;
+                    let parent = element.parentElement;
+                    while (parent) {
+                        const parentStyle = window.getComputedStyle(parent);
+                        if (parentStyle.overflow === 'hidden' ||
+                            parentStyle.overflowX === 'hidden' ||
+                            parentStyle.overflowY === 'hidden') {
+                            const parentRect = parent.getBoundingClientRect();
+                            // Check if element is outside parent bounds
+                            if (rect.right < parentRect.left ||
+                                rect.left > parentRect.right ||
+                                rect.bottom < parentRect.top ||
+                                rect.top > parentRect.bottom) {
+                                isClipped = true;
+                                break;
+                            }
+                        }
+                        parent = parent.parentElement;
+                    }
+                    // Check if covered by another element (check center point)
+                    const centerX = rect.left + rect.width / 2;
+                    const centerY = rect.top + rect.height / 2;
+                    const topElement = document.elementFromPoint(centerX, centerY);
+                    const isCovered = topElement !== element && !element.contains(topElement);
+                    return {
+                        viewportRatio,
+                        isInViewport,
+                        opacity,
+                        display,
+                        visibility,
+                        isClipped,
+                        isCovered,
+                    };
+                });
+                // Determine if scroll is needed
+                const needsScroll = isVisible && !visibilityData.isInViewport;
+                const result = {
+                    // Playwright checks
+                    isVisible,
+                    isInViewport: visibilityData.isInViewport,
+                    viewportRatio: Math.round(visibilityData.viewportRatio * 100) / 100, // Round to 2 decimals
+                    // CSS properties
+                    opacity: visibilityData.opacity,
+                    display: visibilityData.display,
+                    visibility: visibilityData.visibility,
+                    // Failure diagnostics
+                    isClipped: visibilityData.isClipped,
+                    isCovered: visibilityData.isCovered,
+                    needsScroll,
+                };
+                return createSuccessResponse(JSON.stringify(result, null, 2));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to check visibility: ${error.message}`);
+            }
+        });
+    }
+}
+/**
+ * Tool for getting element position and size
+ */
+export class ElementPositionTool extends BrowserToolBase {
+    /**
+     * Execute the element position tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector = this.normalizeSelector(args.selector);
+            const locator = page.locator(selector);
+            try {
+                // Check if element exists
+                const count = await locator.count();
+                if (count === 0) {
+                    return createErrorResponse(`Element not found: ${args.selector}`);
+                }
+                // Get bounding box
+                const boundingBox = await locator.boundingBox();
+                if (!boundingBox) {
+                    return createErrorResponse(`Element has no bounding box (might be hidden or have display:none): ${args.selector}`);
+                }
+                // Check if in viewport
+                const inViewport = await locator.evaluate((element) => {
+                    const rect = element.getBoundingClientRect();
+                    const viewportHeight = window.innerHeight;
+                    const viewportWidth = window.innerWidth;
+                    // Element is in viewport if any part is visible
+                    return (rect.bottom > 0 &&
+                        rect.right > 0 &&
+                        rect.top < viewportHeight &&
+                        rect.left < viewportWidth);
+                });
+                const result = {
+                    x: Math.round(boundingBox.x),
+                    y: Math.round(boundingBox.y),
+                    width: Math.round(boundingBox.width),
+                    height: Math.round(boundingBox.height),
+                    inViewport,
+                };
+                return createSuccessResponse(JSON.stringify(result, null, 2));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to get position: ${error.message}`);
+            }
+        });
+    }
+}