Tools & agent loop

All tools are namespaced dungbeetle_*. Read tools carry readOnlyHint; the 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_list_runs	read	Recent runs, newest first (optional limit, branch) — find a run id to triage.
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_get_usage	read	Current-period usage (snapshots/storage) vs plan limits — check quota before pushing.
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).
dungbeetle_reopen_run	destructive	Set a decided run's review state back to pending for re-review.

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.dev/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_list_runs to discover recent runs (newest first, optionally filtered by branch) and pick a run id to triage.
2. dungbeetle_get_run (or dungbeetle_get_analytics) to triage what changed; detail: "full" adds the per-target text 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. dungbeetle_reopen_run sets a decided run back to pending if it needs another look.

dungbeetle_get_usage reports the current period's snapshot and storage usage against the plan's limits — useful before pushing new runs or baselines.

When the server is configured with a scoped agent token, tools outside the token's granted scopes fail with an HTTP 403 and the server's error message names the missing scope — surface it to the user rather than retrying.

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 one Dungbeetle server — the hosted cloud by default, or the DUNGBEETLE_SERVER_URL you set when self-hosting; run it in your own CI or workstation for zero data egress.