Vision Primitives MCP

August 5, 2026 · View on GitHub

让纯文本模型（DeepSeek / Codex / 任意 MCP 客户端）通过 30 个 MCP 工具获得完整视觉能力：描述 → 定位（坐标）→ OCR → 标注 → 裁切/放大 → 异常扫描 → UI 结构化 → 多轮推理 → 电脑操控。视觉后端可切换（MiMo V2.5 云端 / LM Studio 本地 Qwen2.5-VL 等），单文件 Python，核心仅依赖 Pillow。

项目定位：通用视觉推理桥接层——文本模型 + 任意 VLM 的通用视觉工作流，本地隐私 + 单文件轻量。高泛化优先：核心能力（定位/切块/放大/读取）全部是纯 VLM + PIL，专用检测器（YOLO/CRAFT）只是可插拔加速器，有则加速、无则照跑。不与 UI-TARS / CogAgent 等端到端 GUI 模型竞争（它们有专门训练）；核心差异化是无 grounding 模型的兜底定位与任何模型可用的多轮视觉推理。

纯文本模型（推理与决策）
    │  MCP 协议（stdio, JSON-RPC 2.0）
    ▼
vision_primitives_mcp.py（单文件，30 工具，186 项测试）
    │  OpenAI 兼容 API
    ▼
MiMo V2.5（云端）/ Qwen2.5-VL-7B（本地 LM Studio）/ 任意视觉 VLM

实测基准（2026-08-02，程序化 ground truth）

测试图（900×600，元素位置为已知真值）：红圆中心 (150,140)、绿三角中心 (740,417)：

测试基准图

定位对比（三模型 × 多模式）

定位实测对比

Qwen2.5-VL 对比

定位矩阵（同一基准图，像素级验证）：

模型	locate 红圆	locate 绿三角	som 红圆	som 绿三角	单次调用	ui_parse	ui_refine
MiMo V2.5（云端）	10-64px（波动）	79-97px（波动）	33-82px（波动）	13-123px（波动）	15-25s	21.5s	—
MiMo + som-cv（兜底管线）	0px	4px	—	—	10-12s	—	—
Qwen3-VL-8B（本地）	90px	164px	77px	123px	10-30s	29.4s	>357s
GLM-4v-flash（智谱云）	89px	84px	191px	145px	1.5-3.3s	—	—
Qwen2.5-VL-7B（本地）	28px	27px	15px	123px	1.3-1.7s	12.4s	12.6s

能力矩阵（describe / OCR / 兜底定位 / 文本锚定 / 多轮推理）：

模型	describe	OCR（prompt 修复后）	som-cv（颜色目标）	ui_locate 文本锚定	scratch 论文推理
MiMo V2.5（云端）	4.7s ✓	8.9s，4/4 块	0px（3.2s）	8.6s ✓	45.7s 3轮（漏答图趋势）
Qwen2.5-VL-7B（本地）	1.1s ✓	3.5-4.6s，4/4 块	0px	12.8s ✓	9.6s 1轮全对
GLM-4v-flash（智谱云）	1.5s ✓	2.0s，3/4 块（max_tokens≤1024 限制）	53px（格子选偏）	—	—
Qwen3-VL-8B（本地）	~10s	23s，4/4 块	0px	—	—

消融：定位误差根因是"分辨率稀释"——输入 0.5x→208px / 2x→70px / 目标单独裁切→0-3px。整图定位差不是模型能力问题，是每个对象分到的视觉 token 太少；"粗定位 → 裁切 → 精定位"的管线是正解（som_locate 递归、final="cv"、text_zoom 网格均基于此）。

ZeroBench 评测（视觉推理基准，持续追踪）

ZeroBench（"Impossible" 基准，发布时 SOTA 0%）评测工作流见 benchmarks/zerobench/。基线（MiMo V2.5 直答 + pass@5 采样，2026-08-02）：

数据集	题数	命中	numeric 命中率
主问题	100（numeric 84）	2	2.4%（超发布时 SOTA 0%）
子问题集	334（numeric 257）	183	71.2%

结论：主问题考多步组合视觉推理（模型能力瓶颈）；子问题集是工具链主场——拆解后的单步问题 MiMo 直答 + 采样达 71%，验证"难题拆解 + 采样"是弱模型打硬基准的可行路径。每次模型/工具升级在此基线上重跑对比。

工具一览（30 个）

分类	工具	作用
基础视觉	`describe_image` / `analyze_image`	描述 / 结构化分析（含坐标原语）
定位	`locate_object`	坐标输出定位，`refine` 两阶段精修
	`som_locate`	SoM 编号网格递归定位（`final`: box/number/cv 三模式）
	`cursor_locate`	移动光标 + 视觉反馈循环定位（GUI-Cursor 范式，建议云端强模型）
	`cv_locate`	CV 兜底：颜色分割/模板匹配，像素级（numpy 加速 285x）
文本	`ocr_image`	逐文本块 OCR，带 bbox
	`text_detect`	CRAFT 文本区域检测（本地 onnx，可选加速器）
	`text_zoom`	程序化切块放大读取（高泛化默认路径）：网格逐块放大 VLM 精读
UI 结构化	`ui_parse` / `ui_locate` / `ui_refine`	YOLO 检测 + 文本锚定 + VLM 语义编辑检测框
图像处理	`annotate_image` / `crop_image` / `zoom_region`	标注 / 裁切 / 放大
高级推理	`scratch_think`	视觉草稿纸：跨轮层栈 + 自适应裁切放大（图文论文理解）
	`compare_images` / `compare_infer` / `reason_graph` / `annotate_infer`	多图对比 / 联合推理 / 图形推理协议 / 虚拟标注
扫描	`scan_anomalies`	自动异常扫描：切块候选 → 高清逐点验证（PCB 实战）
电脑控制	`screen_capture` / `screen_info` / `screen_click` / `screen_move` / `screen_drag` / `screen_scroll` / `screen_type` / `screen_key`	截屏 + 鼠标键盘（Windows-only，安全开关默认关）
诊断	`vision_health`	后端配置与连通性

配套脚本 paper_reader.py：arXiv/URL/PDF/图片 → 多屏截图 → 分屏 scratch_think → 结构化摘要。

核心方法论

对抗分辨率稀释：一切定位精度的基础。som_locate 编号递归（模型只选格子）、final="cv"（VLM 收敛 + CV 像素级）、text_zoom 网格切块（插图小字）——三个工具共享"局部放大"原理，只是块的产生方式不同（模型决策 / 检测器 / 网格）
文本锚定：UI 操作指令几乎总带文字——OCR 定位文字 → 控件框。比让模型猜坐标可靠一个量级
检测器可插拔：YOLO（icon_detect）/ CRAFT（text）都是"有则加速、无则照跑"——高泛化路径（纯 VLM）始终可用
视觉草稿纸（scratch_think）：无 grounding 模型缺"视觉工作记忆"——层栈把中间状态渲染回图，模型每轮可见可编辑；坐标链保证裁切放大后一切可映射回原图
几何判定程序化：重叠合并、坐标换算、收敛检测这类确定性问题交给代码，VLM 只做语义判断（实测 VLM 合并会把相邻独立元素误并）

快速上手

# ~/.codex/config.toml
[mcp_servers.vision-primitives]
command = "python"
args = ['/path/to/vision-primitives-mcp/vision_primitives_mcp.py']
startup_timeout_sec = 60

[mcp_servers.vision-primitives.env]
VISION_API_BASE = "https://api.xiaomimimo.com/v1"      # 或本地 http://127.0.0.1:1234/v1
VISION_API_KEY = "你的MiMo密钥"                          # 本地 LM Studio 用任意占位
VISION_MODEL = "mimo-v2.5"                              # 或 qwen/qwen2.5-vl-7b
VISION_OUTPUT_DIR = '/path/to/vision-primitives-mcp/generated'

模型选型：定位/审查/多轮推理首选 Qwen2.5-VL-7B（grounding 专才 + 非思考型，1.3-1.7s/次）；MiMo 通用但定位波动大，需 VISION_SAMPLES=3；Qwen3-VL-8B 仅描述/OCR 场景考虑；GLM-4v-flash（智谱）速度优秀（1.5-3.3s）适合 describe/OCR/粗定位，定位精度弱（84-191px），且 max_tokens 上限 1024（需 VISION_MAX_TOKENS=1024）

可选增强（全部"有则加速、无则照跑"）：

增强	放置	收益
numpy	`pip install numpy`	模板匹配 285x 加速
YOLO UI 检测	`models/icon_detect.pt`（下载，39.7MB）	ui_parse 像素级 UI 元素检测
CRAFT 文本检测	`models/craft_text.onnx`（下载，79MB）	text_detect/text_zoom 检测框加速
playwright	`pip install playwright`	paper_reader 截图

已知边界（诚实声明）

整图定位受分辨率稀释（20-164px），用 som 递归 / final="cv" / text_zoom 对抗
极小小字（<10px）：text_zoom 网格放大可读（实测 False Stop/Class Settings），但个别字符仍可能误读——模型识别极限
cursor_locate 本地模型不可用（483/100px），仅云端强模型；ui_refine VLM 审查建议云端（本地 8B 数分钟）
OCR 对 prompt 长度敏感（已修复，保持简短指令）；表格数据首选 DOM 提取，视觉 OCR 兜底（90-120s）
平台：屏幕控制 8 工具 Windows-only；安全：URL 图片有 SSRF 防护（私网拦截）与解压炸弹限制（URL 源 50MP）
延迟：MiMo 15-25s/次、本地 Qwen2.5-VL 1.3-1.7s/次、多轮推理按轮倍增

版本历史（精简）

v1.14.1（2026-08-02）：ZeroBench 评测工作流（benchmarks/zerobench）：主问题 2.4% / 子问题 71.2% numeric 基线，断点续跑 + 自动判分
v1.14（2026-08-02）：text_detect（CRAFT 可选）+ text_zoom（程序化切块，高泛化默认路径，实测读出 <10px 图内标注）；30 工具 / 186 测试
v1.13（2026-08-02）：scratch_think 视觉草稿纸（层栈 + 自适应 zoom + 坐标链）；paper_reader.py 论文阅读工作流；OCR prompt 修复（召回 1→4 块）；extract_json 截断容错
v1.12（2026-08-02）：ui_refine 检测框语义编辑（VLM 删除误检/标注 + 程序化几何合并）
v1.11（2026-08-02）：ui_parse / ui_locate（UI 结构化 + 文本锚定）+ YOLO 可选检测 + SSRF/解压炸弹防护 + numpy 模板匹配
v1.10（2026-08-02）：som_locate（SoM 编号递归，final=box/number/cv）+ cursor_locate + cv_locate
v1.9（2026-08-02）：Computer Use（8 个屏幕控制工具，安全开关）
v1.7-1.8：refine 两阶段精修（70→20px）、reason_graph、annotate_infer、坐标格式实验（像素最稳）
v1.1-1.6：scan_anomalies（PCB 实战）、compare_images、中文 OCR 修复
v1.9.1 / v1.13.3 修复记录：MCP 响应帧 jsonrpc/id（严格客户端兼容）、长 JSON 截断容错

测试与安全

python test\run_tests.py   # 186 项 mock 测试，不依赖真实 key
python test\e2e_mimo.py    # 真实端到端（需要 VISION_API_KEY）

输入图片只读，上传仅发往配置的后端；out_path 强制限定输出目录
URL 图片：SSRF 防护（私网/链路本地/元数据拦截，回环放行）+ 解压后 50MP 限制
API key 仅存本地配置；屏幕控制类工具默认拒绝（VISION_ALLOW_SCREEN_CONTROL=1 启用）

仓库：github.com/zouyuanqing/vision-primitives-mcp