English · 简体中文 · 繁體中文 · 日本語

BugShot

UI issue capture tool. Capture the screen, mark the spot, add a note, and export the report.

Workflow

A plain screenshot often loses the coordinates and context needed to reproduce an issue. BugShot keeps the image, coordinates, notes, and UI element details together. Use the optional local MCP server when another tool needs to read the current session.

Related MCP server: browser-mcp

Features

• 3 capture modes — Fullscreen (Ctrl+Shift+P), Region (Ctrl+Shift+R), Window (Ctrl+Shift+W)

• 4 annotation tools — Pin markers, arrows, rectangles, freehand drawing

• Undo/redo — Keep up to 50 history steps

• Zoom & pan — Scroll to zoom; Shift+drag to pan

• MCP Server — Optional local JSON-RPC + SSE endpoint for external tools

• Export — Markdown report, annotated PNG, and JSON session data

• UIA integration — Read the Windows UI element name, type, class, and ancestry at each pin

• i18n — English, 简体中文, 繁體中文, 日本語

• System tray — Keep BugShot running from the tray

• Auto-update — Check GitHub Releases for updates

Quick Start

Download

Download the latest installer from Releases.

Build from Source

git clone https://github.com/dreamnight16/bugshot
cd bugshot
npm install
npm run dev      # Start in development mode
npm run build    # Production build
npm run dist     # Package installer

Requirements: Node.js ≥ 20, npm ≥ 10

Usage

Keyboard Shortcuts

Tools

• Pin — Place a numbered marker. Click to add a comment. Drag to reposition.

• Arrow — Draw an arrow from one point to another.

• Rectangle — Draw a dashed rectangle to highlight a region.

• Freehand — Draw freely for custom highlights.

Export Formats

• Copy (Markdown) — Coordinates, notes, cropped regions, colors, and the UIA element tree. Paste it into an issue or review.

• Screenshot (PNG) — Save the annotated image.

• JSON — Save structured session data.

MCP Protocol

BugShot runs an optional local MCP-compatible JSON-RPC server at http://127.0.0.1:3846.

The server creates a fresh bearer token on every launch. The token is printed in the BugShot log as MCP server auth token: Bearer ...; copy it into the Authorization header for every /mcp and /sse request. The server remains loopback-only and rejects requests with a non-loopback Host header.

Tools

Quick Test

# Replace this with the token printed in the BugShot log.
TOKEN="paste-token-here"

curl -s http://127.0.0.1:3846/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list","id":1}'

curl -s http://127.0.0.1:3846/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","id":2,"params":{"name":"list_annotations"}}'

SSE (Server-Sent Events)

Subscribe to real-time session updates at http://127.0.0.1:3846/sse with the same Authorization: Bearer $TOKEN header.

Architecture

bugshot/
├── electron/              # Electron main process
│   ├── main.ts            # Window, IPC, shortcuts, tray
│   ├── preload.ts         # Context bridge API
│   ├── uia.ts             # Windows UIAutomation (PowerShell)
│   ├── updater.ts         # Auto-update via electron-updater
│   ├── logger.ts          # Structured logging
│   ├── mcp/               # MCP protocol server (modular)
│   │   ├── http-server.ts # HTTP bootstrap, routing, CORS
│   │   ├── handlers.ts    # Tool implementations
│   │   ├── sse.ts         # SSE connection management
│   │   └── types.ts       # Shared types
│   └── mcp-server.ts      # Re-export facade
├── src/                   # React renderer
│   ├── components/        # UI components
│   ├── hooks/             # Custom React hooks
│   ├── lib/               # Pure utility modules
│   ├── i18n/              # Internationalization
│   ├── context/           # React context + reducer
│   └── types/             # TypeScript type definitions
├── resources/             # Icons and images
└── .github/workflows/     # CI/CD pipeline

Development

npm install

npm run dev

npm run typecheck

npm run lint

npm test
npm run test:watch

npm run build

npm run dist

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

• 简体中文

• 繁體中文

• 日本語