mcp-web-inspector 0.11.0 → 0.12.0

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/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.11.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",