<div align="center">

<p align="center">
  <strong>🇺🇸 English</strong> · <a href="./docs/locales/ko.md">🇰🇷 한국어</a> · <a href="./docs/locales/ja.md">🇯🇵 日本語</a> · <a href="./docs/locales/zh-CN.md">🇨🇳 中文</a> · <a href="./docs/locales/es.md">🇪🇸 Español</a> · <a href="./docs/locales/de.md">🇩🇪 Deutsch</a><br />
  <a href="./docs/locales/fr.md">🇫🇷 Français</a> · <a href="./docs/locales/pt-BR.md">🇧🇷 Português</a> · <a href="./docs/locales/ru.md">🇷🇺 Русский</a> · <a href="./docs/locales/hi.md">🇮🇳 हिन्दी</a> · <a href="./docs/locales/ar.md">🇸🇦 العربية</a> · <a href="./docs/locales/id.md">🇮🇩 Bahasa Indonesia</a>
</p>

# ⚡ Vibeside MCP (`vibeside-mcp`)

> **The AI Browser & Live Dev Runtime Agent for Vibe Coding — Surpassing Aside.**

[![npm version](https://img.shields.io/badge/npm-v0.17.0-blue.svg)](https://www.npmjs.com/package/vibeside-mcp)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%20v1.0-purple.svg)](https://modelcontextprotocol.io/)

<sub>Architected & Licensed under Proprietary & Confidential (All Rights Reserved) · Zero-Latency Vibe Coding Infrastructure</sub>

</div>

---

<details open>
<summary><b>🌟 Overview & Why Vibeside MCP?</b></summary>

When vibe-coding with AI coding assistants (Claude Code, Cursor, Windsurf, Antigravity), developers frequently hit three massive friction points:
1. **Context Blindness**: The AI edits code, but cannot see what actually rendered on `localhost:3000`.
2. **Error Copy-Paste Fatigue**: When runtime hydration errors, uncaught exceptions, or 500 API responses occur, the developer must manually open browser DevTools and copy-paste stack traces into the chat.
3. **Component Guesswork**: AI has to guess which file renders a specific broken button or banner.

**Aside** (aside.com) introduced the idea of delegating browser tasks to an AI browser agent. However, Aside is a closed proprietary cloud shell with heavy latency, lacks local dev-server telemetry, and cannot map UI elements directly to component source code.

**Vibeside MCP** is engineered specifically for **Vibe Coding**: a zero-cloud-latency Model Context Protocol (MCP) server that hooks directly into your local browser (Chrome/Edge) with authenticated session reuse, real-time dev telemetry streaming, and Click-to-Component Fiber inspection.

</details>

---

<details open>
<summary><b>🥊 Feature Matrix: Aside vs Vibeside MCP</b></summary>

| Feature | Aside (aside.com) | ⚡ Vibeside MCP (`vibeside-mcp`) |
| :--- | :---: | :---: |
| **Source Accessibility** | ❌ Closed cloud black-box | **✅ Full Local Transparency & Direct Execution** |
| **Cloud Latency** | ⚠️ Relies on remote orchestration | **⚡ 0ms Zero-Latency (100% Local Stdio / FastMCP)** |
| **Authenticated Browser Sessions** | ✅ Yes (Browser shell) | **✅ Yes (Existing Chrome/Edge user profiles & CDP)** |
| **Live Dev Server Telemetry (Console/Errors)** | ❌ No active HMR hook | **✅ Auto-catches uncaught exceptions & 500s directly** |
| **Click-to-Source Component Mapper** | ❌ No | **✅ Resolves React Fiber & Vue AST to exact file & line** |
| **Interactive DOM Snapshot** | ⚠️ Raw DOM / Vision | **✅ Clean accessibility & interactive element tree** |
| **Secret & Cookie Security** | ⚠️ Proprietary store | **✅ Windows DPAPI zero-leak isolated profiles & age encryption** |
| **Pricing / Subscription** | 💳 Paid SaaS subscription | **🎁 Free for Developer Self-Hosting** |

</details>

---

<details open>
<summary><b>🛠️ Tool Suite (70 Core MCP Tools)</b></summary>

| Tool | Description |
| :--- | :--- |
| `vibeside_connect` | Connects to active Chrome/Edge via CDP on port `9315`, `9222`, etc. |
| `vibeside_navigate` | Navigates to any local or remote URL using existing authenticated sessions. |
| `vibeside_telemetry_get` | Fetches real-time uncaught exceptions, hydration errors, and 4xx/5xx failures. |
| `vibeside_telemetry_clear`| Clears the telemetry error ring buffer. |
| `vibeside_hmr_telemetry` | Queries live HMR dev server events, compiler errors, warnings, and rebuild latency. |
| `vibeside_hmr_clear` | Clears the live HMR telemetry event ring buffer and build health state. |
| `vibeside_inspect_component`| Resolves a clicked UI element to its React/Vue component name, file path, and line. |
| `vibeside_extract_styles` | Extracts computed styles, matched CSS rules, box model, and suggested Tailwind classes. |
| `vibeside_override_style` | Live-overrides CSS styles via inline attributes or injected stylesheet with XSS sanitization. |
| `vibeside_visual_diff` | Compares baseline and live screenshots (pixel diff, dHash, bounding boxes, magenta diff PNG). |
| `vibeside_perceptual_hash` | Computes 64-bit dHash, aHash, or Blockhash fingerprints for UI regression tracking. |
| `vibeside_click` | Clicks interactive elements by CSS selector or text query. |
| `vibeside_type` | Inputs text into input fields and textareas. |
| `vibeside_screenshot` | Captures viewport, full-page, or element-specific screenshots (Base64 or file). |
| `vibeside_dom_snapshot` | Returns a structured tree of interactive elements (buttons, inputs, links). |
| `vibeside_eval` | Executes arbitrary JavaScript expressions inside the browser context. |
| `vibeside_list_tabs` | Enumerate all open browser tabs and targets with active state, title, and URL. |
| `vibeside_switch_tab` | Switch active tab by index, target ID, URL substring, or title pattern. |
| `vibeside_new_tab` | Open a new browser tab with optional navigation and focus delegation. |
| `vibeside_close_tab` | Close an open browser tab with single-tab safeguard and adjacent focus switch. |
| `vibeside_inspect_storage` | Inspect cookies, LocalStorage, SessionStorage, and IndexedDB with JSON parsing and credential masking. |
| `vibeside_mutate_storage` | Set, delete, or clear storage items across cookies, LocalStorage, SessionStorage, or IndexedDB. |
| `vibeside_mock_route` | Intercept and mock HTTP REST and GraphQL requests with custom status, JSON/text payload, latency, or network faults. |
| `vibeside_list_mock_routes` | List all active route interception rules, hit count statistics, and remaining expiry counters. |
| `vibeside_clear_mock_routes` | Clear all active network mock rules or remove a specific rule by ID. |
| `vibeside_emulate_pseudo_state` | Forces CSS pseudo-classes (`hover`, `focus`, `active`, `visited`) via CDP or synthetic fallback. |
| `vibeside_clear_pseudo_states` | Clears active forced pseudo-states from a specific selector or across the entire document. |
| `vibeside_autofill_form` | Smart one-click form autofill with multi-locale heuristics (English & Korean) and custom value overrides. |
| `vibeside_inspect_form_validation` | Inspects HTML5 constraint validation states across all fields in a form or container. |
| `vibeside_record_session` | Controls offline telemetry recording lifecycle (start, pause, resume, stop, clear, or inspect recording status and metrics). |
| `vibeside_export_session` | Exports recorded session telemetry to NDJSON, JSON bundle, pure Node.js USTAR TAR, or compressed TAR.GZ. |
| `vibeside_import_session` | Imports session telemetry from disk file or inline content for offline time-travel debugging. |
| `vibeside_time_travel_inspect` | Reconstructs and inspects past runtime state, in-flight requests, and jumps to error milestones. |
| `vibeside_observe_dom_mutations` | Observes live DOM mutations, calculates sliding-window mutation rates, and detects re-render storm hotspots. |
| `vibeside_observe_layout_shifts` | Monitors Cumulative Layout Shift (CLS) events, calculates Core Web Vitals rating, and ranks culprit shifting elements. |
| `vibeside_observe_long_tasks` | Tracks main-thread Long Tasks (>50ms), computes estimated Total Blocking Time (TBT), and evaluates responsiveness. |
| `vibeside_clear_dom_telemetry` | Clears buffered DOM mutations, layout shifts, and long tasks telemetry records from memory. |
| `vibeside_spawn_browser` | Launches Chrome/Edge in headless or headed mode with remote debugging enabled (default port 9315) and zero-zombie process lifecycle management. |
| `vibeside_browser_status` | Inspects browser spawner daemon status, active PID, CDP HTTP reachability, and isolated user data profile directory. |
| `vibeside_stop_browser` | Cleanly terminates the spawned browser process tree and purges temporary user data directory. |
| `vibeside_create_profile` | Creates an isolated browser profile directory and configuration in the vault. |
| `vibeside_list_profiles` | Lists all browser vault profiles with storage metrics and active status. |
| `vibeside_switch_profile` | Switches active browser profile with optional browser restart or hot session restore. |
| `vibeside_delete_profile` | Safely deletes a browser profile and all associated session snapshots. |
| `vibeside_save_session_snapshot` | Captures active cookies and web storage into an encrypted vault (DPAPI or AES-256-GCM). |
| `vibeside_restore_session_snapshot` | Decrypts and restores cookies and web storage snapshot into active browser page. |
| `vibeside_list_session_snapshots` | Lists all encrypted session snapshots across profiles with metadata. |
| `vibeside_delete_session_snapshot` | Safely deletes an encrypted session snapshot file from the vault. |
| `vibeside_emulate_device` | Emulate mobile, tablet, or desktop device viewport, userAgent, touch, pixel ratio, and color scheme. |
| `vibeside_reset_emulation` | Reset viewport, device emulation, and optional network/CPU throttling to default desktop state. |
| `vibeside_capture_viewport_matrix` | Capture responsive audit across device presets (mobile, tablet, desktop) and detect layout overflow. |
| `vibeside_throttle_network` | Emulate network conditions (offline, slow-3g, fast-3g, regular-4g, fast-4g, custom, none) via CDP. |
| `vibeside_throttle_cpu` | Emulate CPU slowdown rate (1x to 20x) via CDP Emulation domain. |
| `vibeside_get_emulation_status` | Get current device emulation, viewport, network profile, and CPU throttling status. |
| `vibeside_list_network_profiles` | List available network condition profiles (2G, 3G, 4G, 5G, DSL, Wi-Fi, Fiber, Satellite) with category filtering and bandwidth specs. |
| vibeside_benchmark_network | Benchmark network latency (RTT), jitter, and effective throughput on the active page. |
| vibeside_cluster_status | Inspect multi-browser cluster worker pool status, active/idle workers, queue metrics, and configuration. |
| vibeside_cluster_configure | Configure worker pool limits (minWorkers, maxWorkers, idleTimeoutMs, maxTasksPerWorker, strategy, headless). |
| `vibeside_cluster_scale` | Manually scale the browser worker pool up or down to target worker count. |
| `vibeside_cluster_dispatch` | Dispatch a batch of parallel tasks (navigate, screenshot, extract, evaluate) across the worker pool. |
| `vibeside_cluster_shutdown` | Cleanly terminate all worker browser processes and purge temporary user profile directories. |
| `vibeside_inspect_media_streams` | Inspect HTML5 video/audio elements and WebRTC streams with playback quality and buffer health telemetry. |
| `vibeside_capture_video_frame` | Capture current frame of an HTML5 video element as base64 PNG or JPEG image with dimensions and timestamp. |
| `vibeside_observe_media_events` | Query buffered media events (play, pause, stalled, waiting, frame-drop-spike, error) with selector and time filters. |
| `vibeside_clear_media_telemetry` | Clear buffered media telemetry events for a specific selector or across all elements. |
| `vibeside_audit_accessibility` | Comprehensive automated WCAG 2.2 AA / AAA accessibility audit across 7 categories with scoring and remedies. |
| `vibeside_get_accessibility_tree` | Extract Chrome Accessibility (AX) tree with role breakdown, depth pruning, and element hierarchy. |
| `vibeside_inspect_contrast` | Calculate sRGB color contrast ratio against WCAG AA/AAA thresholds with remediation color suggestions. |
| `vibeside_inspect_aria_element` | Deep inspection of DOM element for WAI-ARIA 1.2/1.3 compliance, accessible name trace, and valid roles. |

</details>

---

<details open>
<summary><b>♿ Automated Accessibility (a11y) Tree & WCAG 2.2 AAA Audit</b></summary>

Automate full-page and subtree web accessibility audits, inspect Chrome's native accessibility tree, calculate sRGB contrast ratios with automated fix suggestions, and validate WAI-ARIA 1.2/1.3 semantic conformance:

#### 1. Full WCAG 2.2 AA / AAA Accessibility Audit
Run an automated audit across 7 categories (contrast, keyboard navigation, ARIA semantics, forms & labels, images & alt text, document structure, and touch target sizes):
```json
{
  "name": "vibeside_audit_accessibility",
  "arguments": {
    "selector": "body",
    "standard": "WCAG2.2-AA",
    "includeIssuesOnly": true
  }
}
```

#### 2. Extract Chrome Accessibility (AX) Tree
Inspect the computed accessibility tree with role frequency distribution and configurable depth pruning:
```json
{
  "name": "vibeside_get_accessibility_tree",
  "arguments": {
    "selector": "#main-content",
    "depth": 10,
    "interestingOnly": false
  }
}
```

#### 3. Inspect sRGB Color Contrast & Remediation Suggestions
Calculate exact contrast ratios ($L_1:L_2$) for on-page text elements or custom color pairs, evaluating against WCAG AA ($4.5:1 / 3:1$) and AAA ($7:1 / 4.5:1$) thresholds, with automated accessible replacement suggestions:
```json
{
  "name": "vibeside_inspect_contrast",
  "arguments": {
    "selector": "button.primary-action",
    "fontSizePx": 16,
    "isBold": false
  }
}
```

#### 4. Deep WAI-ARIA Conformance & Accessible Name Trace
Trace computed roles, accessible name resolution priority (aria-labelledby > aria-label > label > text > title), and validate ARIA attributes against W3C specification:
```json
{
  "name": "vibeside_inspect_aria_element",
  "arguments": {
    "selector": "div[role='slider']"
  }
}
```

</details>

---

<details open>
<summary><b>🌐 Zero-Config Chrome Headless Daemon & CDP Auto-Spawner</b></summary>

Never worry about manually launching a browser with debugging flags. Vibeside MCP includes a built-in background daemon that discovers installed Chrome, Edge, Brave, or Chromium binaries, and **automatically spawns a clean headless instance** on port 9315 if no active browser is running when you invoke a browser command.

You can also explicitly control the browser daemon lifecycle using dedicated MCP tools:

#### 1. Spawn a Browser Instance On-Demand
Launch a dedicated browser instance in headless mode (default) or headed mode with custom debugging ports, arguments, or isolated temporary profile directories:
```json
{
  "name": "vibeside_spawn_browser",
  "arguments": {
    "port": 9315,
    "headless": true
  }
}
```

#### 2. Inspect Spawner Daemon Status & CDP Reachability
Query the daemon state, process ID, listening CDP port, executable binary path, profile directory, and active HTTP reachability:
```json
{
  "name": "vibeside_browser_status",
  "arguments": {
    "checkCdp": true
  }
}
```

#### 3. Graceful Termination & Zero-Zombie Process Teardown
Cleanly terminate the spawned browser process tree (via Windows `taskkill` or POSIX process group signals) and automatically wipe temporary user profile directories:
```json
{
  "name": "vibeside_stop_browser",
  "arguments": {
    "cleanUserDataDir": true,
    "timeoutMs": 5000
  }
}
```

> **Automatic On-Demand Spawning**: When calling `vibeside_connect` or navigation actions without an open browser, Vibeside MCP automatically invokes the auto-spawner daemon in the background with zero developer intervention.

</details>

---

<details open>
<summary><b>⚡ Real-Time DOM Mutation & Layout Shift (CLS) Telemetry</b></summary>

Track live client-side DOM mutations, detect frontend re-render storms, and monitor Core Web Vitals Cumulative Layout Shift (CLS) alongside main-thread Long Tasks (>50ms):

#### 1. Observe DOM Mutations & Detect Re-Render Storms
Analyze real-time DOM mutations over a sliding window (default 5s) to detect infinite re-render loops and culprit component hotspots:
```json
{
  "name": "vibeside_observe_dom_mutations",
  "arguments": {
    "windowSeconds": 5,
    "stormThreshold": 30,
    "criticalThreshold": 100,
    "filterSelector": ".product-card"
  }
}
```

#### 2. Core Web Vitals CLS & Culprit Element Ranking
Capture unexpected layout shifts (`hadRecentInput === false`), assess Core Web Vitals compliance (`good`, `needs_improvement`, `poor`), and rank shifting elements:
```json
{
  "name": "vibeside_observe_layout_shifts",
  "arguments": {
    "unexpectedOnly": true,
    "limit": 50
  }
}
```

#### 3. Main-Thread Long Tasks & Total Blocking Time (TBT)
Identify JavaScript tasks blocking the browser main thread for over 50ms and calculate estimated Total Blocking Time (TBT):
```json
{
  "name": "vibeside_observe_long_tasks",
  "arguments": {
    "minDurationMs": 50,
    "limit": 50
  }
}
```

#### 4. Clear DOM Telemetry Ring Buffers
Reset telemetry buffers selectively or entirely:
```json
{
  "name": "vibeside_clear_dom_telemetry",
  "arguments": {
    "type": "all"
  }
}
```

</details>

---

<details open>
<summary><b>⏱️ Offline Telemetry Session Export & Time-Travel Debugging</b></summary>

Capture and reconstruct live development sessions for asynchronous triage, offline debugging, and bug reproduction:

#### 1. Start Telemetry Recording
```json
{
  "name": "vibeside_record_session",
  "arguments": {
    "action": "start",
    "name": "Checkout Flow Regression",
    "description": "Reproducing payment gateway timeout and hydration error",
    "tags": ["checkout", "payment", "p1"],
    "maxEvents": 5000
  }
}
```

#### 2. Export to Pure Node.js USTAR TAR or Compressed TAR.GZ
Export the session directly to disk or as an inline payload without third-party dependencies:
```json
{
  "name": "vibeside_export_session",
  "arguments": {
    "format": "tar.gz",
    "filePath": "./exports/checkout-debug-session.tar.gz"
  }
}
```

#### 3. Time-Travel Replay & Error Milestone Jump
Inspect the exact runtime state (active URL, console logs, in-flight requests, errors) at any past milestone:
```json
{
  "name": "vibeside_time_travel_inspect",
  "arguments": {
    "jumpTo": "first-error",
    "maxConsoleLogs": 20
  }
}
```

</details>

---

<details open>
<summary><b>🌐 Network Route Mocking & API Interception (REST & GraphQL Examples)</b></summary>

Mock external backend endpoints, slow APIs, or GraphQL queries directly inside the browser session without modifying backend code:

#### 1. REST Route Mocking
Intercept REST requests matching wildcard patterns or regex, returning simulated JSON payloads or HTTP errors:
```json
// Example: Mock GET /api/v1/user/profile with custom JSON and 250ms latency
{
  "name": "vibeside_mock_route",
  "arguments": {
    "urlPattern": "*/api/v1/user/profile",
    "method": "GET",
    "status": 200,
    "body": {
      "id": "usr_9921",
      "name": "Alex Rivera",
      "role": "Staff Engineer",
      "tier": "enterprise"
    },
    "delayMs": 250
  }
}
```

#### 2. GraphQL Operation Mocking
Target specific GraphQL queries and mutations by `operationName` while letting others pass through:
```json
// Example: Mock GraphQL GetUserProjects query with simulated latency
{
  "name": "vibeside_mock_route",
  "arguments": {
    "urlPattern": "*/graphql",
    "method": "POST",
    "operationName": "GetUserProjects",
    "status": 200,
    "body": {
      "data": {
        "projects": [
          { "id": "proj_101", "name": "Vibeside Runtime", "status": "active" },
          { "id": "proj_102", "name": "Telemetry Engine", "status": "shipped" }
        ]
      }
    },
    "times": 3
  }
}
```

#### 3. Inspecting & Clearing Active Mocks
```json
// List all active route interception rules and hit counts
{ "name": "vibeside_list_mock_routes" }

// Clear all active rules or a specific rule by ID
{ "name": "vibeside_clear_mock_routes" }
```

</details>

---

<details open>
<summary><b>📱 Adaptive Viewport Matrix & Device Emulation Grid</b></summary>

Emulate mobile, tablet, and desktop form factors with pixel ratios, touch events, User-Agent strings, and CSS media features. Audit responsive layouts for horizontal scroll blowouts and simulate real-world mobile network conditions and CPU throttling:

#### 1. Emulate Mobile or Tablet Form Factor
Apply an exact device preset (e.g., iPhone 16 Pro, Pixel 8, iPad Pro 11", Desktop 4K) or specify custom viewport dimensions:
```json
{
  "name": "vibeside_emulate_device",
  "arguments": {
    "device": "iPhone 16 Pro",
    "colorScheme": "dark",
    "reducedMotion": "no-preference"
  }
}
```

#### 2. Responsive Viewport Matrix & Layout Overflow Audit
Test responsive behavior across multiple form factors in a single call. Vibeside MCP identifies horizontal layout overflows (`scrollWidth > innerWidth`), ranks offending culprit elements, and audits `<meta name="viewport">` zoom accessibility:
```json
{
  "name": "vibeside_capture_viewport_matrix",
  "arguments": {
    "devices": ["iPhone 16 Pro", "Pixel 8", "iPad Pro 11", "Desktop FHD"],
    "detectOverflow": true,
    "auditViewportMeta": true
  }
}
```

#### 3. Network Conditions & CPU Throttling
Simulate Slow 3G, Fast 3G, Regular 4G, Fast 4G, or offline modes via CDP, and emulate CPU slowdown (1x to 20x) to test mid-tier mobile performance:
```json
// Simulate Slow 3G network conditions
{
  "name": "vibeside_throttle_network",
  "arguments": {
    "profile": "slow-3g"
  }
}

// Emulate 4x CPU slowdown
{
  "name": "vibeside_throttle_cpu",
  "arguments": {
    "rate": 4
  }
}
```

#### 4. Emulation Telemetry Status & One-Click Reset
```json
// Query composite emulation state
{ "name": "vibeside_get_emulation_status" }

// Reset viewport, media queries, network conditions, and CPU rate
{ "name": "vibeside_reset_emulation" }
```

</details>

---

<details open>
<summary><b>🎬 Audio/Video Media Stream Capture & Frame Telemetry</b></summary>

Inspect live HTML5 `<video>` and `<audio>` elements, diagnose playback buffer stalls and frame drops, trace WebRTC `RTCPeerConnection` streams, and extract video frames directly into base64 images:

#### 1. Inspect Media Elements & WebRTC Streams
Inspect all audio/video elements on the page, including buffer health, stall risks, and WebRTC inbound/outbound RTP stats:
```json
{
  "name": "vibeside_inspect_media_streams",
  "arguments": {
    "selector": "video#main-player"
  }
}
```

#### 2. Capture Video Frame as Base64 Image
Extract the exact current frame of an HTML5 video element with dimensions and timestamp (rendered via canvas with cross-origin security guards):
```json
{
  "name": "vibeside_capture_video_frame",
  "arguments": {
    "selector": "video#main-player",
    "format": "png",
    "quality": 0.92
  }
}
```

#### 3. Observe & Filter Media Telemetry Events
Query the 500-event bounded sliding window ring buffer for media playback lifecycle events (`play`, `pause`, `stalled`, `waiting`, `frame-drop-spike`, `error`):
```json
{
  "name": "vibeside_observe_media_events",
  "arguments": {
    "selector": "video#main-player",
    "eventType": "stalled",
    "limit": 25,
    "sinceMs": 60000
  }
}
```

#### 4. Clear Media Telemetry Buffer
```json
// Clear for a specific selector or across all elements
{
  "name": "vibeside_clear_media_telemetry",
  "arguments": {
    "selector": "video#main-player"
  }
}
```

</details>

---

<details open>
<summary><b>🚀 Quickstart & Setup</b></summary>

### 1. Launch Chrome with Remote Debugging (Optional)
Run your daily Chrome or Edge browser with remote debugging enabled (or simply let Vibeside MCP auto-spawn a headless browser daemon on demand):

```powershell
# Windows PowerShell
Start-Process chrome.exe -ArgumentList "--remote-debugging-port=9315", "--user-data-dir=$env:LOCALAPPDATA\Google\Chrome\User Data"
```

```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9315 --user-data-dir="$HOME/Library/Application Support/Google/Chrome"

# Linux
google-chrome --remote-debugging-port=9315 --user-data-dir="$HOME/.config/google-chrome"
```

### 2. Choose Your Installation Mode

You can run Vibeside MCP either as a **standalone native binary (recommended — zero Node.js/npm dependencies)** or via **Node.js / npx**.

---

#### 🌟 Option A: Standalone Binary Installation (Zero Node.js Dependency)

Precompiled, self-contained single executables are built for Windows, Linux, and macOS. You do **not** need Node.js or npm installed on your machine.

Download the latest release binary for your platform from [GitHub Releases](https://github.com/minseokchoi87/vibeside-mcp/releases):

| Platform | Architecture | Binary Asset | Checksum |
| :--- | :--- | :--- | :--- |
| **Windows** | x64 (AMD64) | `vibeside-mcp-windows-x64.exe` | SHA-256 (Authenticode Signed) |
| **Linux** | x64 (glibc 2.31+) | `vibeside-mcp-linux-x64` | SHA-256 |
| **macOS** | Apple Silicon (arm64) / Intel | `vibeside-mcp-darwin-arm64` | SHA-256 |

> **Tip for Linux / macOS**: Grant executable permissions after downloading:
> ```bash
> chmod +x vibeside-mcp-linux-x64      # Linux
> chmod +x vibeside-mcp-darwin-arm64    # macOS
> ```

##### Quick CLI Verification
Run the binary directly from your terminal to verify installation and view available tools:
```bash
./vibeside-mcp-windows-x64.exe --version
./vibeside-mcp-windows-x64.exe --list-tools
```

##### Configure MCP Clients (Standalone Binary Mode)

**Claude Desktop / Claude Code (`claude_desktop_config.json`)**:
```json
{
  "mcpServers": {
    "vibeside": {
      "command": "C:/path/to/vibeside-mcp-windows-x64.exe",
      "args": []
    }
  }
}
```
*(On macOS / Linux, specify `"command": "/usr/local/bin/vibeside-mcp-darwin-arm64"` or `"/usr/local/bin/vibeside-mcp-linux-x64"`)*

**Cursor / Windsurf / Antigravity / VS Code (`mcp.json`)**:
```json
{
  "mcpServers": {
    "vibeside": {
      "command": "C:/path/to/vibeside-mcp-windows-x64.exe",
      "args": []
    }
  }
}
```

---

#### 📦 Option B: Node.js / npx Mode

If you already have Node.js (>= 20) installed, you can launch Vibeside MCP directly with `npx` or point to a local checkout:

**Claude Desktop / Claude Code (`claude_desktop_config.json`)**:
```json
{
  "mcpServers": {
    "vibeside": {
      "command": "npx",
      "args": ["-y", "vibeside-mcp"]
    }
  }
}
```

**Cursor / Windsurf / Antigravity / VS Code (`mcp.json`)**:
```json
{
  "mcpServers": {
    "vibeside": {
      "command": "npx",
      "args": ["-y", "vibeside-mcp"]
    }
  }
}
```

</details>

---

<details open>
<summary><b>📄 License & Attribution</b></summary>

Copyright (c) 2026 minseokchoi87 <w871075@gmail.com>. All Rights Reserved.  
Licensed under [PROPRIETARY & CONFIDENTIAL SOFTWARE LICENSE](LICENSE).  
Upstream open-source notices and component attributions are preserved in [NOTICE](NOTICE).

</details>