<div align="center">
  <img src="assets/logo.svg" alt="MCP Console Hub" width="120" height="120">
  <h1>mcp-console-hub</h1>
  <p><strong>Your browser's DevTools, streamed to your IDE's AI agent.</strong></p>
  <p>
    <a href="https://www.npmjs.com/package/mcp-console-hub"><img src="https://img.shields.io/npm/v/mcp-console-hub?style=flat-square&color=06b6d4" alt="npm"></a>
    <a href="https://www.npmjs.com/package/mcp-console-hub"><img src="https://img.shields.io/npm/dm/mcp-console-hub?style=flat-square&color=06b6d4" alt="downloads"></a>
    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square" alt="MCP"></a>
    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-20%2B-green?style=flat-square" alt="Node"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat-square" alt="License"></a>
  </p>
</div>

---

## What It Captures

| DevTools Tab | What's Captured | Details |
|--------------|----------------|---------|
| **Console** | `console.error/warn/log/info/debug` | With stack traces for errors/warnings |
| **Console** | Unhandled exceptions | `window.onerror` with file + line + column |
| **Console** | Promise rejections | `unhandledrejection` with stack |
| **Network** | All fetch/XHR requests | Method, URL, status, duration, headers, body preview, size |
| **Network** | Failed requests | 4xx, 5xx, connection errors with details |
| **Application** | localStorage | All key-value pairs |
| **Application** | sessionStorage | All key-value pairs |
| **Application** | Cookies | Name, value, domain, path |
| **Application** | IndexedDB | Database names |
| **Performance** | Navigation timing | TTFB, DOM loaded, load complete, DNS, connect |
| **Performance** | Resource loading | JS, CSS, images, fonts with duration + size |
| **Performance** | Memory | Heap size (Chrome only) |
| **Performance** | Marks & Measures | Custom performance marks |

Zero code changes. One bookmarklet. Works with any web app.

---

## Quick Start

### 1. Configure your IDE

<details>
<summary><strong>Cursor</strong></summary>

```json
{
  "mcpServers": {
    "mcp-console-hub": {
      "command": "npx",
      "args": ["-y", "mcp-console-hub@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>VSCode</strong></summary>

```json
{
  "servers": {
    "mcp-console-hub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-console-hub@latest"]
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add mcp-console-hub npx -y mcp-console-hub@latest
```
</details>

<details>
<summary><strong>Antigravity / Windsurf / OpenCode</strong></summary>

```json
{
  "mcpServers": {
    "mcp-console-hub": {
      "command": "npx",
      "args": ["-y", "mcp-console-hub@latest"]
    }
  }
}
```
</details>

### 2. Connect your browser

Open **http://localhost:3200** — drag the bookmarklet to your bookmarks bar.

Navigate to any web app. Click the bookmarklet.

### 3. Ask your AI agent

```
@mcp-console-hub Diagnose all errors and suggest fixes
@mcp-console-hub Show all network failures
@mcp-console-hub Read localStorage and explain the app state
@mcp-console-hub Audit page performance
@mcp-console-hub Fix errors by priority — most critical first
```

---

## MCP Tools (24 tools)

### Console (7 tools)
| Tool | Description |
|------|-------------|
| `query_console` | Filter by level, source, text, time, stack |
| `get_entry_context` | Full context with parsed stack frames + timeline |
| `get_error_chains` | Detect cascading errors (root cause analysis) |
| `get_repeated_patterns` | Find recurring messages |
| `parse_stack_trace` | Structured frames: function, file, line, col |
| `find_by_file` | Find all errors from a specific source file |
| `get_unhandled_errors` | Runtime exceptions + promise rejections |

### Network (4 tools)
| Tool | Description |
|------|-------------|
| `query_network` | Filter by method, status, URL, duration |
| `get_network_detail` | Full request/response: headers, body, timing |
| `get_network_errors` | All 4xx, 5xx, and connection failures |
| `get_slow_requests` | Requests above duration threshold |

### Storage (3 tools)
| Tool | Description |
|------|-------------|
| `read_storage` | All storage: localStorage, sessionStorage, cookies, IndexedDB |
| `read_storage_key` | Read specific key with auto JSON parse |
| `get_cookies` | List/search cookies |

### Performance (2 tools)
| Tool | Description |
|------|-------------|
| `get_performance` | Navigation timing, resources, memory, marks |
| `get_slow_resources` | Find slow-loading JS, CSS, images, fonts |

### General (4 tools)
| Tool | Description |
|------|-------------|
| `get_console_stats` | Aggregated statistics |
| `get_page_info` | Page URL, user agent, all data availability |
| `get_timeline` | Chronological event sequence |
| `clear_console` | Clear all captured data |

### Export (1 tool)
| Tool | Description |
|------|-------------|
| `export_report` | Full DevTools report as JSON or Markdown |

---

## MCP Prompts (7 prompts)

| Prompt | Trigger | Description |
|--------|---------|-------------|
| `diagnose` | `/diagnose` | Full analysis of errors + network + performance |
| `fix_by_priority` | `/fix_by_priority` | Prioritized fix list: Critical > High > Medium |
| `suggest_solution` | `/suggest_solution` | Concrete code fix for the most recent error |
| `debug_network` | `/debug_network` | Analyze failures, CORS issues, auth errors |
| `read_app_state` | `/read_app_state` | Analyze storage to understand app state |
| `performance_audit` | `/performance_audit` | Page load audit with optimization suggestions |
| `fix_entry` | `/fix_entry` | Step-by-step fix for the latest error |

---

## MCP Resources (12 resources)

| URI | Description |
|-----|-------------|
| `console://entries` | All console entries |
| `console://errors` | Error-level only |
| `console://warnings` | Warning-level only |
| `console://timeline` | Chronological timeline |
| `console://summary` | Aggregated stats |
| `network://requests` | All network requests |
| `network://errors` | Failed requests |
| `network://slow` | Slow requests (>1s) |
| `storage://snapshot` | Full storage snapshot |
| `storage://cookies` | Cookies only |
| `performance://data` | All performance data |
| `devtools://page` | Page info + data availability |

---

## How It Works

```
Browser (any web app)              MCP Console Hub                     IDE AI Agent
+-----------------+               +--------------------+              +----------------+
| Bookmarklet     |  WebSocket    |                    |    stdio     |                |
| captures:       |==============>|  Console Store     |<===========>|  24 MCP Tools  |
|                 |  :3201        |  Network Store     |              |  12 Resources  |
| - console.*     |               |  Storage Snapshot  |              |  7 Prompts     |
| - window.onerror|  HTTP POST    |  Performance Data  |              |                |
| - fetch/XHR     |-------------->|                    |              |  Cursor        |
| - localStorage  |  :3200        |  File-backed       |              |  VSCode        |
| - cookies       |               |  (.store/)         |              |  Claude Code   |
| - performance   |               |                    |              |  Antigravity   |
+-----------------+               +--------------------+              +----------------+
  zero code changes                  npx mcp-console-hub               IDE MCP config
```

---

## Ports & Environment

| Port | Protocol | Purpose |
|------|----------|---------|
| 3200 | HTTP | Connector page + health + ingestion |
| 3201 | WebSocket | Real-time data streaming |

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_CONSOLE_HUB_PORT` | `3200` | HTTP port |
| `MCP_CONSOLE_HUB_WS_PORT` | `3201` | WebSocket port |
| `MCP_CONSOLE_HUB_STORE_PATH` | auto | Custom store file path |

---

## License

MIT — see [LICENSE](LICENSE)

---

<div align="center">
  <sub>Built by <a href="https://github.com/nano-step"><strong>nano-step</strong></a> — Copyright &copy; 2026 Hoai Nho Nguyen</sub>
</div>