Where MCP

可视化回归MCP服务器

一个模型上下文协议（MCP）服务器，它带来 智能视觉能力 Claude Code使用Gemini 3 Flash进行视觉回归测试。

概述

再也不要对视觉变化进行模棱两可的对话。通过预期与非预期的更改检测，准确查看更改、圈出和注释的内容。

问题解决了

• 开发人员花费数小时进行UI更改
• 构建通过，代码“干净”
• 你打开应用程序。..完全相同的布局
• 你问：“具体发生了什么变化？”
• Dev说：“我们在卡上添加了2个像素”
• 你问：“在哪里？顶部？底部？盒子里面？周围？”
• 😤 浪费时间，沟通不清

解决方案

Waldo Rick在哪里提供：

1. 从多个平台（macOS、iOS模拟器、Web）捕获屏幕截图
2. 与可配置阈值进行像素完美比较
3. 使用Gemini 3 Flash进行代理视觉分析（迭代缩放/裁剪/注释）
4. 预期与非预期变化检测
5. 对话式调查（“不是那个盒子，是儿童物品”）

安装

需求

• 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代码

添加到您的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

比较两个具有像素级精度和代理视觉的屏幕截图。

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\] 第一阶段：基础（MCP服务器骨架、类型、存储）
• \[\]第2阶段：捕捉和基线（多平台截图）
• \[\]第3阶段：比较引擎（OpenCV+Gemini集成）🔥 高风险
• \[\]第4阶段：操作（缓存、渐进式解析、报告）
• \[\]第五阶段：波兰语（对话式调查）

看 ROADMAP.md 完整的执行计划。

贡献

欢迎投稿！请阅读 要求.md 和 ROADMAP.md 在做出贡献之前。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

内置：

• MCP Python SDK
• FastMCP
• 谷歌双子座3 Flash
• OpenCV
• 海上保安厅

______________________________________________________________________

生成于 克劳德代码 通过 快乐