MCP-сервер для визуального регрессионного тестирования

Сервер протокола контекста модели (MCP), который добавляет возможности агентского зрения в Claude Code для визуального регрессионного тестирования с использованием Gemini 3 Flash.

Обзор

Больше никаких двусмысленных разговоров о визуальных изменениях. Видьте точно, что изменилось, с обводками и аннотациями, а также с функцией обнаружения преднамеренных и непреднамеренных изменений.

Решаемая проблема

• Разработчик часами работает над изменениями интерфейса

• Сборка проходит успешно, код «чист»

• Вы открываете приложение... макет точно такой же

• Вы спрашиваете: «Что именно изменилось?»

• Разработчик отвечает: «Мы добавили 2 пикселя к карточке»

• Вы спрашиваете: «Где? Сверху? Снизу? Внутри блока? Вокруг него?»

• 😤 Потеря времени, неясная коммуникация

Решение

Where's Waldo Rick предоставляет:

1. Захват скриншотов с различных платформ (macOS, симулятор iOS, веб)

2. Попиксельное сравнение с настраиваемыми порогами

3. Анализ агентским зрением с использованием Gemini 3 Flash (итеративное масштабирование/обрезка/аннотирование)

4. Обнаружение ожидаемых и непреднамеренных изменений

5. Диалоговое исследование («Не этот блок, а дочерний элемент»)

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

Установка

Требования

• Python 3.10+

• API-ключ Gemini (бесплатный уровень: 15 запросов в минуту)

Установка из GitHub

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

# Or install locally
pip install -e .

Настройка Claude Code

Добавьте в конфигурацию MCP Claude Code (~/.claude/mcp.json или специфичную для проекта):

{
  "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"
      }
    }
  }
}

Использование

Базовый рабочий процесс

# 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

visual_capture

Захват скриншота и его сохранение для визуального регрессионного тестирования.

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

visual_prepare

Объявление базовой линии с ожидаемыми изменениями перед разработкой.

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

visual_compare

Сравнение двух скриншотов с попиксельной точностью и агентским зрением.

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

Очистка старых скриншотов и кэша.

await visual_cleanup(retention_days=7)

Разработка

Настройка

# 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/

Структура проекта

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

Дорожная карта

• [x] Фаза 1: Основа (скелет MCP-сервера, типы, хранилище)

• [ ] Фаза 2: Захват и базовые линии (мультиплатформенные скриншоты)

• [ ] Фаза 3: Механизм сравнения (интеграция OpenCV + Gemini) 🔥 ВЫСОКИЙ РИСК

• [ ] Фаза 4: Операции (кэширование, прогрессивное разрешение, отчетность)

• [ ] Фаза 5: Полировка (диалоговое исследование)

Полный план выполнения см. в ROADMAP.md.

Участие в разработке

Вклад приветствуется! Пожалуйста, ознакомьтесь с REQUIREMENTS.md и ROADMAP.md перед внесением изменений.

Лицензия

Лицензия MIT — подробности см. в файле LICENSE

Благодарности

Создано с использованием:

• MCP Python SDK

• FastMCP

• Google Gemini 3 Flash

• OpenCV

• MSS

Создано с помощью Claude Code через Happy