what-devtools-mcp 0.11.0 → 0.11.2

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.11.0",
+  "version": "0.11.2",
   "description": "MCP server bridging AI agents to live What Framework app state via WebSocket",
   "type": "module",
   "bin": {

package/src/client.js

@@ -21,7 +21,7 @@ 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() {}, reconnect() {}, isConnected: false, eventCount: 0 };
@@ -57,15 +57,43 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
   // 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. The bridge serves GET http://localhost:{port+1}/__what_mcp_token
-  // (loopback-origin gated), so a 200 here means the bridge is up AND gives us
-  // the token + actual WS port in one round-trip.
+  // platform allows.
   //
-  // Trade-off: 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.
+  // 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:${port + 1}/__what_mcp_token`, { cache: 'no-store' });
       if (res.ok) {
@@ -351,7 +379,8 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
 
   // 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).
+  // 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) {
@@ -365,8 +394,22 @@ export function connectDevToolsMCP({ port = 9229, token = '' } = {}) {
     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.
-  tryConnect();
+  if (pollEnabled) tryConnect();
 
   return {
     disconnect,

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);

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');
     },