browserforce 1.0.0

package/mcp/src/index.js

@@ -0,0 +1,372 @@
+// BrowserForce — MCP Server
+// 2-tool architecture: execute (run Playwright code) + reset (reconnect)
+// Connects to the relay via Playwright's CDP client.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { chromium } from 'playwright-core';
+import {
+  getCdpUrl, CodeExecutionTimeoutError, buildExecContext, runCode, formatResult,
+} from './exec-engine.js';
+
+// ─── Console Log Capture ─────────────────────────────────────────────────────
+
+const MAX_LOGS_PER_PAGE = 5000;
+const consoleLogs = new Map();
+const pagesWithListeners = new WeakSet();
+let contextListenerAttached = false;
+
+function setupConsoleCapture(page) {
+  if (pagesWithListeners.has(page)) return;
+  pagesWithListeners.add(page);
+
+  consoleLogs.set(page, []);
+
+  page.on('console', (msg) => {
+    try {
+      const entry = `[${msg.type()}] ${msg.text()}`;
+      let logs = consoleLogs.get(page);
+      if (!logs) {
+        logs = [];
+        consoleLogs.set(page, logs);
+      }
+      logs.push(entry);
+      if (logs.length > MAX_LOGS_PER_PAGE) {
+        logs.shift();
+      }
+    } catch { /* msg.text() can throw if page navigated */ }
+  });
+
+  page.on('framenavigated', (frame) => {
+    if (frame === page.mainFrame()) {
+      consoleLogs.set(page, []);
+    }
+  });
+
+  page.on('close', () => {
+    consoleLogs.delete(page);
+  });
+}
+
+function ensureAllPagesCapture() {
+  try {
+    const pages = getPages();
+    for (const page of pages) {
+      setupConsoleCapture(page);
+    }
+  } catch { /* not connected yet */ }
+}
+
+// ─── Browser Connection ──────────────────────────────────────────────────────
+
+let browser = null;
+
+async function ensureBrowser() {
+  if (browser?.isConnected()) return;
+  const cdpUrl = getCdpUrl();
+  browser = await chromium.connectOverCDP(cdpUrl);
+  browser.on('disconnected', () => {
+    browser = null;
+    contextListenerAttached = false;
+    consoleLogs.clear();
+  });
+
+  try {
+    const ctx = browser.contexts()[0];
+    if (ctx && !contextListenerAttached) {
+      ctx.on('page', (page) => setupConsoleCapture(page));
+      contextListenerAttached = true;
+      for (const page of ctx.pages()) {
+        setupConsoleCapture(page);
+      }
+    }
+  } catch { /* context not ready yet — capture will attach lazily */ }
+}
+
+function getContext() {
+  if (!browser?.isConnected()) throw new Error('Not connected to relay. Is the relay running?');
+  const contexts = browser.contexts();
+  if (contexts.length === 0) throw new Error('No browser context available');
+  return contexts[0];
+}
+
+function getPages() {
+  return getContext().pages();
+}
+
+// ─── Persistent State ────────────────────────────────────────────────────────
+
+let userState = {};
+
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'browserforce',
+  version: '1.0.0',
+});
+
+// ─── Execute Tool Prompt ───────────────────────────────────────────────────
+
+const EXECUTE_PROMPT = `Run Playwright JavaScript in the user's real Chrome browser.
+This is their actual browser with real cookies, sessions, and tabs — not a sandbox.
+
+═══ AVAILABLE SCOPE ═══
+
+Variables:
+  page        Default page (first tab in context — shared, avoid navigating it)
+  context     Browser context — access all pages via context.pages()
+  state       Persistent object across calls (cleared on reset). Store your working page here.
+
+Helpers:
+  snapshot({ selector?, search? })   Accessibility tree as text. 10-100x cheaper than screenshots.
+  waitForPageLoad({ timeout? })      Smart load detection (filters analytics/ads, polls readyState).
+  getLogs({ count? })                Browser console logs captured for current page.
+  clearLogs()                        Clear captured console logs.
+
+Globals: fetch, URL, URLSearchParams, Buffer, setTimeout, clearTimeout, TextEncoder, TextDecoder
+
+═══ FIRST CALL — PAGE SETUP ═══
+
+IMPORTANT: Do NOT navigate the user's existing tabs. Always create or reuse a dedicated tab.
+
+On your first call, initialize state.page:
+  // Reuse an about:blank tab if one exists, otherwise create a new one
+  state.page = context.pages().find(p => p.url() === 'about:blank') || await context.newPage();
+  await state.page.goto('https://example.com');
+  await waitForPageLoad();
+  return await snapshot();
+
+After setup, use state.page for ALL subsequent operations — not the default page variable.
+If state.page was closed or navigated away, recreate it:
+  if (!state.page || state.page.isClosed()) {
+    state.page = await context.newPage();
+  }
+
+═══ WORKFLOW — OBSERVE → ACT → OBSERVE ═══
+
+After every action, verify its result before proceeding:
+
+1. OBSERVE: snapshot() to understand current page state
+2. ACT: Perform ONE action (click, type, navigate, etc.)
+3. OBSERVE: snapshot() again to verify the action worked
+
+Never chain multiple actions blindly. If you click a button, verify it worked before clicking the next.
+Each execute call should do ONE meaningful action and return verification.
+
+When navigating:
+  await state.page.goto(url);
+  await waitForPageLoad();
+  return await snapshot();
+
+When clicking:
+  await state.page.locator('role=button[name="Submit"]').click();
+  await waitForPageLoad();
+  return await snapshot();
+
+When filling forms:
+  await state.page.locator('role=textbox[name="Email"]').fill('user@example.com');
+  return await snapshot();
+
+═══ SNAPSHOT FIRST ═══
+
+ALWAYS prefer snapshot() over screenshot():
+- snapshot() returns a text accessibility tree — fast, cheap, searchable
+- screenshot() returns a PNG image — expensive, requires vision processing
+
+Use snapshot() for:
+  ✓ Reading page content and text
+  ✓ Finding interactive elements (buttons, links, inputs)
+  ✓ Verifying actions succeeded
+  ✓ Checking if a page loaded correctly
+
+Use screenshot() ONLY for:
+  ✓ Visual layout verification (grids, alignment, spacing)
+  ✓ Seeing images, charts, or visual content
+  ✓ Debugging when snapshot doesn't show the issue
+
+Targeted snapshots: snapshot({ search: /pattern/i }) filters the tree.
+Scoped snapshots: snapshot({ selector: '#main' }) limits to a subtree.
+
+═══ PAGE MANAGEMENT ═══
+
+Listing tabs:       const pages = context.pages();
+Creating a tab:     const p = await context.newPage();
+Navigating:         await state.page.goto(url);
+Current URL:        state.page.url()
+Page title:         await state.page.title()
+
+context.pages() returns ALL open tabs. Index 0 is usually the user's original tab.
+Store your working page in state.page to avoid losing track of it.
+
+For multi-tab workflows:
+  const pages = context.pages();
+  // Find a specific tab by URL
+  const gmail = pages.find(p => p.url().includes('mail.google'));
+
+═══ INTERACTING WITH ELEMENTS ═══
+
+Use Playwright locators with accessibility roles (from snapshot output):
+  await state.page.locator('role=button[name="Sign in"]').click();
+  await state.page.locator('role=textbox[name="Search"]').fill('query');
+  await state.page.locator('role=link[name="Settings"]').click();
+
+If snapshot shows [ref=some-id] for an element with a data-testid or id:
+  await state.page.locator('[data-testid="some-id"]').click();
+
+For text content:
+  const text = await state.page.locator('role=heading').textContent();
+
+═══ COMMON PATTERNS ═══
+
+Navigate and read:
+  await state.page.goto('https://example.com');
+  await waitForPageLoad();
+  return await snapshot();
+
+Click and verify:
+  await state.page.locator('role=button[name="Next"]').click();
+  await waitForPageLoad();
+  return await snapshot();
+
+Fill form and submit:
+  await state.page.locator('role=textbox[name="Username"]').fill('user');
+  await state.page.locator('role=textbox[name="Password"]').fill('pass');
+  await state.page.locator('role=button[name="Login"]').click();
+  await waitForPageLoad();
+  return await snapshot();
+
+Extract data:
+  return await state.page.evaluate(() => {
+    return document.querySelector('.price').textContent;
+  });
+
+Wait for specific element:
+  await state.page.locator('role=heading[name="Dashboard"]').waitFor();
+  return await snapshot();
+
+Debug with console logs:
+  return getLogs({ count: 20 });
+
+═══ ANTI-PATTERNS ═══
+
+✗ Don't navigate the user's existing tabs — create your own via context.newPage()
+✗ Don't screenshot() to read text — use snapshot()
+✗ Don't chain actions without verifying — observe after each action
+✗ Don't use page.waitForTimeout() — use waitForPageLoad() or waitFor()
+✗ Don't forget to return a value — every call should return verification
+✗ Don't write complex multi-step scripts — split into separate execute calls
+✗ Don't use page variable directly — use state.page after first call setup
+
+═══ ERROR RECOVERY ═══
+
+If page closed:      state.page = await context.newPage();
+If navigation fails: Check state.page.url() to see where you actually are
+If element missing:   Use snapshot({ search: /element/ }) to find it
+If connection lost:   Call the reset tool, then re-initialize state.page
+If timeout:          Increase timeout param, or break into smaller steps
+
+═══ API REFERENCE ═══
+
+snapshot(options?)
+  options.selector  CSS selector to scope the snapshot (e.g., '#main', '.sidebar')
+  options.search    Regex string to filter tree nodes (e.g., 'button|link')
+  Returns: Text accessibility tree with interactive element refs
+
+waitForPageLoad(options?)
+  options.timeout   Max wait in ms (default: 30000)
+  Returns: { success, readyState, pendingRequests, waitTimeMs, timedOut }
+  Filters analytics/ad requests that never finish. Polls document.readyState.
+
+getLogs(options?)
+  options.count     Number of recent entries (default: all)
+  Returns: Array of "[type] message" strings from browser console
+
+clearLogs()
+  Clears captured console logs for current page.
+
+state
+  Persistent object — survives across execute calls. Cleared on reset.
+  Use state.page, state.data, state.anything to preserve working state.`;
+
+server.tool(
+  'execute',
+  EXECUTE_PROMPT,
+  {
+    code: z.string().describe('JavaScript to run — page/context/state/snapshot/waitForPageLoad/getLogs in scope'),
+    timeout: z.number().optional().describe('Max execution time in ms (default: 30000)'),
+  },
+  async ({ code, timeout = 30000 }) => {
+    await ensureBrowser();
+    ensureAllPagesCapture();
+    const ctx = getContext();
+    const pages = ctx.pages();
+    const page = pages[0] || null;
+
+    if (page) setupConsoleCapture(page);
+    const execCtx = buildExecContext(page, ctx, userState, {
+      consoleLogs, setupConsoleCapture,
+    });
+    try {
+      const result = await runCode(code, execCtx, timeout);
+      const formatted = formatResult(result);
+      return { content: [formatted] };
+    } catch (err) {
+      const isTimeout = err instanceof CodeExecutionTimeoutError;
+      const hint = isTimeout ? '' : '\n\n[If connection lost, call reset tool to reconnect]';
+      return {
+        content: [{ type: 'text', text: `Error: ${err.message}${hint}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.tool(
+  'reset',
+  'Reconnects to the relay, reinitializes the browser context, and clears persistent state. Use when: connection lost, pages closed unexpectedly, or state is corrupt.',
+  {},
+  async () => {
+    if (browser) {
+      try { await browser.close(); } catch { /* connection may already be dead */ }
+    }
+    browser = null;
+    userState = {};
+    contextListenerAttached = false;
+    consoleLogs.clear();
+    try {
+      await ensureBrowser();
+      ensureAllPagesCapture();
+      const pages = getPages();
+      return {
+        content: [{ type: 'text', text: `Reset complete. ${pages.length} page(s) available. Current URL: ${pages[0]?.url() ?? 'none'}` }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Reset failed: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ─── Start Server ────────────────────────────────────────────────────────────
+
+async function main() {
+  try {
+    await ensureBrowser();
+    process.stderr.write('[bf-mcp] Connected to relay\n');
+  } catch (err) {
+    process.stderr.write(`[bf-mcp] Warning: ${err.message}\n`);
+    process.stderr.write('[bf-mcp] Tools will attempt to connect on first use\n');
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('[bf-mcp] MCP server running\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`[bf-mcp] Fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/mcp/src/snapshot.js

@@ -0,0 +1,197 @@
+// BrowserForce — Accessibility Snapshot Helpers
+// Builds a text-based accessibility tree from Playwright's AX snapshot,
+// with interactive element refs mapped to Playwright locators.
+
+import { createPatch } from 'diff';
+
+export const INTERACTIVE_ROLES = new Set([
+  'button', 'link', 'textbox', 'combobox', 'searchbox',
+  'checkbox', 'radio', 'slider', 'spinbutton', 'switch',
+  'menuitem', 'menuitemcheckbox', 'menuitemradio',
+  'option', 'tab', 'treeitem',
+]);
+
+export const CONTEXT_ROLES = new Set([
+  'navigation', 'main', 'contentinfo', 'banner', 'form',
+  'section', 'region', 'complementary', 'search',
+  'list', 'listitem', 'table', 'rowgroup', 'row', 'cell',
+  'heading', 'img',
+]);
+
+export const SKIP_ROLES = new Set([
+  'generic', 'none', 'presentation',
+]);
+
+export const TEST_ID_ATTRS = [
+  'data-testid', 'data-test-id', 'data-test',
+  'data-cy', 'data-pw', 'data-qa', 'data-e2e',
+];
+
+export function escapeLocatorName(name) {
+  return name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function buildLocator(role, name, stableAttr) {
+  if (stableAttr) {
+    return `[${stableAttr.attr}="${escapeLocatorName(stableAttr.value)}"]`;
+  }
+  const trimmed = name?.trim();
+  if (trimmed) {
+    return `role=${role}[name="${escapeLocatorName(trimmed)}"]`;
+  }
+  return `role=${role}`;
+}
+
+export function walkAxTree(node, visitor, depth = 0, parentNames = []) {
+  if (!node) return;
+  visitor(node, depth, parentNames);
+  const nextNames = node.name ? [...parentNames, node.name] : parentNames;
+  if (node.children) {
+    for (const child of node.children) {
+      walkAxTree(child, visitor, depth + 1, nextNames);
+    }
+  }
+}
+
+export function hasInteractiveDescendant(node) {
+  if (!node.children) return false;
+  for (const child of node.children) {
+    if (INTERACTIVE_ROLES.has(child.role)) return true;
+    if (hasInteractiveDescendant(child)) return true;
+  }
+  return false;
+}
+
+export function hasMatchingDescendant(node, pattern) {
+  if (!node.children) return false;
+  for (const child of node.children) {
+    const text = `${child.role} ${child.name || ''}`;
+    if (pattern.test(text)) return true;
+    if (hasMatchingDescendant(child, pattern)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build snapshot text from an AX tree object.
+ *
+ * stableIdMap: Map<testid/id value → { attr, value }> keyed by the attribute
+ * value itself (not by accessible name) to avoid collisions when multiple
+ * elements share the same name.
+ *
+ * The ref for each interactive element is:
+ *  1. The stable attribute value if a matching stableIdMap entry exists for this
+ *     node's DOM attributes (looked up by the page-evaluate caller).
+ *  2. Otherwise, a fallback counter ref: e1, e2, ...
+ *
+ * When multiple nodes resolve to the same ref, a -2, -3 suffix is appended.
+ */
+export function buildSnapshotText(axTree, stableIdMap, searchPattern) {
+  const lines = [];
+  const refs = [];
+  let refCounter = 0;
+  const refCounts = new Map();
+
+  walkAxTree(axTree, (node, depth) => {
+    const role = node.role;
+    if (SKIP_ROLES.has(role) || role === 'RootWebArea' || role === 'WebArea') {
+      return;
+    }
+
+    const isInteractive = INTERACTIVE_ROLES.has(role);
+    const isContext = CONTEXT_ROLES.has(role);
+    const name = node.name || '';
+
+    if (!isInteractive && !isContext) {
+      if (!hasInteractiveDescendant(node)) return;
+    }
+
+    if (searchPattern) {
+      const text = `${role} ${name}`;
+      if (!searchPattern.test(text) && !hasMatchingDescendant(node, searchPattern)) {
+        return;
+      }
+    }
+
+    const indent = '  '.repeat(depth);
+    let lineText = `${indent}- ${role}`;
+    if (name) {
+      lineText += ` "${escapeLocatorName(name)}"`;
+    }
+
+    if (isInteractive) {
+      refCounter++;
+      const stableEntry = node._stableAttr || null;
+      let baseRef = stableEntry ? stableEntry.value : `e${refCounter}`;
+      const count = refCounts.get(baseRef) ?? 0;
+      refCounts.set(baseRef, count + 1);
+      const ref = count === 0 ? baseRef : `${baseRef}-${count + 1}`;
+      const locator = buildLocator(role, name, stableEntry);
+
+      lineText += ` [ref=${ref}]`;
+      refs.push({ ref, role, name, locator });
+    }
+
+    if (node.children?.length > 0) {
+      const hasRelevantChildren = node.children.some(c =>
+        INTERACTIVE_ROLES.has(c.role) || CONTEXT_ROLES.has(c.role) || hasInteractiveDescendant(c)
+      );
+      if (hasRelevantChildren) {
+        lineText += ':';
+      }
+    }
+
+    lines.push(lineText);
+  });
+
+  return { text: lines.join('\n'), refs };
+}
+
+export function createSmartDiff(oldText, newText) {
+  if (oldText === newText) return { type: 'no-change', content: newText };
+
+  const patch = createPatch('snapshot', oldText, newText, 'previous', 'current', { context: 3 });
+  const patchLines = patch.split('\n');
+  const diffBody = patchLines.slice(4).join('\n');
+
+  const oldLineCount = oldText.split('\n').length;
+  const newLineCount = newText.split('\n').length;
+  const addedLines = (diffBody.match(/^\+[^+]/gm) || []).length;
+  const removedLines = (diffBody.match(/^-[^-]/gm) || []).length;
+  const changeRatio = Math.max(addedLines, removedLines) / Math.max(oldLineCount, newLineCount, 1);
+
+  if (changeRatio >= 0.5 || diffBody.length >= newText.length) {
+    return { type: 'full', content: newText };
+  }
+  return { type: 'diff', content: diffBody };
+}
+
+export function parseSearchPattern(search) {
+  if (!search) return null;
+  try {
+    return new RegExp(search, 'i');
+  } catch (err) {
+    throw new Error(`Invalid search regex "${search}": ${err.message}`);
+  }
+}
+
+/**
+ * Annotate AX tree nodes with stable DOM attributes (data-testid, id, etc.).
+ *
+ * stableIdsByAttrValue: an object of { [attrValue]: { attr, value, names } }
+ * returned from getStableIds(). We match AX nodes to stable IDs by checking
+ * if the node's accessible name appears in the entry's names array.
+ *
+ * This runs once per snapshot before buildSnapshotText, attaching _stableAttr
+ * to matching nodes in-place.
+ */
+export function annotateStableAttrs(axTree, stableIds) {
+  walkAxTree(axTree, (node) => {
+    if (!INTERACTIVE_ROLES.has(node.role)) return;
+    const name = node.name || '';
+    const entry = stableIds[name];
+    if (entry) {
+      node._stableAttr = { attr: entry.attr, value: entry.value };
+    }
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "browserforce",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Give AI agents your real Chrome browser — your logins, cookies, and tabs. Works with OpenClaw, Claude, and any MCP agent.",
+  "homepage": "https://github.com/anthropics/browserforce",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/browserforce.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "browser",
+    "chrome",
+    "playwright",
+    "mcp",
+    "openclaw",
+    "ai-agent",
+    "cdp",
+    "automation",
+    "browserforce"
+  ],
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "bin": {
+    "browserforce": "./bin.js"
+  },
+  "files": [
+    "bin.js",
+    "relay/src/",
+    "relay/package.json",
+    "mcp/src/",
+    "mcp/package.json",
+    "skills/"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "diff": "^8.0.3",
+    "playwright-core": "^1.52.0",
+    "ws": "^8.19.0",
+    "zod": "^3.24.0"
+  },
+  "scripts": {
+    "relay": "lsof -ti tcp:19222 | xargs kill -9 2>/dev/null; sleep 0.3; node relay/src/index.js",
+    "relay:dev": "lsof -ti tcp:19222 | xargs kill -9 2>/dev/null; sleep 0.3; node --watch relay/src/index.js",
+    "mcp": "node mcp/src/index.js",
+    "test": "node --test relay/test/relay-server.test.js && node --test mcp/test/mcp-tools.test.js && node --test test/cli.test.js",
+    "test:relay": "node --test relay/test/relay-server.test.js",
+    "test:mcp": "node --test mcp/test/mcp-tools.test.js"
+  }
+}

package/relay/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }