bugzar-server

A small Node.js server for storing Bugzar QA session reports, organized by project, with a dashboard for triage (status tracking, comments) and an MCP server so an AI agent can query and update reports directly.

Bugzar's SDK exports each captured session as a self-contained, offline-playable HTML file — the whole viewer is inlined, so this server doesn't need to render reports itself. It just needs to store that file, track metadata (project, status, comments) about it, and serve it back at a stable URL.

Quick start

pnpm install
cp .env.example .env   # set DASHBOARD_PASSWORD and SESSION_SECRET to real values
pnpm dev                # http://localhost:3000

For production: pnpm build && pnpm start.

Related MCP server: platform-adapter-mcp

Concepts

• Project — a namespace with its own API key. Create one from the dashboard (/) after logging in with DASHBOARD_PASSWORD; the API key is shown once at creation time.

• Report — one ingested Bugzar HTML export, belonging to a project. Has a 3-state workflow: open → in_progress → resolved.

• Share link — every report is reachable at {PUBLIC_BASE_URL}/r/:reportId, unauthenticated (the id is the access control, same trust model as the offline HTML file itself). Opening it serves the exact stored HTML, which is already the full interactive replay/console/network viewer.

HTTP API

SDK integration

See docs/sdk-integration.md for wiring @bugzar/sdk's onExport callback to this server.

MCP server

Mounted at /mcp (Streamable HTTP transport), authenticated the same way as ingestion — Authorization: Bearer <project_api_key>. All calls are scoped to that project only.

Tools:

• list_reports, get_report_summary, get_repro_steps, get_console_errors, get_failed_requests, get_network_request, get_system_info, get_ai_context — read/query

• update_report_status, add_report_comment — AI can directly triage a report (mark it resolved, leave an investigation note)

Add it to an MCP-capable client pointed at http://<host>/mcp with the Authorization header set to Bearer <project_api_key> (check your client's docs for how it configures custom headers on a remote HTTP MCP server — e.g. Claude Code's claude mcp add --transport http).

Development

pnpm test          # vitest — vendor extractor, ingestion summary, HTTP routes, MCP tools
pnpm build         # tsc -> dist/
pnpm smoke         # after building: spawns the real server, ingests a real fixture report,
                   # and round-trips a real MCP client against it end-to-end
pnpm check         # biome lint/format

Project layout

src/
├── index.ts / app.ts     # entrypoint / Hono app assembly
├── config.ts             # env var loading
├── db/                   # better-sqlite3 client, migrations, hand-written repos
├── vendor/                # copied from @bugzar/shared (private/unpublished) — report HTML extractor + types
├── ingest/                # storage (filesystem), ingestion pipeline, summary derivation
├── auth/                  # API key + dashboard session
├── routes/                # REST API
├── mcp/                   # MCP tool definitions + Streamable HTTP route
└── dashboard/              # server-rendered Hono JSX pages