Skip to main content
Glama
deenesjakoruzh
bretbouchard

Where's Waldo Rick

by bretbouchard
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Visual Regression MCP Server

Gemini 3 Flashを使用した視覚的リグレッションテストのためのエージェント型ビジョン機能をClaude Codeにもたらす、Model Context Protocol (MCP) サーバーです。

概要

視覚的な変更について曖昧な会話をするのはもう終わりにしましょう。何が変更されたのかを正確に把握し、丸で囲んで注釈を付け、意図した変更と意図しない変更を検出します。

解決する課題

  • 開発者がUIの変更に何時間も費やす

  • ビルドは成功し、コードは「クリーン」

  • アプリを開くと…レイアウトが全く同じ

  • 「具体的に何が変わったの？」と尋ねる

  • 開発者は「カードに2ピクセル追加した」と答える

  • 「どこ？上？下？ボックスの中？それとも周り？」と尋ねる

  • 😤 時間の無駄、不明瞭なコミュニケーション

解決策

Where's Waldo Rickは以下を提供します：

  1. 複数のプラットフォーム（macOS、iOSシミュレーター、Web）からのスクリーンショットキャプチャ

  2. 設定可能な閾値によるピクセル単位の比較

  3. Gemini 3 Flashを使用したエージェント型ビジョン分析（反復的なズーム/クロップ/注釈）

  4. 期待される変更と意図しない変更の検出

  5. 対話的な調査（「そのボックスではなく、子要素の方」）

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

インストール

要件

  • Python 3.10+

  • Gemini APIキー（無料枠：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の設定

Claude CodeのMCP設定（~/.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

ピクセルレベルの精度とエージェント型ビジョンを使用して、2つのスクリーンショットを比較します。

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ファイルを参照してください

謝辞

以下を使用して構築されました：

Happy を通じて Claude Code で生成されました

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers