mcp-web-inspector 0.1.0

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

@@ -0,0 +1,12 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for testing a selector and returning information about all matched elements
+ * Useful for selector debugging and finding the right element to interact with
+ */
+export declare class QuerySelectorAllTool extends BrowserToolBase {
+    /**
+     * Execute the query selector all tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/querySelectorAll.js

@@ -0,0 +1,201 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for testing a selector and returning information about all matched elements
+ * Useful for selector debugging and finding the right element to interact with
+ */
+export class QuerySelectorAllTool extends BrowserToolBase {
+    /**
+     * Execute the query selector all tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const selector = this.normalizeSelector(args.selector);
+            const limit = args.limit ?? 10;
+            const onlyVisible = args.onlyVisible; // true = visible only, false = hidden only, undefined = all
+            const showAttributes = args.showAttributes
+                ? args.showAttributes.split(',').map((a) => a.trim())
+                : undefined;
+            try {
+                // Query all elements matching the selector
+                const elements = await page.locator(selector).all();
+                const totalMatches = elements.length;
+                if (totalMatches === 0) {
+                    return createSuccessResponse(`No elements found matching "${args.selector}"\n\nTip: Try using inspect_dom to explore the page structure.`);
+                }
+                // Get detailed information for each element (all elements to allow filtering)
+                const matchData = [];
+                for (let i = 0; i < elements.length; i++) {
+                    const element = elements[i];
+                    try {
+                        const elementInfo = await element.evaluate((el, attrList) => {
+                            const rect = el.getBoundingClientRect();
+                            const styles = window.getComputedStyle(el);
+                            const isVisible = styles.display !== 'none' &&
+                                styles.visibility !== 'hidden' &&
+                                parseFloat(styles.opacity) > 0 &&
+                                rect.width > 0 &&
+                                rect.height > 0;
+                            // Get test ID
+                            const testId = el.getAttribute('data-testid') ||
+                                el.getAttribute('data-test') ||
+                                el.getAttribute('data-cy') ||
+                                undefined;
+                            // Get selector representation
+                            let selectorRepr = '';
+                            if (testId) {
+                                const attrName = el.hasAttribute('data-testid')
+                                    ? 'data-testid'
+                                    : el.hasAttribute('data-test')
+                                        ? 'data-test'
+                                        : 'data-cy';
+                                selectorRepr = `${attrName}="${testId}"`;
+                            }
+                            else if (el.id) {
+                                selectorRepr = `#${el.id}`;
+                            }
+                            else if (el.className && typeof el.className === 'string') {
+                                const classes = el.className.trim().split(/\s+/).slice(0, 3).join('.');
+                                if (classes) {
+                                    selectorRepr = `class="${classes}"`;
+                                }
+                            }
+                            // Check if interactive
+                            const tag = el.tagName.toLowerCase();
+                            const interactiveTags = new Set(['button', 'a', 'input', 'select', 'textarea']);
+                            const isInteractive = interactiveTags.has(tag) ||
+                                el.hasAttribute('onclick') ||
+                                el.hasAttribute('contenteditable') ||
+                                el.getAttribute('role') === 'button';
+                            // Get text content (trimmed and limited)
+                            const text = el.textContent?.trim().slice(0, 100) || '';
+                            // Get requested attributes if specified
+                            let attributes;
+                            if (attrList && attrList.length > 0) {
+                                attributes = {};
+                                attrList.forEach((attr) => {
+                                    const value = el.getAttribute(attr);
+                                    if (value !== null) {
+                                        attributes[attr] = value;
+                                    }
+                                });
+                            }
+                            return {
+                                tag: tag,
+                                selector: selectorRepr,
+                                testId,
+                                classes: Array.from(el.classList).join('.'),
+                                text,
+                                position: {
+                                    x: Math.round(rect.x),
+                                    y: Math.round(rect.y),
+                                    width: Math.round(rect.width),
+                                    height: Math.round(rect.height),
+                                },
+                                isVisible,
+                                isInteractive,
+                                opacity: parseFloat(styles.opacity),
+                                display: styles.display,
+                                attributes,
+                            };
+                        }, showAttributes);
+                        matchData.push(elementInfo);
+                    }
+                    catch (error) {
+                        // Skip elements that fail evaluation (e.g., detached from DOM)
+                        continue;
+                    }
+                }
+                // Filter by visibility if requested
+                let filteredMatches = matchData;
+                if (onlyVisible !== undefined) {
+                    filteredMatches = matchData.filter((match) => onlyVisible ? match.isVisible : !match.isVisible);
+                }
+                // Apply limit after filtering
+                const displayMatches = filteredMatches.slice(0, limit);
+                // Format compact text output
+                const lines = [];
+                // Header with counts
+                if (onlyVisible === true) {
+                    const visibleCount = filteredMatches.length;
+                    lines.push(`Found ${totalMatches} element${totalMatches > 1 ? 's' : ''} matching "${args.selector}" (${visibleCount} visible):`);
+                }
+                else if (onlyVisible === false) {
+                    const hiddenCount = filteredMatches.length;
+                    lines.push(`Found ${totalMatches} element${totalMatches > 1 ? 's' : ''} matching "${args.selector}" (${hiddenCount} hidden):`);
+                }
+                else {
+                    lines.push(`Found ${totalMatches} element${totalMatches > 1 ? 's' : ''} matching "${args.selector}":`);
+                }
+                lines.push('');
+                displayMatches.forEach((match, index) => {
+                    const prefix = `[${index}]`;
+                    // Element tag with selector info
+                    let tagInfo = `<${match.tag}`;
+                    if (match.selector) {
+                        tagInfo += ` ${match.selector}`;
+                    }
+                    tagInfo += '>';
+                    lines.push(`${prefix} ${tagInfo}`);
+                    // Position
+                    lines.push(`    @ (${match.position.x},${match.position.y}) ${match.position.width}x${match.position.height}px`);
+                    // Text content
+                    if (match.text) {
+                        const displayText = match.text.length > 50 ? match.text.slice(0, 47) + '...' : match.text;
+                        lines.push(`    "${displayText}"`);
+                    }
+                    // Attributes (if requested)
+                    if (match.attributes && Object.keys(match.attributes).length > 0) {
+                        Object.entries(match.attributes).forEach(([attr, value]) => {
+                            const displayValue = value.length > 50 ? value.slice(0, 47) + '...' : value;
+                            lines.push(`    ${attr}: "${displayValue}"`);
+                        });
+                    }
+                    // Status symbols
+                    const statusParts = [];
+                    statusParts.push(match.isVisible ? '✓ visible' : '✗ hidden');
+                    if (!match.isVisible) {
+                        // Add reason for being hidden
+                        if (match.display === 'none') {
+                            statusParts.push('display: none');
+                        }
+                        else if (match.opacity === 0) {
+                            statusParts.push('opacity: 0');
+                        }
+                        else if (match.position.width === 0 || match.position.height === 0) {
+                            statusParts.push('zero size');
+                        }
+                    }
+                    if (match.isInteractive) {
+                        statusParts.push('⚡ interactive');
+                    }
+                    lines.push(`    ${statusParts.join(', ')}`);
+                    lines.push('');
+                });
+                // Show omitted count and summary
+                if (filteredMatches.length > limit) {
+                    const omitted = filteredMatches.length - limit;
+                    const matchType = onlyVisible === true ? 'visible ' : onlyVisible === false ? 'hidden ' : '';
+                    lines.push(`Showing ${limit} of ${filteredMatches.length} ${matchType}matches (${omitted} omitted)`);
+                    lines.push(`Use limit parameter to show more: { selector: "${args.selector}", limit: ${Math.min(filteredMatches.length, 50)} }`);
+                }
+                else {
+                    const matchWord = filteredMatches.length === 1 ? 'match' : 'matches';
+                    if (onlyVisible === true) {
+                        lines.push(`Showing ${filteredMatches.length} visible ${matchWord}`);
+                    }
+                    else if (onlyVisible === false) {
+                        lines.push(`Showing ${filteredMatches.length} hidden ${matchWord}`);
+                    }
+                    else {
+                        lines.push(`Showing all ${filteredMatches.length} ${matchWord}`);
+                    }
+                }
+                return createSuccessResponse(lines.join('\n'));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to query selector: ${error.message}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,29 @@
+import { BrowserToolBase } from './base.js';
+import type { ToolContext, ToolResponse } from '../common/types.js';
+interface ExpectResponseArgs {
+    id: string;
+    url: string;
+}
+interface AssertResponseArgs {
+    id: string;
+    value?: string;
+}
+/**
+ * Tool for setting up response wait operations
+ */
+export declare class ExpectResponseTool extends BrowserToolBase {
+    /**
+     * Execute the expect response tool
+     */
+    execute(args: ExpectResponseArgs, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for asserting and validating responses
+ */
+export declare class AssertResponseTool extends BrowserToolBase {
+    /**
+     * Execute the assert response tool
+     */
+    execute(args: AssertResponseArgs, context: ToolContext): Promise<ToolResponse>;
+}
+export {};

package/dist/tools/browser/response.js

@@ -0,0 +1,67 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+const responsePromises = new Map();
+/**
+ * Tool for setting up response wait operations
+ */
+export class ExpectResponseTool extends BrowserToolBase {
+    /**
+     * Execute the expect response tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            if (!args.id || !args.url) {
+                return createErrorResponse("Missing required parameters: id and url must be provided");
+            }
+            const responsePromise = page.waitForResponse(args.url);
+            responsePromises.set(args.id, responsePromise);
+            return createSuccessResponse(`Started waiting for response with ID ${args.id}`);
+        });
+    }
+}
+/**
+ * Tool for asserting and validating responses
+ */
+export class AssertResponseTool extends BrowserToolBase {
+    /**
+     * Execute the assert response tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async () => {
+            if (!args.id) {
+                return createErrorResponse("Missing required parameter: id must be provided");
+            }
+            const responsePromise = responsePromises.get(args.id);
+            if (!responsePromise) {
+                return createErrorResponse(`No response wait operation found with ID: ${args.id}`);
+            }
+            try {
+                const response = await responsePromise;
+                const body = await response.json();
+                if (args.value) {
+                    const bodyStr = JSON.stringify(body);
+                    if (!bodyStr.includes(args.value)) {
+                        const messages = [
+                            `Response body does not contain expected value: ${args.value}`,
+                            `Actual body: ${bodyStr}`
+                        ];
+                        return createErrorResponse(messages.join('\n'));
+                    }
+                }
+                const messages = [
+                    `Response assertion for ID ${args.id} successful`,
+                    `URL: ${response.url()}`,
+                    `Status: ${response.status()}`,
+                    `Body: ${JSON.stringify(body, null, 2)}`
+                ];
+                return createSuccessResponse(messages.join('\n'));
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to assert response: ${error.message}`);
+            }
+            finally {
+                responsePromises.delete(args.id);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,16 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for taking screenshots of pages or elements
+ */
+export declare class ScreenshotTool extends BrowserToolBase {
+    private screenshots;
+    /**
+     * Execute the screenshot tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+    /**
+     * Get all stored screenshots
+     */
+    getScreenshots(): Map<string, string>;
+}

package/dist/tools/browser/screenshot.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse } from '../common/types.js';
+import { getScreenshotsDir } from '../../toolHandler.js';
+const defaultDownloadsPath = path.join(os.homedir(), 'Downloads');
+/**
+ * Tool for taking screenshots of pages or elements
+ */
+export class ScreenshotTool extends BrowserToolBase {
+    constructor() {
+        super(...arguments);
+        this.screenshots = new Map();
+    }
+    /**
+     * Execute the screenshot tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            const screenshotOptions = {
+                type: args.type || "png",
+                fullPage: !!args.fullPage
+            };
+            if (args.selector) {
+                // Normalize selector (support testid: shorthand)
+                const selector = this.normalizeSelector(args.selector);
+                const element = await page.$(selector);
+                if (!element) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Element not found: ${selector}`,
+                            }],
+                        isError: true
+                    };
+                }
+                screenshotOptions.element = element;
+            }
+            // Generate output path
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const filename = `${args.name || 'screenshot'}-${timestamp}.png`;
+            // Use screenshots directory from config, fall back to downloadsDir arg, then default Downloads
+            const downloadsDir = args.downloadsDir || getScreenshotsDir();
+            if (!fs.existsSync(downloadsDir)) {
+                fs.mkdirSync(downloadsDir, { recursive: true });
+            }
+            const outputPath = path.join(downloadsDir, filename);
+            screenshotOptions.path = outputPath;
+            const screenshot = await page.screenshot(screenshotOptions);
+            const base64Screenshot = screenshot.toString('base64');
+            const messages = [`Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
+            // Handle base64 storage
+            if (args.storeBase64 !== false) {
+                this.screenshots.set(args.name || 'screenshot', base64Screenshot);
+                this.server.notification({
+                    method: "notifications/resources/list_changed",
+                });
+                messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
+            }
+            return createSuccessResponse(messages);
+        });
+    }
+    /**
+     * Get all stored screenshots
+     */
+    getScreenshots() {
+        return this.screenshots;
+    }
+}

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

@@ -0,0 +1,15 @@
+import { BrowserToolBase } from './base.js';
+import type { ToolContext, ToolResponse } from '../common/types.js';
+interface CustomUserAgentArgs {
+    userAgent: string;
+}
+/**
+ * Tool for validating custom User Agent settings
+ */
+export declare class CustomUserAgentTool extends BrowserToolBase {
+    /**
+     * Execute the custom user agent tool
+     */
+    execute(args: CustomUserAgentArgs, context: ToolContext): Promise<ToolResponse>;
+}
+export {};

package/dist/tools/browser/useragent.js

@@ -0,0 +1,32 @@
+import { BrowserToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for validating custom User Agent settings
+ */
+export class CustomUserAgentTool extends BrowserToolBase {
+    /**
+     * Execute the custom user agent tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (page) => {
+            if (!args.userAgent) {
+                return createErrorResponse("Missing required parameter: userAgent must be provided");
+            }
+            try {
+                const currentUserAgent = await page.evaluate(() => navigator.userAgent);
+                if (currentUserAgent !== args.userAgent) {
+                    const messages = [
+                        "Page was already initialized with a different User Agent.",
+                        `Requested: ${args.userAgent}`,
+                        `Current: ${currentUserAgent}`
+                    ];
+                    return createErrorResponse(messages.join('\n'));
+                }
+                return createSuccessResponse("User Agent validation successful");
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to validate User Agent: ${error.message}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,20 @@
+import { ToolContext, ToolResponse } from "../common/types.js";
+import { BrowserToolBase } from "./base.js";
+/**
+ * Tool for getting the visible text content of the current page
+ */
+export declare class VisibleTextTool extends BrowserToolBase {
+    /**
+     * Execute the visible text page tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for getting the visible HTML content of the current page
+ */
+export declare class VisibleHtmlTool extends BrowserToolBase {
+    /**
+     * Execute the visible HTML page tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/visiblePage.js

@@ -0,0 +1,170 @@
+import { resetBrowserState } from "../../toolHandler.js";
+import { createErrorResponse, createSuccessResponse } from "../common/types.js";
+import { BrowserToolBase } from "./base.js";
+/**
+ * Tool for getting the visible text content of the current page
+ */
+export class VisibleTextTool extends BrowserToolBase {
+    /**
+     * Execute the visible text page tool
+     */
+    async execute(args, context) {
+        // Check if browser is available
+        if (!context.browser || !context.browser.isConnected()) {
+            // If browser is not connected, we need to reset the state to force recreation
+            resetBrowserState();
+            return createErrorResponse("Browser is not connected. The connection has been reset - please retry your navigation.");
+        }
+        // Check if page is available and not closed
+        if (!context.page || context.page.isClosed()) {
+            return createErrorResponse("Page is not available or has been closed. Please retry your navigation.");
+        }
+        return this.safeExecute(context, async (page) => {
+            try {
+                const visibleText = await page.evaluate(() => {
+                    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, {
+                        acceptNode: (node) => {
+                            const style = window.getComputedStyle(node.parentElement);
+                            return (style.display !== "none" && style.visibility !== "hidden")
+                                ? NodeFilter.FILTER_ACCEPT
+                                : NodeFilter.FILTER_REJECT;
+                        },
+                    });
+                    let text = "";
+                    let node;
+                    while ((node = walker.nextNode())) {
+                        const trimmedText = node.textContent?.trim();
+                        if (trimmedText) {
+                            text += trimmedText + "\n";
+                        }
+                    }
+                    return text.trim();
+                });
+                // Truncate logic
+                const maxLength = typeof args.maxLength === 'number' ? args.maxLength : 20000;
+                let output = visibleText;
+                let truncated = false;
+                if (output.length > maxLength) {
+                    output = output.slice(0, maxLength) + '\n[Output truncated due to size limits]';
+                    truncated = true;
+                }
+                return createSuccessResponse(`Visible text content:\n${output}`);
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to get visible text content: ${error.message}`);
+            }
+        });
+    }
+}
+/**
+ * Tool for getting the visible HTML content of the current page
+ */
+export class VisibleHtmlTool extends BrowserToolBase {
+    /**
+     * Execute the visible HTML page tool
+     */
+    async execute(args, context) {
+        // Check if browser is available
+        if (!context.browser || !context.browser.isConnected()) {
+            // If browser is not connected, we need to reset the state to force recreation
+            resetBrowserState();
+            return createErrorResponse("Browser is not connected. The connection has been reset - please retry your navigation.");
+        }
+        // Check if page is available and not closed
+        if (!context.page || context.page.isClosed()) {
+            return createErrorResponse("Page is not available or has been closed. Please retry your navigation.");
+        }
+        return this.safeExecute(context, async (page) => {
+            try {
+                const { removeComments, removeStyles, removeMeta, minify, cleanHtml } = args;
+                // Default removeScripts to true unless explicitly set to false
+                const removeScripts = args.removeScripts === false ? false : true;
+                // Normalize selector (support testid: shorthand)
+                const selector = args.selector ? this.normalizeSelector(args.selector) : undefined;
+                // Get the HTML content
+                let htmlContent;
+                if (selector) {
+                    // If a selector is provided, get only the HTML for that element
+                    const element = await page.$(selector);
+                    if (!element) {
+                        return createErrorResponse(`Element with selector "${selector}" not found`);
+                    }
+                    htmlContent = await page.evaluate((el) => el.outerHTML, element);
+                }
+                else {
+                    // Otherwise get the full page HTML
+                    htmlContent = await page.content();
+                }
+                // Determine if we need to apply filters
+                const shouldRemoveScripts = removeScripts || cleanHtml;
+                const shouldRemoveComments = removeComments || cleanHtml;
+                const shouldRemoveStyles = removeStyles || cleanHtml;
+                const shouldRemoveMeta = removeMeta || cleanHtml;
+                // Apply filters in the browser context
+                if (shouldRemoveScripts || shouldRemoveComments || shouldRemoveStyles || shouldRemoveMeta || minify) {
+                    htmlContent = await page.evaluate(({ html, removeScripts, removeComments, removeStyles, removeMeta, minify }) => {
+                        // Create a DOM parser to work with the HTML
+                        const parser = new DOMParser();
+                        const doc = parser.parseFromString(html, 'text/html');
+                        // Remove script tags if requested
+                        if (removeScripts) {
+                            const scripts = doc.querySelectorAll('script');
+                            scripts.forEach(script => script.remove());
+                        }
+                        // Remove style tags if requested
+                        if (removeStyles) {
+                            const styles = doc.querySelectorAll('style');
+                            styles.forEach(style => style.remove());
+                        }
+                        // Remove meta tags if requested
+                        if (removeMeta) {
+                            const metaTags = doc.querySelectorAll('meta');
+                            metaTags.forEach(meta => meta.remove());
+                        }
+                        // Remove HTML comments if requested
+                        if (removeComments) {
+                            const removeComments = (node) => {
+                                const childNodes = node.childNodes;
+                                for (let i = childNodes.length - 1; i >= 0; i--) {
+                                    const child = childNodes[i];
+                                    if (child.nodeType === 8) { // 8 is for comment nodes
+                                        node.removeChild(child);
+                                    }
+                                    else if (child.nodeType === 1) { // 1 is for element nodes
+                                        removeComments(child);
+                                    }
+                                }
+                            };
+                            removeComments(doc.documentElement);
+                        }
+                        // Get the processed HTML
+                        let result = doc.documentElement.outerHTML;
+                        // Minify if requested
+                        if (minify) {
+                            // Simple minification: remove extra whitespace
+                            result = result.replace(/>\s+</g, '><').trim();
+                        }
+                        return result;
+                    }, {
+                        html: htmlContent,
+                        removeScripts: shouldRemoveScripts,
+                        removeComments: shouldRemoveComments,
+                        removeStyles: shouldRemoveStyles,
+                        removeMeta: shouldRemoveMeta,
+                        minify
+                    });
+                }
+                // Truncate logic
+                const maxLength = typeof args.maxLength === 'number' ? args.maxLength : 20000;
+                let output = htmlContent;
+                if (output.length > maxLength) {
+                    output = output.slice(0, maxLength) + '\n<!-- Output truncated due to size limits -->';
+                }
+                return createSuccessResponse(`HTML content:\n${output}`);
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to get visible HTML content: ${error.message}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,10 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+export interface WaitForElementArgs {
+    selector: string;
+    state?: 'visible' | 'hidden' | 'attached' | 'detached';
+    timeout?: number;
+}
+export declare class WaitForElementTool extends BrowserToolBase {
+    execute(args: WaitForElementArgs, context: ToolContext): Promise<ToolResponse>;
+}