browser-debug-mcp-bridge 1.1.0

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "browser-debug-mcp-bridge",
+  "version": "1.1.0",
+  "description": "Chrome Extension + Node.js MCP server for browser debugging",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "scripts/mcp-start.cjs",
+    "apps/mcp-server/dist/**/*",
+    "apps/mcp-server/package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "browser-debug-mcp-bridge": "scripts/mcp-start.cjs"
+  },
+  "scripts": {
+    "typecheck": "nx run-many -t lint --projects mcp-server,chrome-extension,shared,redaction,selectors,mcp-contracts",
+    "test": "nx run-many -t test",
+    "lint": "nx run-many -t lint",
+    "build": "nx run-many -t build",
+    "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",
+    "build:mcp-runtime": "pnpm -C apps/mcp-server build",
+    "prepack": "pnpm run build:mcp-runtime",
+    "docs:dev": "nx serve docs",
+    "docs:build": "nx build docs",
+    "docs:lint": "nx lint docs",
+    "docs:ci": "nx run docs:ci",
+    "gha:list": "act -l",
+    "gha:dry-run": "act -n",
+    "gha:ci": "act push -W .github/workflows/ci.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "gha:docs": "act push -W .github/workflows/docs-pages.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "gha:nightly": "act schedule -W .github/workflows/nightly-health.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "gha:release": "act workflow_dispatch -W .github/workflows/release.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "gha:release-please": "act workflow_dispatch -W .github/workflows/release-please.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "gha:dependency-update": "act workflow_dispatch -W .github/workflows/dependency-update.yml -P ubuntu-latest=catthehacker/ubuntu:full-latest",
+    "release:tag": "node tools/release/create-tag.mjs",
+    "release:tag:dry": "node tools/release/create-tag.mjs --dry-run --yes",
+    "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"
+  },
+  "keywords": [
+    "mcp",
+    "chrome-extension",
+    "debugging"
+  ],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@nx/vite": "^22.4.5",
+    "@types/chrome": "^0.1.36",
+    "@types/node": "^20.19.33",
+    "@types/react": "^18.3.24",
+    "@types/react-dom": "^18.3.7",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@easyops-cn/docusaurus-search-local": "^0.53.0",
+    "@mdx-js/react": "^3.1.1",
+    "jsdom": "^28.0.0",
+    "markdownlint-cli2": "^0.18.1",
+    "nx": "^20.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.3.0",
+    "vite": "^7.3.1",
+    "vitest": "^1.6.1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "fastify": "^4.28.0",
+    "jszip": "^3.10.1",
+    "tsx": "^4.20.5",
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  }
+}

package/scripts/mcp-start.cjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+const { spawn } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const { dirname, join, resolve } = require('node:path');
+const { createRequire } = require('node:module');
+const net = require('node:net');
+
+const repoRoot = resolve(__dirname, '..');
+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');
+const mcpBridgeEntry = join(repoRoot, 'apps', 'mcp-server', 'src', 'mcp-bridge.ts');
+const mainServerEntry = join(repoRoot, 'apps', 'mcp-server', 'src', 'main.ts');
+const args = process.argv.slice(2);
+const useTsx = args.includes('--mode=tsx');
+const useDist = args.includes('--mode=dist');
+const dryRun = args.includes('--dry-run');
+const standalone = args.includes('--standalone');
+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';
+
+function resolveRuntimePath(specifier) {
+  try {
+    return localRequire.resolve(specifier);
+  } catch {
+    return '';
+  }
+}
+
+function resolveFromPackage(packageName, relativePath) {
+  const packageJsonPath = resolveRuntimePath(`${packageName}/package.json`);
+  if (!packageJsonPath) return '';
+  const candidate = join(dirname(packageJsonPath), relativePath);
+  return existsSync(candidate) ? candidate : '';
+}
+
+function resolveBinFallback(name) {
+  const cmdSuffix = process.platform === 'win32' ? '.cmd' : '';
+  const candidate = join(repoRoot, 'node_modules', '.bin', `${name}${cmdSuffix}`);
+  return existsSync(candidate) ? candidate : '';
+}
+
+const nxBin =
+  resolveRuntimePath('nx/bin/nx.js') ||
+  resolveFromPackage('nx', 'bin/nx.js') ||
+  resolveBinFallback('nx');
+
+const tsxCli =
+  resolveRuntimePath('tsx/dist/cli.mjs') ||
+  resolveFromPackage('tsx', 'dist/cli.mjs') ||
+  resolveBinFallback('tsx');
+
+function isPortInUse(port, host = '127.0.0.1') {
+  return new Promise((resolvePort) => {
+    const server = net.createServer();
+    server.once('error', (error) => {
+      if (error && error.code === 'EADDRINUSE') {
+        resolvePort(true);
+        return;
+      }
+      resolvePort(false);
+    });
+    server.once('listening', () => {
+      server.close(() => resolvePort(false));
+    });
+    server.listen(port, host);
+  });
+}
+
+if (!existsSync(packageJson)) {
+  process.stderr.write(`[mcp-start] Invalid repository root: ${repoRoot}\n`);
+  process.exit(1);
+}
+
+function spawnRuntime(runtime) {
+  const nxTarget = standalone ? 'mcp-server:serve' : 'mcp-server:serve-mcp';
+  const entryScript =
+    runtime === 'dist'
+      ? standalone
+        ? mainServerDistEntry
+        : mcpBridgeDistEntry
+      : standalone
+        ? mainServerEntry
+        : mcpBridgeEntry;
+
+  if (dryRun) {
+    process.stderr.write(`[mcp-start] Dry run mode. Selected runtime: ${runtime}\n`);
+    if (runtime === 'nx') {
+      process.stderr.write(`[mcp-start] Command: node ${nxBin} run ${nxTarget}\n`);
+    } else if (runtime === 'dist') {
+      process.stderr.write(`[mcp-start] Command: node ${entryScript}\n`);
+    } else {
+      process.stderr.write(`[mcp-start] Command: node ${tsxCli} ${entryScript}\n`);
+    }
+    process.exit(0);
+  }
+
+  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).`;
+  process.stderr.write(`${supportsColor ? `${greenBackground}${startedMessage}${ansiReset}` : startedMessage}\n`);
+  if (!standalone && process.stdin.isTTY) {
+    process.stderr.write(
+      '[mcp-start] Running from interactive terminal without MCP host. ' +
+      'Use --standalone for manual keep-alive testing.\n',
+    );
+  }
+
+  const child =
+    runtime === 'nx'
+      ? spawn(
+          nxBin.endsWith('.cmd') ? nxBin : process.execPath,
+          nxBin.endsWith('.cmd') ? ['run', nxTarget] : [nxBin, 'run', nxTarget],
+          {
+            cwd: repoRoot,
+            env: { ...process.env },
+            stdio: 'inherit',
+          },
+        )
+      : runtime === 'dist'
+        ? spawn(process.execPath, [entryScript], {
+            cwd: repoRoot,
+            env: { ...process.env },
+            stdio: 'inherit',
+          })
+        : spawn(
+            tsxCli.endsWith('.cmd') ? tsxCli : process.execPath,
+            tsxCli.endsWith('.cmd') ? [entryScript] : [tsxCli, entryScript],
+            {
+              cwd: repoRoot,
+              env: { ...process.env },
+              stdio: 'inherit',
+            },
+          );
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    if (!standalone && process.stdin.isTTY && (code ?? 0) === 0) {
+      process.stderr.write(
+        '[mcp-start] MCP stdio process exited (no MCP host attached). ' +
+        'Use --standalone to keep the local server running in a terminal.\n',
+      );
+    }
+    process.exit(code ?? 0);
+  });
+
+  child.on('error', (error) => {
+    process.stderr.write(
+      `[mcp-start] Failed to launch MCP bridge with ${runtime}. ` +
+      `Ensure dependencies are installed. ${error.message}\n`,
+    );
+    process.exit(1);
+  });
+}
+
+async function main() {
+  const port = Number(process.env.PORT || '8065');
+  if (Number.isFinite(port)) {
+    const inUse = await isPortInUse(port);
+    if (inUse) {
+      process.stderr.write(
+        `[mcp-start] Port ${port} is already in use. Another Browser Debug MCP Bridge instance is likely running.\n`,
+      );
+      process.stderr.write(
+        '[mcp-start] Stop the existing process, or run this instance on a different port.\n',
+      );
+      if (process.platform === 'win32') {
+        process.stderr.write(
+          '[mcp-start] Windows help: netstat -ano | findstr :8065\n',
+        );
+      }
+      process.stderr.write(
+        '[mcp-start] Example with different port: PORT=8070 browser-debug-mcp-bridge --standalone\n',
+      );
+      process.exit(1);
+    }
+  }
+
+  if (useDist) {
+    if (!existsSync(mcpBridgeDistEntry) || !existsSync(mainServerDistEntry)) {
+      process.stderr.write(
+        '[mcp-start] Missing dist runtime. Build mcp-server first (pnpm nx build mcp-server).\n',
+      );
+      process.exit(1);
+    }
+    spawnRuntime('dist');
+    return;
+  }
+
+  if (useTsx) {
+    if (!existsSync(tsxCli)) {
+      process.stderr.write('[mcp-start] Missing tsx runtime. Run npm install/pnpm install first.\n');
+      process.exit(1);
+    }
+    spawnRuntime('tsx');
+    return;
+  }
+
+  if (existsSync(mcpBridgeDistEntry) && existsSync(mainServerDistEntry)) {
+    spawnRuntime('dist');
+    return;
+  }
+
+  if (existsSync(nxBin)) {
+    spawnRuntime('nx');
+    return;
+  }
+
+  if (!existsSync(tsxCli)) {
+    process.stderr.write(
+      '[mcp-start] Missing both nx and tsx runtimes. ' +
+      'Install dependencies first (npm install or pnpm install).\n',
+    );
+    process.exit(1);
+  }
+
+  process.stderr.write('[mcp-start] nx runtime not found, using tsx fallback runtime.\n');
+  spawnRuntime('tsx');
+}
+
+main().catch((error) => {
+  process.stderr.write(`[mcp-start] Startup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});