bugsnap-mcp
bugsnap-mcp lets AI coding agents read and diagnose BugSnap bug reports locally over stdio.
List/search recent captures by keyword and status (
open,in-progress,fixed,closed), with limit up to 25.Fetch full diagnostic context for a capture by UUID or share URL, including annotated screenshots, descriptions, team comments with pixel coordinates, console exceptions/stack traces, failed network requests, user action steps, runtime environment, and an AI fix blueprint.
Use MCP resources (
bugsnap://captures/recent,bugsnap://captures/{id}) to attach recent/capture context to chat.Run guided prompts:
bugsnap_fix_bugandbugsnap_triage_open_bugs.Read/query only; it does not mutate captures, workspaces, or billing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bugsnap-mcp check my latest bug report and tell me how to fix it"
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.
bugsnap-mcp
Official Model Context Protocol (MCP) server for BugSnap.
Gives AI coding agents (Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible client) direct multimodal access to your BugSnap bug reports:
📸 High-resolution annotated screenshots (transferred directly as base64 image blocks for vision LLMs).
🔢 Sequential step pins (①, ②, ③) (automatically guides agents through user interaction sequences).
📍 User annotations & team comments with exact spatial pixel coordinates (
pin_x,pin_y).👣 Chronological user action steps (clicks, inputs, and navigation breadcrumbs leading up to the bug).
🔴 Console exceptions & stack traces captured automatically from the browser DevTools.
🌐 Failed network requests (HTTP 4xx/5xx status codes, request methods, and endpoints).
🖥️ Runtime environment (URL, OS, browser, viewport dimensions).
🎯 Actionable AI Fix Blueprint (a structured diagnostic plan preventing coding agents from guessing or modifying the wrong component).
⚠️ Smart Ambiguity Guardrail (if a bug report has no written description and no visual markings, the agent pauses and asks the user directly instead of guessing).
Runs 100% locally over stdio. No server hosting required. The server exposes read/query tools, resources, and guided prompts only; it does not mutate captures, workspaces, or billing.
Validation
For routine changes, run the smallest relevant checks first:
npm run buildUse complete validation for release/commit work or when explicitly requested. Never place API keys, service-role credentials, or authentication artifacts in the repository.
Related MCP server: feedbug-mcp
🚀 Quick Start (Installation & Setup)
1. Get Your BugSnap API Key
Open the BugSnap Dashboard.
Go to Settings BugSnap API Keys.
Click Generate API Key and copy your key (starts with
bugsnap_...).
2. Install & Build the MCP Server
You can install bugsnap-mcp locally on your machine in 2 minutes:
# 1. Clone the repository
git clone https://github.com/akusaradigital/bugsnap-mcp.git
# 2. Enter the directory
cd bugsnap-mcp
# 3. Install dependencies and build
npm install
npm run buildOnce built, the server binary is located at dist/index.js (e.g. D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js or /path/to/bugsnap-mcp/dist/index.js).
(Optional: Run npm link inside bugsnap-mcp to make the bugsnap-mcp command available globally in your terminal).
⚙️ Client Configurations
💡 Bebas Error Path Windows:
Gunakan Opsi A (Universal GitHub) di bawah ini -100% tanpa path file sehingga mustahil terkena error backslash Windows (
\).Jika menggunakan instalasi lokal (Opsi B), jalankan perintah
npm run configdi dalam folderbugsnap-mcpuntuk mencetak JSON konfigurasi yang sudah dinormalisasi otomatis menggunakan forward slash (/).
Pilih AI client yang kamu gunakan di bawah ini:
⚡ 1. Claude Code (CLI)
Opsi A: 1-Baris Langsung dari GitHub (Tanpa Perlu Clone)
claude mcp add --scope user -e BUGSNAP_API_KEY=bugsnap_xxx --transport stdio bugsnap -- npx -y github:akusaradigital/bugsnap-mcpOpsi B: Menggunakan Path Lokal (Offline / Clone Sendiri)
claude mcp add --scope user -e BUGSNAP_API_KEY=bugsnap_xxx --transport stdio bugsnap -- node "D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js"(Untuk macOS/Linux, gunakan path Unix seperti /Users/username/bugsnap-mcp/dist/index.js).
🖥️ 2. Claude Desktop
Buka file konfigurasi claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Opsi A: Langsung via GitHub
{
"mcpServers": {
"bugsnap": {
"command": "npx",
"args": ["-y", "github:akusaradigital/bugsnap-mcp"],
"env": {
"BUGSNAP_API_KEY": "bugsnap_xxx"
}
}
}
}Opsi B: Menggunakan Path Lokal
{
"mcpServers": {
"bugsnap": {
"command": "node",
"args": ["D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js"],
"env": {
"BUGSNAP_API_KEY": "bugsnap_xxx"
}
}
}
}Restart Claude Desktop setelah menyimpan file konfigurasi.
🖱️ 3. Cursor IDE
Tambahkan ke .cursor/mcp.json di root workspace proyek kamu (atau di Cursor Settings Features MCP):
{
"mcpServers": {
"bugsnap": {
"command": "npx",
"args": ["-y", "github:akusaradigital/bugsnap-mcp"],
"env": {
"BUGSNAP_API_KEY": "bugsnap_xxx"
}
}
}
}(Atau gunakan "command": "node" dan "args": ["D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js"] jika menggunakan instalasi lokal).
}
}
---
### 🌊 4. Windsurf IDE
Tambahkan ke konfigurasi MCP Windsurf di `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"bugsnap": {
"command": "node",
"args": ["D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js"],
"env": {
"BUGSNAP_API_KEY": "bugsnap_xxx"
}
}
}
}🔌 5. VS Code (Cline / Roo Code)
Tambahkan ke pengaturan MCP settings (cline_mcp_settings.json):
{
"mcpServers": {
"bugsnap": {
"command": "node",
"args": ["D:/Akusara/EXTENTION CHROME/bugsnap-mcp/dist/index.js"],
"env": {
"BUGSNAP_API_KEY": "bugsnap_xxx"
},
"disabled": false,
"autoApprove": ["bugsnap_list_captures", "bugsnap_get_capture"]
}
}
}💬 Cara Menggunakan Bersama AI Coding Agent
Setelah terhubung, agent kamu akan secara otomatis mengenali tools, resources, dan prompt BugSnap. Kamu cukup mengetik instruksi dalam bahasa sehari-hari:
1. Memperbaiki Bug Spesifik
"Tolong perbaiki bug dari link ini: https://bugsnap.akusaraproject.my.id/v/8cd0c35b-8683-43e7-940b-2fec6c4fd8ef"
"Inspect BugSnap capture 8cd0c35b-xxxx dan cari di repo kita kenapa terjadi error 500."
2. Mencari & Triage Bug Terbuka
"Cari laporan bug di BugSnap yang berkaitan dengan 'checkout' atau 'payment'."
"List bug terbuka di workspace BugSnap kita dan urutkan berdasarkan prioritas."
3. Menggunakan Resource Natively (Cursor & Claude Desktop)
Di Cursor atau klien yang mendukung Resource URI, kamu bisa langsung mengetik:
"Lihat resource
@bugsnap://captures/8cd0c35b-xxxxdan buatkan unit test untuk mencegah bug ini terjadi lagi."
"Buka@bugsnap://captures/recentuntuk melihat daftar bug terbaru."
4. Menjalankan Guided Prompts
Kamu bisa menjalankan alur kerja bawaan:
/bugsnap_fix_bug(dengan argumen ID capture)/bugsnap_triage_open_bugs
🛡️ Guardrails & Pencegahan Kesalahan Diagnosis AI
bugsnap-mcp dirancang khusus agar AI Agent tidak salah membaca atau berasumsi keliru:
1. 📸 Visual Screenshot & Anotasi
Screenshot asli diunduh beresolusi penuh (hingga 15MB).
AI dilatih untuk memeriksa kotak berwarna, anak panah, dan nomor langkah (①, ②, ③) secara berurutan sesuai aksi pengguna.
Untuk screenshot Full-Page yang panjang ke bawah, AI diarahkan untuk memindai kontras visual dan mencocokkan data telemetri, alih-alih menebak dari teks yang terkompresi.
2. ⚠️ Ambiguity Guardrail (Deskripsi & Tanda Kosong)
Jika pengguna membuat laporan yang:
Deskripsi tertulisnya kosong / tidak jelas, DAN
Tidak ada console error maupun network 500, DAN
Tidak ada coretan/tanda pada gambar, Maka AI Agent DILARANG mengubah kode sembarangan. Agent diinstruksikan untuk berhenti dan bertanya langsung kepada pengguna:
"Karena gambar yang kamu kirim tidak ada penjelasan detail maupun tanda pada gambar, bisa tolong jelaskan bagian mana yang bermasalah atau behavior apa yang diharapkan?"
3. 🎥 Video Captures (AI Video Guardrail)
Model LLM saat ini tidak dapat memutar/menonton video mentah. Jika capture berupa rekaman video, MCP menyuntikkan larangan berhalusinasi visual, dan langsung mengarahkan AI ke telemetri deterministik:
Catatan tim bertimestamp (misal: "di detik 14 tombol freeze").
Breadcrumbs aksi klik & ketikan user.
Unhandled JavaScript console errors dengan call stack.
Endpoint network 4xx/5xx yang gagal.
🛠️ MCP Specification Reference
Tools
Tool | Parameter | Deskripsi |
|
| Mencari dan menampilkan daftar laporan bug di workspace. |
|
| Mengambil data diagnostik lengkap: gambar screenshot, anotasi, console error, network failure, user steps, dan fix blueprint. |
Resources
Resource URI | Tipe | Deskripsi |
| Dynamic Resource | Menampilkan 15 laporan bug terbaru di workspace. |
| Resource Template | Meng-attach laporan bug dan telemetri langsung ke dalam chat context. |
Prompts
Prompt | Argumen | Deskripsi |
|
| Alur kerja terpandu 5 langkah untuk mendiagnosa, memperbaiki, dan memverifikasi bug. |
|
| Alur kerja terpandu untuk mengkategorikan dan memprioritaskan bug terbuka. |
🔧 Variabel Lingkungan (Environment Variables)
Variabel | Wajib | Default | Deskripsi |
| Ya | - | API key workspace dari BugSnap Settings ( |
| Tidak |
| Base URL instance BugSnap. |
🧪 Menguji dengan MCP Inspector
Kamu bisa menguji server secara interaktif di browser menggunakan MCP Inspector:
BUGSNAP_API_KEY=bugsnap_xxx npx @modelcontextprotocol/inspector node dist/index.js📄 Lisensi
MIT © BugSnap
Available Tools
2 toolsbugsnap_get_captureGet BugSnap bug report, annotated screenshot & fix guidanceA
Get complete, multimodal debugging context for a BugSnap bug report so you can diagnose and fix it with precision without guessing: (1) multi-modal annotated screenshot image (with user-drawn arrows, boxes, text callouts), (2) user's problem description & expected behavior, (3) team discussion comments with pinned coordinate locations, (4) console exceptions with full stack traces, (5) failed network API requests (4xx/5xx), (6) chronological user action steps prior to the defect, (7) runtime environment (URL, browser, OS, viewport dimensions), and (8) an actionable step-by-step fix blueprint tailored for AI coding agents. Accepts either a bare capture UUID or a full BugSnap share URL.
Inputs: id (required).
bugsnap_list_capturesList and search BugSnap bug reportsA
List and search recent BugSnap bug reports (screenshots, recordings, and diagnostic telemetry) captured for your workspace. Filter by status or search by keyword (title, description, or URL). Use this to find a capture ID before inspecting it with bugsnap_get_capture.
Inputs: limit, query, status.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have crisply distinct roles: one lists/searches captures and returns IDs, the other fetches full detail for a single capture. The list tool even explicitly tells the agent to use it before calling bugsnap_get_capture, making the intended sequence unambiguous.
Both follow the same predictable pattern: bugsnap_<verb>_<resource> (bugsnap_list_captures, bugsnap_get_capture), with a consistent server prefix, verb style, and noun form. No mixed conventions.
Two tools is thin for a bug-reporting domain; the surface is essentially a read-only list/detail pair. It is defensible as a focused retrieval server, but it sits at the borderline where a couple more operations would be expected.
Listing and full-context retrieval are well covered, but the lifecycle is one-directional: despite filtering by status, there is no way to change status, add/resolve comments, or otherwise act on a capture. Agents can diagnose but not close the loop.
Maintenance
Related MCP Connectors
Bug tracking for AI agents: session replay, console/network logs, repro packs, test plans, evidence.
Production bugs with replay, network, console and stack, ranked for your coding agent to fix.
Gives your coding agent the captured console, network, replay and screenshot evidence for a bug.
Traceo bug recordings (console, network, user actions, environment) as context for coding agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to capture, replay, inspect, diff, share, and manage executable bug artifacts (.bug files) via the BugProof CLI, supporting 10 tools and structured prompts for debugging workflows.72 npmAGPL 3.0
- AlicenseAqualityCmaintenanceRead visual bug reports from Feedbug in your AI coding agent: screenshot, console logs, failed network requests, session replay and the DOM context of the element the tester clicked. Trace the bug to its source file, comment and resolve without leaving the editor.725 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables coding agents to access local browser diagnostics—runtime errors, console logs, network failures, breadcrumbs, DOM snapshots, and screenshots—and run closed-loop verification to debug and confirm fixes.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to access recorded browser flows—including user actions, network activity, console logs, storage, DOM events, and screen recordings—for debugging and regression testing. It lets agents inspect and analyze these flows to report bugs and generate tests without manually reproducing issues.-