🧠 MCP Browser Debugger (Python)

Enterprise-grade Model Context Protocol (MCP) server enabling AI agents to perform real browser automation, debugging, visual testing, performance analysis, HAR export, Playwright trace replay, video recording, and OCR-based text extraction on real web applications.

Built with Playwright (Python) and FastMCP, this server allows AI clients to act as autonomous QA engineers operating on real Chromium browsers, not mock environments.

📌 Overview

The MCP Browser Debugger is a stateful MCP server that bridges AI reasoning with real UI behavior.

It enables AI tools (Cursor, VS Code, Windsurf, etc.) to:

• Control a real Chrome browser (non-headless)
• Automatically attach to running localhost servers
• Interact with UI without fragile selectors
• Collect screenshots, videos, HAR files, logs, and traces
• Perform visual regression testing
• Extract visible text via OCR

❗ What This Project Is / Is Not

✅ This project IS

• A long-running MCP server
• A browser automation backend for AI agents
• A QA / debugging system for real web apps
• A stateful, artifact-producing tool

❌ This project is NOT

• A Playwright test framework replacement
• A headless-only automation tool
• A stateless CLI utility
• A mock or simulated browser

🏗 Architecture

AI Client (Cursor / VS Code / Windsurf)
        │
        ▼
Model Context Protocol (MCP)
        │
        ▼
FastMCP Server (Python)
        │
        ▼
Playwright (Chromium – real browser)
        │
        ▼
Artifacts (Screenshots, Video, HAR, Trace, OCR)

🔍 Server Identity (Important)

⚠️ These names are intentionally different. Do not rename either.

⚙️ Core Capabilities

Browser Automation

• Launches real Chrome (channel="chrome", non-headless)
• Auto-detects running localhost servers
• Automatically attaches to the most relevant server
• Creates session folders per project

Universal UI Interaction

• Intelligent form filling
• Button detection without selectors
• Semantic button scoring (submit/login/search)
• Keyboard fallback (Enter)

Debugging & Diagnostics

• Console log capture
• Network request logging
• DOM inspection
• HAR export

Performance Analysis

• LCP (Largest Contentful Paint)
• FCP (First Contentful Paint)
• CLS (Cumulative Layout Shift)
• Load (Navigation Timing based)

Visual Testing

• Full-page screenshots
• Element screenshots
• Baseline creation
• Visual diff with severity classification
• Region-based comparison
• Multi-page regression testing

Video Recording

• Start/stop mid-session
• .webm export
• Cursor & click overlay

Playwright Tracing

• Enabled by default
• Captures actions, DOM, network, screenshots, timeline
• Integrated trace viewer support

⚠️ Traces are saved only after browser_close() is called

OCR (Optical Character Recognition)

• Extracts visible text from page or elements
• Confidence scoring
• Works with canvas, images, popups
• Powered by Tesseract OCR

OCR tools exist without Tesseract installed but will return a guided error until the binary is installed.

✅ Requirements

... View full README on GitHub