Why MCP Error Hub?

When you see an error in your browser, the typical debugging flow looks like this:

Open DevTools → find error → copy stack trace → switch to IDE → paste into AI chat → manually describe context → AI guesses → repeat

MCP Error Hub removes every manual step. Errors stream from your browser to your IDE's AI agent automatically — with full state context, source file mapping, and actionable fix suggestions.

Your AI agent sees exactly what your app's Error Hub shows. No copy-pasting. No context loss. No guessing.

How It Works

Browser                          MCP Error Hub                        IDE
┌──────────────┐                ┌───────────────────┐               ┌──────────────┐
│              │   WebSocket    │                   │    stdio      │              │
│  Your App    │───────────────>│   Error Store     │<────────────>│  Cursor       │
│              │   :3101        │   (file-backed)   │               │  VSCode       │
│  Click the   │                │                   │               │  Claude Code  │
│  bookmarklet │   HTTP POST    │   MCP Resources   │               │  Antigravity  │
│  to connect  │───────────────>│   MCP Tools       │               │  Windsurf     │
│              │   :3100        │   MCP Prompts     │               │  OpenCode     │
└──────────────┘                └───────────────────┘               └──────────────┘
     Zero code changes               npx mcp-error-hub                IDE MCP config

Three components, each independent:

1. MCP Server — Receives errors, stores them, exposes via MCP protocol
2. Browser Connector — Bookmarklet that finds your Redux store and streams state changes (zero code)
3. IDE Config — Standard MCP server config (2 lines of JSON)

Quick Start

1. Configure your IDE

Add MCP Error Hub to your IDE's MCP configuration:

{
  "mcpServers": {
    "mcp-error-hub": {
      "command": "npx",
      "args": ["-y", "mcp-error-hub@latest"]
    }
  }
}

{
  "servers": {
    "mcp-error-hub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-error-hub@latest"]
    }
  }
}

claude mcp add mcp-error-hub npx -y mcp-error-hub@latest

Settings → MCP Servers → Add:

• Command: npx
• Arguments: -y, mcp-error-hub@latest

{
  "mcpServers": {
    "mcp-error-hub": {
      "command": "npx",
      "args": ["-y", "mcp-error-hub@latest"]
    }
  }
}

{
  "mcp": {
    "mcp-error-hub": {
      "type": "local",
      "command": ["npx", "-y", "mcp-error-hub@latest"],
      "enabled": true
    }
  }
}

Your IDE will start the MCP server automatically.

2. Open the Connector Dashboard

Open http://localhost:3100 in your browser. You will see the MCP Error Hub connector page:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                    ⚡ MCP Error Hub                          │
│   Bridge browser errors to your IDE — zero code changes     │
│                                                             │
│   ┌──────────┐  ┌──────────┐  ┌────────────────┐           │
│   │ ● HTTP   │  │ ● WS     │  │ ○ App          │           │
│   │  :3100   │  │  :3101   │  │  Not connected │           │
│   └──────────┘  └──────────┘  └────────────────┘           │
│                                                             │
│   Zero-Code Setup                                           │
│   ┌─────────────────────────────────────────────┐           │
│   │ 1. Drag this button to your Bookmarks Bar   │           │
│   │    ┌──────────────┐                         │           │
│   │    │ MCP Connect  │  ← drag to bookmarks    │           │
│   │    └──────────────┘                         │           │
│   │ 2. Open your app in the browser             │           │
│   │ 3. Click the bookmarklet                    │           │
│   │ 4. Ask your IDE's AI agent                  │           │
│   └─────────────────────────────────────────────┘           │
│                                                             │
│   ┌─────────────────────────────────────────────┐           │
│   │ ● Connected! 10 error(s) synced.            │           │
│   │ Your IDE can now query these errors.        │           │
│   └─────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

The dashboard shows:

• Server status — HTTP and WebSocket ports with live indicators
• App connection status — updates automatically every 3 seconds
• Bookmarklet — drag-and-drop "MCP Connect" button
• Console snippet — copy-paste alternative
• Error count — shows synced errors in real-time

3. Drag the Bookmarklet

On the connector page, find the purple "MCP Connect" button. Click and hold it, then drag it up to your browser's bookmarks bar and release. This is a one-time setup.

  Bookmarks Bar:  [ Gmail ] [ GitHub ] [ MCP Connect ]  ← drag here

4. Activate on your app

Navigate to your app (e.g. http://localhost:8100), wait for it to fully load, then click "MCP Connect" in your bookmarks bar.

Open the browser console (F12) to confirm:

[MCP Error Hub] WebSocket connected
[MCP Error Hub] Connected! Errors will sync to your IDE in real-time.

Go back to http://localhost:3100 — the status will update to:

- ○ App: Not connected
+ ● App: 10 errors          ← live error count

- Waiting for browser connection...
+ Connected! 10 error(s) synced. Your IDE can now query these errors.

Note: Click the bookmarklet once per page load. If you refresh (F5), click it again. The beforeunload handler ensures no errors are lost during refresh.

5. Verify via health endpoint

You can also check the server status programmatically:

curl http://localhost:3100/health

{
  "status": "ok",
  "errors": 10,
  "uptime": 3600.5
}

• errors: 0 — browser not connected yet, or no errors in app
• errors: N — N unique errors synced, IDE can query them

6. Ask your AI agent

@mcp-error-hub What errors are in the Error Hub?
@mcp-error-hub Diagnose all errors and suggest fixes
@mcp-error-hub Fix error #3

Connection Options

| Method | Code Changes | Setup | Best For | | -------------------- | ------------ | ------------------------------------------ | ---------------------------------------- | | Bookmarklet | Zero | Drag to bookmarks bar, click per page load | Most users — no source code changes | | Console snippet | Zero | Paste in DevTools each time | Quick testing | | Redux middleware | 3 lines | Add to store config + .env variable | Automatic connection without bookmarklet | | HTTP POST | Custom | Send JSON to /ingest endpoint | Non-Redux apps, custom integrations |

Redux Middleware (optional)

import { createMcpErrorMiddleware } from "mcp-error-hub/client";

if (process.env.MCP_ERROR_HUB_URL && process.env.NODE_ENV !== "production") {
  middlewares.push(
    createMcpErrorMiddleware({
      serverUrl: process.env.MCP_ERROR_HUB_URL, // http://localhost:3100
    }),
  );
}

MCP Resources

| URI | Description | | ------------------------- | -------------------------------------------------------- | | errors://current | All errors with context, source hints, occurrence counts | | errors://timeline | Chronological error flow with timestamps | | errors://config/banners | Banner config debug queue with validation results | | errors://config/popups | Popup config debug queue with validation results | | errors://config/widgets | Widget config debug queue with validation results | | errors://summary | Statistics: counts by tag, type, level, top errors |

MCP Tools

| Tool | Parameters | Description | | --------------------- | --------------------------------------------------- | --------------------------------------------------------- | | query_errors | tags level search since limit errorType | Filter errors by any combination of criteria | | get_error_context | errorId | Full context: source files, suggested fix, related config | | get_config_debug | type configId | Inspect banner/popup/widget processing results | | clear_errors | tags | Clear all errors or by specific tags | | get_error_stats | — | Breakdown by tag, type, level with top errors | | export_debug_report | format | Export everything as JSON or Markdown |

MCP Prompts

| Prompt | Description | | ----------- | -------------------------------------------------------------------------------------- | | diagnose | Analyze all errors, group by root cause, identify cascading failures, prioritize fixes | | fix_error | Step-by-step fix for a specific error with source hints and config context |

Ports & Environment

| Port | Protocol | Purpose | | ---- | --------- | --------------------------------------------- | | 3100 | HTTP | Connector page, health check, error ingestion | | 3101 | WebSocket | Real-time error streaming from browser |

| Variable | Default | Description | | -------------------------- | ------- | ----------------------------------------------------- | | MCP_ERROR_HUB_PORT | 3100 | HTTP receiver port | | MCP_ERROR_HUB_WS_PORT | 3101 | WebSocket receiver port | | MCP_ERROR_HUB_STORE_PATH | auto | Custom file store path | | MCP_ERROR_HUB_URL | — | Browser middleware target (if using Redux middleware) |

Error Type Coverage

26 error types across 7 categories, each mapped to relevant source files with suggested fix actions:

| Category | Error Types | | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Banner | BannerNotFound BannerNotValid BannerPopupNotFound BannerPopupAmbiguous BannerPopupMalformed BannerDataNotFound | | Popup | PopupNotFound PopupNotValid BrazePopupNotFound AssociatedPopupNotFound AssociatedPopupMalformed CircularReferenceDetected | | Widget | WidgetNotFound WidgetPopupNotFound WidgetPopupAmbiguous WidgetPopupMalformed WidgetDataNotFound WidgetPromotionNotActive | | Promotion | PromotionNotFound PromotionMissing PromotionMismatch | | Image | ImageWrongRatio ImageNotFound | | Purchase | PurchaseFailed MissingPurchasePromotion | | Config | EmbeddedConfigStructureError EmbeddedConfigSegmentNameError |

Roadmap

Q2 2026 — Foundation                                              ✓ CURRENT
├── Real-time streaming (WebSocket + HTTP dual transport)
├── 26 error types with source file mapping
├── Zero-code bookmarklet connector
├── Multi-IDE support (Cursor, VSCode, Claude Code, Antigravity, Windsurf, OpenCode)
├── File-backed persistent store (shared across instances)
└── AI-optimized prompts (diagnose, fix_error)

Q3 2026 — Intelligence
├── Auto-fix code patch generation
├── Error pattern detection and alerts
├── Natural language error search
├── Sentry / Datadog production error correlation
└── MCP resource subscriptions (push notifications)

Q4 2026 — Collaboration
├── Team error dashboard
├── Error annotation and resolution tracking
├── Slack / Teams notifications
├── Custom error type plugin system
└── Error trend analytics

Q1 2027 — Platform
├── Remote hosted MCP server (OAuth 2.0)
├── Error replay with state snapshots
├── Framework adapters (Zustand, MobX, Pinia, Svelte)
└── VS Marketplace / JetBrains plugin

Tech Stack

| Component | Technology | | -------------- | --------------------------------------- | | Runtime | Node.js 20+, TypeScript 5.5 | | MCP SDK | @modelcontextprotocol/sdk v1.12+ | | Transport | WebSocket (ws), native HTTP | | Persistence | File-based JSON (zero database deps) | | Browser Client | Bookmarklet + optional Redux middleware |

Project Structure

mcp-error-hub/
├── src/
│   ├── index.ts                  Entry point: stdio + HTTP + WebSocket
│   ├── server.ts                 MCP server factory
│   ├── store/
│   │   ├── types.ts              Shared types
│   │   ├── error-store.ts        File-backed store
│   │   └── source-map.ts         Error type → source mapping
│   ├── transport/
│   │   ├── http-receiver.ts      HTTP + connector page
│   │   └── ws-receiver.ts        WebSocket receiver
│   ├── resources/index.ts        6 MCP resources
│   ├── tools/index.ts            6 MCP tools
│   └── prompts/index.ts          2 MCP prompts
├── client/
│   ├── mcp-error-client.ts       Redux middleware
│   └── index.ts                  Client exports
└── assets/
    └── logo.svg                  Logo

Contributing

Contributions welcome. Please open an issue to discuss before submitting a PR.

License

MIT — see LICENSE