# 🧠 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)

| Purpose               | Name               |
| --------------------- | ------------------ |
| MCP config name       | `Browser-Debugger` |
| FastMCP internal name | `Browser_Debugger` |

⚠️ 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

| Requirement   | Version | Notes                   |
| ------------- | ------- | ----------------------- |
| Python        | 3.8+    | Required                |
| pip           | Latest  | Auto-upgraded           |
| fastmcp       | < 3.0   | Installed automatically |
| playwright    | ≥ 1.40  | Installed automatically |
| psutil        | ≥ 5.9   | Installed automatically |
| Pillow        | ≥ 9.0   | Installed automatically |
| numpy         | ≥ 1.21  | Installed automatically |
| pytesseract   | ≥ 0.3   | Installed automatically |
| Tesseract OCR | 5.x     | Required only for OCR   |
| Node.js / npm | Latest  | For trace viewer        |
| Git           | Latest  | Recommended             |

---

## 📦 Installation

### Windows (Recommended)

> Run in **Command Prompt or PowerShell**

```bash
git clone https://github.com/Selvadinesh-giga/MCP-based-Browser-Debug-Server.git
cd MCP-based-Browser-Debug-Server
python install.py
```

### What the installer does

* Validates Python version
* Creates a virtual environment
* Installs dependencies
* Installs Playwright Chromium
* Detects Tesseract OCR (optional)
* Registers MCP server for:

  * Cursor
  * VS Code
  * Windsurf
* Writes MCP config with absolute paths

---

### Optional: Install Tesseract OCR (Windows)

Required **only** for OCR features.

```text
https://github.com/tesseract-ocr/tesseract/releases/download/5.5.0/
tesseract-ocr-w64-setup-5.5.0.20241111.exe
```

Verify:

```bash
tesseract --version
```

---

### macOS / Linux

```bash
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python -m playwright install chromium
```

Install Tesseract if OCR is needed:

```bash
brew install tesseract        # macOS
sudo apt-get install tesseract-ocr   # Linux
```

---

## ▶️ Usage (AI-Side)

### Launch Browser

```python
browser_launch()
browser_launch(url="http://localhost:3000")
```

### UI Interaction

```python
app_interact(["admin@test.com", "password"], button="Login")
app_interact(["laptop"])
app_interact(button="Search")
```

### Debugging

```python
debug_read_logs()
dom_get_source()
dom_inspect_element(selector="#submit")
```

### Performance

```python
performance_get_metrics()
```

### Screenshots & Video

```python
media_take_screenshot()
media_record_video("start")
media_record_video("stop")
```

### OCR

```python
media_read_text_ocr()
media_read_text_ocr(selector=".error")
```

### Visual Regression

```python
visual_diff(action="create_baseline", name="homepage")
visual_diff(action="compare", baseline_path="baselines/homepage.png")
```

### Trace Viewer

```python
trace_viewer(action="open")
```

### Close Session (Required)

```python
browser_close()
```

---

## 📁 Session Artifacts

```
.mcp_sessions/
 └── Chrome_Session_YYYY_MM_DD_HH_MM_SS/
     ├── screenshot_*.png
     ├── baselines/
     ├── regression_<name>_<timestamp>/
     ├── full_recording.webm
     ├── network.har
     ├── trace.zip
     └── session.log
```

* Screenshots are stored directly in the session folder
* `.mcp_sessions/.gitignore` is created automatically

---

## 🧹 Uninstall & Cleanup

```bash
python uninstall.py
```

Options:

* Remove MCP config only
* Remove config + virtual environment
* Full cleanup (Playwright cache, Tesseract)

---

## 🔧 Troubleshooting

* Restart IDE after installation
* Always call `browser_close()`
* Use absolute paths only
* OCR requires Tesseract binary
* Avoid running multiple sessions simultaneously

---

## 🎯 Use Cases

* AI-driven QA automation
* Bug reproduction & reporting
* Visual regression testing
* Performance audits
* Accessibility validation
* DevTools automation

---

## 🛣 Roadmap

* Multi-tab automation
* Headless CI execution
* AI-generated bug reports
* Cloud artifact sync
* Mobile browser testing

---

## 🙏 Acknowledgments

* FastMCP
* Playwright
* Tesseract OCR
* Model Context Protocol community

---