// turbo-all

UX Visual Reviewer MCP Server

This skill explains how to use the UX Visual Reviewer MCP server to run automated visual reviews (NRQA checks, screenshots, video recordings) of any web UI accessible via HTTP.

[!IMPORTANT] CC agents must NOT perform visual/UX testing directly (see GEMINI.md rule 10). All visual verification goes through this MCP server. CC agents consume the returned artifacts.

Who Does What

CC agents: skip to Reading NRQA Findings and Post-Run Checklist for your workflow. The Quick Start section below is for UX Visual Reviewer-resident agents only.

Prerequisites

1. •MCP server running on http://127.0.0.1:4040
2. •Target UI served via HTTP (e.g., http://127.0.0.1:3050/gui/index.html)
3. •ffmpeg installed with libwebp_anim encoder (for animated WebP video output)

Starting the MCP Server

cd /Users/anthonywright/Developer/Antigravity\ Apps/ux-visual-reviewer

# Development mode (auto-restarts on code changes via tsx watch)
npm run mcp:dev

# Production mode
npm run mcp

Verify health:

curl http://127.0.0.1:4040/health

Quick Start (Copy-Paste Recipe)

This 4-step recipe runs a complete visual review. Replace YOUR_URL with your target.

Step 1: Register a Token

TOKEN=$(curl -s -X POST http://127.0.0.1:4040/registerToken \
  -H 'Content-Type: application/json' \
  -d '{"tier":"standard","audience":"external","allowedEndpoints":["*"],"budgetRemaining":100,"rateLimitRpm":30}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tokenId'])")
echo "TOKEN=$TOKEN"

Step 2: Start a Smart Run

RESULT=$(curl -s -X POST http://127.0.0.1:4040/startSmartRun \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message":"Visual review of MY_APP at YOUR_URL"}')
RUNID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['runId'])")
echo "RUNID=$RUNID"

Step 3: Wait for Completion (~30s) and Check Status

sleep 30
curl -s "http://127.0.0.1:4040/streamRunEvents?runId=$RUNID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Look for "status": "completed" and "Run completed — PASS". If "status": "failed", check the error message.

Step 4: Get Artifacts

curl -s "http://127.0.0.1:4040/getArtifacts?runId=$RUNID" \
  -H "Authorization: Bearer $TOKEN" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for a in data['artifacts']:
    print(f'{a[\"type\"]:12s} {a[\"sizeBytes\"]:>8d}B  {a[\"relativePath\"]}')"

Artifact Types

[!TIP] Video artifacts are animated .webp files — Antigravity's native format for inline video playback. Embed them in walkthroughs with ![caption](/absolute/path/to/file.webp).

Copying Artifacts to Your Conversation

After getting artifacts, copy the ones you need to your conversation's brain directory:

# Copy screenshot
cp "/Users/anthonywright/Developer/Antigravity Apps/ux-visual-reviewer/captures/<target>/<screenshot>.png" \
   "/Users/anthonywright/.gemini/antigravity/brain/<conversation-id>/my-screenshot.png"

# Copy video
cp "/Users/anthonywright/Developer/Antigravity Apps/ux-visual-reviewer/captures/<target>/<run-uuid>/<video>.webp" \
   "/Users/anthonywright/.gemini/antigravity/brain/<conversation-id>/my-video.webp"

The relativePath from getArtifacts gives you the path relative to the ux-visual-reviewer root.

Reading NRQA Findings

[!CAUTION] NEVER dismiss, rationalize, or deprioritize P-level findings. Every P0, P1, P2, and P3 finding returned by the NRQA report is actionable and must be fixed — not explained away as "just accessibility," "cosmetic-only," or "not the major issue." UX Visual Reviewer checks are explicitly refined by the project owner; they are intentional, not over-sensitive. If a finding is flagged, the default action is to fix it. The only path to not fixing is explicit user confirmation after seeing cropped evidence of the specific issue. See ai-slop-avoidance skill for the full anti-dismissal ruleset.

The assertion report JSON contains findings organized by severity:

curl -s "http://127.0.0.1:4040/getArtifacts?runId=$RUNID" \
  -H "Authorization: Bearer $TOKEN" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for a in data['artifacts']:
    if a['type'] == 'assertion':
        print(a['relativePath'])"

Then read the report file directly for detailed findings with proof objects.

Post-Run Checklist (Mandatory)

After every NRQA run, follow this exact sequence. Do not skip steps.

1. •Read the full assertion report — parse the JSON, don't skim or skip sections
2. •Count findings: report P0=N, P1=N, P2=N, P3=N — all four severity levels
3. •If any findings > 0:
   • •Fix every finding (see ai-slop-avoidance skill for anti-dismissal rules)
   • •Rebuild and relaunch the app
   • •Re-run the NRQA (go back to Step 2 of Quick Start)
   • •Repeat until all counts are 0
4. •If all findings = 0: proceed — no further fixes needed
5. •Report the verified result with exact counts and run ID

[!CAUTION] Never stop after a single run with findings > 0. The cycle is: fix → rebuild → re-run → verify 0. Agents who fix findings but don't re-run to confirm are making premature success claims (see ai-slop-avoidance skill, section 3).

Filing Issues

Use /fileIssue to report bugs found during review:

curl -s -X POST http://127.0.0.1:4040/fileIssue \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "Brief description of the issue",
    "severity": "P1",
    "category": "video-artifacts",
    "description": "Detailed description with reproduction steps",
    "reporter": "command-center/opus"
  }' | python3 -m json.tool

Severity Levels

[!CAUTION] ALL P-level findings (P0–P3) must be fixed (see GEMINI.md rule 11). Do NOT dismiss P2/P3 as "acceptable" or "cosmetic-only." Minor issues collectively destroy UI/UX quality. UX Visual Reviewer checks are explicitly refined by the project owner — they are intentional, not over-sensitive. Agents must NEVER rationalize, explain away, or downplay findings — if the NRQA flags it, fix it. The only path to not fixing a finding is explicit user confirmation after presenting cropped evidence of the specific issue.

Categories

video-artifacts · nrqa-checks · mcp-server · test-execution · evidence-bundle · gate-evaluation · configuration · other

Querying Issues

# All open issues
curl -s "http://127.0.0.1:4040/listIssues?status=open" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

# Filter by severity
curl -s "http://127.0.0.1:4040/listIssues?severity=P1" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Available Endpoints

Troubleshooting

Run Fails with Navigation Timeout

The target UI likely uses WebSockets or long-polling that prevents Playwright's networkidle from resolving. UX Visual Reviewer now uses domcontentloaded as the default wait strategy, which handles this. If you still see timeouts:

1. •Verify target is reachable: curl -s -o /dev/null -w "%{http_code}" YOUR_URL
2. •Check MCP server stderr for error details
3. •Cold restart the MCP server (kill port 4040, restart)

No Video Artifacts Returned

Video finalization requires context.close() before video discovery. If getArtifacts returns 0 videos:

1. •Check server stderr for [discoverVideoFiles] debug logs
2. •Look for files with size=0 — this means the recording wasn't finalized
3. •File an issue via /fileIssue with category video-artifacts

Server Won't Start

# Kill anything on port 4040
lsof -ti:4040 | xargs kill -9 2>/dev/null
sleep 2

# Restart
cd /Users/anthonywright/Developer/Antigravity\ Apps/ux-visual-reviewer
npm run mcp:dev

Cross-Agent Messaging for UX Issues

When reporting issues to UX Visual Reviewer from another repo, use the standard cross-repo message format:

From Team: command-center
By: Opus

To Team: ux-visual-reviewer
For: Opus

File: runners/local-runner.ts
Action: STATUS
Expected response: verbal acknowledgement + fix

[Your issue description here]

See the cross-repo-collab skill for full messaging protocol.