baimaomaomao556 / eagleeye-mcp

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
按剧本还原 UI / 长截图 OCR / 描 SVG	vision-tools
截当前桌面、量像素、做视觉回归	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。

快速开始

本地开发（当前推荐）

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。上下文紧张时可设 EAGLEEYE_TOOL_PROFILE=core，只暴露 Phase 1 的 8 个工具；默认 full 为全部 32 个。

uvx / skills

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 = 渲染表面（可后台，不代表屏幕实际显示）

测试与演示

# 单元测试
.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 — 协议规范（坐标溯源/ImageRef/Observation/错误码/三态/捕获语义）
• docs/TOOL_REFERENCE.md — 32 个工具完整参考与工具选择路由
• docs/USAGE.md — 工具使用手册（含示例参数与工作流）
• docs/HOSTS.md — Claude Desktop / Claude Code / Cursor / DSH / uvx 接入
• skill/SKILL.md / skills/eagleeye/SKILL.md — Agent Skills / DSH 薄包装
• examples/mcp.uvx.json — 公开发布后的 Host 配置模板
• examples/mcp.local.json — 本地已安装时的 Host 配置
• server.json — MCP Registry 元数据（PyPI 上线后用于 mcp-publisher）
• SECURITY.md — 漏洞报告与路径/密钥约定
• CHANGELOG.md — 版本变更记录
• 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 按平台自动安装；其它系统会跳过。