Skip to main content
Glama

Bugboard

License: MIT Node M8ven Score

QA points out the bug, the dev fixes it right there, QA signs it off. One board, no ticket ping-pong.

Bugboard is a local bug board with Excel-like sheet tabs, built for teams that code with AI agents. QA files a defect as a card. The developer's AI agent reads that card over MCP, fixes the code, and moves it to test. QA clicks Pass or Fail in the browser. Nothing gets copied between Jira, spreadsheets and chat.

PT: o QA aponta o defeito, o dev já desenvolve direto no card pelo agente de IA (MCP), e o QA valida no navegador com Passou / Falhou.

How it works

flowchart LR
    QA(["🐞 <b>QA files the bug</b><br/><small>steps · environment · test data</small>"])
    DEV(["🤖 <b>Dev's AI agent fixes it</b><br/><small>reads the card over MCP</small>"])
    TEST(["🧪 <b>Ready to test</b>"])
    CHECK{"👀 <b>QA review</b>"}
    OK(["✅ <b>Done</b>"])
    BACK(["🔁 <b>Back to dev</b><br/><small>reason · screenshots · AI prompt</small>"])

    QA --> DEV --> TEST --> CHECK
    CHECK -->|Pass| OK
    CHECK -->|Fail| BACK
    BACK -.->|next round| DEV

    classDef qa fill:#7c3aed,stroke:#5b21b6,color:#fff
    classDef dev fill:#2563eb,stroke:#1e40af,color:#fff
    classDef test fill:#d97706,stroke:#92400e,color:#fff
    classDef review fill:#334155,stroke:#0f172a,color:#fff
    classDef pass fill:#16a34a,stroke:#166534,color:#fff
    classDef fail fill:#dc2626,stroke:#991b1b,color:#fff

    class QA qa
    class DEV dev
    class TEST test
    class CHECK review
    class OK pass
    class BACK fail
  1. QA points out the defect. One card per bug, with numbered repro steps, the environment (where), and the test data (prep).

  2. The dev fixes it from the card. The AI agent (Claude Code, Cursor or any MCP client) reads the card, changes the code, records fix, files and symbols, and sets the card to testar.

  3. QA validates. Pass closes it as ok. Fail asks for a reason (you can paste screenshots), offers a ready-made prompt to hand back to the AI, and the card returns to the dev with its round counter increased.

Related MCP server: pandan

Why Bugboard

  • The bug and the fix live on the same card. Agents read and write it directly, so nobody re-types the bug report into a prompt.

  • Humans stay in charge of quality. Agents can mark work as ready, but only a person clicks Pass or Fail.

  • Local first. Data stays in SQLite on your machine. Bind the server to your LAN if a small team wants to share one board.

  • Spreadsheet feel. Sheet tabs per project, release or device, plus status filters, repo chips and numbered steps.

  • Speaks your language. The UI ships in the 10 most spoken languages (English by default), switchable from the header.

  • Code aware. Cards link to files and symbols, so you can ask which bugs touch the same code (see Knowledge graph).

Quick start

git clone https://github.com/pauloemmanuel/bugboard.git
cd bugboard
npm install
npm run build
node dist/index.js open

Default URL: http://127.0.0.1:3847 (override with BUGBOARD_PORT).

Global install (optional):

npm link
bugboard open

CLI: serve | open | status | mcp.

Data location

All board data lives in ~/.bugboard/ (SQLite). Cloning this repo does not copy anyone's sheets or cards. Each machine has its own database.

Sheets

Create sheets (tabs) for a project, a release or a device matrix, then add cards through MCP or the HTTP API. Archived sheets are hidden from the default list (MCP: sheet_archive).

Journeys and use cases

Journey cards (kind: journey, parent_id null) group a device or platform run (e.g. iOS release 2.3). Use case cards (kind: usecase, parent_id set) are atomic flows inside that journey (signup, chat, wallet). Each use case has its own status, steps, and pass/fail; one failure does not block the whole journey. Journey cards show child progress (3/7 ok) from use case statuses; marking a journey Passou does not auto-pass children. The journey's own status follows its use cases (cancelled ones ignored): any fazendo keeps it fazendo, otherwise any testar makes it testar, otherwise any falhou makes it falhou, and it turns ok once every use case is ok.

prep is a string array of test data the agent should fill (emails, MFA codes, package names, URLs). The UI shows Preparação on use cases.

platform on journeys: ios | android | web | ipad (icons in the UI). Children may inherit display from the parent.

bug_list and GET /api/sheets/:id/bugs return nested journeys with children[].

Card schema

Field

Type

Notes

title

string

Required

kind

enum

journey (root) or usecase (child)

parent_id

string?

Parent journey id for use cases

platform

enum?

ios, android, web, ipad

prep

string[]

Test data / massa for agents to fill

repos

string[]

Repo names or paths (display only)

status

enum

See below

where

string

Environment or surface to test

steps

string[]

Repro or QA steps (one string per step)

fix

string

What changed or what to verify

round

number

Increments when a failed card returns to testar

note

string

Tester notes on pass/fail

files

string[]

Repo-relative paths prefixed with the repo folder, e.g. wellmexh-frontend-react-native/app/hooks/x.ts

symbols

string[]

Function or component names

Statuses

Status

Meaning

fazendo

In progress

testar

Ready for human QA

ok

Passed

falhou

Failed

cancelado

Cancelled: the card no longer makes sense (the screen changed, or the AI got the scenario wrong). Hidden from Todos, shown under the Cancelado filter, reopen anytime

MCP setup

Bugboard exposes a stdio MCP server. Point your IDE at dist/index.js mcp after npm run build.

Cursor

Edit ~/.cursor/mcp.json (or project MCP config):

{
  "mcpServers": {
    "bugboard": {
      "command": "node",
      "args": ["/absolute/path/to/bugboard/dist/index.js", "mcp"]
    }
  }
}

With a global binary after npm link:

{
  "mcpServers": {
    "bugboard": {
      "command": "bugboard",
      "args": ["mcp"]
    }
  }
}

Restart Cursor after changes.

Claude Code

One command:

claude mcp add bugboard -- node /absolute/path/to/bugboard/dist/index.js mcp

Or add the same block under mcpServers in ~/.claude.json (or your Claude Code MCP config) and restart the CLI session.

See also .mcp.json in this repo for a working absolute-path example.

MCP tools

Tool

Description

board_status

Health, DB path, port, aggregate counts

board_open

Start HTTP server if needed, open browser

sheet_list

List sheets (optional include_archived)

sheet_create

Create a sheet tab

sheet_rename

Rename a sheet

sheet_archive

Archive a sheet

bug_list

List bugs on a sheet (optional status filter, compact: true for one line per card)

bug_get

Get one bug by id

bug_create

Create a card

bug_update

Patch fields (round auto-increment rules apply)

bug_pass

Human pass (ok)

bug_fail

Human fail (falhou)

bug_cancel

Cancel a card that no longer makes sense (cancelado), reason in note

board_query

Graphify-style BFS over the board graph (sheet_id?, question, depth=2, budget=2000)

board_explain

Neighbors of a card (#n/id), file or symbol, grouped by edge type

board_path

Shortest path between two cards, files or symbols

board_clusters

Card groups joined by shared code, links or similar titles, with a suggested journey each

bug_link / bug_unlink

Link cards: related, depends_on, duplicate, regression_of, same_flow

Knowledge graph

The board is also a graph, rebuilt in memory after every write. Nodes: sheets, journeys, use cases, repos, files, symbols. Edges: parent, in_sheet, in_repo, touches_file, touches_symbol, explicit links, plus inferred shares_code (same file or symbol) and similar_title (token overlap).

File nodes are matched against <BUGBOARD_CODE_ROOT>/<repo>/graphify-out/graph.json (default ~/Projetos/GroupLookstar); a hit adds the graphify node id and community, so a card connects into the code graph.

Every rebuild writes ~/.bugboard/graph.json in graphify's format, so the CLI works too:

graphify query "saque documento" --graph ~/.bugboard/graph.json

Env: BUGBOARD_DATA_DIR (default ~/.bugboard), BUGBOARD_CODE_ROOT. Smoke test: npm run build && node test/graph-smoke.mjs (temp dirs only).

HTTP API

The SPA uses GET/PATCH /api/... on the same port as the UI. Useful for scripts; agents should prefer MCP.

Changelog

We follow Keep a Changelog and Semantic Versioning. See CHANGELOG.md.

Contributing

Issues and PRs welcome on GitHub. Keep changes small and documented in the changelog.

License

MIT. Copyright Paulo Emmanuel. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to read and drive a local-first Kanban board for issue tracking, allowing them to list, create, update, and resolve issues from Claude Code sessions.
      9 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to read and write a local kanban board, adding and editing cards, moving them between columns, managing projects, and writing update entries so their work is visible in real time.
      4 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides browser control and testing tools for AI agents, enabling step-by-step web app testing with user confirmation, bug evidence capture, and report generation.
      1
      MIT