Visual Regression MCP Server

Ein Model Context Protocol (MCP)-Server, der agentische Vision-Funktionen für visuelle Regressionstests mittels Gemini 3 Flash in Claude Code integriert.

Überblick

Führen Sie nie wieder zweideutige Gespräche über visuelle Änderungen. Sehen Sie genau, was sich geändert hat – eingekreist und kommentiert – mit Erkennung von beabsichtigten gegenüber unbeabsichtigten Änderungen.

Gelöstes Problem

• Entwickler arbeitet stundenlang an UI-Änderungen

• Build ist erfolgreich, Code ist "sauber"

• Sie öffnen die App... exakt das gleiche Layout

• Sie fragen: "Was genau hat sich geändert?"

• Entwickler sagt: "Wir haben 2 Pixel zur Karte hinzugefügt"

• Sie fragen: "Wo? Oben? Unten? Innerhalb des Kastens? Drumherum?"

• 😤 Zeitverschwendung, unklare Kommunikation

Lösung

Where's Waldo Rick bietet:

1. Screenshot-Aufnahme von mehreren Plattformen (macOS, iOS-Simulator, Web)

2. Pixelgenauer Vergleich mit konfigurierbaren Schwellenwerten

3. Agentische Vision-Analyse mittels Gemini 3 Flash (iteratives Zoomen/Zuschneiden/Kommentieren)

4. Erkennung von erwarteten vs. unbeabsichtigten Änderungen

5. Konversationelle Untersuchung ("Nicht dieser Kasten, das untergeordnete Element")

Related MCP server: visual-ui-debug-agent-mcp

Installation

Voraussetzungen

• Python 3.10+

• Gemini API-Schlüssel (kostenloses Kontingent: 15 Anfragen/Minute)

Installation von GitHub

# Install via uvx
uvx --from git+https://github.com/bretbouchard/gemini-vision-mcp wheres_waldo.server

# Or install locally
pip install -e .

Konfiguration von Claude Code

Fügen Sie dies zur MCP-Konfiguration von Claude Code hinzu (~/.claude/mcp.json oder projektspezifisch):

{
  "mcpServers": {
    "wheres-waldo-rick": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/bretbouchard/gemini-vision-mcp", "wheres_waldo.server"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Verwendung

Grundlegender Arbeitsablauf

# 1. Declare expected changes before work
/visual:prepare "Card padding increases by 2px, button moves to right"

# 2. Capture baseline screenshot
/visual:capture "Phase 3 - Before card update"

# 3. Development happens...

# 4. Capture current state
/visual:capture "Phase 4 - After card update"

# 5. Compare and see all changes
/visual:compare screenshots/phases/3-before.png screenshots/phases/4-after.png

MCP-Tools

visual_capture

Erstellen Sie einen Screenshot und speichern Sie ihn für visuelle Regressionstests.

await visual_capture(
    name="Phase 3 - Before card update",
    platform="macos"  # auto, macos, ios, web
)

visual_prepare

Deklarieren Sie eine Basislinie mit erwarteten Änderungen vor der Entwicklung.

await visual_prepare(
    phase="Phase 3 - Card Layout Update",
    expected_changes="Card padding increases by 2px, button moves to right"
)

visual_compare

Vergleichen Sie zwei Screenshots mit Pixelpräzision und agentischer Vision.

await visual_compare(
    before_path="screenshots/phases/3-before.png",
    after_path="screenshots/phases/4-after.png",
    threshold=2  # 1px, 2px, or 3px
)

visual_cleanup

Bereinigen Sie alte Screenshots und den Cache.

await visual_cleanup(retention_days=7)

Entwicklung

Einrichtung

# Clone repository
git clone https://github.com/bretbouchard/gemini-vision-mcp
cd gemini-vision-mcp

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
ruff check src/

Projektstruktur

src/wheres_waldo/
├── __init__.py
├── server.py          # MCP server with tool definitions
├── models/            # Pydantic domain models
├── services/          # Business logic (capture, compare, storage)
├── tools/             # MCP tool implementations
└── utils/             # Logging, hashing, path helpers

Roadmap

• [x] Phase 1: Grundlage (MCP-Server-Skelett, Typen, Speicher)

• [ ] Phase 2: Aufnahme & Basislinien (Multi-Plattform-Screenshots)

• [ ] Phase 3: Vergleichs-Engine (OpenCV + Gemini-Integration) 🔥 HOCHRISIKO

• [ ] Phase 4: Betrieb (Caching, progressive Auflösung, Berichterstattung)

• [ ] Phase 5: Feinschliff (konversationelle Untersuchung)

Siehe ROADMAP.md für den vollständigen Ausführungsplan.

Mitwirken

Beiträge sind willkommen! Bitte lesen Sie REQUIREMENTS.md und ROADMAP.md, bevor Sie einen Beitrag leisten.

Lizenz

MIT-Lizenz - Siehe LICENSE-Datei für Details

Danksagungen

Erstellt mit:

• MCP Python SDK

• FastMCP

• Google Gemini 3 Flash

• OpenCV

• MSS

Generiert mit Claude Code via Happy