cdp-mcp-server 5.0.1 → 5.0.3

package/dist/tools/interact.js

@@ -199,12 +199,12 @@ async function handleType(ctx, args) {
     }, retryTimeout);
     // Clear existing content if requested (default: true)
     const clearCode = args.clear !== false
-        ? `if ('value' in this) {
-        const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
-                          || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
-        if (nativeSetter) nativeSetter.call(this, '');
-        else this.value = '';
-        this.dispatchEvent(new Event('input', {bubbles:true}));
+        ? `if ('value' in this) {
+        const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
+                          || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+        if (nativeSetter) nativeSetter.call(this, '');
+        else this.value = '';
+        this.dispatchEvent(new Event('input', {bubbles:true}));
       } else if (this.isContentEditable) { this.textContent = ''; }`
         : '';
     await ctx.sendCommand('Runtime.callFunctionOn', {
@@ -264,20 +264,20 @@ async function handleType(ctx, args) {
     else {
         // Instant fill using nativeInputValueSetter for React/Angular compatibility
         await ctx.sendCommand('Runtime.evaluate', {
-            expression: `(() => {
-        const el = document.activeElement;
-        if (!el) return;
-        const val = ${JSON.stringify(args.text)};
-        if ('value' in el) {
-          const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
-                            || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
-          if (nativeSetter) nativeSetter.call(el, val);
-          else el.value = val;
-        } else if (el.isContentEditable) {
-          document.execCommand('insertText', false, val);
-        }
-        el.dispatchEvent(new Event('input', {bubbles:true}));
-        el.dispatchEvent(new Event('change', {bubbles:true}));
+            expression: `(() => {
+        const el = document.activeElement;
+        if (!el) return;
+        const val = ${JSON.stringify(args.text)};
+        if ('value' in el) {
+          const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
+                            || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+          if (nativeSetter) nativeSetter.call(el, val);
+          else el.value = val;
+        } else if (el.isContentEditable) {
+          document.execCommand('insertText', false, val);
+        }
+        el.dispatchEvent(new Event('input', {bubbles:true}));
+        el.dispatchEvent(new Event('change', {bubbles:true}));
       })()`,
         }, sess);
     }
@@ -308,38 +308,38 @@ async function handleFill(ctx, args) {
             }, retryTimeout);
             const fieldType = field.type || 'text';
             const r = await ctx.sendCommand('Runtime.callFunctionOn', {
-                functionDeclaration: `function() {
-          this.scrollIntoView({ block: "center" });
-          const type = ${JSON.stringify(fieldType)};
-          const val = ${JSON.stringify(field.value)};
-          if (type === "checkbox") {
-            const wanted = val === "true" || val === "1";
-            if (this.checked !== wanted) this.click();
-            return { ok: true, value: String(this.checked) };
-          }
-          if (type === "radio") { this.click(); return { ok: true, value: val }; }
-          if (type === "select") {
-            let opt = Array.from(this.options).find(o => o.value === val || o.textContent.trim() === val);
-            if (!opt) return { error: "Option not found: " + val };
-            const nativeSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
-            if (nativeSetter) nativeSetter.call(this, opt.value);
-            else this.value = opt.value;
-            this.dispatchEvent(new Event('input', {bubbles:true}));
-            this.dispatchEvent(new Event('change', {bubbles:true}));
-            return { ok: true, value: opt.textContent.trim() };
-          }
-          this.focus();
-          if ('value' in this) {
-            const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
-                              || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
-            if (nativeSetter) nativeSetter.call(this, val);
-            else this.value = val;
-          } else if (this.isContentEditable) {
-            this.textContent = val;
-          }
-          this.dispatchEvent(new Event('input', {bubbles:true}));
-          this.dispatchEvent(new Event('change', {bubbles:true}));
-          return { ok: true, value: val.substring(0, 40) };
+                functionDeclaration: `function() {
+          this.scrollIntoView({ block: "center" });
+          const type = ${JSON.stringify(fieldType)};
+          const val = ${JSON.stringify(field.value)};
+          if (type === "checkbox") {
+            const wanted = val === "true" || val === "1";
+            if (this.checked !== wanted) this.click();
+            return { ok: true, value: String(this.checked) };
+          }
+          if (type === "radio") { this.click(); return { ok: true, value: val }; }
+          if (type === "select") {
+            let opt = Array.from(this.options).find(o => o.value === val || o.textContent.trim() === val);
+            if (!opt) return { error: "Option not found: " + val };
+            const nativeSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+            if (nativeSetter) nativeSetter.call(this, opt.value);
+            else this.value = opt.value;
+            this.dispatchEvent(new Event('input', {bubbles:true}));
+            this.dispatchEvent(new Event('change', {bubbles:true}));
+            return { ok: true, value: opt.textContent.trim() };
+          }
+          this.focus();
+          if ('value' in this) {
+            const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set
+                              || Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+            if (nativeSetter) nativeSetter.call(this, val);
+            else this.value = val;
+          } else if (this.isContentEditable) {
+            this.textContent = val;
+          }
+          this.dispatchEvent(new Event('input', {bubbles:true}));
+          this.dispatchEvent(new Event('change', {bubbles:true}));
+          return { ok: true, value: val.substring(0, 40) };
         }`,
                 objectId,
                 returnByValue: true,
@@ -363,35 +363,35 @@ async function handleSelect(ctx, args) {
         return resolveElementObjectId(ctx, sess, args.uid, args.selector, args.tabId);
     }, retryTimeout);
     const result = await ctx.sendCommand('Runtime.callFunctionOn', {
-        functionDeclaration: `function() {
-      const sel = this;
-      if (sel.tagName === "SELECT") {
-        const targetVal = ${JSON.stringify(args.value)};
-        let opt = Array.from(sel.options).find(o => o.value === targetVal);
-        if (!opt) opt = Array.from(sel.options).find(o => o.textContent.trim() === targetVal);
-        if (!opt) return { error: "Option not found: " + targetVal + ". Available: " + Array.from(sel.options).map(o => o.textContent.trim()).join(", ") };
-
-        const nativeSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
-        if (nativeSetter) nativeSetter.call(sel, opt.value);
-        else sel.value = opt.value;
-
-        sel.dispatchEvent(new Event("input", { bubbles: true }));
-        sel.dispatchEvent(new Event("change", { bubbles: true }));
-        return { selected: opt.textContent.trim(), value: opt.value };
-      }
-
-      const role = sel.getAttribute("role");
-      const isCustomDropdown = role === "combobox" || role === "listbox" ||
-        sel.getAttribute("aria-haspopup") ||
-        sel.classList.toString().match(/MuiSelect|ant-select|react-select|Select/i);
-
-      if (isCustomDropdown) {
-        sel.scrollIntoView({ block: "center" });
-        sel.click();
-        return { customDropdown: true, message: "Custom dropdown opened — click the matching option" };
-      }
-
-      return { error: "Not a <select> element and not a recognized custom dropdown. Element: <" + sel.tagName.toLowerCase() + ">" };
+        functionDeclaration: `function() {
+      const sel = this;
+      if (sel.tagName === "SELECT") {
+        const targetVal = ${JSON.stringify(args.value)};
+        let opt = Array.from(sel.options).find(o => o.value === targetVal);
+        if (!opt) opt = Array.from(sel.options).find(o => o.textContent.trim() === targetVal);
+        if (!opt) return { error: "Option not found: " + targetVal + ". Available: " + Array.from(sel.options).map(o => o.textContent.trim()).join(", ") };
+
+        const nativeSetter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+        if (nativeSetter) nativeSetter.call(sel, opt.value);
+        else sel.value = opt.value;
+
+        sel.dispatchEvent(new Event("input", { bubbles: true }));
+        sel.dispatchEvent(new Event("change", { bubbles: true }));
+        return { selected: opt.textContent.trim(), value: opt.value };
+      }
+
+      const role = sel.getAttribute("role");
+      const isCustomDropdown = role === "combobox" || role === "listbox" ||
+        sel.getAttribute("aria-haspopup") ||
+        sel.classList.toString().match(/MuiSelect|ant-select|react-select|Select/i);
+
+      if (isCustomDropdown) {
+        sel.scrollIntoView({ block: "center" });
+        sel.click();
+        return { customDropdown: true, message: "Custom dropdown opened — click the matching option" };
+      }
+
+      return { error: "Not a <select> element and not a recognized custom dropdown. Element: <" + sel.tagName.toLowerCase() + ">" };
     }`,
         objectId,
         returnByValue: true,
@@ -403,19 +403,19 @@ async function handleSelect(ctx, args) {
     if (v?.customDropdown) {
         await sleep(300);
         const clickResult = await ctx.sendCommand('Runtime.evaluate', {
-            expression: `(() => {
-        const val = ${JSON.stringify(args.value)};
-        const options = document.querySelectorAll('[role="option"], [role="listitem"], li[data-value], .MuiMenuItem-root, .ant-select-item, [class*="option"]');
-        for (const opt of options) {
-          const text = opt.textContent.trim();
-          const value = opt.getAttribute("data-value") || opt.getAttribute("value") || "";
-          if (text === val || value === val || text.toLowerCase() === val.toLowerCase()) {
-            opt.scrollIntoView({ block: "center" });
-            opt.click();
-            return { selected: text, value: value || text };
-          }
-        }
-        return { error: "Option not found in custom dropdown: " + val + ". Visible options: " + Array.from(options).slice(0, 10).map(o => o.textContent.trim()).join(", ") };
+            expression: `(() => {
+        const val = ${JSON.stringify(args.value)};
+        const options = document.querySelectorAll('[role="option"], [role="listitem"], li[data-value], .MuiMenuItem-root, .ant-select-item, [class*="option"]');
+        for (const opt of options) {
+          const text = opt.textContent.trim();
+          const value = opt.getAttribute("data-value") || opt.getAttribute("value") || "";
+          if (text === val || value === val || text.toLowerCase() === val.toLowerCase()) {
+            opt.scrollIntoView({ block: "center" });
+            opt.click();
+            return { selected: text, value: value || text };
+          }
+        }
+        return { error: "Option not found in custom dropdown: " + val + ". Visible options: " + Array.from(options).slice(0, 10).map(o => o.textContent.trim()).join(", ") };
       })()`,
             returnByValue: true,
         }, sess);
@@ -696,10 +696,10 @@ async function handleFocus(ctx, args) {
     const retryTimeout = args.timeout || ctx.config.actionTimeout;
     const { objectId, resolvedSession } = await withRetry(() => resolveElementObjectId(ctx, sess, args.uid, args.selector, args.tabId), retryTimeout);
     const result = await ctx.sendCommand('Runtime.callFunctionOn', {
-        functionDeclaration: `function() {
-      this.scrollIntoView({ block: "center" });
-      this.focus();
-      return { tag: this.tagName.toLowerCase(), label: (this.getAttribute("aria-label") || this.textContent || "").trim().substring(0, 60) };
+        functionDeclaration: `function() {
+      this.scrollIntoView({ block: "center" });
+      this.focus();
+      return { tag: this.tagName.toLowerCase(), label: (this.getAttribute("aria-label") || this.textContent || "").trim().substring(0, 60) };
     }`,
         objectId,
         returnByValue: true,
@@ -719,14 +719,14 @@ async function handleCheck(ctx, args) {
         return resolveElementObjectId(ctx, sess, args.uid, args.selector, args.tabId);
     }, retryTimeout);
     await ctx.sendCommand('Runtime.callFunctionOn', {
-        functionDeclaration: `function() {
-      this.scrollIntoView({ block: "center" });
-      const desired = ${args.checked === true};
-      if (this.checked !== desired) {
-        this.click();
-        this.dispatchEvent(new Event('change', { bubbles: true }));
-      }
-      return { checked: this.checked };
+        functionDeclaration: `function() {
+      this.scrollIntoView({ block: "center" });
+      const desired = ${args.checked === true};
+      if (this.checked !== desired) {
+        this.click();
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+      }
+      return { checked: this.checked };
     }`,
         objectId,
         returnByValue: true,
@@ -785,14 +785,14 @@ async function resolveElement(ctx, sess, uid, selector, tabId) {
             throw Errors.staleRef(uid);
         // Get bounding rect and element info via JS
         const info = await ctx.sendCommand('Runtime.callFunctionOn', {
-            functionDeclaration: `function() {
-        const r = this.getBoundingClientRect();
-        return {
-          x: r.x + r.width / 2, y: r.y + r.height / 2,
-          w: r.width, h: r.height,
-          tag: this.tagName.toLowerCase(),
-          label: (this.getAttribute('aria-label') || this.textContent || '').trim().substring(0, 60),
-        };
+            functionDeclaration: `function() {
+        const r = this.getBoundingClientRect();
+        return {
+          x: r.x + r.width / 2, y: r.y + r.height / 2,
+          w: r.width, h: r.height,
+          tag: this.tagName.toLowerCase(),
+          label: (this.getAttribute('aria-label') || this.textContent || '').trim().substring(0, 60),
+        };
       }`,
             objectId: object.objectId,
             returnByValue: true,
@@ -804,16 +804,16 @@ async function resolveElement(ctx, sess, uid, selector, tabId) {
     if (!selector)
         throw new Error('Provide uid or selector to identify the element.');
     const result = await ctx.sendCommand('Runtime.evaluate', {
-        expression: `(() => {
-      const el = document.querySelector(${JSON.stringify(selector)});
-      if (!el) return null;
-      const r = el.getBoundingClientRect();
-      return {
-        x: r.x + r.width / 2, y: r.y + r.height / 2,
-        w: r.width, h: r.height,
-        tag: el.tagName.toLowerCase(),
-        label: (el.getAttribute('aria-label') || el.textContent || '').trim().substring(0, 60),
-      };
+        expression: `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return null;
+      const r = el.getBoundingClientRect();
+      return {
+        x: r.x + r.width / 2, y: r.y + r.height / 2,
+        w: r.width, h: r.height,
+        tag: el.tagName.toLowerCase(),
+        label: (el.getAttribute('aria-label') || el.textContent || '').trim().substring(0, 60),
+      };
     })()`,
         returnByValue: true,
     }, sess);
@@ -969,16 +969,16 @@ function getAdjacentKey(char) {
 async function findAndSetFileInput(ctx, sess, files) {
     try {
         const inputObj = await ctx.sendCommand('Runtime.evaluate', {
-            expression: `(() => {
-        function find(root) {
-          const el = root.querySelector('input[type="file"]');
-          if (el) return el;
-          for (const s of root.querySelectorAll('*')) {
-            if (s.shadowRoot) { const f = find(s.shadowRoot); if (f) return f; }
-          }
-          return null;
-        }
-        return find(document);
+            expression: `(() => {
+        function find(root) {
+          const el = root.querySelector('input[type="file"]');
+          if (el) return el;
+          for (const s of root.querySelectorAll('*')) {
+            if (s.shadowRoot) { const f = find(s.shadowRoot); if (f) return f; }
+          }
+          return null;
+        }
+        return find(document);
       })()`,
             returnByValue: false,
         }, sess);
@@ -992,9 +992,9 @@ async function findAndSetFileInput(ctx, sess, files) {
         }, sess);
         // Dispatch change+input events
         await ctx.sendCommand('Runtime.callFunctionOn', {
-            functionDeclaration: `function() {
-        this.dispatchEvent(new Event('change', { bubbles: true }));
-        this.dispatchEvent(new Event('input', { bubbles: true }));
+            functionDeclaration: `function() {
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+        this.dispatchEvent(new Event('input', { bubbles: true }));
       }`,
             objectId: inputObj.result.objectId,
         }, sess).catch(() => { });

package/dist/tools/tabs.js

@@ -253,9 +253,9 @@ export async function handleNew(ctx, args) {
         // Phase 5: Wait for load
         try {
             await ctx.sendCommand('Runtime.evaluate', {
-                expression: `new Promise(resolve => {
-            if (document.readyState === 'complete') return resolve(true);
-            window.addEventListener('load', () => resolve(true), { once: true });
+                expression: `new Promise(resolve => {
+            if (document.readyState === 'complete') return resolve(true);
+            window.addEventListener('load', () => resolve(true), { once: true });
           })`,
                 awaitPromise: true,
                 returnByValue: true,

package/dist/types.d.ts

@@ -43,6 +43,10 @@ export interface ServerConfig {
     maxTempAgeMs: number;
     /** If set, auto-connect to this Chrome instance/profile on startup */
     autoConnectProfile: string;
+    /** Extra User Data dir checked first during discovery (CDP_USER_DATA) */
+    userDataDir: string;
+    /** Process command-line scan on discovery failure (CDP_PROCESS_SCAN, default ON) */
+    processScan: boolean;
     /** If true, expose 6 slim tools instead of 15 full tools (for small-context models) */
     slimMode: boolean;
 }

package/dist/utils/connect-diagnostics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Connect-failure diagnostics — classifies why auto-connect failed and
+ * produces a kind + human message with the exact fix.
+ *
+ * Failure signatures (source-verified, see _archive research 2026-10):
+ *  - TCP refused on every port, no browser processes  → no browser / not launched
+ *  - TCP refused, browser running WITH debug flag     → Chrome 136+ default-profile block
+ *  - Port bound, /json/version → 404                  → gated remote-debugging (toggle)
+ *  - WS rejected with --remote-allow-origins hint     → origin allowlist
+ *  - Port file existed but WS connect failed          → approval dialog denied / stale file
+ */
+/** Outcome of probing one HTTP debug port. */
+export type PortProbeOutcome = 'refused' | 'not_found' | 'timeout' | 'ok' | 'error';
+export interface PortProbeEvidence {
+    port: number;
+    outcome: PortProbeOutcome;
+    /** HTTP status code when available (404 for gated mode). */
+    status?: number;
+    /** Short error detail (error message, never a full stack). */
+    detail?: string;
+}
+/** What the (optional) process scan saw on the machine. */
+export interface ProcessInfo {
+    /** Browser process names seen running (e.g. 'brave', 'chrome'). */
+    browsersRunning: string[];
+    /** At least one browser was launched with --remote-debugging-port. */
+    flagPresent: boolean;
+}
+export type ConnectFailureKind = 'no_browser' | 'no_debug_flag' | 'm136_default_dir' | 'toggle_mode' | 'approval_denied' | 'origin_blocked' | 'generic';
+export interface ConnectDiagnosis {
+    kind: ConnectFailureKind;
+    headline: string;
+    fix: string;
+}
+export interface ClassifyInput {
+    probes: PortProbeEvidence[];
+    /** True when file-based discovery found at least one DevToolsActivePort. */
+    portFilesFound: number;
+    /** Error messages captured from failed WS connect attempts. */
+    connectErrors: string[];
+    /** Process-scan result, or null when scan disabled/unavailable. */
+    processInfo: ProcessInfo | null;
+    host: string;
+    primaryPort: number;
+}
+export declare function classifyConnectFailure(input: ClassifyInput): ConnectDiagnosis;

package/dist/utils/connect-diagnostics.js

@@ -0,0 +1,124 @@
+/**
+ * Connect-failure diagnostics — classifies why auto-connect failed and
+ * produces a kind + human message with the exact fix.
+ *
+ * Failure signatures (source-verified, see _archive research 2026-10):
+ *  - TCP refused on every port, no browser processes  → no browser / not launched
+ *  - TCP refused, browser running WITH debug flag     → Chrome 136+ default-profile block
+ *  - Port bound, /json/version → 404                  → gated remote-debugging (toggle)
+ *  - WS rejected with --remote-allow-origins hint     → origin allowlist
+ *  - Port file existed but WS connect failed          → approval dialog denied / stale file
+ */
+// ─── Helpers ────────────────────────────────────────────────────────
+const ANY_BOUND = (probes) => probes.some((p) => p.outcome === 'not_found' || p.outcome === 'ok');
+const ALL_REFUSED = (probes) => probes.length > 0 && probes.every((p) => p.outcome === 'refused');
+function relaunchCommand(host, port) {
+    const target = host === '127.0.0.1' || host === 'localhost' ? '' : ` ${host}`;
+    return (`& '<browser.exe>' --user-data-dir='<dir>' --remote-debugging-port=${port}${target}`);
+}
+// ─── Classifier ─────────────────────────────────────────────────────
+export function classifyConnectFailure(input) {
+    const { probes, portFilesFound, connectErrors, processInfo, host, primaryPort } = input;
+    const originError = connectErrors.find((e) => e.includes('--remote-allow-origins'));
+    if (originError) {
+        return {
+            kind: 'origin_blocked',
+            headline: 'The browser rejected this WebSocket origin.',
+            fix: `Relaunch the browser with:\n` +
+                `  --remote-allow-origins=${host === '127.0.0.1' ? '*' : host}\n` +
+                `Or connect from the same origin the browser expects.`,
+        };
+    }
+    // Most specific: a port file was found and a WS connect was attempted but
+    // failed (approval dialog denied, stale file, no visible window).
+    if (portFilesFound > 0 && connectErrors.length > 0) {
+        return {
+            kind: 'approval_denied',
+            headline: 'A DevToolsActivePort file was found but the WebSocket connection ' +
+                'was rejected.',
+            fix: `Likely causes:\n` +
+                `  1. The permission dialog was dismissed or no browser window was ` +
+                `visible (approval mode auto-denies without a window).\n` +
+                `  2. The port file is stale (browser restarted on another port). ` +
+                `Retry after the browser settles.\n` +
+                `  3. Or relaunch with the flag: ${relaunchCommand(host, primaryPort)}`,
+        };
+    }
+    // Gated remote-debugging: port bound but the legacy HTTP API is absent.
+    const gated = probes.find((p) => p.outcome === 'not_found' && p.status === 404);
+    if (gated) {
+        return {
+            kind: 'toggle_mode',
+            headline: 'Your browser is running the new gated remote-debugging ' +
+                '(chrome://inspect/#remote-debugging toggle). It does not serve the ' +
+                'legacy HTTP discovery API.',
+            fix: `Do ONE of these:\n` +
+                `  1. Look at your browser — a permission dialog may be waiting. ` +
+                `Click "Allow" (needs a visible browser window).\n` +
+                `  2. Or relaunch with the flag (same data dir keeps your logins):\n` +
+                `     ${relaunchCommand(host, primaryPort)}\n` +
+                `  3. Or keep the toggle and make sure the browser's User Data dir ` +
+                `is discoverable (CDP_USER_DATA env or process scan).`,
+        };
+    }
+    if (ALL_REFUSED(probes)) {
+        const browsers = processInfo?.browsersRunning ?? [];
+        if (browsers.length === 0) {
+            return {
+                kind: 'no_browser',
+                headline: 'Could not find any browser with remote debugging enabled.',
+                fix: `To fix, do ONE of these:\n` +
+                    `  1. Launch your browser with the debug flag:\n` +
+                    `     ${relaunchCommand(host, primaryPort)}\n` +
+                    `  2. Or enable the chrome://inspect/#remote-debugging toggle ` +
+                    `(Chrome/Brave 144+)\n` +
+                    `  3. Or set CDP_PORT env var if using a non-standard port\n\n` +
+                    `The server will auto-connect once debugging is enabled.`,
+            };
+        }
+        if (processInfo?.flagPresent) {
+            // Flag present but nothing listening → Chrome 136+ default-profile block
+            return {
+                kind: 'm136_default_dir',
+                headline: 'The debug port was requested but Chromium 136+ refuses CDP on the ' +
+                    'DEFAULT User Data directory.',
+                fix: `Relaunch with an explicit NON-DEFAULT data dir (your logins stay ` +
+                    `if you reuse the same dir):\n` +
+                    `  ${relaunchCommand(host, primaryPort)}\n` +
+                    `Note: Chrome for Testing is exempt from this restriction.`,
+            };
+        }
+        return {
+            kind: 'no_debug_flag',
+            headline: 'A browser is running, but without remote debugging enabled.',
+            fix: `Do ONE of these:\n` +
+                `  1. Fully exit the browser, then relaunch with:\n` +
+                `     ${relaunchCommand(host, primaryPort)}\n` +
+                `  2. Or enable the chrome://inspect/#remote-debugging toggle ` +
+                `(Chrome/Brave 144+) — the server will ask for permission on connect.`,
+        };
+    }
+    // Port file existed but connect failed without a recognizable signature —
+    // handled above; this branch is unreachable but kept for safety.
+    if (portFilesFound > 0 && connectErrors.length > 0) {
+        return {
+            kind: 'approval_denied',
+            headline: 'A DevToolsActivePort file was found but the WebSocket connection ' +
+                'was rejected.',
+            fix: `Likely causes:\n` +
+                `  1. The permission dialog was dismissed or no browser window was ` +
+                `visible (approval mode auto-denies without a window).\n` +
+                `  2. The port file is stale (browser restarted on another port). ` +
+                `Retry after the browser settles.\n` +
+                `  3. Or relaunch with the flag: ${relaunchCommand(host, primaryPort)}`,
+        };
+    }
+    return {
+        kind: 'generic',
+        headline: 'Could not connect to any browser.',
+        fix: `Launch the browser with:\n` +
+            `  ${relaunchCommand(host, primaryPort)}\n` +
+            `Or enable the chrome://inspect/#remote-debugging toggle.`,
+    };
+}
+//# sourceMappingURL=connect-diagnostics.js.map

package/dist/utils/connect-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-diagnostics.js","sourceRoot":"","sources":["../../src/utils/connect-diagnostics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "cdp-mcp-server",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "The power user's browser MCP — connects to your real Chrome/Edge/Brave with full DevTools capabilities",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "cdp-mcp-server": "dist/index.js"
+  },
   "author": "Tushar Agarwal",
   "license": "MIT",
   "repository": {
@@ -25,18 +28,9 @@
     "browser-mcp"
   ],
   "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "ws": "^8.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.39",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3",
-    "vitest": "^2.1.9"
+    "node": ">=20"
   },
+  "packageManager": "pnpm@12.6.0",
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
@@ -48,5 +42,15 @@
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "clean": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.39",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
   }
-}
+}