mcp-web-inspector 0.1.0

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

@@ -0,0 +1,11 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * 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/elementPosition.js

@@ -0,0 +1,107 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * 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}`);
+                }
+                // Handle multiple matches by using first() - show warning
+                const targetLocator = count > 1 ? locator.first() : locator;
+                const multipleMatchWarning = count > 1
+                    ? `⚠ Warning: Selector matched ${count} elements, showing first:\n\n`
+                    : '';
+                // Get bounding box
+                const boundingBox = await targetLocator.boundingBox();
+                if (!boundingBox) {
+                    // Get element info for better error message
+                    const hiddenInfo = await targetLocator.evaluate((element) => {
+                        const styles = window.getComputedStyle(element);
+                        const tagName = element.tagName.toLowerCase();
+                        const testId = element.getAttribute('data-testid') || element.getAttribute('data-test') || element.getAttribute('data-cy');
+                        let descriptor = `<${tagName}`;
+                        if (testId)
+                            descriptor += ` data-testid="${testId}"`;
+                        descriptor += '>';
+                        return {
+                            descriptor,
+                            display: styles.display,
+                            opacity: styles.opacity,
+                            visibility: styles.visibility,
+                            width: parseFloat(styles.width) || 0,
+                            height: parseFloat(styles.height) || 0
+                        };
+                    });
+                    // Return structured response instead of error
+                    let reason = 'unknown reason';
+                    if (hiddenInfo.display === 'none') {
+                        reason = 'display: none';
+                    }
+                    else if (hiddenInfo.width === 0 || hiddenInfo.height === 0) {
+                        reason = 'zero size';
+                    }
+                    else if (parseFloat(hiddenInfo.opacity) === 0) {
+                        reason = 'opacity: 0';
+                    }
+                    else if (hiddenInfo.visibility === 'hidden') {
+                        reason = 'visibility: hidden';
+                    }
+                    const output = multipleMatchWarning +
+                        `Position: ${hiddenInfo.descriptor}\n` +
+                        `@ null (element hidden: ${reason})\n` +
+                        `display: ${hiddenInfo.display}, opacity: ${hiddenInfo.opacity}, visibility: ${hiddenInfo.visibility}`;
+                    return createSuccessResponse(output);
+                }
+                // Check if in viewport and get element tag info
+                const elementData = await targetLocator.evaluate((element) => {
+                    const rect = element.getBoundingClientRect();
+                    const viewportHeight = window.innerHeight;
+                    const viewportWidth = window.innerWidth;
+                    // Element is in viewport if any part is visible
+                    const inViewport = (rect.bottom > 0 &&
+                        rect.right > 0 &&
+                        rect.top < viewportHeight &&
+                        rect.left < viewportWidth);
+                    // Build element descriptor
+                    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 { inViewport, descriptor };
+                });
+                // Build compact text format
+                const x = Math.round(boundingBox.x);
+                const y = Math.round(boundingBox.y);
+                const width = Math.round(boundingBox.width);
+                const height = Math.round(boundingBox.height);
+                const viewportSymbol = elementData.inViewport ? '✓' : '✗';
+                const viewportStatus = elementData.inViewport ? 'in viewport' : 'outside viewport';
+                const output = multipleMatchWarning +
+                    `Position: ${elementData.descriptor}\n@ (${x},${y}) ${width}x${height}px, ${viewportSymbol} ${viewportStatus}`;
+                return createSuccessResponse(output);
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to get position: ${error.message}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,12 @@
+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>;
+}

package/dist/tools/browser/elementVisibility.js

@@ -0,0 +1,224 @@
+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}`);
+                }
+                // Handle multiple matches by using first() - show warning
+                const targetLocator = count > 1 ? locator.first() : locator;
+                const multipleMatchWarning = count > 1
+                    ? `⚠ Warning: Selector matched ${count} elements, showing first:\n\n`
+                    : '';
+                // Get basic visibility (Playwright's isVisible)
+                const isVisible = await targetLocator.isVisible();
+                // Evaluate detailed visibility information in browser context
+                const visibilityData = await targetLocator.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 and corners)
+                    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);
+                    // Get covering element info if covered
+                    let coveringElementInfo = '';
+                    let coveragePercent = 0;
+                    if (isCovered && topElement) {
+                        const coveringTagName = topElement.tagName.toLowerCase();
+                        const coveringTestId = topElement.getAttribute('data-testid');
+                        const coveringId = topElement.id ? `#${topElement.id}` : '';
+                        const coveringClasses = topElement.className && typeof topElement.className === 'string'
+                            ? `.${topElement.className.split(' ').filter((c) => c).slice(0, 2).join('.')}`
+                            : '';
+                        const coveringStyles = window.getComputedStyle(topElement);
+                        const zIndex = coveringStyles.zIndex;
+                        let descriptor = `<${coveringTagName}`;
+                        if (coveringTestId)
+                            descriptor += ` data-testid="${coveringTestId}"`;
+                        else if (coveringId)
+                            descriptor += coveringId;
+                        else if (coveringClasses)
+                            descriptor += coveringClasses;
+                        descriptor += `> (z-index: ${zIndex})`;
+                        coveringElementInfo = descriptor;
+                        // Calculate approximate coverage by checking multiple points
+                        const samplePoints = [
+                            [centerX, centerY],
+                            [rect.left + rect.width * 0.25, rect.top + rect.height * 0.25],
+                            [rect.left + rect.width * 0.75, rect.top + rect.height * 0.25],
+                            [rect.left + rect.width * 0.25, rect.top + rect.height * 0.75],
+                            [rect.left + rect.width * 0.75, rect.top + rect.height * 0.75],
+                        ];
+                        let coveredPoints = 0;
+                        samplePoints.forEach(([x, y]) => {
+                            const pointElement = document.elementFromPoint(x, y);
+                            if (pointElement !== element && !element.contains(pointElement)) {
+                                coveredPoints++;
+                            }
+                        });
+                        coveragePercent = Math.round((coveredPoints / samplePoints.length) * 100);
+                    }
+                    // Check interactability
+                    const computedStyles = window.getComputedStyle(element);
+                    const pointerEvents = computedStyles.pointerEvents;
+                    const isDisabled = element.disabled || false;
+                    const isReadonly = element.readOnly || false;
+                    const ariaDisabled = element.getAttribute('aria-disabled') === 'true';
+                    return {
+                        viewportRatio,
+                        isInViewport,
+                        opacity,
+                        display,
+                        visibility,
+                        isClipped,
+                        isCovered,
+                        coveringElementInfo,
+                        coveragePercent,
+                        pointerEvents,
+                        isDisabled,
+                        isReadonly,
+                        ariaDisabled,
+                    };
+                });
+                // Determine if scroll is needed
+                const needsScroll = isVisible && !visibilityData.isInViewport;
+                // Get element tag name for output
+                const tagInfo = await targetLocator.evaluate((el) => {
+                    const tagName = el.tagName.toLowerCase();
+                    const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('data-cy');
+                    const id = el.id ? `#${el.id}` : '';
+                    const classes = el.className && typeof el.className === 'string' ? `.${el.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;
+                });
+                // Build compact text format
+                const viewportPercent = Math.round(visibilityData.viewportRatio * 100);
+                let output = multipleMatchWarning + `Visibility: ${tagInfo}\n\n`;
+                // Status line
+                const visibleSymbol = isVisible ? '✓' : '✗';
+                const viewportSymbol = visibilityData.isInViewport ? '✓' : '✗';
+                const viewportText = visibilityData.isInViewport
+                    ? `in viewport${viewportPercent < 100 ? ` (${viewportPercent}% visible)` : ''}`
+                    : `not in viewport${viewportPercent > 0 ? ` (${viewportPercent}% visible)` : ''}`;
+                output += `${visibleSymbol} ${isVisible ? 'visible' : 'hidden'}, ${viewportSymbol} ${viewportText}\n`;
+                // CSS properties
+                output += `opacity: ${visibilityData.opacity}, display: ${visibilityData.display}, visibility: ${visibilityData.visibility}\n`;
+                // Interactability section
+                const interactabilityIssues = [];
+                if (visibilityData.isDisabled) {
+                    interactabilityIssues.push('disabled');
+                }
+                if (visibilityData.isReadonly) {
+                    interactabilityIssues.push('readonly');
+                }
+                if (visibilityData.ariaDisabled) {
+                    interactabilityIssues.push('aria-disabled');
+                }
+                if (visibilityData.pointerEvents === 'none') {
+                    interactabilityIssues.push('pointer-events: none');
+                }
+                if (interactabilityIssues.length > 0) {
+                    output += `⚠ interactability: ${interactabilityIssues.join(', ')}\n`;
+                }
+                // Issues section
+                const issues = [];
+                if (visibilityData.isClipped) {
+                    issues.push('  ✗ clipped by parent overflow:hidden');
+                }
+                if (visibilityData.isCovered) {
+                    const coverageInfo = visibilityData.coveragePercent > 0
+                        ? ` (~${visibilityData.coveragePercent}% covered)`
+                        : '';
+                    issues.push(`  ✗ covered by another element${coverageInfo}`);
+                    if (visibilityData.coveringElementInfo) {
+                        issues.push(`    Covering: ${visibilityData.coveringElementInfo}`);
+                    }
+                }
+                if (needsScroll) {
+                    issues.push('  ⚠ needs scroll to bring into view');
+                }
+                if (issues.length > 0) {
+                    output += '\nIssues:\n';
+                    output += issues.join('\n') + '\n';
+                }
+                // Suggestions
+                const suggestions = [];
+                if (needsScroll) {
+                    suggestions.push('→ Call scroll_to_element before clicking');
+                }
+                if (visibilityData.isCovered) {
+                    suggestions.push('→ Element may be behind modal, overlay, or fixed header');
+                }
+                if (interactabilityIssues.length > 0) {
+                    suggestions.push('→ Element cannot be interacted with in current state');
+                }
+                if (suggestions.length > 0) {
+                    output += '\n' + suggestions.join('\n');
+                }
+                return createSuccessResponse(output.trim());
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to check visibility: ${error.message}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,13 @@
+import { ToolHandler } from '../common/types.js';
+import { BrowserToolBase } from './base.js';
+import type { ToolContext, ToolResponse } from '../common/types.js';
+export interface FindByTextArgs {
+    text: string;
+    exact?: boolean;
+    caseSensitive?: boolean;
+    regex?: boolean;
+    limit?: number;
+}
+export declare class FindByTextTool extends BrowserToolBase implements ToolHandler {
+    execute(args: FindByTextArgs, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/findByText.js

@@ -0,0 +1,207 @@
+import { BrowserToolBase } from './base.js';
+export class FindByTextTool extends BrowserToolBase {
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const { text, exact = false, caseSensitive = false, regex = false, limit = 10 } = args;
+            // Build the text selector based on exact, caseSensitive, and regex options
+            let selector;
+            if (regex) {
+                // Validate and use user-provided regex pattern
+                try {
+                    // Extract pattern and flags from /pattern/flags format
+                    const regexMatch = text.match(/^\/(.+?)\/([gimuy]*)$/);
+                    if (regexMatch) {
+                        const [, pattern, flags] = regexMatch;
+                        // Validate the regex pattern
+                        new RegExp(pattern, flags);
+                        selector = `text=/${pattern}/${flags}`;
+                    }
+                    else {
+                        // If not in /pattern/flags format, treat as raw pattern
+                        new RegExp(text);
+                        selector = `text=/${text}/`;
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `✗ Invalid regex pattern: ${error.message}`
+                            }
+                        ],
+                        isError: true
+                    };
+                }
+            }
+            else if (exact) {
+                selector = `text="${text}"`;
+            }
+            else {
+                // Use regex for partial match with case sensitivity
+                const flags = caseSensitive ? '' : 'i';
+                const escapedText = text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                selector = `text=/${escapedText}/${flags}`;
+            }
+            // Find all matching elements
+            const locator = page.locator(selector);
+            const count = await locator.count();
+            if (count === 0) {
+                // Build "not found" message based on search type
+                let notFoundMsg;
+                if (regex) {
+                    notFoundMsg = `✗ No elements found matching regex ${text}`;
+                }
+                else if (exact) {
+                    notFoundMsg = `✗ No elements found with exact text "${text}"`;
+                }
+                else {
+                    notFoundMsg = `✗ No elements found containing "${text}"`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: notFoundMsg
+                        }
+                    ],
+                    isError: false
+                };
+            }
+            // Limit results
+            const elementsToShow = Math.min(count, limit);
+            const elements = [];
+            for (let i = 0; i < elementsToShow; i++) {
+                const element = locator.nth(i);
+                // Get element info
+                const [tagName, boundingBox, textContent, isVisible, isEnabled] = await Promise.all([
+                    element.evaluate((el) => el.tagName.toLowerCase()),
+                    element.boundingBox().catch(() => null),
+                    element.textContent().catch(() => ''),
+                    element.isVisible().catch(() => false),
+                    element.isEnabled().catch(() => true)
+                ]);
+                // Get selector attributes for better identification
+                const selectorInfo = await element.evaluate((el) => {
+                    const attrs = {};
+                    if (el.id)
+                        attrs.id = el.id;
+                    if (el.className && typeof el.className === 'string') {
+                        attrs.class = el.className.split(' ').slice(0, 2).join(' ');
+                    }
+                    const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('data-cy');
+                    if (testId)
+                        attrs.testid = testId;
+                    if (el.getAttribute('href'))
+                        attrs.href = el.getAttribute('href') || '';
+                    if (el.getAttribute('name'))
+                        attrs.name = el.getAttribute('name') || '';
+                    if (el.getAttribute('type'))
+                        attrs.type = el.getAttribute('type') || '';
+                    if (el.getAttribute('aria-label'))
+                        attrs['aria-label'] = el.getAttribute('aria-label') || '';
+                    return attrs;
+                });
+                // Build selector string
+                let selectorStr = `<${tagName}`;
+                if (selectorInfo.id)
+                    selectorStr += `#${selectorInfo.id}`;
+                if (selectorInfo.class)
+                    selectorStr += ` class="${selectorInfo.class}"`;
+                if (selectorInfo.testid)
+                    selectorStr += ` data-testid="${selectorInfo.testid}"`;
+                if (selectorInfo.name)
+                    selectorStr += ` name="${selectorInfo.name}"`;
+                if (selectorInfo.type)
+                    selectorStr += ` type="${selectorInfo.type}"`;
+                if (selectorInfo.href)
+                    selectorStr += ` href="${selectorInfo.href.slice(0, 30)}${selectorInfo.href.length > 30 ? '...' : ''}"`;
+                if (selectorInfo['aria-label'])
+                    selectorStr += ` aria-label="${selectorInfo['aria-label']}"`;
+                selectorStr += '>';
+                // Format position
+                let positionStr = '';
+                if (boundingBox) {
+                    const x = Math.round(boundingBox.x);
+                    const y = Math.round(boundingBox.y);
+                    const w = Math.round(boundingBox.width);
+                    const h = Math.round(boundingBox.height);
+                    positionStr = `    @ (${x},${y}) ${w}x${h}px`;
+                }
+                else {
+                    positionStr = `    @ (no bounding box)`;
+                }
+                // Format text content (truncate if too long)
+                const truncatedText = textContent && textContent.length > 100
+                    ? textContent.slice(0, 100) + '...'
+                    : textContent;
+                const textStr = `    "${truncatedText}"`;
+                // Format state
+                let stateStr = '    ';
+                if (isVisible) {
+                    stateStr += '✓ visible';
+                }
+                else {
+                    stateStr += '✗ hidden';
+                    // Try to detect why it's hidden
+                    const hiddenReason = await element.evaluate((el) => {
+                        const style = window.getComputedStyle(el);
+                        if (style.display === 'none')
+                            return '(display: none)';
+                        if (style.visibility === 'hidden')
+                            return '(visibility: hidden)';
+                        if (style.opacity === '0')
+                            return '(opacity: 0)';
+                        const rect = el.getBoundingClientRect();
+                        if (rect.width === 0 || rect.height === 0)
+                            return '(zero size)';
+                        return '';
+                    }).catch(() => '');
+                    if (hiddenReason)
+                        stateStr += ` ${hiddenReason}`;
+                }
+                // Check if interactive
+                const isInteractive = await element.evaluate((el) => {
+                    const tag = el.tagName.toLowerCase();
+                    if (['a', 'button', 'input', 'select', 'textarea'].includes(tag))
+                        return true;
+                    if (el.getAttribute('onclick'))
+                        return true;
+                    if (el.getAttribute('role') === 'button')
+                        return true;
+                    return false;
+                }).catch(() => false);
+                if (isVisible && isInteractive && isEnabled) {
+                    stateStr += ', ⚡ interactive';
+                }
+                else if (isVisible && isInteractive && !isEnabled) {
+                    stateStr += ', ✗ disabled';
+                }
+                elements.push(`[${i}] ${selectorStr}\n${positionStr}\n${textStr}\n${stateStr}`);
+            }
+            // Build header message based on search type
+            let searchDesc;
+            if (regex) {
+                searchDesc = `matching regex ${text}`;
+            }
+            else if (exact) {
+                searchDesc = `with exact text "${text}"`;
+            }
+            else {
+                searchDesc = `containing "${text}"`;
+            }
+            const header = count > limit
+                ? `Found ${count} elements ${searchDesc} (showing first ${limit}):\n`
+                : `Found ${count} element${count > 1 ? 's' : ''} ${searchDesc}:\n`;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: header + '\n' + elements.join('\n\n')
+                    }
+                ],
+                isError: false
+            };
+        });
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { ToolContext, ToolResponse } from '../common/types.js';
+import { BrowserToolBase } from './base.js';
+interface GetRequestDetailsArgs {
+    index: number;
+}
+export declare class GetRequestDetailsTool extends BrowserToolBase {
+    execute(args: GetRequestDetailsArgs, context: ToolContext): Promise<ToolResponse>;
+}
+export {};