MCP 服务器

TraceBug

Local stdio MCP server that gives AI coding agents (Claude Code, Cursor, Windsurf) read-tools over TraceBug bug-report .html files — session replay, console errors with stacks, network activity, and a millisecond repro timeline. All data is read from local disk; zero network connections. Free, MIT. Unedited crash-to-root-cause transcript: tracebug.dev/proof

README

<h1 align="center">TraceBug</h1>

Bug reports your dev can actually open. Local-first. One <code>.html</code> file with full replay, console errors, network requests, and screenshots. Opens offline.

<a href="https://tracebug.dev/#demo"><img src="./website/public/tracebug-demo-poster.png" alt="TraceBug 15-second demo — a crash happens, TraceBug catches it live, one click builds the ticket" width="820"></a> <a href="https://tracebug.dev/#demo">▶ Watch the 15-second demo</a> · <a href="https://tracebug.dev/proof">watch Claude debug a real bug</a> · <a href="https://tracebug.dev/try.html">try it live in the sandbox</a>

TraceBug is a local-first debugging assistant. Capture a bug → produce a single self-contained .html file → email/Slack it to a dev → they open it offline and see exactly what happened.

Every report opens with:

🔍 Possible Cause (high confidence): API POST /orders failed with 500 after clicking 'Place Order'
> TL;DR: TypeError thrown on /checkout when clicking 'Place Order' button

No accounts. No SaaS lock-in. Data stays in your browser by default.

Optional cloud sharing (built, UI-gated off by default): if you'd rather share a URL than a file, sign in once and get a share link with the same content. The code ships behind a feature flag (PHASE2-CLOUD); the Share button stays disabled until the portal is switched on. Local .html export is the supported sharing path today.

Works with any frontend framework: React, Angular, Vue, Next.js, Nuxt, Vite, Svelte, SvelteKit, Remix, Astro, or plain HTML.

⚡ Get Started in 30 Seconds

New here? Report your first bug in 2 minutes →

npx tracebug init

That's it. The CLI detects your framework and prints the exact 2-line snippet. Paste it into your app, run npm run dev, and you'll see the TraceBug toolbar on the right edge.

Report a bug in 2 clicks:

Press Ctrl+Shift+B (or click the ⚡ button on the toolbar)
Review the auto-filled report, click "Copy GitHub Issue"
Paste into your repo. Done.

What TraceBug Does

Tester opens the page
  ↓
Arm a session (idle until you act):
  • ⚡ Quick Bug      — Ctrl+Shift+B opens the ticket-review modal
  • 📷 Screenshot / Region
  • 🔴 Record         — Sentry mode: rolling video buffer + HUD with timestamped
                        comments. File multiple bugs from one screen-share.
  • ⏺ Track session   — event-only capture (no video). Survives full-page
                        navigation, so clicking a link keeps recording.
  ↓
The SDK captures: clicks, inputs, navigation, API calls, console, errors, the DOM
stream (rrweb), environment, and a redacted Web-Storage snapshot
  ↓
Review the ticket, then export:
  • Export .html          — self-contained interactive DOM replay (KB, not MB)
  • Export for AI (.html) — tiny text-only report to paste into a chat
  • Download report (.md) · Export HAR · file a real GitHub/Linear/Slack/Jira issue
  ↓
Complete report includes:
  - Auto-generated title + smart summary + root-cause hint (high/medium/low confidence)
  - Steps to reproduce, full session timeline
  - Interactive DOM replay (or screen recording .webm), screenshots
  - Console errors + stack traces, failed network requests with response snippets
  - Environment (browser, OS, viewport, device)
  ↓
Send the .html → developer opens it offline and sees exactly what happened,
or an MCP-connected coding agent reads it and debugs from it.

Scan Page (a11y via axe-core, broken images, mixed content, frustration signals, failed/slow APIs, JS errors) is available programmatically as TraceBug.scanPage(); it is no longer a toolbar button.

Two Ways to Use TraceBug

Option 1: npm Package (For Developers)

Install the SDK in your project — best for teams who want TraceBug always active on dev/staging.

npm install tracebug-sdk

import TraceBug from "tracebug-sdk";
TraceBug.init({ projectId: "my-app" });

Option 2: Chrome Extension (For Non-Developers)

Install the browser extension — no code needed. QA testers, PMs, and clients can use it on any website.

Install from Chrome Web Store — one click, works immediately.

Browser	Supported
Chrome	Yes — install from Chrome Web Store
Edge	Yes — Chrome Web Store extensions work natively
Brave	Yes — Chrome Web Store extensions work natively
Opera	Yes — install "Install Chrome Extensions" add-on first
Firefox	Not yet — use the npm SDK instead

Browser support

Browser	npm SDK	Extension
Chrome	✅	✅
Edge	✅	✅
Brave / Opera	✅	✅
Firefox	✅	⏳ (port paused — SDK only)
Safari	✅¹	❌ (SDK only)

The SDK is framework- and browser-agnostic — it runs anywhere modern JS runs. ¹ The interactive DOM-replay export uses the browser-native CompressionStream / DecompressionStream (Chrome 80+, Firefox 113+, Safari 16.4+); on older engines the exporter ships the replay uncompressed and the viewer falls back to the screenshot gallery. The extension is Chromium-only today (Firefox port paused; no Safari build) — on those, use the npm SDK.

Features

🧠 Debugging Assistant (v1.3)

Every report opens with four derived signals that turn "what happened" into "why it likely happened":

Signal	What it looks like
🔍 Root Cause Hint	`"API POST /orders failed with 500 after clicking 'Place Order'"` with confidence tier (high/medium/low)
TL;DR	One-sentence summary combining network + error + click + page signals
User clicked	Tag, text, selector, id, aria-label, testId for the last click before the bug
Recent Actions	Last ~10 user actions as plain-English steps (`"Clicked 'Edit' button"`, `"Navigated to /checkout"`)

Plus:

Network response snippets — first 200 chars of every failed fetch/XHR response body, captured asynchronously (never blocks the request)
In-memory failure buffer — last 10 failed requests accessible via TraceBug.getNetworkFailures()
Deterministic — pure functions, no AI APIs, O(1) on already-computed report fields

All four signals ship inline in GitHub issues, Jira tickets, PDF reports, and the Quick Bug modal. See docs/bug-reporting.md for full output examples.

🤖 MCP Server — AI Agents Debug Your Reports (v1.5)

Your coding agent (Claude Code, Cursor, Windsurf, VS Code) reads TraceBug bug reports and fixes the bug — fully local, nothing uploaded:

claude mcp add tracebug -- npx -y tracebug mcp --dir ./bug-reports

The server reads the same self-contained .html files TraceBug exports. A tester hands a dev the report file, the dev drops it in the repo, and the agent gets six tools: list_bug_reports, get_bug_report, get_console_errors, get_network_activity, get_repro_steps, and get_screenshot (real image content). get_bug_report returns a prioritized investigation guide computed from what the report contains, so the agent knows exactly which tools to call next. Console stacks + failed-request bodies + repro steps + frustration signals — everything an agent needs to go from bug report to fix.

Kicking off is one paste: the extension shows a ready-made agent prompt after every Export .html (auto-copied), the exported file itself carries the same prompt in its AI tab, and in Claude Code you can just type /tracebug:debug_bug_report.

Other tools' MCP servers are cloud-hosted: your bug data must live on their servers first. TraceBug's runs on your machine over stdio and opens zero network connections. Try it instantly — this repo ships a demo report and a pre-configured .mcp.json. See docs/mcp.md.

🎭 Playwright Reporter — Bug Reports From Failed Tests (v1.6)

Every failed Playwright test becomes the same self-contained .html bug report — assertion error + code snippet, step timeline as repro steps, page console + network (via the optional fixture), failure screenshot, and a root-cause hint. Upload bug-reports/ as a CI artifact, then debug it with your agent via the MCP server:

// playwright.config.ts — that's the whole setup
reporter: [["list"], ["tracebug-sdk/playwright", { outputDir: "bug-reports" }]],

Nobody else captures bugs from test runs as portable files — cloud tools can't attach their viewer to a CI artifact. See docs/playwright.md.

🧠 AI Debugger — BYO-Key LLM Analysis (v1.6)

Run real LLM root-cause analysis with your own key — Anthropic, OpenAI, or local Ollama. The call goes directly from your browser to the provider: TraceBug never sees the key, the prompt, or the response, and the prompt is scrubbed of secret shapes before it leaves the page. No metered credits, no vendor cloud in the path.

Combined with the local heuristic hint and the local MCP server, this is AI debugging that never phones home — the one position no cloud-hosted, metered competitor can copy. See docs/ai-debugger.md.

🌐 HAR Export (v1.6)

One click exports the captured network activity as a standard HAR 1.2 file that opens in DevTools, Charles, Fiddler, or Postman. No competitor ships this — Jam even markets "everything a HAR offers" without the export. Your network capture is a portable file you own, not a row in someone's cloud. See docs/har-export.md.

Auto-Captured (Zero Effort)

What	Details
Clicks	Element tag, text, id, className, aria-label, role, data-testid, href, button type
Inputs	Field name, type, value (sensitive fields auto-redacted), placeholder
Dropdowns	Selected option text + value, all available options
Form Submits	Form id, action, method, all field values (passwords redacted)
Navigation	Route from → to (supports pushState, replaceState, popstate)
API Requests	URL, method, status code, response time (both `fetch` and `XMLHttpRequest`)
Errors	Message, stack trace, source file, line, column
Console Errors	`console.error()` calls
Unhandled Rejections	Promise rejection reason + stack
Environment	Browser, OS, viewport, device type, connection, language, timezone

Sentry Mode — Rolling Video Buffer

Click Record once at the start of a QA session, file as many bug tickets as you want from the same screen-share. Inspired by NVIDIA Shadowplay / OBS replay buffer.

Feature	What it does
One-time picker	Click Record → pick screen/window/tab in the OS dialog. The HUD appears; you do QA normally.
📸 Capture button	Snapshots the in-progress recording into a finished `.webm` and opens the ticket modal. Recording keeps running.
Timestamped comments	Type a note in the HUD → press Enter → it's saved with the current video timestamp.
Auto-capture on error	When a JS error fires while armed, the error toast offers "Capture with video" — one click captures the buffer.
Smart Stop	If you took at least one capture, Stop ends silently. Otherwise it opens the modal with the full recording.

Auto-Scanner

Click Scan to run six in-browser detectors in parallel and surface issues you might not have noticed:

Detector	What it catches
a11y	WCAG 2.0/2.1 A+AA violations via axe-core
Broken images	`<img>` elements that failed to load
Mixed content	`http://` resources on HTTPS pages (CSP-blocked or downgraded)
JS errors	Deduped console errors + unhandled rejections
Failed requests	4xx/5xx/network-error API calls with response body snippets
Slow APIs	Successful calls over 2s

Each issue offers Locate (flash the offending element), File ticket (pre-fills the Quick Bug modal), and Dismiss.

QA Tools (One Click)

Tool	What it does
Quick Bug Capture	`Ctrl+Shift+B` opens the ticket-review modal with auto-filled title + description
Screenshot	Captures viewport with auto-generated name (e.g., `01_click_add_vendor.png`); added to the active ticket
Region Screenshot	Drag-to-select snipping-tool style; added to ticket
Voice Note	Speak to describe the bug — speech-to-text via Web Speech API
GitHub Issue	Generates complete GitHub markdown — copies to clipboard, screenshots + .webm auto-download
Jira Ticket	Generates Jira markup with priority + labels

Available Programmatically (cut from default UI in v1.0)

These features still ship in the bundle but no longer have toolbar buttons. Power users can call them directly:

TraceBug.activateAnnotateMode();   // element annotate mode (Ctrl+Shift+A no longer wired)
TraceBug.activateDrawMode();       // live-page rectangles/ellipses
TraceBug.downloadPdf();            // PDF report
TraceBug.exportAnnotationsJSON();  // JSON / Markdown export

Auto-Generated

Output	Details
Bug Title	Smart title from session context (e.g., "Vendor Update Fails — TypeError")
Repro Steps	Numbered steps generated from event timeline
Session Timeline	Debug timeline with elapsed timestamps for every event
Environment Snapshot	Browser version, OS, viewport, device type, connection

Smart Filtering

SDK self-filtering: TraceBug never records its own UI interactions (clicks on the dashboard, annotation canvas, buttons)
Framework noise removal: Internal dev-server requests (webpack HMR, Vite ping, Next.js stack frames) are automatically excluded from timeline and reports
Duplicate error dedup: Consecutive identical errors are collapsed

User Identification & Bug Workflow

// Identify who's using the app (persisted in localStorage)
TraceBug.setUser({ id: "user_123", email: "dev@co.com", name: "Jane" });

// Flag current session as a bug (adds red BUG badge)
TraceBug.markAsBug();

// Get a 2-sentence Slack-friendly summary
const summary = TraceBug.getCompactReport();
// "Bug on /vendor — TypeError: Cannot read 'status' after clicking Edit → selecting Inactive..."

Plugin & Hook System

Extend TraceBug without forking — filter events, enrich reports, or trigger custom actions:

TraceBug.use({
  name: "slack-webhook",
  onReport: (report) => { fetch("https://hooks.slack.com/...", { method: "POST", body: JSON.stringify(report) }); return report; },
});

TraceBug.on("error:captured", (error) => console.log("Bug found:", error.data.error.message));

CI/CD Helpers

// In Playwright/Cypress tests
expect(TraceBug.getErrorCount()).toBe(0);

// Upload full session as test artifact on failure
const json = TraceBug.exportSessionJSON();

Installation

From npm

npm install tracebug-sdk

From GitHub

npm install github:prashantsinghmangat/tracebug-ai

Chrome Extension (No Code Required)

See Chrome Extension section below.

Configuration

TraceBug.init({
  projectId: "my-app",        // Required: identifies your app
  maxEvents: 200,             // Max events per session (default 200)
  maxSessions: 50,            // Max sessions in localStorage (default 50)
  enableDashboard: true,      // Show the floating bug button (default true)
  enabled: "auto",            // Control when SDK is active (see below)
});

`enabled` option

Value	Behavior
`"auto"`	Enabled in dev/staging, disabled in production (default)
`"development"`	Only when `NODE_ENV` is `"development"`
`"staging"`	Dev + staging hosts (`staging`, `stg`, `uat`, `qa` in hostname)
`"all"`	Always enabled, including production
`"off"`	Completely disabled
`string[]`	Custom hostnames, e.g. `["localhost", "staging.myapp.com"]`

Programmatic API

Core

import TraceBug from "tracebug-sdk";

TraceBug.pauseRecording();
TraceBug.resumeRecording();
TraceBug.startRecording();   // alias for resumeRecording
TraceBug.stopRecording();    // alias for pauseRecording
TraceBug.isRecording();
TraceBug.getSessionId();
TraceBug.destroy();

Screenshots

// Capture full-viewport screenshot (auto-named from last event context)
const screenshot = await TraceBug.takeScreenshot();
// → { filename: "01_click_add_vendor.png", dataUrl: "data:image/png;...", ... }

// Snipping-tool style: user drags a region, press Esc to cancel
const region = await TraceBug.takeRegionScreenshot();
// → { filename: "02_click_..._region.png", ... } | null

const allScreenshots = TraceBug.getScreenshots();

Voice Recording

// Check if voice recording is supported in the browser
if (TraceBug.isVoiceSupported()) {
  // Start recording — speech-to-text via Web Speech API (free, no API keys)
  TraceBug.startVoiceRecording({
    onUpdate: (text, interim) => console.log("Transcript:", text),
    onStatus: (status, msg) => console.log("Status:", status),
  });

  // Stop recording — returns the transcript
  const transcript = TraceBug.stopVoiceRecording();
  // → { id, timestamp, text: "When I click update the page breaks", duration }

  // Get all voice transcripts
  TraceBug.getVoiceTranscripts();
}

Voice transcripts are automatically included in GitHub Issue, Jira Ticket, and PDF reports.

Tester Notes

TraceBug.addNote({
  text: "Button doesn't respond after selecting Inactive status",
  expected: "Vendor should update successfully",
  actual: "App throws TypeError and freezes",
  severity: "critical",  // "critical" | "major" | "minor" | "info"
});

Reports

// Generate complete bug report object
const report = TraceBug.generateReport();

// Get auto-generated bug title
const title = TraceBug.getBugTitle();
// → "Vendor Update Fails — TypeError"

// Get GitHub issue markdown (copies to clipboard in dashboard)
const markdown = TraceBug.getGitHubIssue();

// Get Jira ticket payload
const ticket = TraceBug.getJiraTicket();
// → { summary, description, environment, priority, labels }

// Download PDF report
TraceBug.downloadPdf();

// Get environment info
const env = TraceBug.getEnvironment();
// → { browser: "Chrome", browserVersion: "122", os: "Windows 10/11", ... }

Data Access

import { getAllSessions, clearAllSessions, deleteSession } from "tracebug-sdk";

const sessions = getAllSessions();
const bugs = sessions.filter(s => s.errorMessage);
clearAllSessions();
deleteSession("session-id");

Standalone Utilities

import {
  generateReproSteps,
  captureEnvironment,
  buildReport,
  generateGitHubIssue,
  generateJiraTicket,
  generateBugTitle,
  buildTimeline,
  formatTimelineText,
} from "tracebug-sdk";

Element Annotation & Draw

// Activate modes programmatically
TraceBug.activateAnnotateMode();   // Click elements to annotate
TraceBug.activateDrawMode();       // Draw shapes on the page

// Check state
TraceBug.isAnnotateModeActive();
TraceBug.isDrawModeActive();

// Export all annotations
const report = TraceBug.getAnnotationReport();
const md = TraceBug.exportAnnotationsMarkdown();
await TraceBug.copyAnnotationsToClipboard("markdown");

// Deactivate
TraceBug.deactivateAnnotateMode();
TraceBug.deactivateDrawMode();
TraceBug.clearAnnotations();

Dashboard

The compact toolbar on the right edge of the screen provides:

⚡ Quick Bug — open the ticket-review modal (Ctrl+Shift+B)
📷 Screenshot — capture the page, with an annotation editor
▢ Region — capture a selected region
🔴 Record — screen recording (Sentry mode: rolling buffer + HUD)
⏺ Track session — event-only capture, no video (survives navigation)
✓ View saved tickets — the offline Saved Tickets list
✕ — turn TraceBug off on this page

Annotate and Draw modes still ship in the bundle but were cut as standalone toolbar buttons in v1.0 — reach them programmatically or via the recording HUD's Pen button. See docs/annotate-and-draw.md.

Quick Bug modal

Review and edit the ticket, then export or file it:

Auto-generated title, summary, root-cause hint, reproduction steps, timeline
Interactive DOM replay (or the screen recording), screenshots gallery
Tabs: Info · Console · Network · Actions · AI · Events
Export: Export .html (replay) · Export for AI (.html) · Download report (.md) · Export HAR
File directly: GitHub · Linear · Slack · Jira (real issues with a configured token)

Keyboard Shortcuts

Shortcut	Action
`Ctrl+Shift+B`	Open the Quick Bug ticket modal
`Ctrl+Shift+S`	Take a screenshot
`Esc`	Exit the current mode / close the modal

Note: Ctrl+Shift+A (annotate) and Ctrl+Shift+D (draw) are no longer bound by default. The underlying modes remain callable via the programmatic API (TraceBug.activateAnnotateMode() / activateDrawMode()); draw mode is also reachable from the ✎ button on the recording HUD.

Documentation

Full documentation is in the docs/ folder:

Getting Started — Install, setup, first use
API Reference — Complete programmatic API
Configuration — All config options explained
Bug Reporting — Screenshots, notes, voice, export
MCP Server — Let AI agents (Claude Code, Cursor) debug your reports
Annotate & Draw — UI annotation features
Chrome Extension — Extension install & usage
Architecture — How TraceBug works internally

Chrome Extension

The TraceBug Chrome Extension lets non-developers use all TraceBug features without writing code.

How to Install

Recommended: Install from Chrome Web Store — works in Chrome, Edge, Brave, and Opera.

From source (for developers):

git clone this repo, then npm install && npm run build
Open chrome://extensions/ → Enable Developer mode → Load unpacked → select tracebug-extension/

How to Use

Navigate to any website (staging, production, localhost, internal tools)
Click the TraceBug extension icon in the toolbar
Toggle "Enable on this site" — the page reloads with TraceBug active
The floating bug button appears on the page
Use all QA tools: screenshots, notes, GitHub/Jira issues, PDF reports
Quick actions also available directly from the extension popup

Extension Features

Per-site toggle — enable only on sites you're testing
Badge indicator — shows "ON" in green when active on current tab
Quick actions — Annotate, Draw, Screenshot, PDF Report, GitHub Issue, Jira Ticket from the popup
Active sites list — manage all enabled sites from the popup
Compact toolbar on page — same full-featured toolbar as the npm SDK
CSP-safe — uses chrome.scripting.executeScript with world: "MAIN" to bypass Content Security Policy restrictions

Browser Compatibility

Browser	Supported
Google Chrome	Yes
Microsoft Edge	Yes
Brave	Yes
Opera	Yes (install "Install Chrome Extensions" add-on first)
Firefox	Not yet — use the npm SDK

Chrome Web Store

TraceBug is published on the Chrome Web Store:

Install TraceBug Extension

Build from Source

# Clone the repo
git clone https://github.com/prashantsinghmangat/tracebug-ai.git
cd tracebug-ai

# Install dependencies
npm install

# Build SDK (produces CJS + ESM + IIFE for extension)
npm run build

# Output:
#   dist/index.js              — ESM (npm package)
#   dist/index.cjs             — CJS (npm package)
#   dist/index.d.ts            — TypeScript declarations
#   tracebug-extension/tracebug-sdk.js — IIFE (Chrome Extension)

Run Example App

cd example-app
npm install
npm run dev
# Open http://localhost:3000

Test the Example Bug

Go to /vendor
Click "Edit"
Change Status to "Inactive"
Click "Update" — triggers TypeError
Click the bug button to see the report with reproduction steps

Privacy

Sensitive fields auto-redacted (password, secret, token, ssn, credit)
All data stays in localStorage — nothing leaves the browser
SDK never captures its own UI interactions
No external servers, no tracking, no analytics

Framework Compatibility

Format	File	Works with
ESM (`import`)	`dist/index.js`	Vite, Next.js, Nuxt, SvelteKit, modern webpack
CJS (`require`)	`dist/index.cjs`	Angular CLI, older webpack, Node.js
IIFE (global)	`tracebug-extension/tracebug-sdk.js`	Chrome Extension, plain `<script>` tag
TypeScript	`dist/index.d.ts`	Full type support in both ESM and CJS

Uninstall

npm Package

npm uninstall tracebug-sdk

Then remove the TraceBug.init() call from your app's entry file.

⭐ Star this repo if it saves you time

If TraceBug helped you ship faster, a star is the best way to say thanks — it helps other developers find it too.

Spread the word:

Found a bug or have a feature idea? Open an issue — TraceBug was built because bug reports sucked. We're here to make them suck less.

Built with ❤ by <a href="https://github.com/prashantsinghmangat">Prashant Singh Mangat</a> MIT Licensed · No tracking · No backend · Your data stays in your browser

Chrome Extension

Go to chrome://extensions/ → click Remove on TraceBug.

License

MIT

Author

Prashant Singh Mangat

GitHub: prashantsinghmangat
npm: tracebug-sdk

TraceBug

README

⚡ Get Started in 30 Seconds

What TraceBug Does

Two Ways to Use TraceBug

Option 1: npm Package (For Developers)

Option 2: Chrome Extension (For Non-Developers)

Browser support

Features

🧠 Debugging Assistant (v1.3)

🤖 MCP Server — AI Agents Debug Your Reports (v1.5)

🎭 Playwright Reporter — Bug Reports From Failed Tests (v1.6)

🧠 AI Debugger — BYO-Key LLM Analysis (v1.6)

🌐 HAR Export (v1.6)

Auto-Captured (Zero Effort)

Sentry Mode — Rolling Video Buffer

Auto-Scanner

QA Tools (One Click)

Available Programmatically (cut from default UI in v1.0)

Auto-Generated

Smart Filtering

User Identification & Bug Workflow

Plugin & Hook System

CI/CD Helpers

Installation

From npm

From GitHub

Chrome Extension (No Code Required)

Configuration

enabled option

Programmatic API

Core

Screenshots

Voice Recording

Tester Notes

Reports

Data Access

Standalone Utilities

Element Annotation & Draw

Dashboard

Quick Bug modal

Keyboard Shortcuts

Documentation

Chrome Extension

How to Install

How to Use

Extension Features

Browser Compatibility

Chrome Web Store

Build from Source

Run Example App

Test the Example Bug

Privacy

Framework Compatibility

Uninstall

npm Package

⭐ Star this repo if it saves you time

Chrome Extension

License

Author

推荐服务器

`enabled` option