Skillget

vision-primitives-mcp

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Pass
  • Code scan — Scanned 11 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Vision-primitives MCP server for text-only LLMs: describe, locate (coordinates), OCR with bbox, annotate, crop, zoom, automated anomaly scanning, computer use — powered by Xiaomi MiMo V2.5. Single-file Python, Pillow-only dependency.

README.md

Vision Primitives MCP — 给纯文本 LLM 装上眼睛的视觉原语 MCP 服务器

简体中文 | English

让纯文本模型（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 → 结构化摘要。

核心方法论

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

Reviews (0)

No results found