TestivAI

@testivai/mcp

MCP (Model Context Protocol) server that gives AI coding agents eyes on your visual regression results. The agent changes UI code, runs your test suite, then uses these tools to find out what actually changed on screen — and whether it is a real change, likely render noise, or a case the DOM and style signals cannot settle.

Tools

The server also ships two prompts. review-visual-changes walks the agent through a full review: summary, explain_snapshot per change, diff images when the evidence is ambiguous, and a recommendation per snapshot. triage-visual-diff (optional snapshot and intent arguments) sorts each diff, and each missing baseline, into glitch, intended change, bug or possible bug, with the evidence and a next step; a changed DOM or changed computed styles is never a glitch, and neither is a missing baseline. The same rules run in CI with the testivai/testivai-oss/review@v1 action.

Approval is a human decision

approve_snapshot and approve_all exist so a human who has looked at a diff can say "approve it" in the conversation and have the agent carry it out. They are not for the agent to decide on its own: approving rewrites what "correct" means, so an agent that approves its own change can launder a regression into the baseline. Both tool descriptions, the review-visual-changes prompt, and every get_visual_results response say so. After approving, commit .testivai/baselines/.

In Claude Code the client enforces this: both approve tools are marked anthropic/requiresUserInteraction, so Claude Code asks you on every approve call, even in auto-approving permission modes. To turn that off, start the server with --no-approval-prompt or set "mcpApprovalPrompt": false in .testivai/config.json (the flag wins); the approve tools then follow your client's own permission settings. Walkthrough: Review and approve in Claude Code.

The other approval paths stay available: npx testivai approve locally, or a /testivai approve comment on the pull request.

Setup

Claude Code

claude mcp add testivai -- npx -y @testivai/mcp

Cursor / other MCP clients

// .cursor/mcp.json (or your client's equivalent)

{ "mcpServers": { "testivai": { "command": "npx", "args": ["-y", "@testivai/mcp"] } } }

The server reads the project from its working directory (pass --root to override) and respects reportDir from .testivai/config.json.

Typical agent flow

1. Agent edits UI code.
2. Agent runs npx playwright test (the TestivAI reporter captures + diffs).
3. Agent calls get_visual_results and sees, for example, homepage: changed (4.20% pixels differ) and the DOM changed (2 added, 1 removed, 0 attribute changes) — a real structural change; confirm it is intended before approving.
4. Agent calls explain_snapshot homepage for the evidence, and get_diff homepage to look at the images (the full page, then the changed regions at native scale), then confirms the change matches the task (or fixes its own regression).
5. Agent reports to the human: what changed, whether it looks intended, and which snapshots need approval. If the human says to approve, the agent calls approve_snapshot; otherwise the human approves with npx testivai approve or /testivai approve on the PR.

Local mode only — no account, no API key, nothing leaves the machine.

Full integration guide (instructions-file level, MCP level, zero-test-suite apps, real transcript): docs/guides/ai-agents.md