dungbeetle-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,110 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             DungbeetleDev
+
+Licensed Work:        Dungbeetle Server
+                      The Licensed Work is the contents of the Dungbeetle Cloud
+                      repository
+                      (https://github.com/DungbeetleTech/cloud) — the
+                      self-hostable cloud ingest, storage, review, and
+                      analytics service. The Licensed Work is
+                      (c) 2026 DungbeetleDev.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided that you do not offer the Licensed Work to
+                      third parties as a hosted or managed service whose value
+                      derives substantially from the functionality of the
+                      Licensed Work, where such a service competes with any
+                      hosted or managed Dungbeetle offering provided by the
+                      Licensor.
+
+                      For clarity, internal use of the Licensed Work — for
+                      example, running your own self-hosted Dungbeetle Server for
+                      your own team, company, or projects — is permitted
+                      production use under this grant.
+
+Change Date:          2030-06-28
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor (see SECURITY.md / the repository for contact
+details).
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or
+its affiliates (provided that you may use a trademark or logo of Licensor to the
+extent expressly required to comply with the notice requirements above).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR
+IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR
+A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or
+   a license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be
+   included in a program with software provided under GPL Version 2.0 or a later
+   version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,72 @@
+# dungbeetle-mcp
+
+The MCP server for [Dungbeetle](https://dungbeetle.dev) — the snapshot and
+visual regression testing tool built for AI agents and the humans they work
+for. It lets a coding agent (Claude Code, Cursor, Codex, Gemini CLI, or any
+MCP client) list runs, read **low-token semantic diffs**, check usage, and
+record reviews — while **promoting a baseline stays a human decision** unless
+a human explicitly grants the `baselines:write` scope.
+
+## Setup in 60 seconds
+
+1. Get an agent token (a human approves a one-time code in the browser — no
+   secret is ever copy-pasted):
+
+   ```sh
+   npx dungbeetle login --label "My agent"
+   ```
+
+2. Add the server to your MCP client:
+
+   ```json
+   {
+     "mcpServers": {
+       "dungbeetle": {
+         "command": "npx",
+         "args": ["-y", "dungbeetle-mcp"],
+         "env": { "DUNGBEETLE_AGENT_TOKEN": "dbat_…" }
+       }
+     }
+   }
+   ```
+
+   Claude Code one-liner:
+   `claude mcp add dungbeetle --env DUNGBEETLE_AGENT_TOKEN=… -- npx -y dungbeetle-mcp`
+
+Per-client guides: [Claude Code](https://dungbeetle.dev/mcp/claude-code) ·
+[Cursor](https://dungbeetle.dev/mcp/cursor) ·
+[Codex](https://dungbeetle.dev/mcp/codex) ·
+[Gemini CLI](https://dungbeetle.dev/mcp/gemini-cli)
+
+## Environment
+
+| Variable | Meaning |
+| --- | --- |
+| `DUNGBEETLE_AGENT_TOKEN` | Scoped, revocable agent token from `dungbeetle login` (recommended) |
+| `DUNGBEETLE_CLIENT_ID` / `DUNGBEETLE_CLIENT_SECRET` | Repository client credentials (CI-style alternative) |
+| `DUNGBEETLE_SERVER_URL` | Only when self-hosting — defaults to `https://dungbeetle.dev` |
+
+stdout is the JSON-RPC channel; diagnostics go to stderr. Missing credentials
+exit non-zero with guidance.
+
+## Why the auth model is different
+
+Agent tokens are minted via an RFC 8628 device flow and scoped: the default
+**Triage** preset reads runs/baselines/analytics and writes reviews, but
+promoting a baseline requires the separate `baselines:write` scope — so an
+agent can triage its own visual regressions without ever being able to
+approve them. Reviews are attributed as
+`"<label> (agent, on behalf of <owner>)"`, and tokens are revocable from the
+dashboard at any time. Details: <https://dungbeetle.dev/mcp/auth>
+
+## Machine-readable docs
+
+Full docs index for agents: <https://dungbeetle.dev/llms.txt> — every docs
+page also serves raw markdown at its URL + `.md`. See
+<https://dungbeetle.dev/docs-for-agents>.
+
+## License
+
+Source-available under the Business Source License 1.1 (converts to
+Apache-2.0). The Dungbeetle CLI (`dungbeetle` on npm) is a separate,
+FSL-licensed package.

package/dist/brand.js

@@ -0,0 +1,117 @@
+// Brand assets, served inline so the server stays a single self-contained
+// process with no static-file build step (consistent with the hand-rendered
+// views). The same SVG sources live in server/docs/public for the site and README.
+//
+// Raster exports (og-card.jpg, apple-touch-icon.png, manifest icons) are
+// generated from these SVGs by `npm run brand:rasters` and committed as
+// src/brandRasters.ts (base64, served by routes in app.ts) plus raw files in
+// docs/public. Rerun that script after editing any SVG below.
+const GREEN_DARK = "#137a43";
+// Display name, overridable via env so the app can be white-labelled when
+// self-hosted without editing source. Structural identifiers (package/bin names,
+// the Dungbeetle-Api-Version wire header) are intentionally NOT driven by this — they
+// stay fixed.
+export const BRAND_NAME = process.env.BRAND_NAME?.trim() || "Dungbeetle";
+export const BRAND_SHORT_NAME = process.env.BRAND_SHORT_NAME?.trim() || BRAND_NAME;
+// Shared brand copy — one source so every heading, tagline, and meta tag stays
+// in sync. Docs/README mirror these strings (they build separately and can't
+// import this module).
+export const BRAND_SLOGAN = "Test anything, anywhere, instantly.";
+export const BRAND_SUBTITLE = "The regression safety net for AI agents and the humans they work for — web, desktop, terminal, anything. Zero adoption cost, runs anywhere.";
+// The canonical entity description — the one-line answer to "what is
+// Dungbeetle", used verbatim across metadata surfaces (meta/OG descriptions,
+// docs site description; mirrored in the npm package and registry listings) so
+// search and AI engines ground the entity consistently. Deliberately
+// keyword-bearing ("snapshot", "visual regression testing") where
+// BRAND_SUBTITLE is the on-page brand voice for humans. Keep the two distinct:
+// this line is for machines and SERP snippets, the subtitle is the hero.
+export const BRAND_DESCRIPTION = `${BRAND_NAME} is a snapshot and visual regression testing tool — a free CLI plus self-hostable cloud — built for AI agents and the humans they work for.`;
+// Escape XML-significant chars so a brand name containing & < > " stays valid
+// inside the inline SVG/aria strings below. The manifest uses JSON.stringify,
+// which escapes on its own. ponytail: covers an operator setting an odd name.
+const xe = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+// Square app mark: a dung beetle pushing its ball (the snapshot it rolls
+// everywhere) on a green tile. Used as the favicon and the header
+// glyph. viewBox 0 0 64 64 so it scales cleanly to any icon size.
+export const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="${xe(BRAND_NAME)}">
+  <defs>
+    <linearGradient id="ck-bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1ea65c"/>
+      <stop offset="1" stop-color="${GREEN_DARK}"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="15" fill="url(#ck-bg)"/>
+  <g fill="none" stroke="#ffffff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="25" cy="33" r="11"/>
+    <path d="M38 46a6.5 6.5 0 0 1 13 0"/>
+    <path d="M12 48h40"/>
+  </g>
+  <circle cx="35.6" cy="44" r="2.6" fill="#ffffff"/>
+</svg>`;
+// Standalone mark without the tile background, for inlining next to text where
+// the surrounding element already provides colour/contrast.
+export const MARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="${xe(BRAND_NAME)}" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="25" cy="33" r="11"/>
+  <path d="M38 46a6.5 6.5 0 0 1 13 0"/>
+  <path d="M12 48h40"/>
+  <circle cx="35.6" cy="44" r="2.6" fill="currentColor" stroke="none"/>
+</svg>`;
+// Horizontal lockup: tile mark + wordmark. Dark text suits light backgrounds
+// (README, docs); the app header inlines the mark with CSS-coloured text so it
+// adapts to light/dark themes.
+export const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 290 64" width="290" height="64" role="img" aria-label="${xe(BRAND_NAME)}">
+  <defs>
+    <linearGradient id="ck-logo-bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1ea65c"/>
+      <stop offset="1" stop-color="${GREEN_DARK}"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="15" fill="url(#ck-logo-bg)"/>
+  <g fill="none" stroke="#ffffff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="25" cy="33" r="11"/>
+    <path d="M38 46a6.5 6.5 0 0 1 13 0"/>
+    <path d="M12 48h40"/>
+  </g>
+  <circle cx="35.6" cy="44" r="2.6" fill="#ffffff"/>
+  <text x="80" y="42" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="30" font-weight="700" fill="#0f2e1c">${xe(BRAND_NAME)}</text>
+</svg>`;
+// OpenGraph / Twitter card (1200x630). SVG is fine for the docs/app reference;
+// for maximal scraper support, export a PNG at release (brand/README.md).
+export const OG_CARD_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 630" width="1200" height="630" role="img" aria-label="${xe(BRAND_NAME)} — snapshot testing">
+  <defs>
+    <linearGradient id="ck-og" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0f2e1c"/>
+      <stop offset="1" stop-color="${GREEN_DARK}"/>
+    </linearGradient>
+  </defs>
+  <rect width="1200" height="630" fill="url(#ck-og)"/>
+  <g transform="translate(96 150)">
+    <rect width="120" height="120" rx="28" fill="#ffffff"/>
+    <g transform="translate(28 28) scale(1.0)" fill="none" stroke="${GREEN_DARK}" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="25" cy="33" r="11"/>
+      <path d="M38 46a6.5 6.5 0 0 1 13 0"/>
+      <path d="M12 48h40"/>
+      <circle cx="35.6" cy="44" r="2.6" fill="${GREEN_DARK}" stroke="none"/>
+    </g>
+  </g>
+  <text x="100" y="360" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="92" font-weight="800" fill="#ffffff">${xe(BRAND_NAME)}</text>
+  <text x="100" y="430" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif" font-size="38" font-weight="400" fill="#cdeedd">${xe(BRAND_SLOGAN)}</text>
+</svg>`;
+// PWA manifest. The SVG icon covers modern browsers; the generated PNG sizes
+// (served by app.ts from src/brandRasters.ts) cover installers that want
+// raster icons.
+export const WEBMANIFEST = JSON.stringify({
+    name: BRAND_NAME,
+    short_name: BRAND_SHORT_NAME,
+    description: BRAND_SUBTITLE,
+    start_url: "/",
+    display: "standalone",
+    background_color: "#ffffff",
+    theme_color: GREEN_DARK,
+    icons: [
+        { src: "/favicon.svg", type: "image/svg+xml", sizes: "any", purpose: "any maskable" },
+        { src: "/assets/icon-192.png", type: "image/png", sizes: "192x192" },
+        { src: "/assets/icon-512.png", type: "image/png", sizes: "512x512" }
+    ]
+}, null, 2);
+export const BRAND_THEME_COLOR = GREEN_DARK;

package/dist/contract.js

@@ -0,0 +1,11 @@
+// Wire contract for run ingestion.
+//
+// Deliberately kept independent of the CLI's internal `RunnerReport` type: this
+// is a network boundary, so the server validates structurally rather than
+// trusting a shared compile-time type. The CLI builds this payload from the
+// JSON report it already writes.
+// The major version of the HTTP API this server speaks. Served at /health and on
+// every /api response as the `Dungbeetle-Api-Version` header, so a client can detect
+// an incompatible server (a future v2) with a clear message instead of opaque
+// 404s. Bump when the API breaks compatibility (and mount the new path).
+export const API_VERSION = 1;

package/dist/mcp/api.js

@@ -0,0 +1,104 @@
+// An error carrying the HTTP status and the server's `{ error }` message, so the
+// MCP layer can surface an actionable message to the agent.
+export class DungbeetleApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "DungbeetleApiError";
+    }
+}
+export class DungbeetleApi {
+    baseUrl;
+    authHeader;
+    fetchImpl;
+    repoCache;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.authHeader =
+            opts.agentToken !== undefined
+                ? `Bearer ${opts.agentToken}`
+                : `Basic ${Buffer.from(`${opts.clientId}:${opts.clientSecret}`, "utf8").toString("base64")}`;
+        this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    // Deep link to the web review UI for a run (humans approve there).
+    async reviewUrl(runId) {
+        const repo = await this.repository();
+        return `${this.baseUrl}/ui/repos/${repo.id}/runs/${encodeURIComponent(runId)}`;
+    }
+    async health() {
+        return this.request("GET", "/healthz", { auth: false });
+    }
+    async repository() {
+        if (!this.repoCache) {
+            const { repository } = await this.request("GET", "/api/v1/repository");
+            this.repoCache = repository;
+        }
+        return this.repoCache;
+    }
+    async listBaselines() {
+        return this.request("GET", "/api/v1/baselines");
+    }
+    async baselineHistory(target) {
+        return this.request("GET", `/api/v1/baselines/${encodeURIComponent(target)}`);
+    }
+    async getRun(id) {
+        return this.request("GET", `/api/v1/runs/${encodeURIComponent(id)}`);
+    }
+    // Recent runs for the repository, newest first. `limit` defaults to 50
+    // server-side (clamped to 200); `branch` is an exact filter.
+    async listRuns(params) {
+        const query = new URLSearchParams();
+        if (params?.limit !== undefined) {
+            query.set("limit", String(params.limit));
+        }
+        if (params?.branch !== undefined) {
+            query.set("branch", params.branch);
+        }
+        const qs = query.toString();
+        return this.request("GET", `/api/v1/runs${qs ? `?${qs}` : ""}`);
+    }
+    // Current-period usage (snapshots + storage) with the plan limits it is
+    // measured against.
+    async usage() {
+        return this.request("GET", "/api/v1/usage");
+    }
+    async analytics() {
+        return this.request("GET", "/api/v1/analytics");
+    }
+    async reviewRun(id, body) {
+        return this.request("POST", `/api/v1/runs/${encodeURIComponent(id)}/review`, { body });
+    }
+    async request(method, path, opts = {}) {
+        const headers = {};
+        if (opts.auth !== false) {
+            headers.authorization = this.authHeader;
+        }
+        let body;
+        if (opts.body !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers, body });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new DungbeetleApiError(0, `Could not reach the Dungbeetle server at ${this.baseUrl}: ${reason}`);
+        }
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = { error: text };
+        }
+        if (!res.ok) {
+            const message = parsed.error ?? `Request failed with status ${res.status}.`;
+            throw new DungbeetleApiError(res.status, message);
+        }
+        return parsed;
+    }
+}

package/dist/mcp/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: BUSL-1.1
+// Dungbeetle Server — Copyright 2026 DungbeetleDev. See LICENSE.
+//
+// stdio entrypoint for the Dungbeetle MCP server (`dungbeetle-mcp` bin). Point any MCP
+// client at this command with an agent token (recommended — mint one with
+// `dungbeetle login`, so the agent has its own identity and scoped permissions):
+//
+//   DUNGBEETLE_AGENT_TOKEN=dbat_… dungbeetle-mcp
+//
+// or with the repository's client credentials, as used by `dungbeetle push`:
+//
+//   DUNGBEETLE_CLIENT_ID=cid_… DUNGBEETLE_CLIENT_SECRET=csec_… dungbeetle-mcp
+//
+// The hosted cloud is the default target; set DUNGBEETLE_SERVER_URL only when
+// self-hosting. stdout is the JSON-RPC channel — all diagnostics go to stderr.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DungbeetleApi } from "./api.js";
+import { createMcpServer } from "./server.js";
+// Keep in sync with the client CLI's DEFAULT_SERVER_URL (client/src/cloud.ts) —
+// the two packages build separately and can't share the constant.
+const DEFAULT_SERVER_URL = "https://dungbeetle.dev";
+async function main() {
+    const baseUrl = process.env.DUNGBEETLE_SERVER_URL || DEFAULT_SERVER_URL;
+    const agentToken = process.env.DUNGBEETLE_AGENT_TOKEN;
+    const clientId = process.env.DUNGBEETLE_CLIENT_ID;
+    const clientSecret = process.env.DUNGBEETLE_CLIENT_SECRET;
+    if (!agentToken && (!clientId || !clientSecret)) {
+        console.error("dungbeetle-mcp: set DUNGBEETLE_AGENT_TOKEN (an agent token from `dungbeetle login`) " +
+            "or DUNGBEETLE_CLIENT_ID and DUNGBEETLE_CLIENT_SECRET (the repository's client " +
+            "credentials, as used by `dungbeetle push`). DUNGBEETLE_SERVER_URL is only " +
+            "needed when self-hosting.");
+        process.exit(1);
+    }
+    const api = agentToken
+        ? new DungbeetleApi({ baseUrl, agentToken })
+        : new DungbeetleApi({ baseUrl, clientId: clientId, clientSecret: clientSecret });
+    const server = createMcpServer(api, process.env.DUNGBEETLE_VERSION ?? "0.1.0");
+    await server.connect(new StdioServerTransport());
+    console.error(`dungbeetle-mcp ready → ${baseUrl}`);
+}
+main().catch((err) => {
+    console.error("dungbeetle-mcp failed to start:", err);
+    process.exit(1);
+});

package/dist/mcp/server.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Dungbeetle Server — Copyright 2026 DungbeetleDev. See LICENSE.
+//
+// Builds the Dungbeetle MCP server: a low-level @modelcontextprotocol/sdk Server that
+// advertises the dungbeetle_* tools and dispatches calls through the tool layer. The
+// low-level API (plain JSON Schema, no zod) keeps this independent of the SDK's
+// internal validation library. Transport is attached by the caller (stdio in
+// src/mcp/index.ts; an in-memory pair in tests).
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { callTool, TOOLS } from "./tools.js";
+import { BRAND_NAME } from "../brand.js";
+export const MCP_SERVER_NAME = "dungbeetle";
+export function createMcpServer(api, version = "0.1.0") {
+    const server = new Server({
+        name: MCP_SERVER_NAME,
+        version,
+        title: `${BRAND_NAME} snapshot review`
+    }, {
+        capabilities: { tools: {} },
+        instructions: `${BRAND_NAME} exposes snapshot-test runs, diffs, baselines, and analytics for one repository. ` +
+            "Discovery loop: dungbeetle_list_runs to find a run id (newest first, filterable by branch), " +
+            "dungbeetle_get_run to triage it (a low-token structured diff summary; images are never " +
+            "inlined — open the review URL), then dungbeetle_approve_run / dungbeetle_reject_run to " +
+            "decide, or dungbeetle_reopen_run to set a decided run back to pending for re-review. " +
+            "dungbeetle_get_usage reports quota (snapshots/storage vs plan limits) before you push. " +
+            "Approving with promote=true mutates baselines, so confirm with a human before calling " +
+            "dungbeetle_approve_run. If authenticated with a scoped agent token, tools outside its " +
+            "granted scopes fail with HTTP 403 — surface the server's error message to the user."
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map((t) => ({
+            name: t.name,
+            title: t.title,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            annotations: { title: t.title, ...t.annotations }
+        }))
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return callTool(name, args ?? {}, api);
+    });
+    return server;
+}

package/dist/mcp/tools.js

@@ -0,0 +1,283 @@
+import { DungbeetleApiError } from "./api.js";
+function str(args, key) {
+    const v = args[key];
+    if (typeof v !== "string" || v.trim() === "") {
+        throw new DungbeetleApiError(400, `Missing required string argument "${key}".`);
+    }
+    return v;
+}
+// Concise, token-cheap summary of a run: counts + per-target status, with the
+// changed targets called out. No diff bodies, no screenshots.
+function summarizeRun(detail, reviewUrl) {
+    const { run, report } = detail;
+    const targets = report.results.map((r) => ({ name: r.name, kind: r.kind, status: r.status }));
+    const changed = targets.filter((t) => t.status !== "passed").map((t) => t.name);
+    return {
+        id: run.id,
+        status: run.status,
+        reviewState: run.reviewState ?? "pending",
+        branch: run.branch,
+        commit: run.commit,
+        createdAt: run.createdAt,
+        project: report.project,
+        counts: run.counts,
+        targets,
+        changed,
+        reviewUrl,
+        note: "Screenshots are not inlined — open reviewUrl to view before/after images."
+    };
+}
+// Detailed view: adds the structured text diff per target and flags whether an
+// image / promotable snapshot exists, still without shipping any base64 payload.
+function detailRun(detail, reviewUrl) {
+    const base = summarizeRun(detail, reviewUrl);
+    return {
+        ...base,
+        targets: detail.report.results.map((r) => ({
+            name: r.name,
+            kind: r.kind,
+            status: r.status,
+            diff: r.diff ?? null,
+            hasScreenshot: Boolean(r.screenshotRefs?.baseline ||
+                r.screenshotRefs?.candidate ||
+                r.screenshotRefs?.diff ||
+                r.screenshot?.baseline ||
+                r.screenshot?.candidate ||
+                r.screenshot?.diff),
+            promotable: typeof r.snapshot === "string" && r.snapshot.length > 0
+        }))
+    };
+}
+export const TOOLS = [
+    {
+        name: "dungbeetle_health",
+        title: "Server health",
+        description: "Liveness/version probe for the configured Dungbeetle server. Use to confirm connectivity before other calls.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (_args, api) => api.health()
+    },
+    {
+        name: "dungbeetle_get_repository",
+        title: "Identify repository",
+        description: "Return the repository the configured credentials resolve to (id, name). Everything else is scoped to it.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (_args, api) => api.repository()
+    },
+    {
+        name: "dungbeetle_list_baselines",
+        title: "List baseline targets",
+        description: "List the repository's baseline targets with their latest version and last-updated time. Start here to see what's under test.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (_args, api) => api.listBaselines()
+    },
+    {
+        name: "dungbeetle_get_baseline_history",
+        title: "Baseline version history",
+        description: "Full version history for one baseline target (versions, digests, timestamps).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                target: { type: "string", description: 'Target name, e.g. "home-page".' }
+            },
+            required: ["target"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (args, api) => api.baselineHistory(str(args, "target"))
+    },
+    {
+        name: "dungbeetle_list_runs",
+        title: "List recent runs",
+        description: "List recent runs for the repository, newest first — use this to discover a run id to triage with dungbeetle_get_run. Returns compact per-run summaries (id, status/passed, mode, branch, commit, createdAt, reviewState, failedCount, url); no diffs, no images.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Max runs to return (default 50, clamped to 200)."
+                },
+                branch: {
+                    type: "string",
+                    description: "Only runs pushed from this exact branch."
+                }
+            },
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: async (args, api) => {
+            const limit = typeof args.limit === "number" ? args.limit : undefined;
+            const branch = typeof args.branch === "string" && args.branch.trim() !== "" ? args.branch : undefined;
+            const { runs } = await api.listRuns({ limit, branch });
+            // Keep the per-run shape compact and explicit — enough to pick a run id
+            // for triage, nothing an agent has to page through.
+            return {
+                runs: runs.map((r) => ({
+                    id: r.id,
+                    status: r.status,
+                    passed: r.passed,
+                    mode: r.mode,
+                    branch: r.branch,
+                    commit: r.commit,
+                    createdAt: r.createdAt,
+                    reviewState: r.reviewState,
+                    failedCount: r.failedCount,
+                    url: r.url
+                }))
+            };
+        }
+    },
+    {
+        name: "dungbeetle_get_run",
+        title: "Get run / diff summary",
+        description: 'Structured summary of a run for triage: per-target status, counts, changed targets, current review state, and a review URL. Use detail="full" to include the text diff per target. Screenshots are never inlined — open the review URL for images.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                run_id: { type: "string", description: "Run id (from an ingested run or analytics)." },
+                detail: {
+                    type: "string",
+                    enum: ["concise", "full"],
+                    description: '"concise" (default) = status only; "full" = include text diffs.'
+                }
+            },
+            required: ["run_id"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: async (args, api) => {
+            const id = str(args, "run_id");
+            const [detail, reviewUrl] = await Promise.all([api.getRun(id), api.reviewUrl(id)]);
+            return args.detail === "full"
+                ? detailRun(detail, reviewUrl)
+                : summarizeRun(detail, reviewUrl);
+        }
+    },
+    {
+        name: "dungbeetle_get_review_url",
+        title: "Get review URL",
+        description: "Deep link to the web review page for a run, where a human reviews diffs and approves baselines.",
+        inputSchema: {
+            type: "object",
+            properties: { run_id: { type: "string", description: "Run id." } },
+            required: ["run_id"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: async (args, api) => {
+            const id = str(args, "run_id");
+            return { runId: id, url: await api.reviewUrl(id) };
+        }
+    },
+    {
+        name: "dungbeetle_get_analytics",
+        title: "Repository analytics",
+        description: "Pass rate, run trend, and per-target flakiness over the recent run window. Use to spot flaky targets before approving.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (_args, api) => api.analytics()
+    },
+    {
+        name: "dungbeetle_get_usage",
+        title: "Usage & plan limits",
+        description: "Current-period usage (snapshots ingested, storage bytes, repositories) alongside the plan limits it is measured against, plus any active quota warnings. Use to check quota before pushing runs or baselines.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: (_args, api) => api.usage()
+    },
+    {
+        name: "dungbeetle_approve_run",
+        title: "Approve run (optionally promote baselines)",
+        description: "Approve a run. With promote=true, the run's candidate snapshots become new hosted baseline versions — this MUTATES baselines and should be confirmed by a human first. Returns the recorded review and any promoted targets.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                run_id: { type: "string", description: "Run id to approve." },
+                note: { type: "string", description: "Optional reviewer note for the audit trail." },
+                promote: {
+                    type: "boolean",
+                    description: "Promote candidate snapshots to new baselines (default false)."
+                }
+            },
+            required: ["run_id"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+        handler: async (args, api) => {
+            const id = str(args, "run_id");
+            const note = typeof args.note === "string" ? args.note : undefined;
+            const promote = args.promote === true;
+            const result = await api.reviewRun(id, { state: "approved", note, promote });
+            return { ...result, reviewUrl: await api.reviewUrl(id) };
+        }
+    },
+    {
+        name: "dungbeetle_reject_run",
+        title: "Reject run",
+        description: "Reject a run's changes (records a rejected review in the append-only audit trail). Does not modify baselines.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                run_id: { type: "string", description: "Run id to reject." },
+                note: { type: "string", description: "Optional reviewer note." }
+            },
+            required: ["run_id"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+        handler: async (args, api) => {
+            const id = str(args, "run_id");
+            const note = typeof args.note === "string" ? args.note : undefined;
+            return api.reviewRun(id, { state: "rejected", note });
+        }
+    },
+    {
+        name: "dungbeetle_reopen_run",
+        title: "Reopen run for re-review",
+        description: "Reopen a previously approved or rejected run by setting its review state back to pending, so it can be re-reviewed. Recorded in the append-only audit trail; does not modify baselines.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                run_id: { type: "string", description: "Run id to reopen." },
+                note: { type: "string", description: "Optional reviewer note." }
+            },
+            required: ["run_id"],
+            additionalProperties: false
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+        handler: async (args, api) => {
+            const id = str(args, "run_id");
+            const note = typeof args.note === "string" ? args.note : undefined;
+            return api.reviewRun(id, { state: "pending", note });
+        }
+    }
+];
+// Dispatch a tool call to its handler, shaping the result into an MCP tool
+// result. Both a human-readable JSON `text` block and `structuredContent` are
+// returned so simple and structured clients are both served.
+export async function callTool(name, args, api) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const result = await tool.handler(args ?? {}, api);
+        const structured = result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { result };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: structured
+        };
+    }
+    catch (err) {
+        const message = err instanceof DungbeetleApiError
+            ? `${err.message}${err.status ? ` (HTTP ${err.status})` : ""}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "dungbeetle-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Dungbeetle, the snapshot and visual regression testing tool built for AI agents: list runs, read low-token semantic diffs, and review — with human-gated baseline promotion.",
+  "type": "module",
+  "license": "BUSL-1.1",
+  "mcpName": "dev.dungbeetle/mcp",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "dungbeetle-mcp": "dist/mcp/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/mcp/index.js', 0o755)\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "visual-regression-testing",
+    "snapshot-testing",
+    "visual-testing",
+    "dungbeetle",
+    "ai-agents",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://dungbeetle.dev/mcp/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DungbeetleTech/cloud.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/DungbeetleTech/cloud/issues"
+  },
+  "author": "DungbeetleDev <tech@dungbeetle.dev>",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  }
+}