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

Related MCP server: hermes-computer-use

平台能力

窗口类工具在非 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

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

Phase 3 · Visual QA（5 个）

组合工具（1 个）

Phase 4 · Visual Inspection Runtime（1 个）

设计约定（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 按平台自动安装；其它系统会跳过。