what-devtools-mcp 0.10.0 → 0.11.1

package/README.md

@@ -174,6 +174,18 @@ installDevTools(core);
 connectDevToolsMCP({ port: 9229 });
 ```
 
+Without the Vite plugin the client starts **dormant** — it does not poll for a
+bridge, so apps with no bridge running produce zero console/network noise.
+To activate it, do one of:
+
+- pass an explicit `token` (e.g. from `WHAT_MCP_TOKEN`): `connectDevToolsMCP({ token })`
+- set `window.__WHAT_DEVTOOLS_DEBUG__ = true` before calling it
+- call `window.__WHAT_MCP_RECONNECT__()` from the browser console after starting the bridge
+
+The Vite plugin doesn't need any of this: it serves a same-origin
+`/__what_mcp_discovery` endpoint and the client polls that quietly, so the
+bridge is discovered automatically whenever it's running.
+
 ## Configuration
 
 | Option | Default | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools-mcp",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "MCP server bridging AI agents to live What Framework app state via WebSocket",
   "type": "module",
   "bin": {

package/src/bridge.js

@@ -13,7 +13,7 @@ import { join } from 'path';
 const MAX_EVENT_LOG = 1000;
 const MAX_ERROR_LOG = 100;
 
-export function createBridge({ port = 9229, host = '127.0.0.1' } = {}) {
+export function createBridge({ port = 9229, host = '127.0.0.1', onError } = {}) {
   let latestSnapshot = null;
   const eventLog = [];
   const errorLog = [];
@@ -60,6 +60,30 @@ export function createBridge({ port = 9229, host = '127.0.0.1' } = {}) {
     }
   }});
 
+  // The WebSocketServer binds the port immediately on construction. Without an
+  // 'error' listener, an EADDRINUSE (very likely — 9229 is also Node's default
+  // --inspect port) is emitted as an unhandled 'error' event, which an
+  // EventEmitter rethrows and hard-crashes the whole process. The bridge IS the
+  // server, so unlike the optional HTTP discovery port we cannot silently carry
+  // on with a dead WS server. Strategy: gracefully exit(0) with an actionable
+  // message so the launcher (e.g. `what dev`) sees a clean shutdown rather than
+  // an uncaught-exception stack trace. Callers (tests) can pass `onError` to
+  // intercept instead of exiting.
+  wss.on('error', (err) => {
+    if (err && err.code === 'EADDRINUSE') {
+      const inspectNote = port === 9229 ? ' (note: 9229 is also Node\'s default --inspect port)' : '';
+      console.error(`[what-devtools-mcp] port ${port} in use — set WHAT_MCP_PORT to a free port or stop the process using it${inspectNote}.`);
+    } else {
+      console.error(`[what-devtools-mcp] bridge WebSocket server error: ${err && err.message ? err.message : err}`);
+    }
+    if (typeof onError === 'function') {
+      onError(err);
+    } else {
+      // Graceful exit: the bridge cannot function without its WS port.
+      process.exit(0);
+    }
+  });
+
   // --- Token Discovery ---
   // Two mechanisms so the browser client can find the token automatically:
   //

package/src/client-commands.js

@@ -138,9 +138,16 @@ export async function handleExtendedCommand(command, args, devtools) {
       const segments = code.split('.');
       const isSimpleIdent = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
       const PROTO_DENYLIST = new Set(['constructor', 'prototype', '__proto__']);
+      // Sensitive property paths: reads that exfiltrate secrets/state must
+      // require the explicit unsafe flag (document.cookie, window.localStorage...).
+      // Mirror of SENSITIVE_PATHS in tools-extended.js what_eval.
+      const SENSITIVE_PATHS = new Set([
+        'cookie', 'localStorage', 'sessionStorage', 'indexedDB', 'credentials',
+        'geolocation', 'clipboard', 'serviceWorker', 'caches', 'opener',
+      ]);
       const isSafeRead = segments.length >= 2 &&
         SAFE_GLOBALS.has(segments[0]) &&
-        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s));
+        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s) && !SENSITIVE_PATHS.has(s));
 
       if (!evalEnabled && !isSafeRead) {
         return {

package/src/client.js

@@ -21,80 +21,143 @@ function logGrouped(badge, badgeStyle, title, data) {
   console.groupEnd();
 }
 
-export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
+export function connectDevToolsMCP({ port = 9229, token = '', discoveryUrl = '' } = {}) {
   // Never connect in production
   if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
-    return { disconnect() {}, isConnected: false, eventCount: 0 };
+    return { disconnect() {}, reconnect() {}, isConnected: false, eventCount: 0 };
   }
   try {
     if (import.meta?.env?.PROD) {
-      return { disconnect() {}, isConnected: false, eventCount: 0 };
+      return { disconnect() {}, reconnect() {}, isConnected: false, eventCount: 0 };
     }
   } catch {}
 
   let ws = null;
   let connected = false;
-  let reconnectTimer = null;
-  let reconnectDelay = 1000;
-  const MAX_RECONNECT_DELAY = 30000;
-  const pendingResponses = new Map();
+  let stopped = false;
+  let probeTimer = null;
+  // Probe back-off: first retry after 10s, then ×3 each time, capped at 5min.
+  // With no bridge running this yields probes at ~0s / 10s / 40s / 130s / 430s…
+  // — at most 3-4 quiet fetch attempts in the first two minutes, then near-silence.
+  const PROBE_DELAY_INITIAL = 10000;
+  const PROBE_DELAY_RECONNECT = 2000; // bridge restarts are usually fast
+  const PROBE_BACKOFF_FACTOR = 3;
+  const PROBE_DELAY_MAX = 300000;
+  let probeDelay = PROBE_DELAY_INITIAL;
   let eventCount = 0;
-  let hasLoggedDisconnect = false;
-  let reconnectAttempts = 0;
+  let hasLoggedMissingBridge = false;
+  let hasShownBanner = false;
   let unsubscribeFn = null;
   let flushEventBatch = null; // Hoisted — set during subscription, called by set-signal
   let discoveredToken = token;
   let discoveredPort = port;
 
-  // Startup banner
-  console.log(
-    '%c⚡ What DevTools MCP %c Client v0.2.0',
-    'background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;padding:4px 10px;border-radius:4px;font-weight:bold;font-size:13px',
-    'color:#a855f7;font-weight:bold'
-  );
-
-  // --- Token Auto-Discovery ---
-  // If no token is provided, try to discover it from the bridge's HTTP endpoint.
-  // The bridge serves GET http://localhost:{port+1}/__what_mcp_token
-  async function discoverToken() {
-    if (discoveredToken) return true; // Already have a token
-
-    const discoveryPort = port + 1;
+  // --- Quiet bridge probe (also discovers the token) ---
+  // We NEVER open a WebSocket until this HTTP probe succeeds. A failed
+  // WebSocket connection always prints an unsuppressible red error in the
+  // browser console; a failed fetch wrapped in catch() prints at most a single
+  // muted "Failed to load resource" network line — the quietest probe the
+  // platform allows.
+  //
+  // Two probe modes:
+  //
+  // 1. Same-origin discovery (preferred — `discoveryUrl`, set by the Vite
+  //    plugin): the dev server proxies the bridge probe Node-side, so a
+  //    missing bridge produces ZERO console output — the dev server itself is
+  //    up, so there is no network-layer ERR_CONNECTION_REFUSED line either.
+  //
+  // 2. Direct probe of GET http://localhost:{port+1}/__what_mcp_token
+  //    (loopback-origin gated; a 200 means the bridge is up AND returns the
+  //    token + actual WS port in one round-trip). Even wrapped in catch(),
+  //    the browser's network layer logs net::ERR_CONNECTION_REFUSED for every
+  //    failed attempt — unsuppressible from JS — so this mode only runs when
+  //    a bridge is actually expected (explicit token, or the
+  //    window.__WHAT_DEVTOOLS_DEBUG__ flag). See `pollEnabled` below.
+  //
+  // Trade-off (direct mode): if the discovery HTTP port (port+1) is occupied
+  // by another process while the WS port is free, we won't connect even with
+  // an explicit token. That edge case is rarer and cheaper than spamming
+  // every fresh app (the default state: no bridge running) with red WS errors.
+  async function probeBridge() {
+    if (discoveryUrl) {
+      try {
+        const res = await fetch(discoveryUrl, { cache: 'no-store' });
+        if (res.ok) {
+          const data = await res.json();
+          if (!data.bridge) return false;
+          if (data.token) discoveredToken = data.token;
+          discoveredPort = data.wsPort || port;
+          return true;
+        }
+      } catch {
+        // Dev server unreachable (page about to die) — stay quiet.
+      }
+      return false;
+    }
     try {
-      const res = await fetch(`http://localhost:${discoveryPort}/__what_mcp_token`);
+      const res = await fetch(`http://localhost:${port + 1}/__what_mcp_token`, { cache: 'no-store' });
       if (res.ok) {
         const data = await res.json();
-        discoveredToken = data.token;
+        if (data.token) discoveredToken = data.token;
         discoveredPort = data.wsPort || port;
-        log('MCP', BADGE, `Token discovered automatically from bridge`);
         return true;
       }
     } catch {
-      // Discovery endpoint not available — bridge may not be running yet
+      // Bridge not running — stay quiet; back-off handles retries.
     }
     return false;
   }
 
-  log('MCP', BADGE, `Connecting to bridge on ws://localhost:${port}`);
+  async function tryConnect() {
+    if (stopped) return;
+    const bridgeUp = await probeBridge();
+    if (stopped) return;
+    if (!bridgeUp) {
+      if (!hasLoggedMissingBridge) {
+        hasLoggedMissingBridge = true;
+        // Single muted line — the ONLY console-API message a fresh app sees.
+        console.info(
+          '%c[what]%c devtools bridge not detected — start what-devtools-mcp to enable agent debugging (retrying quietly in background)',
+          DIM, DIM
+        );
+      }
+      scheduleProbe();
+      return;
+    }
+    openSocket();
+  }
+
+  function scheduleProbe() {
+    if (probeTimer || stopped) return;
+    probeTimer = setTimeout(() => {
+      probeTimer = null;
+      probeDelay = Math.min(probeDelay * PROBE_BACKOFF_FACTOR, PROBE_DELAY_MAX);
+      tryConnect();
+    }, probeDelay);
+  }
 
-  function connect() {
-    reconnectAttempts++;
+  function openSocket() {
     try {
       const tokenParam = discoveredToken ? `?token=${encodeURIComponent(discoveredToken)}` : '';
       ws = new WebSocket(`ws://localhost:${discoveredPort}${tokenParam}`);
     } catch {
-      if (reconnectAttempts <= 1) {
-        log('MCP', BADGE_WARN, 'Bridge not available — retrying silently in background');
-      }
-      scheduleReconnect();
+      scheduleProbe();
       return;
     }
 
     ws.onopen = () => {
       connected = true;
-      reconnectDelay = 1000;
-      hasLoggedDisconnect = false;
-      reconnectAttempts = 0;
+      probeDelay = PROBE_DELAY_RECONNECT;
+      hasLoggedMissingBridge = false;
+      if (!hasShownBanner) {
+        hasShownBanner = true;
+        // Banner only once we KNOW the bridge exists — silent otherwise.
+        console.log(
+          '%c⚡ What DevTools MCP %c Client v0.2.0',
+          'background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;padding:4px 10px;border-radius:4px;font-weight:bold;font-size:13px',
+          'color:#a855f7;font-weight:bold'
+        );
+      }
       log('MCP', BADGE, '🟢 Connected to bridge — AI agent can now inspect this app');
 
       // Send initial snapshot
@@ -151,11 +214,12 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
     ws.onclose = () => {
       const wasConnected = connected;
       connected = false;
-      if (wasConnected && !hasLoggedDisconnect) {
-        hasLoggedDisconnect = true;
-        log('MCP', BADGE_WARN, '🔴 Disconnected from bridge — will reconnect silently');
+      if (wasConnected) {
+        log('MCP', BADGE_WARN, '🔴 Disconnected from bridge — will reconnect quietly in background');
+        // Bridge restarts are usually quick — retry fast, then back off.
+        probeDelay = PROBE_DELAY_RECONNECT;
       }
-      scheduleReconnect();
+      scheduleProbe();
     };
 
     ws.onerror = () => {
@@ -294,47 +358,62 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
     }
   }
 
-  function scheduleReconnect() {
-    if (reconnectTimer) return;
-    // After 5 failures, go very slow (30s) to avoid console spam
-    if (reconnectAttempts === 5 && !hasLoggedDisconnect) {
-      log('MCP', BADGE_WARN, `Bridge not available — will retry every 30s. Start the MCP server to connect.`);
-      hasLoggedDisconnect = true;
-    }
-    const delay = reconnectAttempts >= 5 ? MAX_RECONNECT_DELAY : reconnectDelay;
-    reconnectTimer = setTimeout(async () => {
-      reconnectTimer = null;
-      reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
-      // Try to discover token before each reconnect attempt
-      // (bridge may have started since last attempt)
-      await discoverToken();
-      connect();
-    }, delay);
-  }
-
   function disconnect() {
+    stopped = true;
     if (unsubscribeFn) {
       unsubscribeFn();
       unsubscribeFn = null;
     }
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer);
-      reconnectTimer = null;
+    if (probeTimer) {
+      clearTimeout(probeTimer);
+      probeTimer = null;
     }
     if (ws) {
       ws.onclose = null; // prevent reconnect
       ws.close();
       ws = null;
     }
+    if (connected) log('MCP', BADGE, 'Disconnected');
     connected = false;
-    log('MCP', BADGE, 'Disconnected');
   }
 
-  // Initial connect — try token discovery first, then connect
-  discoverToken().then(() => connect());
+  // Manual retry escape hatch — resets the back-off and probes immediately.
+  // Useful when the dev just started the bridge and doesn't want to wait
+  // out the back-off (or reload the page). Also the opt-in for clients that
+  // start dormant (see pollEnabled below).
+  function reconnect() {
+    if (stopped || connected) return;
+    if (probeTimer) {
+      clearTimeout(probeTimer);
+      probeTimer = null;
+    }
+    probeDelay = PROBE_DELAY_INITIAL;
+    tryConnect();
+  }
+  if (typeof window !== 'undefined') {
+    window.__WHAT_MCP_RECONNECT__ = reconnect;
+  }
+
+  // Direct cross-origin polling logs net::ERR_CONNECTION_REFUSED from the
+  // browser's network layer on every attempt when no bridge runs — JS cannot
+  // suppress it, and a fresh scaffold (no bridge) saw that on every load.
+  // So without a same-origin discoveryUrl, only poll when a bridge is
+  // actually expected: an explicit token was provided, or the developer set
+  // window.__WHAT_DEVTOOLS_DEBUG__ = true. Otherwise stay dormant — zero
+  // network traffic, zero console output — until reconnect() opts in
+  // (window.__WHAT_MCP_RECONNECT__() from the console works too).
+  const pollEnabled = Boolean(
+    discoveryUrl
+    || token
+    || (typeof window !== 'undefined' && window.__WHAT_DEVTOOLS_DEBUG__)
+  );
+
+  // Initial attempt — quiet probe first; WebSocket only if the bridge answers.
+  if (pollEnabled) tryConnect();
 
   return {
     disconnect,
+    reconnect,
     get isConnected() { return connected; },
     get eventCount() { return eventCount; },
   };

package/src/index.js

@@ -4,18 +4,52 @@
  * Creates WS bridge, registers tools + resources, connects MCP stdio transport.
  */
 
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createBridge } from './bridge.js';
 import { registerTools } from './tools.js';
 
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+
+// --help / --version must print and exit BEFORE any server starts — this bin
+// otherwise opens a WebSocket bridge + discovery HTTP server and blocks on
+// the MCP stdio transport, which made `what-devtools-mcp --help` hang.
+const cliArgs = process.argv.slice(2);
+if (cliArgs.includes('--help') || cliArgs.includes('-h')) {
+  console.log(`what-devtools-mcp ${pkg.version} — MCP server bridging AI agents to live What Framework app state
+
+Usage:
+  what-devtools-mcp [flags]
+
+Runs an MCP server on stdio (add it to your MCP client config) plus a local
+WebSocket bridge the browser devtools client connects to.
+
+Flags:
+  -h, --help       Show this help and exit
+  -v, --version    Print the version and exit
+  --unsafe-eval    Enable the what_eval tool (arbitrary JS in the browser — dev only)
+
+Environment:
+  WHAT_MCP_PORT      WebSocket bridge port (default: 9229; token discovery on port+1)
+  WHAT_MCP_TOKEN     Pre-shared auth token (default: random per run)
+  WHAT_UNSAFE_EVAL   Set to 1/true to enable what_eval (same as --unsafe-eval)
+
+Docs: https://whatfw.com`);
+  process.exit(0);
+}
+if (cliArgs.includes('--version') || cliArgs.includes('-v')) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
 const port = parseInt(process.env.WHAT_MCP_PORT || '9229', 10);
 
 const bridge = createBridge({ port });
 
 const server = new McpServer({
   name: 'what-devtools-mcp',
-  version: '0.2.0',
+  version: pkg.version,
 });
 
 registerTools(server, bridge);
@@ -1033,7 +1067,7 @@ server.prompt(
         type: 'text',
         text: `# WhatFW MCP DevTools — Quick Reference
 
-You have access to 28 MCP tools for inspecting and debugging a live What Framework app running in the browser.
+You have access to 29 MCP tools for inspecting and debugging a live What Framework app running in the browser.
 
 ## Connection Check
 Always start with: \`what_connection_status\` — confirms the browser is connected and shows signal/effect/component counts.

package/src/tools-extended.js

@@ -434,9 +434,16 @@ export function registerExtendedTools(server, bridge) {
       const segments = trimmed.split('.');
       const isSimpleIdent = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
       const PROTO_DENYLIST = new Set(['constructor', 'prototype', '__proto__']);
+      // Sensitive property paths: reads that exfiltrate secrets/state must
+      // require the explicit unsafe flag (document.cookie, window.localStorage,
+      // navigator.credentials...). Mirror of SENSITIVE_PATHS in client-commands.js.
+      const SENSITIVE_PATHS = new Set([
+        'cookie', 'localStorage', 'sessionStorage', 'indexedDB', 'credentials',
+        'geolocation', 'clipboard', 'serviceWorker', 'caches', 'opener',
+      ]);
       const isSafeRead = segments.length >= 2 &&
         SAFE_GLOBALS.has(segments[0]) &&
-        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s));
+        segments.every(s => isSimpleIdent.test(s) && !PROTO_DENYLIST.has(s) && !SENSITIVE_PATHS.has(s));
 
       if (!unsafeEvalEnabled && !isSafeRead) {
         return errorResponse(

package/src/vite-plugin.js

@@ -41,11 +41,46 @@ const RESOLVED_BOOTSTRAP_ID = '\0' + VIRTUAL_BOOTSTRAP_ID;
 // Vite encodes `\0` as `__x00__` in `/@id/` URLs — stable since Vite 2 (2021).
 const BROWSER_BOOTSTRAP_URL = '/@id/__x00__' + VIRTUAL_BOOTSTRAP_ID;
 
+// Same-origin discovery endpoint served by the dev server (see configureServer).
+// The browser polls THIS instead of the bridge's cross-origin port directly:
+// a failed cross-origin fetch logs net::ERR_CONNECTION_REFUSED in the console
+// on every fresh scaffold (no bridge running) — unsuppressible from JS. The
+// dev server itself is always up while the page is open, so polling it never
+// produces console noise; the bridge probe happens Node-side instead.
+export const DISCOVERY_PATH = '/__what_mcp_discovery';
+
 export default function whatDevToolsMCP({ port = 9229, token = '' } = {}) {
   return {
     name: 'what-devtools-mcp',
     apply: 'serve',
 
+    // Node-side bridge probe, exposed same-origin to the browser client.
+    // Responds { bridge: false } when no bridge is running (quietly), or
+    // { bridge: true, token, wsPort } when it is — one round-trip discovery.
+    configureServer(server) {
+      server.middlewares.use(DISCOVERY_PATH, async (req, res) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        try {
+          const probe = await fetch(`http://127.0.0.1:${port + 1}/__what_mcp_token`, {
+            signal: AbortSignal.timeout(1000),
+          });
+          if (probe.ok) {
+            const data = await probe.json();
+            res.end(JSON.stringify({
+              bridge: true,
+              token: data.token || '',
+              wsPort: data.wsPort || port,
+            }));
+            return;
+          }
+        } catch {
+          // Bridge not running — the normal state for a fresh scaffold.
+        }
+        res.end(JSON.stringify({ bridge: false }));
+      });
+    },
+
     // Resolve the virtual module so Vite knows we own it.
     resolveId(id) {
       if (id === VIRTUAL_BOOTSTRAP_ID || id === RESOLVED_BOOTSTRAP_ID) {
@@ -66,7 +101,7 @@ export default function whatDevToolsMCP({ port = 9229, token = '' } = {}) {
         `import { installDevTools } from 'what-devtools';`,
         `import { connectDevToolsMCP } from 'what-devtools-mcp/client';`,
         `installDevTools(core);`,
-        `connectDevToolsMCP({ port: ${port}, token: ${JSON.stringify(tokenValue)} });`,
+        `connectDevToolsMCP({ port: ${port}, token: ${JSON.stringify(tokenValue)}, discoveryUrl: ${JSON.stringify(DISCOVERY_PATH)} });`,
       ].join('\n');
     },