mcp-web-inspector 0.10.0 → 0.12.0

package/README.md

@@ -962,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`

package/dist/index.js

@@ -8,6 +8,7 @@ import { setSessionConfig } from "./toolHandler.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { createServer } from "node:net";
 // Get package.json version
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = join(__dirname, "..");
@@ -37,6 +38,9 @@ const { values } = parseArgs({
             type: 'boolean',
             default: false,
         },
+        'cdp-port': {
+            type: 'string',
+        },
         'print-tools-json': {
             type: 'boolean',
             default: false,
@@ -48,17 +52,49 @@ const { values } = parseArgs({
     },
     strict: false,
 });
+// Probe localhost:port; resolve true if free, false if in use.
+function isPortFree(port) {
+    return new Promise(resolve => {
+        const srv = createServer();
+        srv.once('error', () => resolve(false));
+        srv.once('listening', () => srv.close(() => resolve(true)));
+        srv.listen(port, '127.0.0.1');
+    });
+}
+// First free port in [start, start+span). Throws if none.
+async function findFreePort(start, span) {
+    for (let p = start; p < start + span; p++) {
+        if (await isPortFree(p))
+            return p;
+    }
+    throw new Error(`No free CDP port in ${start}..${start + span - 1}`);
+}
+// Resolve --cdp-port: 0 disables; explicit value used as-is; unset auto-picks from 9222 upward.
+async function resolveCdpPort(raw) {
+    if (raw === undefined)
+        return findFreePort(9222, 100);
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        console.error(`Invalid --cdp-port value: ${raw}. Must be an integer in 0..65535 (0 disables).`);
+        process.exit(1);
+    }
+    return n;
+}
 // 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() {
+    // Skip port resolution when only printing metadata — no browser will launch.
+    const printOnly = Boolean(values['print-tools-json'] || values['print-tools-md']);
+    const cdpPort = printOnly ? 0 : await resolveCdpPort(values['cdp-port']);
+    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']),
+        cdpPort,
+    };
+    setSessionConfig(sessionConfig);
     // Create tool definitions with session config
     const TOOLS = createToolDefinitions(sessionConfig);
     // CLI utilities: print tools metadata (JSON/Markdown) and exit
@@ -72,6 +108,9 @@ async function runServer() {
         return;
     }
     console.error(`Starting mcp-web-inspector v${VERSION}`);
+    const cdpInstruction = sessionConfig.cdpPort > 0
+        ? `External Playwright clients can attach to this browser via Chrome DevTools Protocol at http://localhost:${sessionConfig.cdpPort} — pass that URL to chromium.connectOverCDP() to share cookies, localStorage, and the open page set with this server.`
+        : undefined;
     const server = new Server({
         name: "mcp-web-inspector",
         version: VERSION,
@@ -80,6 +119,7 @@ async function runServer() {
             resources: {},
             tools: {},
         },
+        ...(cdpInstruction ? { instructions: cdpInstruction } : {}),
     });
     // Setup request handlers
     setupRequestHandlers(server, TOOLS);

package/dist/toolHandler.js

@@ -13,6 +13,7 @@ let sessionConfig = {
     screenshotsDir: './.mcp-web-inspector/screenshots',
     headlessDefault: false,
     exposeSensitiveNetworkData: false,
+    cdpPort: 0,
 };
 let colorSchemeOverride = null;
 /**
@@ -400,10 +401,14 @@ export async function ensureBrowser(browserSettings) {
             // IPs (e.g. Tailscale 100.64.0.0/10). This breaks environments where the API is on an
             // internal network but the app is served from a public CDN.
             // Prepare context options
+            const launchArgs = ['--disable-features=LocalNetworkAccessChecks'];
+            if (sessionConfig.cdpPort && sessionConfig.cdpPort > 0) {
+                launchArgs.push(`--remote-debugging-port=${sessionConfig.cdpPort}`);
+            }
             const contextOptions = {
                 headless,
                 executablePath: executablePath,
-                args: ['--disable-features=LocalNetworkAccessChecks'],
+                args: launchArgs,
             };
             // If device config exists, use it; otherwise use manual viewport/userAgent
             if (deviceConfig) {
@@ -439,7 +444,10 @@ export async function ensureBrowser(browserSettings) {
             else {
                 browser = await browserInstance.launch({
                     headless,
-                    executablePath: executablePath
+                    executablePath: executablePath,
+                    args: sessionConfig.cdpPort && sessionConfig.cdpPort > 0
+                        ? [`--remote-debugging-port=${sessionConfig.cdpPort}`]
+                        : [],
                 });
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
@@ -608,10 +616,14 @@ export async function ensureBrowser(browserSettings) {
             retryViewportHeight = screenSize?.height ?? 720;
         }
         // Prepare context options
+        const retryLaunchArgs = ['--disable-features=LocalNetworkAccessChecks'];
+        if (sessionConfig.cdpPort && sessionConfig.cdpPort > 0) {
+            retryLaunchArgs.push(`--remote-debugging-port=${sessionConfig.cdpPort}`);
+        }
         const retryContextOptions = {
             headless,
             executablePath: executablePath,
-            args: ['--disable-features=LocalNetworkAccessChecks'],
+            args: retryLaunchArgs,
         };
         // If device config exists, use it; otherwise use manual viewport/userAgent
         if (deviceConfig) {
@@ -644,7 +656,10 @@ export async function ensureBrowser(browserSettings) {
         else {
             browser = await browserInstance.launch({
                 headless,
-                executablePath: executablePath
+                executablePath: executablePath,
+                args: sessionConfig.cdpPort && sessionConfig.cdpPort > 0
+                    ? [`--remote-debugging-port=${sessionConfig.cdpPort}`]
+                    : [],
             });
             currentBrowserType = browserType;
             browser.on('disconnected', () => {

package/dist/tools/browser/interaction/fill.d.ts

@@ -1,8 +1,6 @@
 import { BrowserToolBase } from '../base.js';
 import { ToolContext, ToolResponse, ToolMetadata, SessionConfig } from '../../common/types.js';
-/**
- * Tool for filling form fields
- */
+export declare const BOUNDED_FILLABLE_DESCENDANT_SELECTOR: string;
 export declare class FillTool extends BrowserToolBase {
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     execute(args: any, context: ToolContext): Promise<ToolResponse>;

package/dist/tools/browser/interaction/fill.js

@@ -1,18 +1,33 @@
 import { BrowserToolBase } from '../base.js';
 import { ANNOTATIONS, createSuccessResponse } from '../../common/types.js';
-/**
- * Tool for filling form fields
- */
+const FILLABLE_BASE_SELECTOR = 'input:not([type="button"]):not([type="submit"]):not([type="reset"])' +
+    ':not([type="checkbox"]):not([type="radio"]):not([type="file"])' +
+    ':not([type="image"]):not([type="hidden"]),' +
+    'textarea,' +
+    '[contenteditable=""],' +
+    '[contenteditable="true"]';
+const MAX_DESCENT_DEPTH = 4;
+export const BOUNDED_FILLABLE_DESCENDANT_SELECTOR = (() => {
+    const parts = FILLABLE_BASE_SELECTOR.split(',').map((s) => s.trim());
+    const groups = [];
+    for (let depth = 1; depth <= MAX_DESCENT_DEPTH; depth++) {
+        const ancestors = '* > '.repeat(depth - 1);
+        for (const p of parts) {
+            groups.push(`:scope > ${ancestors}${p}`);
+        }
+    }
+    return groups.join(', ');
+})();
 export class FillTool extends BrowserToolBase {
     static getMetadata(sessionConfig) {
         return {
             name: "fill",
-            description: "fill out an input field",
+            description: "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)",
             annotations: ANNOTATIONS.interaction,
             inputSchema: {
                 type: "object",
                 properties: {
-                    selector: { type: "string", description: "CSS selector for input field" },
+                    selector: { type: "string", description: "CSS selector for input field or its wrapper" },
                     value: { type: "string", description: "Value to fill" },
                 },
                 required: ["selector", "value"],
@@ -23,14 +38,97 @@ export class FillTool extends BrowserToolBase {
         this.recordInteraction();
         return this.safeExecute(context, async (page) => {
             const normalizedSelector = this.normalizeSelector(args.selector);
-            // Use standard element selection with error on multiple matches
             const locator = page.locator(normalizedSelector);
             const { element } = await this.selectPreferredLocator(locator, {
                 errorOnMultiple: true,
                 originalSelector: args.selector,
             });
-            await element.fill(args.value);
-            return createSuccessResponse(`Filled ${args.selector} with: ${args.value}`);
+            const wrapperInfo = await element.evaluate((el) => {
+                const fillableMatch = (node) => {
+                    if (!node || node.nodeType !== 1)
+                        return false;
+                    const tag = (node.tagName || '').toLowerCase();
+                    if (tag === 'textarea')
+                        return true;
+                    if (tag === 'input') {
+                        const type = (node.getAttribute('type') || '').toLowerCase();
+                        return !['button', 'submit', 'reset', 'checkbox', 'radio', 'file', 'image', 'hidden'].includes(type);
+                    }
+                    const ce = node.getAttribute('contenteditable');
+                    return ce === '' || ce === 'true';
+                };
+                return {
+                    isFillable: fillableMatch(el),
+                    tag: (el.tagName || '').toLowerCase(),
+                };
+            });
+            if (wrapperInfo.isFillable) {
+                await element.fill(args.value);
+                return createSuccessResponse(`Filled ${args.selector} with: ${args.value}`);
+            }
+            const descendants = element.locator(BOUNDED_FILLABLE_DESCENDANT_SELECTOR);
+            const count = await descendants.count();
+            if (count === 0) {
+                throw new Error(`Selector "${args.selector}" matched a <${wrapperInfo.tag}> wrapper with no fillable descendants within ${MAX_DESCENT_DEPTH} levels (input, textarea, contenteditable).`);
+            }
+            if (count > 1) {
+                const candidates = await describeFillableCandidates(descendants, count);
+                throw new Error(`Selector "${args.selector}" matched a <${wrapperInfo.tag}> wrapper with ${count} fillable descendants. ` +
+                    `Use a more specific selector or add data-testid to the input itself.\n\nCandidates:\n${candidates}`);
+            }
+            const target = descendants.first();
+            const targetTag = await target.evaluate((el) => {
+                const tag = (el.tagName || '').toLowerCase();
+                const type = el.getAttribute?.('type');
+                return type ? `<${tag} type="${type}">` : `<${tag}>`;
+            });
+            await target.fill(args.value);
+            return createSuccessResponse(`Filled ${args.selector} with: ${args.value} (descended into ${targetTag})`);
         });
     }
 }
+async function describeFillableCandidates(locator, count) {
+    const max = Math.min(count, 5);
+    const lines = [];
+    for (let i = 0; i < max; i++) {
+        const nth = locator.nth(i);
+        try {
+            const info = await nth.evaluate((el) => {
+                const tag = (el.tagName || '').toLowerCase();
+                const type = el.getAttribute?.('type') || null;
+                const name = el.getAttribute?.('name') || null;
+                const id = el.id || null;
+                const placeholder = el.getAttribute?.('placeholder') || null;
+                const ariaLabel = el.getAttribute?.('aria-label') || null;
+                const testid = el.getAttribute?.('data-testid') || el.getAttribute?.('data-test') || el.getAttribute?.('data-cy') || null;
+                return { tag, type, name, id, placeholder, ariaLabel, testid };
+            });
+            const attrs = [];
+            if (info.type)
+                attrs.push(`type="${info.type}"`);
+            if (info.name)
+                attrs.push(`name="${info.name}"`);
+            if (info.id)
+                attrs.push(`id="${info.id}"`);
+            if (info.placeholder)
+                attrs.push(`placeholder="${truncate(info.placeholder)}"`);
+            if (info.ariaLabel)
+                attrs.push(`aria-label="${truncate(info.ariaLabel)}"`);
+            if (info.testid)
+                attrs.push(`data-testid="${info.testid}"`);
+            const head = `[${i}] <${info.tag}${attrs.length ? ' ' + attrs.join(' ') : ''}>`;
+            const suggestion = info.testid ? `testid:${info.testid}` : info.id ? `id=${info.id}` : null;
+            lines.push(suggestion ? `${head}\n    selector: ${suggestion}` : head);
+        }
+        catch {
+            lines.push(`[${i}] (element)`);
+        }
+    }
+    if (count > max) {
+        lines.push(`… and ${count - max} more.`);
+    }
+    return lines.join('\n');
+}
+function truncate(s) {
+    return s.length > 60 ? `${s.slice(0, 57)}...` : s;
+}

package/dist/tools/common/types.d.ts

@@ -38,6 +38,7 @@ export interface SessionConfig {
     screenshotsDir: string;
     headlessDefault: boolean;
     exposeSensitiveNetworkData?: boolean;
+    cdpPort?: number;
 }
 export interface ToolContext {
     page?: Page;

package/package.json

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