What can you do with this server?

This server is a Model Context Protocol (MCP) endpoint for browser forensics and live DOM intelligence, letting AI agents record, reconstruct, inspect, and interact with web pages. * Manage recorded browser sessions: list, get, export, import, and delete forensic sessions. * Query event timelines and filtered events across DOM mutations, user actions, console logs, errors, network requests, and navigation. * Reconstruct DOM state at any historical timestamp or event via time-travel, inspect individual nodes and subtrees, and compute structural diffs between two states. * Trace element lifecycles, find short-lived or disappearing elements, and run automated root-cause diagnosis with confidence scores and evidentiary trails. * Retrieve diagnostics (console, errors, promise rejections) and network events, with health/integrity auditing for sessions. * Inspect live browser state: URL, viewport, element bounds, computed styles, visibility, ARIA roles, occlusion, and visual state. * Activate a Ctrl+Shift+Click visual element picker and retrieve the selected element details. * Capture clean full-page or element-bounded screenshots with overlay hiding and canvas-based cropping. * Interact synthetically with live elements (click, hover, focus, type, press_key, select_option, scroll, etc.) and measure before/after effects. * Start/stop focused element observation to get combined mutation, diagnostics, and network correlation bundles. * Obtain live DOM snapshots and subtrees in HTML or structured JSON formats.

Which integrations are available for this server?

Provides browser forensic recording and DOM time-travel debugging for Google Chrome, enabling live DOM inspection, visual element selection, screenshots, synthetic user interactions, and root-cause analysis of disappearing or re-rendered elements.

How do I use Mcp-DOM?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mcp-DOM Find out why the login form disappeared and show the DOM state before it was removed" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Mcp-DOM

by IrMaho

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

⚡ Browser Forensic Recorder, Live DOM Intelligence & Universal MCP Server

A high-fidelity browser forensic recorder, sub-millisecond DOM time-travel state reconstruction engine, element lifecycle tracer, live DOM intelligence controller, zero-config on-demand auto-bridge, and 34-tool Model Context Protocol (MCP) server for autonomous AI coding agents and frontend engineers.

Overview • Key Features • Universal CLI • Architecture • MCP Tools (34) • Auto-Bridge Engine • Visual Forensics & Screenshots • Installation & Quick Start • Testing & Certification

📖 Table of Contents

Related MCP server: relay-inspect

⚡ Overview & Why This Project Exists

Modern web applications are dynamic ecosystems composed of virtual DOM reconciliation engines (React, Vue, Svelte), micro-frontends, injected extensions, floating assistant widgets, analytics tags, and complex asynchronous state machines.

When an injected component or UI widget unexpectedly disappears, re-renders incorrectly, or breaks during user interaction, traditional debugging tools fall short:

Standard Chrome DevTools only inspects the current state of the DOM; once an element is unmounted, its history, styles, attributes, and parentage are lost.
Video Screen Recorders only capture raw pixel arrays with no underlying semantic DOM tree, network timings, or selector relationships.
Console Logs lack temporal alignment with granular DOM mutation records.

The Solution

Browser Forensic Recorder & DOM Time-Travel Debugger bridges this gap. It operates as an unobtrusive, high-performance forensic recorder, live browser controller, and universal MCP server that continuously correlates:

Granular DOM Mutations: childList additions, removals, moves, attribute changes, and text edits.
Deterministic Stable Node Identities (LogicalNodeId): Preserving element identities across reparenting and class mutations using WeakMap bindings.
Live Browser Control & Visual Intelligence: Inspecting live DOM hierarchy, picking elements visually via Ctrl + Shift + Mouse Click, capturing clean full/element screenshots, executing synthetic actions, and running focused observation around target components.
Zero-Config Auto-Bridge: On-demand automatic WebSocket bridge initialization on port 3847 so AI agents and users never need to start separate manual terminal processes.
Sub-Millisecond Temporal Ordering: Checkpoint + delta interpolation engine for instant historical time-travel.
Contextual Diagnostic Signals: Correlating console outputs, unhandled errors, XHR/fetch network requests, and SPA route changes.
Autonomous AI Forensics via Model Context Protocol (MCP): Providing 34 structured JSON-RPC 2.0 tools allowing AI coding assistants to autonomously inspect live DOM, interact with elements, calculate structural diffs, trace lifecycles, and diagnose root causes with evidentiary confidence scoring.

✨ Key Features

Feature	Description
Dedicated Universal CLI (`dom-antigravity`)	Install MCP configs globally or into any workspace with `dom-antigravity install --workspace` or `dom-antigravity install --global`.
Zero-Config On-Demand Auto-Bridge	`ForensicMCPServer` automatically starts background WebSocket bridge on port `3847` on demand or connects conflict-free to active instances.
Clean Screenshot Pipeline	Automatically hides in-page floating host overlays and highlighters during capture (`display: none !important`) with compositor paint delay, restoring them seamlessly.
Pure TypeScript Zero-Dependency PNG Builder	Built-in `PNGBuilder` generating standard, fully compliant PNG binary images (IHDR, IDAT, IEND, CRC32, Adler32, Deflate) for offline/standalone execution.
Canvas Element-Bounded Screenshots	`capture_element_screenshot` crops full-page captures to exact target bounding boxes and `devicePixelRatio` scaling via HTML5 canvas.
`Ctrl + Shift + Click` Visual Element Picker	Hold `Ctrl + Shift` and click any element on the live browser page to immediately select and transmit its rich structured metadata to connected AI agents.
Live Browser Control & Live DOM Intelligence	Deeply inspect live page state, query element geometry, styles, roles, and state with deterministic targeting (`selectedElementRef` → `nodeId` → `selector` → `coordinates`).
Synthetic Live Interactions & Effects Measurement	Dispatch user actions (`click`, `hover`, `focus`, `type`, `press_key`, `select_option`, `scroll`) and measure before/after state and mutation effects.
Element-Focused Observation & Forensics	Continuous observation engine around target components that captures mutations, errors, and network calls, and explains why an element vanished or changed layout.
Sub-Millisecond DOM Time-Travel	`StateReconstructor.getStateAt(T \| eventId)` seeks the closest preceding snapshot checkpoint and replays mutation deltas with LRU snapshot caching.
Structural DOM Diff Engine	Calculates added, removed, moved, attribute, class, style, and text deltas between any two timestamps ($T_1 \leftrightarrow T_2$) or events ($E_1 \leftrightarrow E_2$).
Automated Root-Cause Forensics	`DisappearingElementAnalyzer` diagnoses whether an element vanished due to direct removal, ancestor container destruction (e.g. React/Vue re-render), style hiding (`display: none`), class changes, or preceding runtime errors/network updates.
Declarative Shadow DOM Support	Preserves Shadow DOM boundaries across capture, serialization, virtual tree reconstruction, and sandboxed replay using `<template shadowrootmode="...">`.
Privacy & Masking by Default	`PrivacyEngine` automatically redacts passwords, credit card numbers, SSNs, authorization headers, API tokens, and user-specified CSS selectors in both recording and live inspection.

💻 Dedicated Universal CLI (`dom-antigravity`)

The package exposes a global CLI binary registered as dom-antigravity (with aliases mcp-dom and browser-antigravity):

# 1. Install MCP configuration & skills into current workspace (.agents)
dom-antigravity install --workspace
# Short alias:
dom-antigravity install -w

# 2. Install globally for ALL projects in Antigravity IDE
dom-antigravity install --global
# Short alias:
dom-antigravity install -g

# 3. Install into a specific target directory
dom-antigravity install --target "C:/path/to/project"

# 4. Check bridge server health & connected Chrome tabs
dom-antigravity status

# 5. Capture clean live Chrome screenshot (Full Page + Cropped Element)
dom-antigravity screenshot

# 6. Start WebSocket Bridge manually (Optional — Auto-Bridge handles this on demand)
dom-antigravity bridge

# 7. Print ready-to-use JSON configuration for Claude Desktop or Cursor
dom-antigravity config cursor
dom-antigravity config claude

🏗️ System Architecture

Dual-Environment Execution Model

A complete browser forensic and live control system operates across two distinct runtime environments:

Browser Runtime (Chrome Extension / Page Script / Content Script):
- Captures DOM mutations via MutationObserver.
- Assigns unique stable LogicalNodeIds using WeakMap bindings.
- Listens to Ctrl + Shift + Mouse Click for visual element picking.
- Dispatches live interactions (click, type, hover, focus, scroll).
- Crops element bounding boxes on HTML5 Canvas.
- Hides floating overlays during screenshot captures.
Node.js / MCP Server Runtime (ForensicMCPServer):
- Implements JSON-RPC 2.0 protocol over stdio and HTTP.
- Automatically initializes and manages the WebSocket bridge on port 3847.
- Reconstructs virtual DOM snapshots at sub-millisecond timestamps.
- Computes structural DOM diffs and element lifecycle traces.
- Executes automated root-cause heuristics with confidence scores.

High-Level Architecture Diagram

┌────────────────────────────────────────────────────────────────────────┐
│                          AI AGENT / MCP CLIENT                         │
│             (Antigravity IDE / Cursor / Claude Desktop / CLI)          │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ (JSON-RPC 2.0 over stdio)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   FORENSIC MCP SERVER (34 TOOLS)                       │
│  ├── 13 Live Browser Control & Visual Intelligence Tools               │
│  ├── 21 Historical Forensics, State Reconstruction & Diff Tools        │
│  └── Zero-Config On-Demand Auto-Bridge Dispatcher                      │
└───────────────────┬────────────────────────────────┬───────────────────┘
                    │                                │ (WebSocket / HTTP :3847)
                    ▼                                ▼
┌───────────────────────────────┐  ┌────────────────────────────────────┐
│   LOCAL TIME-TRAVEL ENGINE    │  │    LIVE WEBSOCKET BRIDGE SERVER    │
│  ├── FileStorageProvider      │  │    (Port 3847 - Auto-Managed)      │
│  ├── StateReconstructor       │  └─────────────────┬──────────────────┘
│  ├── DOMDiffEngine            │                    │
│  └── DisappearingAnalyzer     │                    ▼
└───────────────────────────────┘  ┌────────────────────────────────────┐
                                   │     CHROME EXTENSION (MV3)         │
                                   │  ├── service-worker.ts (Background)│
                                   │  ├── content-script.ts (In-Page)   │
                                   │  ├── floating-controller.ts (UI)   │
                                   │  └── page-script.ts (XHR/Fetch)    │
                                   └─────────────────┬──────────────────┘
                                                     │ (DOM / Events / Canvas)
                                                     ▼
                                   ┌────────────────────────────────────┐
                                   │    LIVE BROWSER TAB (REAL DOM)     │
                                   │  ├── Native DOM MutationObserver   │
                                   │  ├── Ctrl+Shift+Click Picker       │
                                   │  ├── chrome.tabs.captureVisibleTab │
                                   │  └── Canvas Element Crop Engine    │
                                   └────────────────────────────────────┘

⚡ Zero-Config On-Demand Auto-Bridge

The system eliminates the need to run manual background processes in separate terminals:

When ForensicMCPServer is instantiated or invoked over stdio, it automatically checks port 3847.
If port 3847 is free, it spawns MCPBridgeServer in the background.
If port 3847 is already running (e.g. from an existing instance), it transparently connects as a client without EADDRINUSE conflicts.
When the Chrome extension is active, it connects to ws://127.0.0.1:3847 automatically, enabling instantaneous bidirectional communication for all 13 live tools.

📸 Clean Screenshot & Visual Forensics Pipeline

AI Agent calls capture_page_screenshot or capture_element_screenshot
   ↓
MCP Server forwards command to Chrome Extension Service Worker
   ↓
Service Worker sends HIDE_FORENSIC_OVERLAYS to Content Script
   ↓
Content Script sets display: none !important & visibility: hidden on #forensic-recorder-floating-host
   ↓
Compositor Wait Delay (150ms) ensures GPU frame committed without UI overlay
   ↓
chrome.tabs.captureVisibleTab captures pristine hardware pixels
   ↓
Service Worker sends RESTORE_FORENSIC_OVERLAYS to restore floating widget instantly
   ↓
[For capture_element_screenshot]:
Content Script loads image into Canvas, crops to targetBounds * devicePixelRatio, and encodes PNG
   ↓
Zero-Dependency PNGBuilder decodes/validates binary stream
   ↓
Pristine, viewable, pixel-perfect PNG returned to AI Agent

📁 Repository Structure

mcp_dom/
├── .agents/                                # Local & Plugin Customizations
│   ├── mcp_config.json                     # 34-Tool Local MCP Server Declaration
│   ├── plugins/browser-forensics/          # Local Plugin Definition
│   └── skills/browser-forensics/SKILL.md   # Comprehensive 34-Tool Agent Skill
├── bin/                                    # Universal CLI & Server Entrypoints
│   ├── cli.js                              # dom-antigravity Multi-Command CLI
│   ├── mcp-server.js                       # Stdio JSON-RPC MCP Server Executable
│   └── bridge-server.js                    # Standalone Bridge Server Executable
├── operational-tests/                      # Acceptance Testing & Evidence Suite
│   ├── _inventory/                         # Discovered Tools Schema & Capability Matrix
│   ├── _fixtures/                          # DOM & Visual Geometry Fixtures
│   ├── _reports/                           # Final Certification & Capability Reports
│   └── tools/ (001-034)                    # Dedicated Evidence Dirs with raw requests/responses
├── scripts/                                # Build, Test & Automation Utilities
│   ├── build-extension.js                  # Standalone IIFE Extension Bundler
│   ├── run-operational-suite.js            # Stdio JSON-RPC Operational Test Runner
│   ├── test-mcp-e2e.js                     # Real Subprocess E2E Test Suite
│   └── capture-real-chrome.js              # Live Browser Screenshot Verification
├── src/                                    # TypeScript Source Code
│   ├── core/                               # Recording Engine & Live Browser Controller
│   │   ├── recorder.ts                     # Ingestion Coordinator
│   │   ├── live-browser-controller.ts      # Live DOM Inspection & Action Dispatcher
│   │   ├── element-picker.ts               # Ctrl+Shift+Click Interactive Picker
│   │   ├── element-observer.ts             # Continuous Targeted Mutation Observer
│   │   ├── element-interaction-engine.ts   # Synthetic Click, Type, Focus, Hover Engine
│   │   ├── live-dom-inspector.ts           # Deep DOM & Accessibility Inspector
│   │   ├── png-builder.ts                  # Pure TS Zero-Dependency PNG Encoder
│   │   ├── mutation-observer.ts            # DOM Mutation Ingestion
│   │   └── node-registry.ts                # LogicalNodeId WeakMap Mapper
│   ├── diff/                               # Structural DOM Diff Engine
│   ├── extension/                          # Chrome Extension Manifest V3
│   │   ├── background/service-worker.ts    # Background Worker & Bridge Client
│   │   ├── content/content-script.ts       # In-Page Injection & Live Command Router
│   │   └── content/floating-controller.ts  # In-Page Floating Debugger Overlay
│   ├── lifecycle/                          # Disappearing UI & Lifecycle Forensics
│   ├── mcp/                                # Model Context Protocol Server
│   │   ├── server.ts                       # ForensicMCPServer with Auto-Bridge
│   │   ├── bridge-server.ts                # WebSocket / HTTP Ingestion Bridge
│   │   ├── live-tools-handler.ts           # 13 Live Browser Control Tools
│   │   └── tools-handler.ts                # 21 Historical Forensics Tools
│   ├── reconstruction/                     # Time-Travel Virtual DOM Reconstructor
│   ├── storage/                            # File, IndexedDB & Memory Storage
│   ├── types/                              # Strict TypeScript Interfaces
│   └── ui/                                 # Glassmorphic Developer Dashboard
├── package.json                            # Scripts, Dependencies & Binaries
├── tsconfig.json                           # TypeScript Compiler Config
└── vite.config.ts                          # Multi-Target Build Configuration

🧩 Core Subsystems & Module Breakdown

1. Core Recording & Live Control Engine (`src/core/`)

ForensicRecorder: Coordinates session lifecycle, batching events and emitting structured records (DOM_MUTATION_ADD, USER_EVENT_CLICK, CONSOLE_LOG, NETWORK_REQUEST_START).
LiveBrowserController: Central dispatcher routing live inspection, visual picking, synthetic interactions, observation, and screenshot capture.
LiveDOMInspector: Calculates unique CSS selectors, bounding boxes, visibility states, computed styles, accessibility roles, and parent hierarchy.
ElementPicker: Attaches interactive highlight overlay and captures Ctrl + Shift + Mouse Click selections.
ElementInteractionEngine: Synthesizes standard browser interaction sequences (focus → pointerdown → mousedown → click or input → change).
PNGBuilder: Pure TypeScript uncompressed Deflate and PNG chunk encoder with CRC32 and Adler32 checksums.

2. Time-Travel & Query Engine (`src/reconstruction/`)

StateReconstructor: Seeks the closest preceding full checkpoint snapshot and applies sequential mutation deltas up to target timestamp $T$.
LRUSnapshotCache: In-memory cache holding up to 50 historical snapshots for sub-10ms scrub operations.
VirtualQueryEngine: Evaluates CSS selectors against virtual DOM trees without requiring live browser DOM.

3. Structural Diff Engine (`src/diff/`)

DOMDiffEngine: Reconstructs states at $T_1$ and $T_2$ and produces categorized deltas (added, removed, moved, attributes, classes, styles, text) in Markdown or JSON format.

4. Lifecycle & Forensics Engine (`src/lifecycle/`)

DisappearingElementAnalyzer: Evaluates 5 primary disappearance mechanisms:
1. PARENT_SUBTREE_REPLACED: Ancestor container unmounted (e.g. React/Vue re-render).
2. DIRECT_NODE_REMOVAL: Direct removeChild / remove().
3. STYLE_DISPLAY_NONE: CSS visibility toggling.
4. CLASS_TRIGGERED_HIDDEN: Class additions triggering layout collapse.
5. REMOVED_DURING_NAVIGATION: Unmounted during SPA page navigation.
ElementLifecycleTracer: Reconstructs the full chronological lifecycle of an element from initial attachment to destruction.

5. Storage & Indexing (`src/storage/`)

FileStorageProvider: Persistent storage using session.json, events.jsonl (line-delimited streaming), and checkpoints/.
IndexedDBStorageProvider: Browser-side storage for the Chrome Extension.
SessionSerializer: Portable session bundle export and import with CRC verification.

6. Chrome Extension MV3 (`src/extension/`)

service-worker.ts: Background script maintaining WebSocket bridge connection, coordinating tab-specific recordings and hardware screenshot captures.
content-script.ts: Injected script managing on-page DOM observers, floating UI overlay, visual element picker, and canvas image cropping.
floating-controller.ts: Draggable glassmorphic floating widget allowing on-page recording control, event counter monitoring, and manual checkpoint capture.

7. MCP Server & Auto-Bridge Dispatcher (`src/mcp/`)

ForensicMCPServer: Universal JSON-RPC 2.0 server with on-demand auto-bridge.
MCPBridgeServer: High-performance HTTP/WebSocket server listening on port 3847.
LiveToolsHandler: Dispatches live commands over WebSocket bridge or local JSDOM fallback.

🤖 Model Context Protocol (MCP) Tools Reference

Complete 34-Tool Catalog

🌟 Live Browser Control & Visual Intelligence (13 Tools)

Tool	Description	Key Arguments
`inspect_live_page`	Inspect active page URL, title, viewport, dimensions, and readyState	`{}`
`inspect_live_element`	Deeply inspect live element bounds, styles, visibility, attributes, state, role, aria	`selector`, `nodeId`, `selectedElementRef`
`get_selected_element`	Retrieve element picked visually via `Ctrl + Shift + Click`	`{}`
`start_element_picker`	Activate interactive visual element picker mode with hover highlight	`highlightColor`
`stop_element_picker`	Deactivate visual element picker mode	`{}`
`capture_page_screenshot`	Capture full visible viewport screenshot with clean overlay hiding	`format` (`png` / `jpeg`)
`capture_element_screenshot`	Capture element-bounded screenshot cropped to target bounds and DPR	`selector`, `nodeId`, `selectedElementRef`
`interact_with_element`	Perform action (`click`, `hover`, `type`, `focus`, `clear`, `press_key`, `select_option`, `scroll`)	`action`, `selector`, `text`, `key`, `optionValue`, `scrollDelta`, `waitForStabilization`
`start_element_observation`	Start focused continuous observation around target element	`selector`, `nodeId`
`stop_element_observation`	Stop observation and receive complete mutation & root-cause correlation bundle	`{}`
`get_live_dom_snapshot`	Capture current live virtual DOM state snapshot in HTML or JSON	`format` (`html` / `json`)
`get_live_dom_subtree`	Reconstruct and extract live HTML structure of a subtree	`selector`, `nodeId`
`get_element_visual_state`	Inspect layout, occlusion, clipping, opacity, z-index, and viewport visibility	`selector`, `nodeId`

🕰️ Historical Forensics & Time-Travel (21 Tools)

Tool	Description	Key Arguments
`list_sessions`	List recorded forensic sessions with stats and metadata	`limit`
`get_session`	Get full metadata, capabilities, and stats for a session	`sessionId`
`export_session`	Export session as portable JSON bundle	`sessionId`
`import_session`	Import session from raw JSON string	`bundleJson`
`delete_session`	Remove session from storage	`sessionId`
`get_timeline`	Retrieve event category timeline breakdown	`sessionId`
`get_events`	Query events by category, type, timestamp, or selector	`sessionId`, `category`, `type`, `fromTimestamp`, `toTimestamp`, `limit`
`get_events_around`	Retrieve contextual event slice around timestamp/event	`sessionId`, `timestamp`, `eventId`, `windowMs`
`get_dom_state`	Reconstruct virtual DOM tree at timestamp $T$	`sessionId`, `timestamp`, `sequence`, `format`
`get_dom_node`	Query exact properties of a node at timestamp $T$	`sessionId`, `nodeId`, `selector`, `timestamp`
`get_dom_subtree`	Reconstruct HTML structure of a subtree at timestamp $T$	`sessionId`, `selector`, `nodeId`, `timestamp`
`diff_dom`	Calculate structural diff between two timestamps or events	`sessionId`, `t1`, `t2`, `e1`, `e2`, `format`
`trace_element`	Reconstruct complete lifecycle history of an element	`sessionId`, `nodeId`, `selector`
`find_disappearing_elements`	Scan session for elements with short lifespans	`sessionId`, `maxLifespanMs`
`why_did_element_disappear`	Automated diagnostic engine pinpointing disappearance root cause	`sessionId`, `target`
`get_diagnostics`	Retrieve console logs, uncaught errors, and promise rejections	`sessionId`, `level`, `category`
`get_network_events`	Retrieve fetch/XHR network requests and responses	`sessionId`, `status`, `method`, `query`
`get_screenshots`	Retrieve visual screenshot checkpoints	`sessionId`
`annotate_session`	Add developer hypothesis or diagnostic note	`sessionId`, `text`, `timestamp`, `tags`
`get_annotations`	Retrieve all notes and annotations for a session	`sessionId`
`get_recording_health`	Verify data integrity, sequence continuity, and dropped frames	`sessionId`

Representative MCP Tool Invocations

1. Automated Root-Cause Diagnosis (`why_did_element_disappear`)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "why_did_element_disappear",
    "arguments": {
      "sessionId": "live_session_001",
      "target": ".ai-action-btn"
    }
  }
}

Response Preview:

{
  "targetNodeId": 10,
  "targetSelector": ".ai-action-btn",
  "disappearanceMechanism": "PARENT_SUBTREE_REPLACED",
  "confidenceScore": 92,
  "likelyRootCause": "Host framework (e.g. React/Vue re-render) destroyed and replaced Ancestor container [ID: 4], causing injected element to be unmounted",
  "evidentiaryTrail": [
    "At T=250.0ms, Network response completed for /api/refresh (Status: 200)",
    "At T=280.0ms, Ancestor container #host-sidebar [ID: 4] was removed from DOM",
    "At T=280.0ms, Injected element .ai-action-btn [ID: 10] unmounted as part of ancestor subtree removal"
  ],
  "actionableRecommendation": "Avoid injecting directly into volatile component tree #host-sidebar. Mount inside a stable portal container or attach MutationObserver re-mount guard."
}

2. Live Element Inspection (`inspect_live_element`)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "inspect_live_element",
    "arguments": {
      "selector": "#prompt-textarea"
    }
  }
}

3. Live Clean Cropped Element Screenshot (`capture_element_screenshot`)

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "capture_element_screenshot",
    "arguments": {
      "selector": "#prompt-textarea"
    }
  }
}

🚀 Installation & Quick Start

1. Global System Installation (One-Click)

To make all 34 MCP capabilities globally available across ALL projects in Antigravity IDE:

git clone https://github.com/IrMaho/Mcp-DOM.git
cd Mcp-DOM
npm install
npm run build
npm link

# Install globally into ~/.gemini/config/plugins/browser-forensics
dom-antigravity install --global

2. Workspace Installation for Any Project

To install the MCP server configuration into any specific project directory:

# Inside any project directory:
dom-antigravity install --workspace

# Or specify a target directory:
dom-antigravity install --target "C:/Users/ASUS/Desktop/flutter_project/my_project"

This creates .agents/mcp_config.json with all 34 tools authorized and registers .agents/skills/browser-forensics/SKILL.md.

3. Load Chrome Extension in Browser

Open Google Chrome and navigate to chrome://extensions.
Enable Developer mode in the top-right corner.
Click Load unpacked and select the dist/ directory (or root mcp_dom/).
The Forensic Debugger extension will connect automatically to ws://127.0.0.1:3847.

4. Configure External AI Clients (Claude / Cursor / Cline)

To print ready-to-copy JSON configuration files:

# For Cursor (.cursor/mcp.json)
dom-antigravity config cursor

# For Claude Desktop (claude_desktop_config.json)
dom-antigravity config claude

🧪 Testing & Quality Verification

The repository includes a comprehensive testing hierarchy combining unit tests, integration channels, end-to-end multi-agent scenarios, and an automated operational acceptance suite:

# 1. Run full Vitest unit & E2E suite (20 suites, 53 tests)
npm test

# 2. Run real Stdio JSON-RPC Operational Acceptance Suite (34/34 CERTIFIED)
npm run test:operational

# 3. Run real Subprocess IPC E2E Test
npm run test:e2e:mcp

Verification Results

================================================================
⚡ MCP-DOM REAL STDIO JSON-RPC OPERATIONAL ACCEPTANCE TEST SUITE
================================================================
[Phase 1] Executing Dynamic MCP Capability Discovery...
✔ Discovered 34 exposed MCP tools from runtime definition.

[Phase 2] Seeding Deterministic Historical Forensic Session...
✔ Historical session 'operational_acceptance_session_001' seeded.

[Phase 3] Launching Real MCP Server Subprocess over stdio JSON-RPC...
✔ MCP Stdio Server connected: browser-forensic-mcp (Protocol 2024-11-05)

[Phase 4] Executing Operational Tests Across All 34 Tools over stdio JSON-RPC...
✔ 001/034 list_sessions ................ PASS
✔ 002/034 get_session .................. PASS
✔ 015/034 why_did_element_disappear .... PASS
✔ 022/034 inspect_live_page ............ PASS
✔ 023/034 inspect_live_element ......... PASS
✔ 027/034 capture_page_screenshot ...... PASS
✔ 028/034 capture_element_screenshot ... PASS
✔ 029/034 interact_with_element ........ PASS
✔ 034/034 get_element_visual_state ..... PASS

================================================================
🎉 OPERATIONAL SUITE EXECUTION COMPLETE: 34/34 PASSED
Certification Status: CERTIFIED
================================================================

🔐 Security, Privacy & Performance

Privacy Masking by Default: PrivacyEngine automatically masks password fields, credit card patterns (Luhn-compliant), Social Security numbers, bearer tokens, API keys, and custom user-specified CSS selectors.
Sandboxed Replay Security: Replay viewport strips all inline on* event handlers and disables script execution, preventing arbitrary code execution.
Low-Overhead Streaming: Observers use requestAnimationFrame and requestIdleCallback throttling to ensure zero dropped frames on recorded pages.
Clean Compositor Framing: Hiding extension UI overlays during screenshots ensures zero visual contamination.

❓ Troubleshooting & FAQ

Q: Do I need to run `npm run bridge` in a separate terminal?

A: No! ForensicMCPServer includes zero-config auto-bridge. Whenever an AI agent or client connects via MCP, the server automatically initializes the WebSocket bridge on port 3847 in the background.

Q: How do I test capturing a real Chrome screenshot?

A: Run dom-antigravity screenshot in your terminal. It connects to your active Chrome tab, captures a pristine full-page screenshot and cropped element screenshot, and saves them to disk.

Q: Why are my element screenshots corrupted in some viewers?

A: The built-in PNGBuilder generates 100% standard PNG binaries with complete IHDR, IDAT, IEND chunks, Adler-32 and CRC-32 checksums, compatible with all image viewers.

📜 License

Licensed under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License in the LICENSE file or at:

http://www.apache.org/licenses/LICENSE-2.0

Available Tools

34 tools

annotate_sessionC

Add an investigative annotation or hypothesis to the session timeline.

Inputs: label (required), comment (required), sessionId (required), nodeId, +1 more.

capture_element_screenshotB

Capture an element-specific screenshot bounded to the target element exact geometry and device pixel ratio.

Inputs: nodeId, selector, selectedElementRef.

capture_page_screenshotA

Capture a screenshot of the visible browser page viewport with temporal, scroll, and viewport metadata.

Inputs: format.

delete_sessionB

Delete a recording session from storage.

Inputs: sessionId (required).

diff_domA

Compare two DOM states between timestamp T1 and T2 (or event E1 and E2) and return structured additions, removals, moves, attribute, style, and text changes.

Inputs: sessionId (required), e1, e2, t1, +1 more.

export_sessionA

Export a complete recording session as a portable, self-contained JSON bundle.

Inputs: sessionId (required).

find_disappearing_elementsC

Automatically scan the session and identify all elements that existed temporarily and were subsequently removed or hidden.

Inputs: sessionId (required), maxLifespanMs.

get_annotationsB

Retrieve all human and AI annotations created for a session.

Inputs: sessionId (required).

get_diagnosticsA

Query recorded console messages, runtime errors, and unhandled promise rejections with stack traces.

Inputs: sessionId (required), level, toTimestamp, fromTimestamp.

get_dom_nodeB

Inspect detailed properties of a specific DOM node at a given timestamp (tag, attributes, text, parent, children, visibility state).

Inputs: sessionId (required), nodeId, selector, timestamp.

get_dom_stateA

Reconstruct the complete DOM snapshot at an arbitrary timestamp or event ID using checkpoint delta replay.

Inputs: sessionId (required), format, eventId, timestamp.

get_dom_subtreeA

Reconstruct and extract the HTML of a specific subtree (e.g. #app or .gpt-panel) at a given timestamp.

Inputs: sessionId (required), nodeId, selector, timestamp.

get_element_visual_stateA

Inspect detailed visual layout, occlusion, clipping, opacity, z-index, and viewport visibility for a live element.

Inputs: nodeId, selector.

get_eventsC

Query recorded events with filtering by category (DOM, USER, ERROR, CONSOLE, NETWORK, etc.), type, timestamp range, target node, or search query.

Inputs: sessionId (required), type, limit, offset, +6 more.

get_events_aroundA

Retrieve a focused contextual window of events occurring immediately before and after a specific timestamp or event ID.

Inputs: sessionId (required), eventId, windowMs, timestamp.

get_live_dom_snapshotA

Capture the current live virtual DOM state snapshot of the active browser page in HTML or structured JSON format.

Inputs: format.

get_live_dom_subtreeA

Reconstruct and extract the live HTML or node structure of a specific subtree on the active browser page.

Inputs: nodeId, selector.

get_network_eventsA

Query recorded network requests and responses correlated with timing and duration.

Inputs: sessionId (required), statusFilter.

get_recording_healthA

Run an automated integrity audit on a recording session to check sequence monotonicity, missing nodes, and capability health.

Inputs: sessionId (required).

get_screenshotsA

List visual checkpoints and screenshot checkpoints captured during the recording session.

Inputs: sessionId (required).

get_selected_elementA

Retrieve the DOM element visually selected by the user via Ctrl + Shift + Mouse Click in the live browser.

Inputs: no named parameters.

get_sessionA

Retrieve full metadata, capabilities, health status, and statistics for a specific debugging session.

Inputs: sessionId (required).

get_timelineB

Retrieve summary breakdown of events across the session timeline, including event categories and significant milestones.

Inputs: sessionId (required).

import_sessionB

Import a recording session bundle from raw JSON string.

Inputs: bundleJson (required).

inspect_live_elementA

Deeply inspect a live DOM element on the active browser page by CSS selector, LogicalNodeId, or selectedElementRef, returning bounds, computed styles, visibility, attributes, state, role, aria, and parent context.

Inputs: xpath, nodeId, selector, selectedElementRef.

inspect_live_pageA

Inspect the current live browser page state, including URL, title, viewport dimensions, scroll positions, readyState, active and focused elements.

Inputs: no named parameters.

interact_with_elementA

Perform an interaction (click, double_click, right_click, hover, focus, blur, type, clear, press_key, select_option, scroll_into_view, scroll) on a live element and return before/after state and effect measurements.

Inputs: action (required), key, text, nodeId, +6 more.

list_sessionsA

List all recorded browser forensic debugging sessions with metadata, timestamps, and stats.

Inputs: limit.

start_element_observationB

Start focused continuous recording and observation around a target element and its subtree/ancestors.

Inputs: nodeId, selector.

start_element_pickerA

Activate the interactive visual element picker mode in the live browser with hover highlighting and click selection.

Inputs: highlightColor.

stop_element_observationA

Stop focused element observation and assemble a complete correlation bundle with mutations, diagnostics, network activity, and root-cause analysis.

Inputs: no named parameters.

stop_element_pickerA

Deactivate the visual element picker mode in the browser and restore normal cursor and interaction state.

Inputs: no named parameters.

trace_elementA

Trace the entire chronological lifecycle of a DOM element from creation, mounting, mutations, style changes to unmounting/removal.

Inputs: sessionId (required), nodeId, selector.

why_did_element_disappearA

Forensic root-cause diagnosis for why an injected or existing UI element disappeared. Pinpoints removal mechanism, ancestor container destruction, style changes, and correlated errors/network triggers.

Inputs: target (required), sessionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

B3.4/5.0

Scored 2026-09-01 19:40 across 34 tools

Disambiguation4/5

Tools are largely grouped by clear domains: session management, recorded forensics, and live inspection. The recorded vs live distinction is usually clear (get_dom_* vs get_live_dom_*), but a few live inspection tools such as inspect_live_element, get_live_dom_snapshot, and get_element_visual_state overlap enough that an agent may need to read descriptions carefully.

Naming Consistency4/5

Most tools follow a predictable snake_case verb_noun pattern like list_sessions, get_events, capture_page_screenshot, and start_element_picker. The pattern is weakened by the question-style why_did_element_disappear and by phrases like get_events_around and interact_with_element, but overall naming remains consistent and readable.

Tool Count2/5

With 34 tools, this is well above the 25+ threshold that makes a tool surface feel heavy. Many inspection, observation, and element-state tools could be consolidated or grouped without losing core capability, so the count feels excessive for a single server.

Completeness4/5

The set covers session management, recorded event/DOM/network/console forensics, element lifecycle analysis, annotations, and live page inspection/interaction/observation. Minor gaps remain around live console diagnostics outside observation and lack of annotation mutation, but core debugging workflows are well supported.

Maintenance

ActivityStale

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

sncroA
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
https://relay.sncro.net/tools/mcp
mcp
com.screenshotink
Screenshot, diff, audit and sitemap-capture any web page — 5 MCP tools for AI agents.
Browser Automation Web Scraping
2
https://mcp.screenshotink.com/mcp
ReconstructB
dev.reconstruct
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Design Tools Developer Tools Testing & QA Tools
701
https://reconstruct.dev/mcp
chromedevtoolsmcp-mcp
com.clauxel.chromedevtoolsmcp
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
Browser Automation Developer Tools Agent Orchestration
2
https://chromedevtoolsmcp.clauxel.com/mcp

Related MCP Servers

visual-ui-debug-agent-mcp
Browser Automation Testing & QA Tools Developer Tools
samihalawa
A
license
C
quality
C
maintenance
An MCP server that enables AI agents to autonomously test, debug, and analyze web interfaces visually using Playwright, with 30 tools for screenshots, workflows, performance, and visual comparison.
Updated 11 days ago (2026-11-01 16:27 UTC)
30
48 npm
84
ISC
relay-inspect
Browser Automation Developer Tools Testing & QA Tools
samsolomon
A
license
A
quality
D
maintenance
Provides AI coding agents real-time browser access to console logs, network requests, DOM elements, and screenshots via MCP, enabling tight edit-reload-verify feedback loops.
Updated 8 months ago (2026-03-13 14:55 UTC)
15
3 npm
2
MIT
a11ydriver-mcp
Browser Automation Agent Orchestration
idugeni
F
license
Not graded
quality
B
maintenance
MCP server that enables AI agents to control Chrome via DevTools CDP and accessibility trees, providing 21 tools for browser automation including tab management, navigation, interactions, and page capture.
Updated 3 months ago (2026-08-13 05:56 UTC)
-
web-ui-tester
Browser Automation Testing & QA Tools
hofmeister
A
license
A
quality
B
maintenance
Enables AI agents to rapidly drive and inspect real web pages through persistent browser sessions, using accessibility-tree snapshots and DevTools-grade diagnostics to identify and diagnose issues.
Updated a month ago (2026-09-27 19:25 UTC)
26
MIT

⚡ Browser Forensic Recorder, Live DOM Intelligence & Universal MCP Server

📖 Table of Contents

⚡ Overview & Why This Project Exists

The Solution

✨ Key Features

💻 Dedicated Universal CLI (dom-antigravity)

🏗️ System Architecture

Dual-Environment Execution Model

High-Level Architecture Diagram

⚡ Zero-Config On-Demand Auto-Bridge

📸 Clean Screenshot & Visual Forensics Pipeline

📁 Repository Structure

🧩 Core Subsystems & Module Breakdown

1. Core Recording & Live Control Engine (src/core/)

2. Time-Travel & Query Engine (src/reconstruction/)

3. Structural Diff Engine (src/diff/)

4. Lifecycle & Forensics Engine (src/lifecycle/)

5. Storage & Indexing (src/storage/)

6. Chrome Extension MV3 (src/extension/)

7. MCP Server & Auto-Bridge Dispatcher (src/mcp/)

🤖 Model Context Protocol (MCP) Tools Reference

Complete 34-Tool Catalog

🌟 Live Browser Control & Visual Intelligence (13 Tools)

🕰️ Historical Forensics & Time-Travel (21 Tools)

Representative MCP Tool Invocations

1. Automated Root-Cause Diagnosis (why_did_element_disappear)

2. Live Element Inspection (inspect_live_element)

3. Live Clean Cropped Element Screenshot (capture_element_screenshot)

🚀 Installation & Quick Start

1. Global System Installation (One-Click)

2. Workspace Installation for Any Project

3. Load Chrome Extension in Browser

4. Configure External AI Clients (Claude / Cursor / Cline)

🧪 Testing & Quality Verification

Verification Results

🔐 Security, Privacy & Performance

❓ Troubleshooting & FAQ

Q: Do I need to run npm run bridge in a separate terminal?

Q: How do I test capturing a real Chrome screenshot?

Q: Why are my element screenshots corrupted in some viewers?

📜 License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

visual-ui-debug-agent-mcp

relay-inspect

a11ydriver-mcp

web-ui-tester

💻 Dedicated Universal CLI (`dom-antigravity`)

1. Core Recording & Live Control Engine (`src/core/`)

2. Time-Travel & Query Engine (`src/reconstruction/`)

3. Structural Diff Engine (`src/diff/`)

4. Lifecycle & Forensics Engine (`src/lifecycle/`)

5. Storage & Indexing (`src/storage/`)

6. Chrome Extension MV3 (`src/extension/`)

7. MCP Server & Auto-Bridge Dispatcher (`src/mcp/`)

1. Automated Root-Cause Diagnosis (`why_did_element_disappear`)

2. Live Element Inspection (`inspect_live_element`)

3. Live Clean Cropped Element Screenshot (`capture_element_screenshot`)

Q: Do I need to run `npm run bridge` in a separate terminal?