agentbridgelens 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# agentbridgelens
+
+MCP server that bridges AI coding agents (Claude Code, etc.) to a **real Chrome browser** via the AgentBridgeLens extension: DOM inspection, screenshots (incl. background tabs), network/console capture, source-map tracing (UI → component source line), visual overlays, action record/replay, and multi-tab targeting.
+
+It runs over MCP stdio and relays tool calls to the browser extension over a local WebSocket.
+
+## Install (recommended: once, globally)
+
+No clone/build needed — run straight from npm via `npx`, registered at **user scope** so every project/session has it:
+
+```bash
+claude mcp add -s user bridgelens -- npx -y agentbridgelens
+```
+
+Or add it to your MCP config manually:
+
+```json
+{
+  "mcpServers": {
+    "bridgelens": { "command": "npx", "args": ["-y", "agentbridgelens"] }
+  }
+}
+```
+
+Then install the **AgentBridgeLens Chrome extension** and open any page. The extension auto-connects to the bridge on `127.0.0.1:19222`.
+
+## Environment variables
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `BRIDGELENS_PORT` | `19222` | WebSocket port |
+| `BRIDGELENS_HOST` | `127.0.0.1` | Bind address. Set `0.0.0.0` for cross-machine (extension on another machine). |
+| `BRIDGELENS_TOKEN` | _(none)_ | Shared secret required from the extension. **Strongly recommended whenever HOST ≠ 127.0.0.1.** |
+
+Single machine needs no env vars. For cross-machine, prefer an SSH tunnel (`ssh -L 19222:127.0.0.1:19222 …`) and keep the bridge on loopback.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/ws-relay.ts
+import { WebSocketServer, WebSocket } from "ws";
+var WsRelay = class {
+  wss;
+  client = null;
+  token;
+  pending = /* @__PURE__ */ new Map();
+  constructor(options) {
+    const host = options.host || "127.0.0.1";
+    this.token = options.token;
+    this.wss = new WebSocketServer({
+      port: options.port,
+      host,
+      // Reject unauthorized clients during the HTTP upgrade, before the WS
+      // handshake completes — so a bad token never reaches an open socket.
+      verifyClient: (info, done) => {
+        if (this.authorize(info.req)) return done(true);
+        console.error(`[BridgeLens] Rejected connection from ${info.req.socket.remoteAddress}: invalid token`);
+        done(false, 401, "Unauthorized");
+      }
+    });
+    this.wss.on("connection", (ws, req) => {
+      this.client = ws;
+      console.error(`[BridgeLens] Extension connected from ${req.socket.remoteAddress}`);
+      const heartbeat = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ t: "ping" }));
+        }
+      }, 2e4);
+      ws.on("message", (raw) => {
+        const msg = JSON.parse(raw.toString());
+        const pending = this.pending.get(msg.id);
+        if (!pending) return;
+        this.pending.delete(msg.id);
+        if (msg.error) {
+          pending.reject(new Error(msg.error.message));
+        } else {
+          pending.resolve(msg.result);
+        }
+      });
+      ws.on("close", () => {
+        clearInterval(heartbeat);
+        this.client = null;
+        console.error(`[BridgeLens] Extension disconnected`);
+        for (const [id, { reject }] of this.pending) {
+          reject(new Error("Extension disconnected"));
+          this.pending.delete(id);
+        }
+      });
+    });
+    const authNote = this.token ? "token required" : "no token";
+    if (host !== "127.0.0.1" && !this.token) {
+      console.error(
+        `[BridgeLens] WARNING: listening on ${host}:${options.port} with no BRIDGELENS_TOKEN \u2014 the browser-control channel is exposed to the network unauthenticated.`
+      );
+    }
+    console.error(`[BridgeLens] WebSocket server listening on ${host}:${options.port} (${authNote})`);
+  }
+  /** Validate the connecting extension's ?token= query against the configured token. */
+  authorize(req) {
+    if (!this.token) return true;
+    let provided = null;
+    try {
+      provided = new URL(req.url ?? "/", "ws://localhost").searchParams.get("token");
+    } catch {
+      provided = null;
+    }
+    return provided === this.token;
+  }
+  get connected() {
+    return this.client?.readyState === WebSocket.OPEN;
+  }
+  async send(tool, params) {
+    if (!this.client || this.client.readyState !== WebSocket.OPEN) {
+      throw new Error(
+        "Chrome extension not connected. Please open Chrome with the AgentBridgeLens extension installed."
+      );
+    }
+    const id = crypto.randomUUID();
+    const request = { id, tool, params };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Tool '${tool}' timed out after 120s`));
+      }, 12e4);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timeout);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timeout);
+          reject(e);
+        }
+      });
+      this.client.send(JSON.stringify(request));
+    });
+  }
+  close() {
+    this.wss.close();
+  }
+};
+
+// src/mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/error-tracer.ts
+import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
+function parseStack(stack) {
+  const frames = [];
+  const re = /(https?:\/\/[^\s)]+?):(\d+):(\d+)/;
+  for (const line of stack.split("\n")) {
+    const m = re.exec(line);
+    if (m) {
+      frames.push({
+        url: m[1],
+        line: parseInt(m[2], 10),
+        column: parseInt(m[3], 10),
+        raw: line.trim()
+      });
+    }
+  }
+  return frames;
+}
+async function loadTraceMap(jsUrl) {
+  const res = await fetch(jsUrl);
+  if (!res.ok) return null;
+  const js = await res.text();
+  const m = /\/\/[#@]\s*sourceMappingURL=(.+?)\s*$/m.exec(js);
+  if (!m) return null;
+  const mapRef = m[1].trim();
+  let rawMap;
+  if (mapRef.startsWith("data:")) {
+    const comma = mapRef.indexOf(",");
+    const meta = mapRef.slice(0, comma);
+    const payload = mapRef.slice(comma + 1);
+    rawMap = meta.includes("base64") ? Buffer.from(payload, "base64").toString("utf8") : decodeURIComponent(payload);
+  } else {
+    const abs = new URL(mapRef, jsUrl).href;
+    const mr = await fetch(abs);
+    if (!mr.ok) return null;
+    rawMap = await mr.text();
+  }
+  return new TraceMap(JSON.parse(rawMap));
+}
+async function traceErrorToSource(stack) {
+  const frames = parseStack(stack);
+  if (frames.length === 0) {
+    return {
+      error: "\u672A\u4ECE\u5806\u6808\u4E2D\u89E3\u6790\u51FA url:line:column \u5F62\u5F0F\u7684\u5E27",
+      hint: "\u8BF7\u4F20\u5165\u5305\u542B\u5B8C\u6574 URL \u7684\u5806\u6808\uFF08\u5982 Chrome \u63A7\u5236\u53F0\u91CC Error.stack \u7684\u5185\u5BB9\uFF09"
+    };
+  }
+  const cache = /* @__PURE__ */ new Map();
+  const resolved = [];
+  for (const f of frames) {
+    if (!cache.has(f.url)) {
+      try {
+        cache.set(f.url, await loadTraceMap(f.url));
+      } catch {
+        cache.set(f.url, null);
+      }
+    }
+    const map = cache.get(f.url) ?? null;
+    if (map) {
+      const pos = originalPositionFor(map, { line: f.line, column: f.column });
+      resolved.push({
+        raw: f.raw,
+        source: pos.source,
+        line: pos.line,
+        column: pos.column,
+        name: pos.name
+      });
+    } else {
+      resolved.push({
+        raw: f.raw,
+        note: "\u65E0 source map\uFF08\u751F\u4EA7\u6784\u5EFA\u672A\u53D1\u5E03 .map\uFF0C\u6216\u6587\u4EF6\u4E0D\u53EF\u8BBF\u95EE\uFF09",
+        url: f.url,
+        line: f.line,
+        column: f.column
+      });
+    }
+  }
+  return { frames: resolved };
+}
+
+// src/mcp-server.ts
+function createMcpServer(relay2) {
+  const server = new McpServer({ name: "AgentBridgeLens", version: "0.1.0" });
+  const TAB = {
+    tabId: z.number().optional().describe("\u76EE\u6807\u6807\u7B7E\u9875 id\uFF08\u6765\u81EA list_tabs\uFF09\u3002\u7701\u7565\u5219\u7528\u5DF2\u56FA\u5B9A\u7684\u76EE\u6807\u6807\u7B7E\u9875\uFF0C\u5426\u5219\u7528\u5F53\u524D\u6FC0\u6D3B\u6807\u7B7E\u9875")
+  };
+  const asText = (result) => ({
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+  });
+  const page = (name, description, schema = {}) => server.tool(name, description, { ...schema, ...TAB }, async (args) => asText(await relay2.send(name, args)));
+  const plain = (name, description, schema = {}) => server.tool(name, description, schema, async (args) => asText(await relay2.send(name, args)));
+  plain("list_tabs", "List all open tabs across all windows (tabId/title/url/active/isTarget/openedByTarget). Multiple tabs can be pinned as targets; operate on any tab by passing its tabId.");
+  plain("set_target_tab", "Pin a tab into the target set (multiple tabs can be pinned). When a tool is called without tabId, the most-recently-active pinned tab is used.", {
+    tabId: z.number().describe("Tab id to pin (from list_tabs)")
+  });
+  plain("get_target_tab", "Get the set of pinned target tabs and which one is the current default (follow-active if none pinned).");
+  plain("clear_target_tab", "Unpin a target tab, or clear all pinned targets if tabId is omitted.", {
+    tabId: z.number().optional().describe("Tab id to unpin. Omit to clear all.")
+  });
+  page("get_page_info", "Get current page URL, title, and meta information");
+  server.tool(
+    "capture_screenshot",
+    "Capture a screenshot of a tab, or crop to a specific element. Background tabs are captured via CDP.",
+    {
+      selector: z.string().optional().describe("CSS selector to capture a specific element (scrolled into view and cropped). Omit for full viewport."),
+      ...TAB
+    },
+    async (args) => {
+      const result = await relay2.send("capture_screenshot", args);
+      const base64 = result.dataUrl.replace(/^data:image\/png;base64,/, "");
+      return { content: [{ type: "image", data: base64, mimeType: "image/png" }] };
+    }
+  );
+  page("execute_js", "Execute a JavaScript expression in the page context and return the result (falls back to CDP on strict-CSP pages)", {
+    code: z.string().describe("JavaScript code to execute in the page context")
+  });
+  page("get_dom_snapshot", "Get a simplified DOM snapshot of the page or a specific subtree", {
+    selector: z.string().optional().describe("CSS selector for subtree root. Omit for full page."),
+    maxDepth: z.number().optional().describe("Maximum depth of DOM tree to capture. Default 6.")
+  });
+  page("inspect_element", "Inspect a DOM element: attributes, computed styles, box model, and text content", {
+    selector: z.string().describe("CSS selector of the element to inspect")
+  });
+  page("get_accessibility_tree", "Get a simplified accessibility tree (roles + accessible names) of the page or a subtree", {
+    selector: z.string().optional().describe("CSS selector for subtree root. Omit for full page."),
+    maxDepth: z.number().optional().describe("Maximum depth to traverse. Default 12.")
+  });
+  page("get_performance_metrics", "Get page performance metrics: navigation timing, FCP, LCP, CLS, JS heap memory");
+  page("trace_element_to_source", "Trace a DOM element back to its source component file and line number (React/Vue dev builds)", {
+    selector: z.string().describe("CSS selector of the element to trace")
+  });
+  page("trace_style_to_source", "Trace which CSS rules apply to an element and which stylesheet they come from", {
+    selector: z.string().describe("CSS selector of the element to trace"),
+    property: z.string().optional().describe("Only return rules that set this CSS property")
+  });
+  server.tool(
+    "trace_error_to_source",
+    "Resolve a JS error stack trace back to original source files/lines via source maps (runs in the bridge, fetches the bundle and .map)",
+    { stack: z.string().describe("The error stack string (e.g. from Error.stack or get_errors output)") },
+    async ({ stack }) => asText(await traceErrorToSource(stack))
+  );
+  page("get_console_logs", "Get captured console log entries from the page", {
+    level: z.enum(["log", "warn", "error", "info", "debug"]).optional().describe("Filter by log level"),
+    limit: z.number().optional().describe("Maximum number of entries to return. Default 50.")
+  });
+  page("get_errors", "Get only error-level console entries (uncaught errors and rejections included)");
+  page("get_network_requests", "Get network requests captured (lightweight; only those after content-script injection)", {
+    urlPattern: z.string().optional().describe("Filter by URL substring"),
+    status: z.number().optional().describe("Filter by HTTP status code")
+  });
+  page("start_cdp_network", "Attach the Chrome debugger to a tab and start capturing full network traffic via CDP. Shows a debugging banner; works per-tab (multiple tabs supported).");
+  page("stop_cdp_network", "Detach the Chrome debugger and stop CDP network capture for a tab");
+  page("get_cdp_network", "Get network requests captured via CDP for a tab (requires start_cdp_network first)", {
+    urlPattern: z.string().optional().describe("Filter by URL substring"),
+    status: z.number().optional().describe("Filter by HTTP status code")
+  });
+  page("mark_elements", "Mark/annotate a set of elements with colored boxes (e.g. to flag changed regions)", {
+    selectors: z.array(z.string()).describe("CSS selectors of elements to mark"),
+    color: z.string().optional().describe("Box color (CSS color). Default '#ff3b30'"),
+    label: z.string().optional().describe("Optional label text shown on each box")
+  });
+  page("visualize_layout", "Outline elements whose content is clipped by overflow (layout debugging)");
+  page("show_responsive_frame", "Overlay a target-viewport-width frame and list elements wider than it (responsive debugging)", {
+    width: z.number().optional().describe("Target viewport width in px. Default 375.")
+  });
+  page("clear_overlays", "Remove all visual overlays (marks / layout / responsive frame)");
+  page("start_recording", "Start recording user interactions (clicks, inputs, scrolls) on a tab");
+  page("stop_recording", "Stop recording and return the captured action sequence");
+  page("replay_actions", "Replay a previously recorded action sequence on a tab", {
+    actions: z.array(z.record(z.string(), z.unknown())).describe("Action sequence, as returned by stop_recording")
+  });
+  page("show_hud", "Show a small on-page HUD panel in the bottom-right corner");
+  page("hide_hud", "Hide the on-page HUD panel");
+  page("update_hud", "Update the HUD status text", {
+    text: z.string().describe("Status text to display in the HUD")
+  });
+  plain(
+    "request_user_confirmation",
+    "Ask the user a question in the side panel and wait for their choice (the AgentBridgeLens side panel must be open).",
+    {
+      message: z.string().describe("The question/prompt shown to the user"),
+      options: z.array(z.string()).optional().describe("Choice buttons. Default ['\u786E\u8BA4', '\u53D6\u6D88']")
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+var WS_PORT = parseInt(process.env.BRIDGELENS_PORT || "19222", 10);
+var WS_HOST = process.env.BRIDGELENS_HOST || "127.0.0.1";
+var WS_TOKEN = process.env.BRIDGELENS_TOKEN || void 0;
+var relay = new WsRelay({ port: WS_PORT, host: WS_HOST, token: WS_TOKEN });
+var mcpServer = createMcpServer(relay);
+var transport = new StdioServerTransport();
+await mcpServer.connect(transport);
+console.error(`[BridgeLens] MCP server started (WS ${WS_HOST}:${WS_PORT})`);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "agentbridgelens",
+  "version": "0.1.0",
+  "description": "MCP server bridging AI coding agents to a real Chrome browser via the AgentBridgeLens extension — DOM inspection, screenshots, network/console capture, source-map tracing, visual overlays, multi-tab targeting.",
+  "type": "module",
+  "bin": {
+    "agentbridgelens": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai-agent",
+    "chrome-extension",
+    "browser",
+    "cdp",
+    "debugging",
+    "source-map"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Erhao/AgentBridgeLens.git",
+    "directory": "packages/bridge"
+  },
+  "homepage": "https://github.com/Erhao/AgentBridgeLens#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch --onSuccess 'node dist/index.js'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsup src/index.ts --format esm --dts"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.25",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/ws": "^8.18.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0"
+  }
+}