browser-bridge-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mukesh Bishnoi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# browser-bridge-mcp
+
+Give [Claude Code](https://docs.anthropic.com/en/docs/claude-code) direct access to your browser — console logs, network requests, JS errors, storage, DOM, and more.
+
+## How it works
+
+```
+Browser <──WebSocket──> MCP Server <──stdio──> Claude Code
+```
+
+A small client script runs in your browser tab, hooks into console, fetch, XHR, and error events, and streams everything to an MCP server that Claude Code can query.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -D browser-bridge-mcp
+```
+
+### 2. Register with Claude Code
+
+```bash
+# User scope (just you)
+npx browser-bridge-mcp setup
+
+# Project scope (whole team via .mcp.json)
+npx browser-bridge-mcp setup --scope project
+```
+
+### 3. Connect your app (pick one)
+
+**Next.js** — add to `next.config.mjs` (or `.ts`):
+
+```js
+import { withBrowserBridge } from 'browser-bridge-mcp/next';
+
+// Wrap your config — no-op in production
+export default withBrowserBridge(nextConfig);
+```
+
+**Vite** — add to `vite.config.js`:
+
+```js
+import { browserBridge } from 'browser-bridge-mcp/vite';
+
+export default defineConfig({
+  plugins: [browserBridge()],
+});
+```
+
+**Any page** (bookmarklet / console paste):
+
+```bash
+npx browser-bridge-mcp bookmarklet   # generates clickable bookmarklet HTML
+npx browser-bridge-mcp snippet       # prints client.js to stdout
+```
+
+### 4. Use it
+
+Restart Claude Code, run your dev server, done. Claude can now see everything in your browser.
+
+## What Claude Can See
+
+| Tool | Description |
+|------|-------------|
+| `browser_get_console_logs` | Console output (log, warn, error, info, debug) |
+| `browser_get_network_requests` | Fetch/XHR with status, timing, headers, body |
+| `browser_get_errors` | JS errors and unhandled promise rejections |
+| `browser_get_local_storage` | Read localStorage |
+| `browser_get_session_storage` | Read sessionStorage |
+| `browser_get_cookies` | Read cookies |
+| `browser_get_page_info` | URL, title, viewport, scroll position |
+| `browser_execute_js` | Run arbitrary JS in the page |
+| `browser_get_redux_state` | Redux store state |
+| `browser_get_react_query_cache` | React Query cache |
+| `browser_get_performance` | Page load timing, memory, resources |
+| `browser_get_dom_snapshot` | DOM tree snapshot (CSS selector targeted) |
+| `browser_list_connections` | List connected tabs |
+| `browser_focus_tab` | Focus a specific tab for queries |
+| `browser_clear_all` | Clear all event buffers |
+
+## Multi-Tab Support
+
+Connect multiple browser tabs simultaneously. Use `browser_focus_tab` to switch which tab Claude is actively querying. The focused tab gets a blue badge; other connected tabs get a gray badge.
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BROWSER_BRIDGE_PORT` | `8089` | WebSocket server port |
+| `BROWSER_BRIDGE_HTTP_PORT` | `8090` | HTTP server port (serves client.js) |
+
+Browser-side (set before client.js loads):
+
+```js
+window.__BRIDGE_PORT = 8089;           // WebSocket port
+window.__BRIDGE_LABEL = "my-tab";      // Custom tab label
+window.__BRIDGE_CAPTURE_BODIES = true; // Capture request/response bodies
+window.__BRIDGE_MAX_BODY_SIZE = 10000; // Max body size in chars
+```
+
+## Framework Plugins
+
+All plugins are **dev-only** and **no-op in production**.
+
+### Next.js
+
+```js
+import { withBrowserBridge } from 'browser-bridge-mcp/next';
+export default withBrowserBridge(nextConfig);
+// Composes with other wrappers:
+// export default withSentryConfig(withBrowserBridge(nextConfig), sentryOptions);
+```
+
+### Vite
+
+```js
+import { browserBridge } from 'browser-bridge-mcp/vite';
+export default defineConfig({ plugins: [browserBridge()] });
+```
+
+### Express / Connect
+
+```js
+import { browserBridgeMiddleware } from 'browser-bridge-mcp/middleware';
+app.use(browserBridgeMiddleware());
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx browser-bridge-mcp setup` | Register MCP server with Claude Code |
+| `npx browser-bridge-mcp setup --scope project` | Add to `.mcp.json` (team-wide) |
+| `npx browser-bridge-mcp bookmarklet` | Generate bookmarklet HTML file |
+| `npx browser-bridge-mcp snippet` | Print client.js to stdout |
+| `npx browser-bridge-mcp serve` | Start server manually (debugging) |
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+/**
+ * Browser Bridge MCP — CLI
+ *
+ * Commands:
+ *   setup              Register MCP server with Claude Code (user scope)
+ *   setup --scope project  Register in .mcp.json (project scope, git-committed)
+ *   bookmarklet        Generate bookmarklet.html and open it
+ *   snippet            Print client.js to stdout for console paste
+ *   serve              Start the MCP server manually (for debugging)
+ *   (default)          Start MCP server via stdio (used by Claude Code)
+ */
+
+import { execSync } from "child_process";
+import { readFileSync, writeFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "..");
+const CLIENT_PATH = join(ROOT, "src", "client.js");
+
+const command = process.argv[2];
+
+switch (command) {
+  case "setup":
+    setup();
+    break;
+  case "bookmarklet":
+    bookmarklet();
+    break;
+  case "snippet":
+    snippet();
+    break;
+  case "serve":
+    serve();
+    break;
+  default:
+    // Default: start the MCP server (this is what Claude Code invokes via stdio)
+    await import("../src/server.mjs");
+    break;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function setup() {
+  const scopeFlag = process.argv.includes("--scope") && process.argv[process.argv.indexOf("--scope") + 1] === "project";
+
+  if (scopeFlag) {
+    // Project-scope: write .mcp.json
+    const mcpConfig = {
+      mcpServers: {
+        "browser-bridge": {
+          command: "npx",
+          args: ["-y", "browser-bridge-mcp"],
+        },
+      },
+    };
+
+    const mcpPath = join(process.cwd(), ".mcp.json");
+    let existing = {};
+    try {
+      existing = JSON.parse(readFileSync(mcpPath, "utf-8"));
+    } catch {
+      // File doesn't exist yet
+    }
+
+    existing.mcpServers = existing.mcpServers || {};
+    existing.mcpServers["browser-bridge"] = mcpConfig.mcpServers["browser-bridge"];
+
+    writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + "\n");
+    console.log("✓ Added browser-bridge to .mcp.json (project scope)");
+    console.log("  Commit .mcp.json so your team gets it automatically.");
+  } else {
+    // User-scope: use claude mcp add
+    try {
+      execSync(
+        'claude mcp add browser-bridge --transport stdio -- npx -y browser-bridge-mcp',
+        { stdio: "inherit" }
+      );
+      console.log("\n✓ Browser Bridge MCP registered with Claude Code");
+      console.log("  Restart Claude Code to activate.");
+    } catch (err) {
+      console.error("Failed to register MCP server. Is Claude Code CLI installed?");
+      console.error("  Try: npx browser-bridge-mcp setup --scope project");
+      process.exit(1);
+    }
+  }
+}
+
+function bookmarklet() {
+  const clientJs = readFileSync(CLIENT_PATH, "utf-8");
+
+  // Basic minification: remove comments and extra whitespace
+  const minified = clientJs
+    .replace(/\/\*[\s\S]*?\*\//g, "")  // block comments
+    .replace(/\/\/.*$/gm, "")          // line comments
+    .replace(/\n\s*\n/g, "\n")         // empty lines
+    .replace(/^\s+/gm, "")            // leading whitespace
+    .trim();
+
+  const bookmarkletUrl = `javascript:${encodeURIComponent(minified)}`;
+
+  const html = `<!DOCTYPE html>
+<html><head><title>Browser Bridge Bookmarklet</title></head>
+<body style="font-family:system-ui;max-width:600px;margin:40px auto;padding:20px;">
+  <h1>Browser Bridge</h1>
+  <p>Drag this link to your bookmarks bar:</p>
+  <p style="font-size:24px;padding:20px;background:#f0f0f0;border-radius:8px;text-align:center;">
+    <a href="${bookmarkletUrl}" style="color:#059669;text-decoration:none;font-weight:bold;">
+      Connect to Claude
+    </a>
+  </p>
+  <p style="color:#666;">Click it on any page to connect that tab to Claude Code's Browser Bridge.</p>
+  <h2>Or paste in console:</h2>
+  <pre style="background:#1e1e1e;color:#d4d4d4;padding:16px;border-radius:8px;overflow-x:auto;font-size:12px;max-height:300px;overflow-y:auto;">${clientJs.replace(/</g, "&lt;").replace(/>/g, "&gt;")}</pre>
+</body></html>`;
+
+  const outPath = join(process.cwd(), "bookmarklet.html");
+  writeFileSync(outPath, html);
+  console.log(`✓ Bookmarklet written to ${outPath}`);
+  console.log(`  (${bookmarkletUrl.length} characters)`);
+
+  // Try to open in browser
+  try {
+    const platform = process.platform;
+    if (platform === "darwin") {
+      execSync(`open "${outPath}"`);
+    } else if (platform === "linux") {
+      execSync(`xdg-open "${outPath}"`);
+    } else if (platform === "win32") {
+      execSync(`start "${outPath}"`);
+    }
+  } catch {
+    console.log("  Open bookmarklet.html in your browser to use it.");
+  }
+}
+
+function snippet() {
+  const clientJs = readFileSync(CLIENT_PATH, "utf-8");
+  process.stdout.write(clientJs);
+}
+
+async function serve() {
+  console.log("Starting Browser Bridge MCP server...");
+  console.log("  WebSocket: ws://127.0.0.1:8089");
+  console.log("  HTTP (client.js): http://127.0.0.1:8090/client.js");
+  console.log("  Press Ctrl+C to stop.\n");
+  await import("../src/server.mjs");
+}

package/middleware.mjs

@@ -0,0 +1,22 @@
+/**
+ * Express/Connect middleware: browserBridgeMiddleware()
+ * Injects the browser bridge client script into HTML responses.
+ * For non-Next/Vite frameworks (Express, Fastify, etc.).
+ */
+export function browserBridgeMiddleware(options = {}) {
+  const httpPort = options.httpPort || 8090;
+  return (req, res, next) => {
+    const originalEnd = res.end;
+    res.end = function (chunk, ...args) {
+      if (res.getHeader("content-type")?.includes("text/html") && chunk) {
+        const html = chunk.toString();
+        chunk = html.replace(
+          "</body>",
+          `<script src="http://127.0.0.1:${httpPort}/client.js" async></script></body>`
+        );
+      }
+      originalEnd.call(this, chunk, ...args);
+    };
+    next();
+  };
+}

package/next.mjs

@@ -0,0 +1,40 @@
+/**
+ * Next.js plugin: withBrowserBridge(nextConfig)
+ * Auto-injects the browser bridge client script in development mode.
+ * Complete no-op in production.
+ */
+export function withBrowserBridge(nextConfig = {}, options = {}) {
+  if (process.env.NODE_ENV !== "development") return nextConfig;
+
+  const httpPort = options.httpPort || 8090;
+
+  return {
+    ...nextConfig,
+    webpack(config, ctx) {
+      // Only inject on client-side build
+      if (!ctx.isServer) {
+        const { BannerPlugin } = ctx.webpack;
+        config.plugins.push(
+          new BannerPlugin({
+            banner: `
+              if (typeof window !== 'undefined' && !window.__browserBridge) {
+                var s = document.createElement('script');
+                s.src = 'http://127.0.0.1:${httpPort}/client.js';
+                s.async = true;
+                s.onerror = function() { console.debug('[BrowserBridge] MCP server not running'); };
+                document.head.appendChild(s);
+              }
+            `,
+            raw: true,
+            entryOnly: true,
+          })
+        );
+      }
+      // Chain with user's webpack config if present
+      if (typeof nextConfig.webpack === "function") {
+        return nextConfig.webpack(config, ctx);
+      }
+      return config;
+    },
+  };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "browser-bridge-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Give Claude Code direct access to your browser - console, network, errors, storage, DOM and more",
+  "author": "Mukesh Bishnoi <mukeshb.work@gmail.com>",
+  "bin": {
+    "browser-bridge-mcp": "./bin/cli.mjs"
+  },
+  "main": "./src/server.mjs",
+  "exports": {
+    ".": "./src/server.mjs",
+    "./next": "./next.mjs",
+    "./vite": "./vite.mjs",
+    "./middleware": "./middleware.mjs",
+    "./client": "./src/client.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "next.mjs",
+    "vite.mjs",
+    "middleware.mjs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "browser",
+    "devtools",
+    "debugging",
+    "console",
+    "network"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mukeshblackhat/browser-bridge-mcp.git"
+  },
+  "homepage": "https://github.com/mukeshblackhat/browser-bridge-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/mukeshblackhat/browser-bridge-mcp/issues"
+  }
+}