Skip to main content
Glama

bugsnap-mcp

License: MIT MCP Standard GitHub Repository

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 build

Use 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

  1. Open the BugSnap Dashboard.

  2. Go to Settings BugSnap API Keys.

  3. 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 build

Once 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 config di dalam folder bugsnap-mcp untuk 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-mcp

Opsi 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.json

  • Windows: %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-xxxx dan buatkan unit test untuk mencegah bug ini terjadi lagi."
"Buka @bugsnap://captures/recent untuk 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

bugsnap_list_captures

query (string), limit (int 1-25), status (open/in-progress/fixed/closed)

Mencari dan menampilkan daftar laporan bug di workspace.

bugsnap_get_capture

id (string: UUID atau share URL)

Mengambil data diagnostik lengkap: gambar screenshot, anotasi, console error, network failure, user steps, dan fix blueprint.

Resources

Resource URI

Tipe

Deskripsi

bugsnap://captures/recent

Dynamic Resource

Menampilkan 15 laporan bug terbaru di workspace.

bugsnap://captures/{id}

Resource Template

Meng-attach laporan bug dan telemetri langsung ke dalam chat context.

Prompts

Prompt

Argumen

Deskripsi

bugsnap_fix_bug

id (string), repo_hint (string opsional)

Alur kerja terpandu 5 langkah untuk mendiagnosa, memperbaiki, dan memverifikasi bug.

bugsnap_triage_open_bugs

query (string opsional)

Alur kerja terpandu untuk mengkategorikan dan memprioritaskan bug terbuka.


🔧 Variabel Lingkungan (Environment Variables)

Variabel

Wajib

Default

Deskripsi

BUGSNAP_API_KEY

Ya

-

API key workspace dari BugSnap Settings (bugsnap_...).

BUGSNAP_API_BASE

Tidak

https://bugsnap.akusaraproject.my.id

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 tools
bugsnap_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

    A3.8/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Read 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.
      7
      25 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -