Tools & agent loop

All tools are namespaced dungbeetle_*. Read tools carry readOnlyHint; the two mutating tools carry destructiveHint so clients gate them behind approval.

Tool	Kind	Purpose
dungbeetle_health	read	Liveness/version probe — confirm connectivity.
dungbeetle_get_repository	read	The repository the credentials resolve to (id, name).
dungbeetle_list_baselines	read	Baseline targets with their latest version.
dungbeetle_get_baseline_history	read	Version history for one target.
dungbeetle_get_run	read	Structured run/diff summary; detail: "full" adds per-target text diffs.
dungbeetle_get_review_url	read	Deep link to the web review page for a run.
dungbeetle_get_analytics	read	Pass rate, trend, and per-target flakiness.
dungbeetle_approve_run	destructive	Approve a run; promote: true turns candidate snapshots into new baselines.
dungbeetle_reject_run	destructive	Record a rejection (no baseline change).

Token-cheap by design

dungbeetle_get_run returns a compact object — per-target status, counts, the changed list, the current reviewState, and a reviewUrl — instead of image payloads:

{
  "id": "run_…",
  "status": "failed",
  "reviewState": "pending",
  "changed": ["home-page"],
  "counts": { "failed": 1 },
  "reviewUrl": "https://dungbeetle.example.com/ui/repos/…/runs/run_…",
  "note": "Screenshots are not inlined — open reviewUrl to view before/after images."
}

detail: "full" adds the structured text diff and hasScreenshot / promotable flags per target — still without shipping any base64.

The agent loop

1. dungbeetle_get_run (or dungbeetle_get_analytics) to triage what changed.
2. dungbeetle_get_run with detail: "full" to read the per-target diff.
3. For images, hand the human dungbeetle_get_review_url.
4. On confirmation, dungbeetle_approve_run (with promote: true to update baselines) or dungbeetle_reject_run. The decision is recorded in the same append-only audit trail as the web UI.

Security notes

• The MCP server holds repository client credentials — treat them like any CI secret; scope one credential pair per repository.
• Approvals are attributed to the repository's owning user behind the credentials (not per-caller) in the audit trail — a credential pair is a shared CI secret.
• It speaks only to the DUNGBEETLE_SERVER_URL you configure; run it in your own CI or workstation for zero data egress.