mcp-web-inspector 0.9.5 → 0.11.0

package/README.md

@@ -491,6 +491,8 @@ RELATED TOOLS: For comparing TWO elements' alignment (not parent-child), use com
 
 ⚠️ More efficient than get_html() or evaluate() for structural analysis. Use BEFORE visual tools (screenshot) or evaluate(). Supports testid shortcuts.
 
+NOTE: Dropdowns, listboxes, dialogs, and popovers (especially in react-aria/headless UI/Radix) are commonly portaled to document.body — when a combobox or menu is open, query at the root level (e.g. `[role="listbox"]`, `[role="dialog"]`) rather than inside the trigger's subtree.
+
 - Parameters:
   - selector (string, optional): CSS selector, text selector, or testid shorthand to inspect. Omit for page overview (defaults to body). Use 'testid:login-form', '#main', etc.
   - includeHidden (boolean, optional): Include hidden elements in results (default: false)
@@ -927,7 +929,7 @@ Navigate to a URL. Browser sessions (cookies, localStorage, sessionStorage) are
   - height (number, optional): Viewport height in pixels. If not specified, automatically matches screen height. Ignored if device is specified.
   - timeout (number, optional): Navigation timeout in milliseconds
   - waitUntil (string, optional): Navigation wait condition
-  - headless (boolean, optional): Run browser in headless mode (default: true - no window shown)
+  - headless (boolean, optional): Run browser in headless mode (no visible window). Defaults to visible on desktop, headless on Linux without a display or when --headless is passed.
 
 #### `scroll_by`
 Scroll a container (or page) by a specific number of pixels. Auto-detects scroll direction when only one is available. Essential for: testing sticky headers/footers, triggering infinite scroll, carousel navigation, precise scroll position testing. Use 'html' or 'body' for page scrolling. Positive pixels = down/right, negative = up/left. Outputs: ✓ success summary with axis position and percent of max scroll; ⚠️ boundary notice when movement is limited; ⚠️ ambiguous-direction guidance when both axes scroll; ⚠️ not-scrollable report with ancestor suggestions; 💡 follow-up tips matching the detected scenario.
@@ -960,10 +962,10 @@ Drag an element to a target location
   - targetSelector (string, required): CSS selector for the target location
 
 #### `fill`
-fill out an input field
+fill an input/textarea/contenteditable; if the selector matches a wrapper, descends up to 4 levels to a unique fillable descendant (errors if zero or multiple)
 
 - Parameters:
-  - selector (string, required): CSS selector for input field
+  - selector (string, required): CSS selector for input field or its wrapper
   - value (string, required): Value to fill
 
 #### `hover`
@@ -996,7 +998,7 @@ Upload a file to an input[type='file'] element on the page
 ### Content
 
 #### `get_html`
-⚠️ 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); if larger, returns a preview and a one-time token to fetch the full output. Scripts removed by default for security/size. Supports testid shortcuts.
+[may return preview+token] ⚠️ 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); if larger, returns a preview and a one-time token to fetch the full output. Scripts removed by default for security/size. Supports testid shortcuts.
 
 - Parameters:
   - selector (string, optional): CSS selector, text selector, or testid shorthand to limit HTML extraction to a specific container. Omit to get entire page HTML. Example: 'testid:main-content' or '#app'
@@ -1004,14 +1006,14 @@ Upload a file to an input[type='file'] element on the page
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `get_text`
-⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts.
+[may return preview+token] ⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts.
 
 - Parameters:
   - selector (string, optional): CSS selector, text selector, or testid shorthand to limit text extraction to a specific container. Omit to get text from entire page. Example: 'testid:article-body' or '#main-content'
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `visual_screenshot_for_humans`
-📸 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).
+[may return preview+token] 📸 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).
 
 ❌ WRONG: "Take screenshot to debug button alignment"
 ✅ RIGHT: "Use compare_element_alignment() - alignment in <100 tokens"
@@ -1042,7 +1044,7 @@ Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-p
 Clears captured console logs and returns the number of entries cleared.
 
 #### `get_console_logs`
-Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
+[may return preview+token] Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
   - type (string, optional): Type filter (all, error, warning, log, info, debug, exception). Note: 'error' also includes 'exception' entries for convenience.
@@ -1054,7 +1056,7 @@ Retrieve console logs with filtering and token‑efficient output. Defaults: sin
 ### Evaluation
 
 #### `evaluate`
-⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return a compact, token-efficient summary of the result. Includes a large-output preview guard with a one-time token. ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_element_alignment). Use ONLY when specialized tools cannot accomplish the task. Automatically detects common patterns and suggests better alternatives.
+[may return preview+token] ⚙️ CUSTOM JAVASCRIPT EXECUTION - Execute arbitrary JavaScript in the browser console and return a compact, token-efficient summary of the result. Single expressions return their value automatically; multi-statement scripts must use `return`. Includes a large-output preview guard with a one-time token. ⚠️ NOT for: scroll detection (inspect_dom shows 'scrollable ↕️'), element dimensions (use measure_element), DOM inspection (use inspect_dom), CSS properties (use get_computed_styles), position comparison (use compare_element_alignment). Use ONLY when specialized tools cannot accomplish the task. Automatically detects common patterns and suggests better alternatives.
 
 - Parameters:
   - script (string, required): JavaScript code to execute
@@ -1075,7 +1077,7 @@ Retrieve console logs with filtering and token‑efficient output. Defaults: sin
 ### Network
 
 #### `get_request_details`
-Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. If a request or response body exceeds 500 chars, includes a preview and a one-time confirm_output token that, when called, saves the full body to disk under ./.mcp-web-inspector/network-bodies/ and returns the file path(s). Essential for debugging API responses and investigating failed requests.
+[may return preview+token] Get detailed information about a specific network request by index (from list_network_requests). Returns request/response headers, body (truncated at 500 chars), timing, and size. Request bodies with passwords are automatically masked. If a request or response body exceeds 500 chars, includes a preview and a one-time confirm_output token that, when called, saves the full body to disk under ./.mcp-web-inspector/network-bodies/ and returns the file path(s). Essential for debugging API responses and investigating failed requests.
 
 - Parameters:
   - index (number, required): Index of the request from list_network_requests output (e.g., [0], [1], etc.)

package/dist/src/__tests__/helpers/browserSetup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check synchronously whether the Playwright Chromium executable is available.
+ * Use this to conditionally skip entire describe blocks:
+ *
+ *   const d = browserAvailable ? describe : describe.skip;
+ *   d('MySuite', () => { ... });
+ */
+export declare const browserAvailable: boolean;

package/dist/src/__tests__/helpers/browserSetup.js

@@ -0,0 +1,10 @@
+import { chromium } from 'playwright';
+import fs from 'fs';
+/**
+ * Check synchronously whether the Playwright Chromium executable is available.
+ * Use this to conditionally skip entire describe blocks:
+ *
+ *   const d = browserAvailable ? describe : describe.skip;
+ *   d('MySuite', () => { ... });
+ */
+export const browserAvailable = fs.existsSync(chromium.executablePath());

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createToolDefinitions } from "./tools/common/registry.js";
+import { setupRequestHandlers } from "./requestHandler.js";
+import { parseArgs } from "node:util";
+import { setSessionConfig } from "./toolHandler.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Get package.json version
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(__dirname, "..");
+// Expose package root for tools that need to spawn child processes (e.g., npx playwright)
+// Tests and non-CLI environments can override or ignore this.
+if (!process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT) {
+    process.env.MCP_WEB_INSPECTOR_PACKAGE_ROOT = PACKAGE_ROOT;
+}
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
+const VERSION = packageJson.version;
+// Parse command line arguments
+const { values } = parseArgs({
+    options: {
+        'no-save-session': {
+            type: 'boolean',
+            default: false,
+        },
+        'expose-sensitive-network-data': {
+            type: 'boolean',
+            default: false,
+        },
+        'user-data-dir': {
+            type: 'string',
+            default: './.mcp-web-inspector',
+        },
+        'headless': {
+            type: 'boolean',
+            default: false,
+        },
+        'print-tools-json': {
+            type: 'boolean',
+            default: false,
+        },
+        'print-tools-md': {
+            type: 'boolean',
+            default: false,
+        },
+    },
+    strict: false,
+});
+// Configure session settings (session saving is enabled by default)
+const baseDir = String(values['user-data-dir'] || './.mcp-web-inspector');
+const sessionConfig = {
+    saveSession: !Boolean(values['no-save-session']),
+    userDataDir: `${baseDir}/user-data`,
+    screenshotsDir: `${baseDir}/screenshots`,
+    headlessDefault: Boolean(values['headless']) || (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY),
+    exposeSensitiveNetworkData: Boolean(values['expose-sensitive-network-data']),
+};
+setSessionConfig(sessionConfig);
+async function runServer() {
+    // Create tool definitions with session config
+    const TOOLS = createToolDefinitions(sessionConfig);
+    // CLI utilities: print tools metadata (JSON/Markdown) and exit
+    if (values['print-tools-json']) {
+        process.stdout.write(JSON.stringify(TOOLS, null, 2));
+        return;
+    }
+    if (values['print-tools-md']) {
+        const md = formatToolsMarkdown(TOOLS);
+        process.stdout.write(md + "\n");
+        return;
+    }
+    console.error(`Starting mcp-web-inspector v${VERSION}`);
+    const server = new Server({
+        name: "mcp-web-inspector",
+        version: VERSION,
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    // Setup request handlers
+    setupRequestHandlers(server, TOOLS);
+    // Graceful shutdown logic
+    function shutdown() {
+        console.error('Shutdown signal received');
+        process.exit(0);
+    }
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    process.on('exit', shutdown);
+    process.on('uncaughtException', (err) => {
+        console.error('Uncaught Exception:', err);
+    });
+    // Create transport and connect
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+runServer().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});
+// Render a simple Markdown for tools (flat list)
+function formatToolsMarkdown(tools) {
+    const lines = [];
+    for (const t of tools) {
+        lines.push(`#### \`${t.name}\``);
+        if (t.description)
+            lines.push(String(t.description));
+        // Parameters
+        const schema = t.inputSchema;
+        if (schema && schema.properties) {
+            lines.push('');
+            lines.push('- Parameters:');
+            const req = new Set(Array.isArray(schema.required) ? schema.required : []);
+            for (const key of Object.keys(schema.properties)) {
+                const p = schema.properties[key] || {};
+                const type = p.type || 'any';
+                const desc = p.description || '';
+                const required = req.has(key) ? 'required' : 'optional';
+                lines.push(`  - ${key} (${type}, ${required}): ${desc}`);
+            }
+        }
+        // Output bullets
+        const outputs = t.outputs;
+        if (outputs) {
+            const list = Array.isArray(outputs) ? outputs : [outputs];
+            lines.push('');
+            lines.push('- Output:');
+            for (const item of list) {
+                const s = String(item);
+                lines.push(/^\s*[-*]/.test(s) ? `  ${s}` : `  - ${s}`);
+            }
+        }
+        // Examples
+        const examples = t.examples;
+        if (examples && examples.length) {
+            lines.push('');
+            lines.push('- Examples:');
+            for (const ex of examples)
+                lines.push(`- ${ex}`);
+        }
+        // Example outputs
+        const exampleOutputs = t.exampleOutputs;
+        if (exampleOutputs && exampleOutputs.length) {
+            for (const eo of exampleOutputs) {
+                lines.push('');
+                lines.push(`- Example Output (${eo.call}):`);
+                lines.push('```');
+                lines.push(eo.output);
+                lines.push('```');
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/src/requestHandler.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare function setupRequestHandlers(server: Server, tools: Tool[]): void;

package/dist/src/requestHandler.js

@@ -0,0 +1,53 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { handleToolCall, getConsoleLogs, getScreenshots } from "./toolHandler.js";
+export function setupRequestHandlers(server, tools) {
+    // List resources handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: "console://logs",
+                mimeType: "text/plain",
+                name: "Browser console logs",
+            },
+            ...Array.from(getScreenshots().keys()).map(name => ({
+                uri: `screenshot://${name}`,
+                mimeType: "image/png",
+                name: `Screenshot: ${name}`,
+            })),
+        ],
+    }));
+    // Read resource handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri.toString();
+        if (uri === "console://logs") {
+            const logs = getConsoleLogs().join("\n");
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "text/plain",
+                        text: logs,
+                    }],
+            };
+        }
+        if (uri.startsWith("screenshot://")) {
+            const name = uri.split("://")[1];
+            const screenshot = getScreenshots().get(name);
+            if (screenshot) {
+                return {
+                    contents: [{
+                            uri,
+                            mimeType: "image/png",
+                            blob: screenshot,
+                        }],
+                };
+            }
+        }
+        throw new Error(`Resource not found: ${uri}`);
+    });
+    // List tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools,
+    }));
+    // Call tool handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => handleToolCall(request.params.name, request.params.arguments ?? {}, server));
+}

package/dist/src/toolHandler.d.ts

@@ -0,0 +1,105 @@
+import type { Page } from 'playwright';
+import type { SessionConfig, ToolResponse } from './tools/common/types.js';
+export interface NetworkRequest {
+    index: number;
+    method: string;
+    url: string;
+    resourceType: string;
+    timestamp: number;
+    status?: number;
+    statusText?: string;
+    timing?: number;
+    requestData: {
+        headers: Record<string, string>;
+        postData: string | null;
+    };
+    responseData?: {
+        headers: Record<string, string>;
+        body: string | null;
+    };
+}
+type ColorSchemeOverride = 'light' | 'dark' | 'no-preference';
+/**
+ * Sets the session configuration
+ */
+export declare function setSessionConfig(config: Partial<SessionConfig>): void;
+/**
+ * Gets the current session configuration
+ */
+export declare function getSessionConfig(): SessionConfig;
+/**
+ * Gets the screenshots directory
+ */
+export declare function getScreenshotsDir(): string;
+/**
+ * Gets the default headless setting
+ */
+export declare function getHeadlessDefault(): boolean;
+/**
+ * Resets browser and page variables
+ * Used when browser is closed
+ */
+export declare function resetBrowserState(): void;
+/**
+ * Gets the network log
+ */
+export declare function getNetworkLog(): NetworkRequest[];
+/**
+ * Clears the network log
+ */
+export declare function clearNetworkLog(): void;
+/**
+ * Sets the provided page to the global page variable
+ * @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;
+        height?: number;
+    };
+    userAgent?: string;
+    headless?: boolean;
+    browserType?: 'chromium' | 'firefox' | 'webkit';
+    device?: string;
+}
+declare function registerConsoleMessage(page: any): Promise<void>;
+/**
+ * Ensures a browser is launched and returns the page
+ */
+export declare function ensureBrowser(browserSettings?: BrowserSettings): Promise<Page>;
+/**
+ * Main handler for tool calls
+ */
+export declare function handleToolCall(name: string, args: any, server: any): Promise<ToolResponse>;
+/**
+ * Get console logs
+ */
+export declare function getConsoleLogs(): string[];
+/**
+ * Get console logs captured after the last navigation
+ */
+export declare function getConsoleLogsSinceLastNavigation(): string[];
+/**
+ * Get console logs captured after the last interaction
+ */
+export declare function getConsoleLogsSinceLastInteraction(): string[];
+/**
+ * Get screenshots
+ */
+export declare function getScreenshots(): Map<string, string>;
+/**
+ * Update last interaction timestamp
+ */
+export declare function updateLastInteractionTimestamp(): void;
+/**
+ * Update last navigation timestamp
+ */
+export declare function updateLastNavigationTimestamp(): void;
+/**
+ * Clear console logs
+ */
+export declare function clearConsoleLogs(): void;
+export { registerConsoleMessage };