browser-debug-mcp-bridge 1.6.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-debug-mcp-bridge",
-  "version": "1.6.0",
+  "version": "1.10.0",
   "description": "Chrome Extension + Node.js MCP server for browser debugging",
   "private": false,
   "publishConfig": {
@@ -19,11 +19,17 @@
   "scripts": {
     "typecheck": "nx run-many -t lint --projects mcp-server,chrome-extension,shared,redaction,selectors,mcp-contracts",
     "test": "nx run-many -t test",
+    "test:non-e2e": "nx run-many -t test --exclude=e2e-playwright",
     "lint": "nx run-many -t lint",
     "build": "nx run-many -t build",
+    "verify:ci": "pnpm typecheck && pnpm lint && pnpm test:non-e2e && pnpm build && pnpm docs:ci && pnpm mcp:check-stdio-guard",
     "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm docs:ci && pnpm mcp:check-stdio-guard",
     "serve": "nx serve mcp-server",
     "mcp:start": "node scripts/mcp-start.cjs",
+    "mcp:diagnose": "node tools/mcp/diagnose-bridge.mjs",
+    "mcp:doctor": "node tools/mcp/diagnose-bridge.mjs",
+    "mcp:doctor:json": "node tools/mcp/diagnose-bridge.mjs --json",
+    "mcp:smoke": "node tools/mcp/diagnose-bridge.mjs --smoke",
     "build:mcp-runtime": "pnpm -C apps/mcp-server build",
     "prepack": "pnpm run build:mcp-runtime",
     "docs:dev": "nx serve docs",
@@ -43,7 +49,11 @@
     "release:tag:yes": "node tools/release/create-tag.mjs --yes",
     "mcp:print-config": "node tools/mcp/print-client-config.mjs",
     "mcp:check-stdio-guard": "node tools/mcp/check-stdio-guard.mjs",
-    "hooks:install": "git config core.hooksPath .githooks && git config commit.template .gitmessage.txt"
+    "hooks:install": "git config core.hooksPath .githooks && git config commit.template .gitmessage.txt",
+    "test:e2e": "nx test e2e-playwright",
+    "test:e2e:head": "node tools/e2e/run-headed-e2e.mjs",
+    "test:e2e:smoke": "nx run e2e-playwright:smoke",
+    "test:e2e:full": "nx run e2e-playwright:full"
   },
   "keywords": [
     "mcp",
@@ -59,17 +69,18 @@
   "devDependencies": {
     "@docusaurus/core": "^3.9.2",
     "@docusaurus/preset-classic": "^3.9.2",
-    "@easyops-cn/docusaurus-search-local": "^0.55.0",
+    "@easyops-cn/docusaurus-search-local": "^0.55.1",
     "@mdx-js/react": "^3.1.1",
     "@nx/vite": "^22.5.2",
+    "@playwright/test": "^1.58.2",
     "@types/chrome": "^0.1.37",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.3",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.0.18",
     "jsdom": "^28.1.0",
     "markdownlint-cli2": "^0.21.0",
-    "nx": "^22.5.2",
+    "nx": "^22.5.3",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "typescript": "^5.9.3",
@@ -77,7 +88,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "better-sqlite3": "^12.6.2",
     "fastify": "^5.7.4",
     "jszip": "^3.10.1",

package/scripts/mcp-start.cjs

@@ -5,8 +5,10 @@ const { dirname, join, resolve } = require('node:path');
 const { createRequire } = require('node:module');
 const net = require('node:net');
 const http = require('node:http');
+const { homedir } = require('node:os');
 
 const repoRoot = resolve(__dirname, '..');
+const runtimeDirName = 'browser-debug-mcp-bridge';
 const packageJson = join(repoRoot, 'package.json');
 const mcpBridgeDistEntry = join(repoRoot, 'apps', 'mcp-server', 'dist', 'mcp-bridge.js');
 const mainServerDistEntry = join(repoRoot, 'apps', 'mcp-server', 'dist', 'main.js');
@@ -22,10 +24,45 @@ const localRequire = createRequire(join(repoRoot, 'package.json'));
 const supportsColor = Boolean(process.stderr.isTTY) && !process.env.NO_COLOR;
 const greenBackground = '\x1b[42m\x1b[30m';
 const ansiReset = '\x1b[0m';
-const launchLockPath = join(process.env.DATA_DIR ? resolve(process.env.DATA_DIR) : join(repoRoot, 'data'), '.mcp-start.lock');
+const resolvedDataDir = resolveRuntimeDataDir();
+const launchLockPath = join(resolvedDataDir, '.mcp-start.lock');
 
 let launchLockHeld = false;
 
+function resolveRuntimeDataDir() {
+  const explicitDataDir = process.env.DATA_DIR && process.env.DATA_DIR.trim();
+  if (explicitDataDir) {
+    return resolve(explicitDataDir);
+  }
+
+  const home = process.env.HOME || homedir();
+
+  if (process.platform === 'win32') {
+    const appDataRoot = process.env.LOCALAPPDATA || process.env.APPDATA;
+    if (appDataRoot) {
+      return resolve(appDataRoot, runtimeDirName);
+    }
+  }
+
+  if (process.platform === 'darwin' && home) {
+    return resolve(home, 'Library', 'Application Support', runtimeDirName);
+  }
+
+  if (process.env.XDG_STATE_HOME) {
+    return resolve(process.env.XDG_STATE_HOME, runtimeDirName);
+  }
+
+  if (process.env.XDG_DATA_HOME) {
+    return resolve(process.env.XDG_DATA_HOME, runtimeDirName);
+  }
+
+  if (home) {
+    return resolve(home, '.local', 'share', runtimeDirName);
+  }
+
+  return resolve(process.cwd(), '.browser-debug-mcp-bridge');
+}
+
 function resolveRuntimePath(specifier) {
   try {
     return localRequire.resolve(specifier);
@@ -181,6 +218,115 @@ function releaseLaunchLock(lockPath) {
   }
 }
 
+function clearLaunchLockForPid(lockPath, pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return;
+  }
+
+  try {
+    const existing = readLaunchLock(lockPath);
+    const lockPid = Number(existing && existing.pid);
+    if (lockPid !== pid) {
+      return;
+    }
+    unlinkSync(lockPath);
+  } catch (error) {
+    if (error && error.code !== 'ENOENT') {
+      process.stderr.write(`[mcp-start] Warning: failed to clear startup lock ${lockPath}.\n`);
+    }
+  }
+}
+
+function isStandaloneLauncherCommand(command) {
+  const normalized = String(command || '').toLowerCase();
+  return (
+    (normalized.includes('scripts\\mcp-start.cjs') || normalized.includes('scripts/mcp-start.cjs'))
+    && normalized.includes('--standalone')
+  );
+}
+
+async function tryRecoverLockedStandaloneForMcpStdio(lockPath) {
+  if (standalone || dryRun || stopRequested) {
+    return false;
+  }
+
+  const existing = readLaunchLock(lockPath);
+  const lockPid = Number(existing && existing.pid);
+  if (!Number.isInteger(lockPid) || lockPid <= 0 || lockPid === process.pid) {
+    return false;
+  }
+
+  if (!isProcessAlive(lockPid) || !isStandaloneLauncherCommand(existing && existing.command)) {
+    return false;
+  }
+
+  process.stderr.write(
+    `[mcp-start] Replacing running standalone launcher (pid ${lockPid}) so MCP stdio can own the bridge runtime.\n`,
+  );
+
+  if (!terminateProcess(lockPid)) {
+    process.stderr.write(`[mcp-start] Failed to terminate standalone launcher ${lockPid}.\n`);
+    process.exit(1);
+  }
+
+  for (let attempt = 0; attempt < 20; attempt++) {
+    await delay(200);
+    if (!isProcessAlive(lockPid)) {
+      break;
+    }
+  }
+
+  if (isProcessAlive(lockPid)) {
+    process.stderr.write(
+      `[mcp-start] Standalone launcher ${lockPid} did not exit after termination request.\n`,
+    );
+    process.exit(1);
+  }
+
+  clearLaunchLockForPid(lockPath, lockPid);
+  return true;
+}
+
+async function tryReplaceExistingBridgeForMcpStdio(port) {
+  if (standalone || dryRun || stopRequested) {
+    return false;
+  }
+
+  const endpointLooksLikeBridge = await isBridgeHttpEndpoint(port);
+  if (!endpointLooksLikeBridge) {
+    return false;
+  }
+
+  const listenerPids = getListeningPids(port).filter((pid) => pid !== process.pid);
+  if (listenerPids.length === 0) {
+    return false;
+  }
+
+  process.stderr.write(
+    `[mcp-start] Replacing existing Browser Debug MCP Bridge listener(s) on port ${port} so MCP stdio can own the runtime.\n`,
+  );
+
+  for (const pid of listenerPids) {
+    if (!terminateProcess(pid)) {
+      process.stderr.write(`[mcp-start] Failed to terminate bridge listener ${pid} on port ${port}.\n`);
+      process.exit(1);
+    }
+  }
+
+  for (let attempt = 0; attempt < 20; attempt++) {
+    await delay(200);
+    const inUse = await isPortInUse(port);
+    if (!inUse) {
+      return true;
+    }
+  }
+
+  process.stderr.write(
+    `[mcp-start] Existing bridge listeners stopped, but port ${port} is still in use.\n`,
+  );
+  process.exit(1);
+}
+
 function getStartupTimeoutMs() {
   const timeoutMs = Number(process.env.MCP_STARTUP_TIMEOUT_MS || '15000');
   if (!Number.isFinite(timeoutMs) || timeoutMs < 1000) {
@@ -264,7 +410,7 @@ function getWindowsProcessCommandLine(pid) {
   const result = spawnSync(
     'powershell.exe',
     ['-NoProfile', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`],
-    { encoding: 'utf8' },
+    { encoding: 'utf8', timeout: 2000 },
   );
 
   if (result.status !== 0) {
@@ -285,7 +431,16 @@ function isLikelyBridgeCommandLine(commandLine) {
 }
 
 function killWindowsProcess(pid) {
-  const result = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8' });
+  const stopResult = spawnSync(
+    'powershell.exe',
+    ['-NoProfile', '-Command', `Stop-Process -Id ${pid} -Force`],
+    { encoding: 'utf8', timeout: 5000 },
+  );
+  if (stopResult.status === 0) {
+    return true;
+  }
+
+  const result = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { encoding: 'utf8', timeout: 5000 });
   return result.status === 0;
 }
 
@@ -477,6 +632,7 @@ if (!existsSync(packageJson)) {
 }
 
 async function spawnRuntime(runtime, port) {
+  const attachExistingBridge = !standalone && process.env.MCP_ATTACH_EXISTING_BRIDGE === '1';
   const nxTarget = standalone ? 'mcp-server:serve' : 'mcp-server:serve-mcp';
   const entryScript =
     runtime === 'dist'
@@ -506,14 +662,24 @@ async function spawnRuntime(runtime, port) {
           nxBin.endsWith('.cmd') ? ['run', nxTarget] : [nxBin, 'run', nxTarget],
           {
             cwd: repoRoot,
-            env: { ...process.env },
+            env: {
+              ...process.env,
+              DATA_DIR: resolvedDataDir,
+              MCP_ATTACH_EXISTING_BRIDGE: attachExistingBridge ? '1' : '',
+              MCP_ATTACH_HTTP_BASE_URL: `http://127.0.0.1:${port}`,
+            },
             stdio: 'inherit',
           },
         )
       : runtime === 'dist'
         ? spawn(process.execPath, [entryScript], {
             cwd: repoRoot,
-            env: { ...process.env },
+            env: {
+              ...process.env,
+              DATA_DIR: resolvedDataDir,
+              MCP_ATTACH_EXISTING_BRIDGE: attachExistingBridge ? '1' : '',
+              MCP_ATTACH_HTTP_BASE_URL: `http://127.0.0.1:${port}`,
+            },
             stdio: 'inherit',
           })
         : spawn(
@@ -521,7 +687,12 @@ async function spawnRuntime(runtime, port) {
             tsxCli.endsWith('.cmd') ? [entryScript] : [tsxCli, entryScript],
             {
               cwd: repoRoot,
-              env: { ...process.env },
+              env: {
+                ...process.env,
+                DATA_DIR: resolvedDataDir,
+                MCP_ATTACH_EXISTING_BRIDGE: attachExistingBridge ? '1' : '',
+                MCP_ATTACH_HTTP_BASE_URL: `http://127.0.0.1:${port}`,
+              },
               stdio: 'inherit',
             },
           );
@@ -604,7 +775,9 @@ async function spawnRuntime(runtime, port) {
   startupFinished = true;
   const startedMessage = standalone
     ? `[mcp-start] Started Browser Debug MCP Bridge (runtime: ${runtime}, mode: standalone). Keep this terminal open.`
-    : `[mcp-start] Started Browser Debug MCP Bridge (runtime: ${runtime}, mode: mcp-stdio).`;
+    : attachExistingBridge
+      ? `[mcp-start] Attached MCP stdio to existing Browser Debug MCP Bridge (runtime: ${runtime}, mode: attach).`
+      : `[mcp-start] Started Browser Debug MCP Bridge (runtime: ${runtime}, mode: mcp-stdio).`;
   process.stderr.write(`${supportsColor ? `${greenBackground}${startedMessage}${ansiReset}` : startedMessage}\n`);
   if (!standalone && process.stdin.isTTY) {
     process.stderr.write(
@@ -612,6 +785,13 @@ async function spawnRuntime(runtime, port) {
       'Use --standalone for manual keep-alive testing.\n',
     );
   }
+
+  if (standalone) {
+    await new Promise((resolve) => {
+      child.once('exit', () => resolve());
+      child.once('close', () => resolve());
+    });
+  }
 }
 
 async function main() {
@@ -626,12 +806,22 @@ async function main() {
     return;
   }
 
-  if (!dryRun) {
-    acquireLaunchLock(launchLockPath);
-    process.on('exit', () => releaseLaunchLock(launchLockPath));
+  let attachExistingBridge = false;
+  if (!standalone && !dryRun) {
+    attachExistingBridge = await isBridgeHttpEndpoint(port);
+    if (attachExistingBridge) {
+      process.env.MCP_ATTACH_EXISTING_BRIDGE = '1';
+      process.stderr.write(
+        `[mcp-start] Found existing Browser Debug MCP Bridge on port ${port}; attaching MCP stdio instead of replacing it.\n`,
+      );
+    }
   }
 
-  if (Number.isFinite(port)) {
+  if (!dryRun && !attachExistingBridge) {
+    await tryRecoverLockedStandaloneForMcpStdio(launchLockPath);
+    await tryReplaceExistingBridgeForMcpStdio(port);
+    acquireLaunchLock(launchLockPath);
+    process.on('exit', () => releaseLaunchLock(launchLockPath));
     let inUse = await isPortInUse(port);
     if (inUse) {
       const recovered = await tryRecoverStaleBridgeOnWindowsPort(port);