BrowserTrack 🔍

Local browser diagnostics shared with coding agents through MCP.

BrowserTrack is a lightweight, framework-agnostic local development daemon and Model Context Protocol (MCP) bridge. It automatically collects browser-side runtime errors, unhandled rejections, console logs, network failures, user breadcrumbs, and DOM snapshots—making them instantly accessible to AI coding assistants (Antigravity, Cursor, Claude Code) for rapid debugging and closed-loop verification.

---

⚡ Quick Start

1. Start the Local Daemon

npm install -g browsertrack
browsertrack start

This starts the local diagnostics server at http://127.0.0.1:7331 (WebSocket at ws://127.0.0.1:7331).

⚡ Zero-Config Auto-Start: If you configure BrowserTrack via MCP in your AI editor (Cursor, Antigravity, Claude Code), you do not need to manually run browsertrack start! The MCP server automatically launches and manages a single background daemon (singleton) on port 7331. Multiple windows or sessions share this single daemon without duplicate processes or port conflicts.

2. Connect Your Web Project

Option A: Zero-install script tag (Plain HTML / Vite / Next.js)

<script src="http://127.0.0.1:7331/client.js"></script>

Option B: NPM package (React / Vue / Svelte / Astro)

npm install -D browsertrack

In your main application entry point (e.g. main.ts or index.tsx):

import 'browsertrack/client';

---

🤖 Coding Agent (MCP) Setup

Add BrowserTrack to your MCP client configuration:

Cursor (~/.cursor/mcp.json) & Claude Code

{
  "mcpServers": {
    "browsertrack": {
      "command": "npx",
      "args": ["browsertrack", "mcp"]
    }
  }
}

Antigravity (~/.gemini/antigravity-ide/mcp_config.json)

{
  "mcpServers": {
    "browsertrack": {
      "command": "browsertrack",
      "args": ["mcp"]
    }
  }
}

---

🛠️ MCP Tools Exposed to AI Agents

📋 Incidents & Diagnostics

MCP Tool	Description
list_incidents	Lists grouped error incidents with occurrences, severity, and status.
get_incident	Retrieves concise, high-signal context (stack trace, breadcrumbs, network failures, last interacted element, error screenshot).
get_console	Retrieves recent console errors/warnings.
get_network_failures	Retrieves recent 4xx/5xx HTTP failures and aborted requests.
get_breadcrumbs	Returns user interaction timeline leading up to an error.
get_page_state	Queries live DOM/URL state from the active browser tab.
capture_element	Captures an on-demand screenshot of a specific element or full page.

📝 Visual Notes, Scenarios & Layout Inspector

MCP Tool	Description
list_notes	Lists visual annotations left on elements/regions (Alt+Click notes).
get_note	Retrieves complete note context (component source file & line, DOM selector, bounding rect, screenshot).
capture_note_context	Inspects live DOM bounding box, styles, and overflow on an element.
verify_note	Runs automated layout verification and geometry diffing with screenshot comparison.
get_note_verification	Retrieves latest layout verification verdict and screenshots.
resolve_note	Marks a visual note as RESOLVED.
reopen_note	Reopens a previously resolved visual note.
list_scenarios	Lists multi-step user reproduction flows.
get_scenario	Retrieves complete step-by-step reproduction flow.

🎛️ Session, Verification & Agent Guidelines

MCP Tool	Description
list_projects	Lists registered local development projects and mapped filesystem paths.
list_sessions	Lists active browser tabs connected over WebSocket.
verify_incident	Runs closed-loop verification: reloads browser, checks if error reoccurs, executes probes, captures after-screenshot, and returns verdict (VERIFIED, FAILED, INCONCLUSIVE).
get_verification	Returns latest verification result and before/after screenshot artifacts.
get_agent_guidelines	Retrieves full AI agent guidelines, workflows, and tool references.

---

💻 CLI Commands

Powered by mcponce:

browsertrack start             # Start local daemon
browsertrack start --verbose   # Verbose logging mode
browsertrack stop              # Stop background daemon
browsertrack status            # Check status & connected sessions

browsertrack projects          # List tracked projects
browsertrack project add myapp --origin http://localhost:5173 --path ~/projects/myapp

browsertrack errors            # List open runtime errors
browsertrack errors --project myapp

browsertrack clear             # Clear stored logs & incidents

# MCP & mcponce Developer Suite
browsertrack mcp               # Run MCP server over stdio (auto-boots singleton daemon)
browsertrack inspect           # Launch interactive zero-dependency Web Inspector & Playground
browsertrack mcp tools         # Inspect all 21 tool signatures and input schemas
browsertrack mcp call <tool>   # Test any MCP tool directly in terminal
browsertrack mcp analytics     # Real-time tool execution metrics and latency
browsertrack mcp install       # Auto-install MCP server to Claude Desktop or Cursor

---

🛡️ Security & Privacy

• Localhost Only: Daemon strictly binds to 127.0.0.1.
• Sensitive Key Redaction: Powered by @visulima/redact — Authorization, Cookie, Set-Cookie, passwords, API tokens, bearer tokens, JWTs, AWS credentials, credit cards, SSNs, and secret query parameters are automatically sanitized.
• No Form Values: Form inputs (<input>, <textarea>) are never inspected or collected.
• Zero Request/Response Body: Payload bodies are disabled by default.

---

🏗️ Architecture

Browser Client (Vanilla / React / Vue / Vite)
      ↕ WebSocket (ws://127.0.0.1:7331)
Local Daemon (SQLite Persistence + Verification Engine)
      ↕ MCP (stdio)
Coding Agents (Antigravity / Cursor / Claude Code)

---

🧪 Testing

Run the automated test suite:

npm test

Start the interactive fixture app for manual and end-to-end verification:

npx serve examples/test-app