MCP server
CLOUD API URL REQUIRED. There is no working hosted default or supported production self-host quick start. Use cloud-dependent source only with a deployment you operate and have independently verified.
@frontguard/mcp gives coding agents structured access to local visual regression reports, diff clusters and static CSS patch checks. Reading local reports needs no cloud account or API key.
Configuration
From your project directory, start the app and prepare reviewed baselines first. JSON output goes to stdout, so create the report directory and redirect it into the file MCP will read:
Exit 1 means the report contains regressions or unaccepted screenshots; exit 2 indicates an error to investigate. Run the MCP client from this project directory, or use an absolute FRONTGUARD_LOCAL_REPORT path.
Cloud-dependent tools require an independently verified FRONTGUARD_API_URL deployment and FRONTGUARD_API_KEY; no working hosted default is supplied. The package ships an MCP Registry server.json manifest under io.github.ravidsrk/frontguard and negotiates both 2025-11-25 and 2026-07-28 MCP protocol versions.
Tools
| MCP Tool Name | Required Arguments | What It Returns to the Coding Agent |
|---|---|---|
list_regressions | pr_id; optional repo, limit, cursor | Lists regressions worst first, each with a diffId and a clusterCount, 25 per page by default (max 200). Use a PR number, a run ID returned by recent_runs, or "latest" for the newest run (the report's run in local-report mode). Pass nextCursor back as cursor for the next page. |
inspect_diff_cluster_dom | diff_id; optional cluster_id | Returns the diff clusters with bounding boxes and recorded target selectors, plus the classification, explanation and suggested fix. |
get_suggested_fix | diff_id | Returns a stored suggested fix if one exists. Fixes exist only when the run had an ai provider and generateFixes: true. |
verify_css_patch | diff_id, css_patch, target_selector | Statically checks CSS syntax, a deny list, and whether target_selector matches a selector recorded for the diff. It renders nothing and does not apply the patch: staticCheck pass comes with rendered: false. |
promote_baseline | run_id, confirm_reviewed: true; optional routes | Write tool, registered only with FRONTGUARD_MCP_WRITES=1; agents should not call it. Cloud API mode only: records whole-run approval through the same endpoint as accept_baseline and promotes no screenshots. routes must include every changed route. Refuses local-report mode. |
accept_baseline | run_id, confirm_all_regressions_reviewed: true | Write tool, registered only with FRONTGUARD_MCP_WRITES=1. Records whole-run approval metadata in the local JSON report or Cloud API; does not replace screenshot baselines. |
recent_runs | optional repo, branch, limit | Lists runs, including the local run ID when reading a JSON report. |
list_horizontal_overflow | optional run_id, flagged_only, limit, cursor | Lists horizontal overflow from the JSON report, largest overflow first, 25 per page by default (max 200). A flagged row is a visible unclipped box past the right edge; only flagged rows are returned unless flagged_only is false. It does not change the pixel result. |
Agentic debugging workflow
list_regressions with {"pr_id": "latest"} for the newest run, or with a run ID from recent_runs. Rows come worst first; pass nextCursor back as cursor for more. Pass a returned diffId as the diff_id input to inspect_diff_cluster_dom or get_suggested_fix.Approval limit
promote_baseline and accept_baseline are registered only when FRONTGUARD_MCP_WRITES=1, and agents should not call them. MCP promotion is refused in local-report mode and does not write the frontguard-baselines branch. The local write is the CLI command frontguard update-baselines --confirm-baselines, which a human runs. An agent setting confirm_reviewed: true on itself is not a human review, and an advisory caption cannot set that flag. Cloud approveRun is not a production path; do not point the MCP client at a production host. accept_baseline can mark a JSON report approved, but it does not replace screenshot baselines. Cloud tools record approval metadata only; cloud screenshot promotion is not implemented.
