# bug-ledger-mcp

A shared, concurrency-safe ledger for LLM code audits. Point a fleet of agents at
a codebase, let them record what they find into one place, and get back a
verified, deduplicated, trackable list instead of a pile of scattered notes.

## The problem it solves

Running many LLM agents over a codebase is easy. Trusting what they find is not.
Turn a few agents loose and you hit the same failures every time:

- Findings collide. Agents writing to a shared file or doc overwrite each other,
  and reports silently go missing.
- Findings hallucinate. An agent cites a bug at a file and line that do not
  exist, and nobody notices until a human goes looking.
- Findings pile up. The same defect gets reported five times, and there is no
  lifecycle, so "found", "actually a bug", and "fixed" all look alike.

bug-ledger-mcp is the missing system of record. It gives your agents one place to
report into, checks every finding as it lands, and tracks each one from reported
to verified to resolved.

## What you get

- Safe for many writers at once. A fleet of agents can report into the same
  ledger concurrently without losing or corrupting a single finding.
- Hallucination-resistant by design. Every finding has to anchor to a real spot
  in the actual source; a made-up file or line is rejected on the spot. The
  required fields (the invariant it breaks, the failure, the reproduction) make
  the agent argue its case instead of hand-waving.
- A real lifecycle. Each finding carries a verdict (confirmed, partial, refuted)
  and a resolution (fixed, already fixed, won't fix), so you can tell at a glance
  what is real, what is done, and what still needs work.
- Deduplication that actually works. Rather than trusting agents to catch their
  own repeats, the ledger surfaces findings whose code locations overlap so you
  reconcile them after the fact.
- Answers, not dumps. Ask for the open criticals, the hotspot files, or a
  one-line summary of the whole audit, without pulling every record into context.
- Drift awareness. As the code moves on, the ledger flags findings that no longer
  match the source they were filed against.

## Built for LLMs to drive

- It is an MCP server. Add it to any MCP-capable client and your agents get the
  tools automatically. There is nothing to wire up by hand.
- It is self-documenting. One call to how_to_use_this_mcp returns the full
  contract, so an agent that lands on the server cold can onboard itself.
- It corrects mistakes for you. Every error says what was wrong, the allowed
  values, and one example of a correct call, so agents recover on their own
  instead of looping. Enum inputs are read leniently; close enough is accepted.
- No bookkeeping for the model. No UUIDs to invent, no idempotency keys to carry.
  Ids are short and stable, and when two agents collide the loser gets a clear
  "refresh and retry" instead of silently clobbering the other's work.

## How a run looks

1. The orchestrator creates a ledger for the project.
2. Finder agents report findings into it, in parallel.
3. Verifier agents confirm, narrow, or refute each one.
4. Fixers resolve them, and duplicates are reconciled.
5. Anyone queries the ledger for status, hotspots, or a summary.

The server stores, validates, and answers. It never dictates the process; that
stays with your orchestrator.

## Tools

- create_ledger, find_ledgers, ledger_summary, close_ledger
- report_bug, get_bugs, list_bugs
- verify_bug, resolve_bug, reopen_bug, mark_duplicate, correct_bug, append_bug_note
- find_duplicate_candidates, hotspots
- how_to_use_this_mcp returns the full contract

## Run it

Build it, then register it with your MCP client as a stdio server:

    npm install && npm run build

```json
{
  "mcpServers": {
    "ledger": {
      "command": "node",
      "args": ["/path/to/bug-ledger-mcp/dist/index.js"]
    }
  }
}
```

The whole ledger is a single SQLite file at $LEDGER_DB, or ~/.ledger/ledger.db by
default. Nothing to host, no service to keep alive; it sits next to your tools.

## Develop

- npm test: type-check and run the vitest suite
- npm run itest: drive the compiled stdio server end to end
- npm run db:empty: clear ledger data, keep the schema