# 🪰🔌 gadfly-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an MCP client (e.g. Claude) read and
**grade** [Gadfly](https://gitea.stevedudenhoeffer.com/steve/gadfly) review findings stored in
[gadfly-reports](https://gitea.stevedudenhoeffer.com/steve/gadfly-reports). It's a tiny, stateless
stdio process — a thin HTTP client to the store — so there's nothing to install or manage: your MCP
client launches it on demand with `go run …@latest`.

> ### 🤖 Heads up: this is a vibe-coded project
> gadfly-mcp was built almost entirely by an AI agent (Claude Code) — code and docs. It's small and
> tested, but treat it as homelab-grade. Issues and PRs welcome.

## Add it to Claude

The store (`gadfly-reports`) runs persistently somewhere; this MCP server is throwaway. Point your
client at it via `go run` (first launch compiles + caches; needs Go + access to the module host):

```jsonc
{
  "mcpServers": {
    "gadfly": {
      "command": "go",
      "args": [
        "run", "gitea.stevedudenhoeffer.com/steve/gadfly-mcp@latest",
        "--store", "https://gadfly-reports.your-host:8090"
      ],
      "env": { "GADFLY_REPORTS_TOKEN": "the-same-token-the-store-uses" }
    }
  }
}
```

`--store` defaults to `$GADFLY_REPORTS_URL` (else `http://localhost:8090`). If the store requires a
bearer token, set `GADFLY_REPORTS_TOKEN`.

## Tools

| Tool | Args | Does |
|---|---|---|
| `list_findings` | `repo?`, `pr?`, `only_ungraded?` | lists findings (one entry per finding; reports from multiple models grouped, distinct models listed) |
| `record_finding_grade` | `finding_id`, `is_real`, `severity?`, `usefulness?`, `notes?` | records a triage grade (grader is always `claude`) |
| `scoreboard` | `model?` | per-model rollup (runs, minutes, tokens, confirmed-by-severity histogram) |

`severity` is one of `trivial|small|medium|high|critical` (set it when `is_real=true`; omit for a
false positive). **Points are not stored or returned** — gadfly-reports keeps raw facts, so any
"value per minute / per token" ranking is computed client-side (map severity → points, divide by
minutes). Use `scoreboard` for the raw material.

Typical flow: *"List the ungraded gadfly findings on PR 2, look into each against the code, and
record a grade for each."*

## Build / test

```sh
go build ./...
go test ./...
gofmt -l .   # must be clean
```

## License

MIT © 2026 Steve Dudenhoeffer.