Fovea Web

A browser extension plus a small local server that lets an AI assistant see and control your actual browser tab — not a throwaway automation profile, your real, already-logged-in tab — and specifically check whether a page's mobile layout is broken (overflowing content, unreadable text, tiny tap targets) rather than just clicking around it.

Under the hood it's a cross-browser MCP server + Manifest V3 extension for mobile-first layout auditing and browser automation. Most MCP browser tools treat the browser as a robot to click through; this one is built to think like a responsive-QA engineer first.

Architecture

AI Harness <--(Stdio/MCP)--> MCP Server <--(WebSocket :8080)--> Extension Background Worker <--(CDP/DOM)--> Web Page
                              keeps login (extension) vs disposable profile (Playwright)

Related MCP server: visual-review-workbench

Why Fovea Web vs Playwright / chrome-devtools-mcp / BrowserTools

Quick Start

1. Build

npm install
npm run build

2. Load Extension

• Chrome / Brave / Edge: chrome://extensions → Developer Mode → Load unpacked → dist/extension

• Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → dist/extension/manifest.firefox.json

Popup shows ● Connected / ○ Disconnected, active tabs, and a one-click Audit This Page checker.

3. Connect to AI Harness

Add to mcp.json:

{
  "mcpServers": {
    "fovea-web": {
      "command": "node",
      "args": ["/path/to/fovea-web/dist/server/index.js"],
      "env": { "WS_PORT": "8080" }
    }
  }
}

Or use the included .mcp.json.

Tools (16)

Example — responsive audit

Ask your LLM: "audit responsive layout for this page, include screenshots" → calls audit_responsive{devices:[iPhone_SE, Pixel_7, Desktop], includeScreenshots:true} → returns:

# Responsive Audit — https://example.com
_2025-08-20_ — ❌ FAIL — 2 errors, 1 warnings
| Viewport | Overflow | Issues |
| iPhone_SE (375px) | ⚠️ YES | 2 |
## iPhone_SE — 2 issue(s)
- 🔴 HORIZONTAL_OVERFLOW document — scrollWidth 412px > viewport 375px
- 🔴 FIXED_WIDTH_OVERFLOW div.hero — width 400px > viewport 375px

Project Structure

fovea-web/
├── src/
│   ├── protocol.ts          # WS wire + 8 device presets + ViewportMetrics/AuditResult
│   ├── tools.ts             # Zod schemas for 16 tools
│   ├── ws-bridge.ts         # WS server :8080 with req_id timeout map
│   ├── layout-analyzer.ts   # analyzeLayout + auditBreakpoint + formatAuditAsMarkdown
│   └── mcp-server.ts        # 16 MCP tools via stdio
├── extension/
│   ├── manifest.json        # MV3 + alarms keep-alive (Fovea Web)
│   ├── background.ts        # CDP + scripting + audit orchestration + badge
│   ├── content.ts           # console hook + viewport/media/audit snapshot
│   ├── popup.html/ts        # status + tabs + quick audit
│   └── manifest.firefox.json
└── tests/
    ├── mcp-server.test.ts
    └── layout-analyzer.test.ts

Testing

npm test          # vitest
npm run lint      # tsc --noEmit
npm run build     # esbuild -> dist/

Env

See .env.example. WS_PORT defaults to 8080. Extension uses chrome.alarms keep-alive to survive MV3 idle.

Roadmap

• Device matrix + touch + viewport + media introspection

• Audit + matrix (differentiators)

• Network throttling (slow4g/cpu4x), Lighthouse-mobile

• Visual regression store + diff threshold