# EagleEye MCP

<!-- mcp-name: io.github.baimaomaomao556/eagleeye-mcp -->

**0.6.1 beta** — Pixel-accurate visual toolbox for Agents  
截屏 · 像素测量 · OCR · 模板匹配 · 视觉回归（确定性优先，不是「把图读成一段话」）

> Acquire → Focus → Measure → Perceive · Compare · Verify

公开仓库：https://github.com/baimaomaomao556/eagleeye-mcp（git tag `dsh-plugin`）。  
与摄像头 MCP「Open Eagle Eye」无关。

## 这是什么 / 不是什么

EagleEye 是 **MCP Server**（stdio），不是一次性看图 CLI。DSH / Agent Skills 薄包装见 `skills/eagleeye/`。

| 你要做的事 | 用 |
|---|---|
| 对话里出现一张图，先读成结构化证据 | [modlens](https://www.npmjs.com/package/@liustack/modlens) |
| 按剧本还原 UI / 长截图 OCR / 描 SVG | [vision-tools](https://github.com/Anionex/agent-vision-toolkit) |
| **截当前桌面、量像素、做视觉回归** | **EagleEye** |

## 平台能力

| 能力 | Windows | macOS / Linux |
|---|---|---|
| `capture_screen` / `load_image` / 测量 / OCR / Visual QA | 支持 | 支持 |
| `list_monitors` | 支持（含 DPI） | 支持（mss bounds，无 DPI） |
| `list_windows` / `capture_window` | 支持 | `PLATFORM_UNSUPPORTED` |
| `capture_window_graphics`（后台渲染表面） | Win10 2004+ | `PLATFORM_UNSUPPORTED` |

窗口类工具在非 Windows 上返回结构化错误，不会静默失败。请改用 `capture_screen` 或 `load_image`。

## 快速开始

### 本地开发（当前推荐）

```bash
python -m venv .venv
.venv\Scripts\pip install -e .          # Windows
# .venv/bin/pip install -e .            # Linux/macOS

copy .env.example .env                  # 或写入 ~/.eagleeye/.env
.venv\Scripts\eagleeye doctor
.venv\Scripts\eagleeye                  # MCP stdio
# 等价：python -m eagleeye_mcp
```

Host 接入见 [docs/HOSTS.md](docs/HOSTS.md)。上下文紧张时可设 `EAGLEEYE_TOOL_PROFILE=core`，只暴露 Phase 1 的 8 个工具；默认 `full` 为全部 32 个。

### uvx / skills

```bash
uvx --from git+https://github.com/baimaomaomao556/eagleeye-mcp eagleeye doctor
npx skills add baimaomaomao556/eagleeye-mcp --skill eagleeye
```

示例 Host 配置见 `examples/mcp.uvx.json`；本地已安装时用 `examples/mcp.local.json`。

## 工具清单（32 个，按计划分层）

### Phase 1 · MVP（8 个）· `EAGLEEYE_TOOL_PROFILE=core`

| 层级 | 工具 | 说明 |
|---|---|---|
| L0 获取 | `capture_screen` | 屏幕截图（mss，多显示器，含黑帧检测） |
| L0 获取 | `load_image` | 加载本地图片 |
| L1 视野 | `crop_image` | 按精确坐标裁剪 |
| L2 测量 | `get_pixel` | 读取像素颜色 |
| L2 测量 | `sample_region` | 区域颜色统计（均值/主色） |
| L2 测量 | `compare_images` | 逐像素差异比较（MSE/差异图，纯数学不做判定） |
| L3 感知 | `ocr` | 本地 Tesseract 文字识别 |
| L3 感知 | `analyze_image` | 多模态模型视觉问答（OpenAI 兼容端点，支持 structured 证据区域） |

### Phase 2 · 主动视觉与发现（17 个）

| 层级 | 工具 | 说明 |
|---|---|---|
| L0 发现 | `list_windows` | **枚举窗口**（句柄/标题/进程/位置/最小化），解决动态标题无法匹配的问题 |
| L0 发现 | `list_monitors` | **枚举显示器**（bounds/work_area/DPI 缩放/primary/mss_index） |
| L0 获取 | `capture_window` | 按窗口句柄/标题截取指定窗口（**= 用户实际看到的画面**，可 bring_to_front 置前台） |
| L0 获取 | `capture_window_graphics` | **后台捕获渲染表面**（Graphics Capture）：被遮挡/非前台也能拿到，**不代表屏幕实际显示** |
| L0 获取 | `save_image` | 将 image_ref 导出到指定路径（png/jpeg/webp） |
| L1 视野 | `focus_region` | **便捷语义定位**：按线索（模板/颜色/文字/视觉）自动聚焦局部，返回实际使用的方法 |
| L1 视野 | `zoom_region` | 放大局部精查（保留原始分辨率与缩放变换） |
| L1 视野 | `tile_image` | 大图拆瓦片，分区域扫描 |
| L2 测量 | `get_image_info` | 图像完整元数据（来源链/变换/屏幕原点/内存/哈希） |
| L2 测量 | `find_color` | 查找指定颜色（数量/包围盒/质心） |
| L2 测量 | `template_match` | OpenCV 模板匹配（多尺度、多匹配、可视化） |
| L2 测量 | `measure_region` | 区域几何测量（位置/尺寸/面积/中心） |
| L2 测量 | `detect_edges` | Canny 边缘检测（边缘占比 + 可视化） |
| L2 测量 | `detect_contours` | 轮廓检测（数量/包围盒/面积 + 可视化） |
| L3 感知 | `locate_text` | OCR 文本框定位（文字目标的确定性定位） |
| L3 感知 | `locate_visual_element` | 视觉模型语义定位 bbox（推断，需复核） |
| L3 感知 | `describe_image` | 视觉模型整图描述（语义，冷路径） |
| L3 感知 | `score_image` | **感知评分**：画质/审美 0~1（Q-ReAlign Mini 默认，可换 musiq-ava/nima；`pip install eagleeye-mcp[score]`） |

### Phase 3 · Visual QA（5 个）

| 层级 | 工具 | 说明 |
|---|---|---|
| L4 高级 | `check_ui_element` | 按规范检查**单个元素**：存在/素材/位置/尺寸/裁切/颜色（三态 pass/fail/inconclusive） |
| L4 高级 | `check_layout` | 元素间几何关系：越界/重叠 |
| L4 高级 | `inspect_ui` | 测试套件编排器：批量检查 + 可选布局分析，汇总报告 |
| L4 高级 | `compare_with_reference` | 判定层：与参考图对比（identical/similar/different，支持 ignore_regions） |
| L4 高级 | `visual_regression` | 生命周期层：基线管理 + 判定 + 差异图（支持 ignore_regions 屏蔽动态区域） |

### 组合工具（1 个）

| 层级 | 工具 | 说明 |
|---|---|---|
| L3 感知 | `ocr_verify` | OCR + 低置信度视觉复核（确定性优先、语义兜底，按行合并碎片） |

### Phase 4 · Visual Inspection Runtime（1 个）

| 层级 | 工具 | 说明 |
|---|---|---|
| L0 运行时 | `wait_for_visual` | 轮询直到视觉条件成立：text/template/color appears、image_changes、image_stabilizes；超时为 inconclusive |

## 设计约定（v0.5 基础设施重构）

- **image_ref**：工具间通过 `vision://image/xxx` 引用图像，不传输 Base64；图像落盘于 `vision_store/` 或 `~/.eagleeye/vision_store`，
  生命周期自动管理（LRU 逐出 + 可选 TTL）
- **坐标系**：统一左上角原点 `(x, y, width, height)`，物理像素；`region` 也兼容 `[x,y,w,h]`
- **三坐标系溯源（provenance）**：所有返回 region 的工具附带
  `local_region`（本图）/ `root_region`（根图）/ `screen_region`（屏幕像素）——
  无论 capture → crop → tile → crop → zoom → OCR 都能追溯回原始像素
- **统一信封**：成功 `{ok: true, ...}`；失败 `{ok: false, error: {code, message}}`；
  测试类工具三态 `pass / fail / inconclusive`；**找不到目标 ≠ 失败 ≠ 工具错误**
- **工具选择优先级**：`L2 算法视觉 > L3 OCR > L3 视觉模型 > L4 组合`——
  优先使用能得到确定性结果的最低层工具，视觉推断负责提假设、确定性工具负责验证
- **confidence** 为模型自评/启发式评分，**不是校准概率**（附 high/medium/low 档位）
- **capture 语义固化**：capture_window = 用户看到的画面（受遮挡）；
  capture_window_graphics = 渲染表面（可后台，不代表屏幕实际显示）

## 测试与演示

```bash
# 单元测试
.venv\Scripts\python -m pytest tests -q

# 端到端 MCP stdio 测试（当前 profile 下已注册工具全链路，真实调用 MCP 协议）
.venv\Scripts\python scripts\test_client.py
# 跳过截图 / 跳过视觉模型调用
.venv\Scripts\python scripts\test_client.py --skip-capture --skip-vision

# Phase 4 闭环演示：基线检查 → 模拟改动 → 回归检出 → 修复确认
.venv\Scripts\python scripts\demo_agent_loop.py

# 自动化游戏截图演示：等待窗口 → bring_to_front → 截图（无人为干预）
.venv\Scripts\python scripts\demo_auto_capture.py
```

## 文档

- [docs/PROTOCOL.md](docs/PROTOCOL.md) — 协议规范（坐标溯源/ImageRef/Observation/错误码/三态/捕获语义）
- [docs/TOOL_REFERENCE.md](docs/TOOL_REFERENCE.md) — 32 个工具完整参考与工具选择路由
- [docs/USAGE.md](docs/USAGE.md) — 工具使用手册（含示例参数与工作流）
- [docs/HOSTS.md](docs/HOSTS.md) — Claude Desktop / Claude Code / Cursor / DSH / uvx 接入
- [skill/SKILL.md](skill/SKILL.md) / [skills/eagleeye/SKILL.md](skills/eagleeye/SKILL.md) — Agent Skills / DSH 薄包装
- [examples/mcp.uvx.json](examples/mcp.uvx.json) — 公开发布后的 Host 配置模板
- [examples/mcp.local.json](examples/mcp.local.json) — 本地已安装时的 Host 配置
- [server.json](server.json) — MCP Registry 元数据（PyPI 上线后用于 `mcp-publisher`）
- [SECURITY.md](SECURITY.md) — 漏洞报告与路径/密钥约定
- [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
- [LICENSE](LICENSE) — MIT

## 已知缺口（beta）

- OCR 依赖本机 Tesseract（不会随 pip 安装语言包）
- 窗口捕获 / Graphics Capture 仅 Windows
- 默认暴露 32 个工具，部分 Host 上下文会偏紧——用 `EAGLEEYE_TOOL_PROFILE=core`
- `save_image` / 回归基线默认只能写到当前工作目录；需要写到别处时设
  `EAGLEEYE_ALLOW_UNRESTRICTED_PATHS=1`
- PyPI 尚未上线；GitHub 已公开，可用 `uvx --from git+https://github.com/baimaomaomao556/eagleeye-mcp`
- FastMCP 启动时可能出现上游 `IncompleteFieldDefinitionWarning`（`lifespan` 前向引用），不影响 stdio

## 环境依赖

- Python ≥ 3.10（开发环境 3.13）
- Tesseract OCR（`conda create -n tess -c conda-forge tesseract`，自带 chi_sim/eng 语言包，
  代码自动探测路径与 TESSDATA_PREFIX）。仅用 `load_image` + 像素工具时可不装。
- 视觉模型：**任意 OpenAI Chat Completions 兼容端点**（OpenAI / MIMO / vLLM / 本地网关）。
  未配置时 `analyze_image` 等返回 `MISSING_CONFIG`，截图与测量工具仍可用。
- Windows：`pywin32` 与 `windows-capture` 由 pip 按平台自动安装；其它系统会跳过。