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.

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.

Platform	Package
Windows	.exe (NSIS installer)
macOS	.dmg
Linux	.AppImage

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

Global Shortcut	Action
Ctrl+Shift+P	Capture full screen
Ctrl+Shift+R	Capture region
Ctrl+Shift+W	Capture window
Ctrl+Z / Ctrl+Shift+Z	Undo / Redo

In-App Shortcut	Action
P / A / R / F	Switch tool: Pin / Arrow / Rect / Freehand
Esc	Deselect all
Scroll	Zoom in/out
Shift + Drag	Pan

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

Tool	Description
list_annotations	List all active annotation pins and drawings
get_screenshot	Get current screenshot metadata
resolve_annotation	Mark an annotation as resolved (removes from list)
get_context	Get structured Markdown context for a person or external tool

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.

---

• 简体中文
• 繁體中文
• 日本語