claude-browser-bridge 3.0.0 → 3.0.2

package/index.js

@@ -17,14 +17,20 @@ import WebSocket, { WebSocketServer } from "ws";
 
 const PORT = Number(process.env.BRIDGE_PORT) || 8787;
 
-let TOKEN = null;
-try {
-  TOKEN = readFileSync(new URL("./.bridge-token", import.meta.url), "utf8").trim();
-} catch {}
-if (!TOKEN) {
+// F2 FIX: Re-read token on every auth attempt so `init` token regeneration
+// takes effect without restarting the server.
+const TOKEN_PATH = new URL("./.bridge-token", import.meta.url);
+function readToken() {
+  try {
+    return readFileSync(TOKEN_PATH, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+if (!readToken()) {
   console.error(
-    "[bridge] WARNING: server/.bridge-token is missing — run `node gen-token.js` " +
-      "in the server directory. Refusing all extension connections until then."
+    "[bridge] WARNING: server/.bridge-token is missing — run `claude-browser-bridge init` " +
+      "or `node gen-token.js`. Refusing all extension connections until then."
   );
 }
 
@@ -87,7 +93,7 @@ function setupOwner(wss) {
       }
 
       if (!role) {
-        if (msg.type === "auth" && TOKEN && msg.token === TOKEN) {
+        if (msg.type === "auth" && readToken() && msg.token === readToken()) {
           role = msg.role === "relay" ? "relay" : "extension";
           clearTimeout(authTimer);
           if (role === "extension") {
@@ -150,7 +156,7 @@ function connectRelay() {
   mode = "relay";
   const ws = new WebSocket(`ws://127.0.0.1:${PORT}`);
   ws.on("open", () => {
-    ws.send(JSON.stringify({ type: "auth", token: TOKEN, role: "relay" }));
+    ws.send(JSON.stringify({ type: "auth", token: readToken(), role: "relay" }));
     upstream = ws;
     console.error(`[bridge] relay mode: forwarding through the session that owns port ${PORT}`);
   });
@@ -211,10 +217,48 @@ establish();
 
 // --- MCP server exposed to Claude Code -------------------------------------
 
+const HELP_TOOL = {
+  name: "browser_bridge_help",
+  description:
+    "Returns the complete usage guide for all 57 browser-bridge tools. Call this ONCE at the start of any session where you need to use browser tools, to learn the optimal workflows and avoid slow anti-patterns.",
+  inputSchema: { type: "object", properties: {} },
+};
+
+const HELP_TEXT = `# Claude Browser Bridge — 57 Tools Usage Guide
+
+## CRITICAL RULES (read before using ANY tool):
+1. ALWAYS start with \`diagnose\` — it returns snapshot + console errors + network failures + API responses in ONE call. NEVER call snapshot, get_console, get_network separately.
+2. Use \`batch\` for 2+ independent calls — e.g. batch([{name:"get_cookies"}, {name:"get_storage"}]).
+3. Pin with \`select_tab\` once, then stop passing tab_id — the pin persists.
+4. Use \`new_tab\` for research — NEVER navigate away from the app tab.
+5. After EVERY CSS/UI code change, take a \`screenshot\` to verify. Never claim "this should work" without seeing it.
+6. Use \`inject_css\` to test CSS fixes instantly without rebuilding, then write to file once confirmed.
+7. After 3 failed fix attempts, search the web: new_tab({url:"https://google.com/search?q=..."}).
+
+## Tool Categories:
+- Core: diagnose, batch, select_tab, snapshot, eval, screenshot, full_page_screenshot, get_page_text, get_html, get_page_info
+- Interaction: click, fill, hover, scroll, press_key, select_option, upload_file, highlight_element
+- Navigation: navigate, new_tab, close_tab, go_back, go_forward, reload, list_tabs, wait_for
+- Debugging: get_console, get_grouped_console, get_network, search_network_bodies, get_styles, get_cookies, get_storage, get_clipboard, watch_dom_changes, generate_selector
+- Performance: performance_trace, heap_snapshot_summary, get_load_timeline
+- Accessibility: get_accessibility_tree, check_contrast
+- Emulation: emulate_device, network_throttle, set_geolocation, toggle_dark_mode
+- Testing: visual_diff, inject_css, mock_network, record_actions, replay_actions, handle_dialog
+- Productivity: save_form_profile, load_form_profile, save_tab_session, restore_tab_session, edit_cookie, export_pdf
+
+## Key Workflows:
+- Investigate a page: diagnose → read errors → fix → screenshot to verify
+- Visual bug fix: batch([screenshot, get_styles]) → edit code → screenshot → compare → iterate
+- Performance audit: batch([performance_trace, heap_snapshot_summary, get_load_timeline])
+- Accessibility check: batch([get_accessibility_tree, check_contrast])
+- Test error states: mock_network({url_pattern:"/api/x", status_code:500}) → reload → screenshot
+- Record regression test: record_actions → reproduce bug → stop → fix → replay_actions to verify
+`;
+
 const BATCH_TOOL = {
   name: "batch",
   description:
-    "Execute multiple tool calls in a single round-trip for speed. Pass an array of {name, arguments} objects. All calls run in parallel and results are returned in the same order. Use this when you need to call 2+ tools that don't depend on each other.",
+    "Execute multiple tool calls in a single round-trip for speed. Pass an array of {name, arguments} objects. All calls run in parallel and results are returned in the same order. Use this when you need to call 2+ tools that don't depend on each other. ALWAYS prefer this over sequential calls.",
   inputSchema: {
     type: "object",
     properties: {
@@ -502,7 +546,7 @@ const TOOLS = [
   {
     name: "diagnose",
     description:
-      "PREFERRED first tool — returns snapshot + console errors + failed network requests + recent API responses + CAPTCHA/iframe detection + localStorage keys, ALL in a single call. Use this instead of calling snapshot + get_console + get_network separately. Replaces 4 round-trips with 1.",
+      "⚡ CALL THIS FIRST on any page. Returns snapshot (interactive elements with refs for click/fill) + console errors with stacks + failed network requests with response bodies + recent successful API responses + CAPTCHA detection + cross-origin iframe warnings + localStorage keys — ALL in ONE call. Replaces 4-5 sequential tool calls. After this, use refs from the snapshot to click/fill elements.",
     inputSchema: {
       type: "object",
       properties: {
@@ -809,7 +853,7 @@ const server = new Server(
   { capabilities: { tools: {} } }
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [BATCH_TOOL, ...TOOLS] }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [HELP_TOOL, BATCH_TOOL, ...TOOLS] }));
 
 function formatResult(name, result) {
   if ((name === "screenshot" || name === "full_page_screenshot") && result?.dataUrl) {
@@ -837,6 +881,11 @@ function formatResult(name, result) {
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: args } = req.params;
   try {
+    // Help: return the full usage guide (no extension needed).
+    if (name === "browser_bridge_help") {
+      return { content: [{ type: "text", text: HELP_TEXT }] };
+    }
+
     // Batch: run multiple calls in one round-trip through the extension.
     if (name === "batch") {
       const calls = args?.calls;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-browser-bridge",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Connect your live Chrome tabs to Claude Code — 57 tools for debugging, performance, accessibility, device emulation, and browser automation.",
   "type": "module",
   "bin": {