Luma Vision MCP

为纯文本大模型（DeepSeek 等）补齐视觉理解能力的 MCP Server

基于 luma-mcp (v1.7.0) 迭代增强

---

致谢与来源

本项目基于 JochenYang/luma-mcp 的 v1.7.0 版本进行二次开发和迭代增强，保留了原项目的核心图片预处理能力（压缩、自适应裁剪、SSRF 防护、LRU 缓存等），并在此基础上新增了三大核心特性。

衷心感谢原作者 @JochenYang 的开源贡献。 原项目 luma-mcp 是一个非常优秀的视觉理解 MCP Server，本项目在其基础上进行了以下增强：

与原项目的关系

维度	原项目 luma-mcp v1.7.0	本项目 luma-vision-mcp v2.0
Provider 模式	单 Provider，主挂了报错	多 Provider Fallback 链（sequential/race）
视觉描述策略	固定 Prompt	Focus Hint 上下文感知（10 维度匹配）
工具数量	1 个（image_understand）	3 个（+ image_ocr + image_compare）
图片预处理	✅ 保留	✅ 完整保留（压缩/裁剪/SSRF/缓存）
HTTP/Docker	✅ 保留	规划中（后续版本）
配置方式	纯环境变量	环境变量（兼容）+ Fallback 链扩展

---

核心特性

1. 多 Provider Fallback 链

不再依赖单一视觉模型。配置主备 Provider 链，主 Provider 失败自动切换备用：

主：智谱 GLM-4.6V（免费）→ 备1：硅基 DeepSeek-OCR → 备2：阿里 Qwen-VL

两种降级策略：

• sequential（默认）：按优先级依次尝试，失败换下一个
• race：同时向多个 Provider 发请求，谁快用谁

2. Focus Hint 上下文感知

不再泛泛地"描述这张图"。系统自动分析用户 prompt，提取关注维度，让视觉模型只描述当前需要的细节：

用户："这个按钮什么颜色？"
  → Focus Hint = "Focus on color: exact names, hex values, contrast..."
  → 视觉模型只描述颜色，省 token、更精准

支持 10 个维度自动匹配：颜色、文字、布局、结构、错误、样式、位置、图标、数据、对比。

3. 三个专用工具

工具	用途	亮点
image_understand	通用图片理解	Focus Hint + task_type 自动路由
image_ocr	专用 OCR 文字提取	语言提示 + 格式输出 + 单图高保真
image_compare	图片对比	结构化差异报告（类型/严重级别）

---

快速开始

第一步：获取免费 API Key

推荐 智谱 AI（永久免费视觉模型）：

1. 访问 bigmodel.cn 注册账号
2. 进入控制台 → API Keys → 创建新 Key
3. 复制你的 API Key

第二步：安装

git clone https://github.com/你的用户名/luma-vision-mcp.git
cd luma-vision-mcp
npm install
npm run build

第三步：配置 MCP 客户端

Claude Desktop

编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "luma-vision": {
      "command": "node",
      "args": ["/absolute/path/to/luma-vision-mcp/dist/index.js"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "你的智谱APIKey"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "luma-vision": {
      "command": "node",
      "args": ["/absolute/path/to/luma-vision-mcp/dist/index.js"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "你的智谱APIKey"
      }
    }
  }
}

Claude Code（命令行快捷添加）

claude mcp add -s user luma-vision \
  --env MODEL_PROVIDER=zhipu \
  --env ZHIPU_API_KEY=你的智谱APIKey \
  -- node /absolute/path/to/luma-vision-mcp/dist/index.js

VS Code / Trae / 其他 MCP 客户端

同样格式，将 command 和 args 和 env 填入对应 MCP 配置位置即可。

第四步：验证

重启 MCP 客户端，在对话中上传一张图片或提供图片路径，然后提问：

请帮我看一下这个截图的内容 /Users/demo/screenshot.png

模型会自动调用 image_understand 工具完成视觉理解。

---

完整配置教程

单 Provider（最简配置）

只需 2 个环境变量：

MODEL_PROVIDER=zhipu
ZHIPU_API_KEY=你的Key

多 Provider Fallback（推荐配置）

{
  "mcpServers": {
    "luma-vision": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "MODEL_PROVIDER": "zhipu",
        "ZHIPU_API_KEY": "智谱Key",

        "FALLBACK_CHAIN": "siliconflow,qwen",
        "FALLBACK_STRATEGY": "sequential",

        "SILICONFLOW_API_KEY": "硅基流动Key",
        "DASHSCOPE_API_KEY": "阿里云Key"
      }
    }
  }
}

效果：智谱 → 硅基 → 阿里，依次降级，任一成功即返回。

竞速模式（多免费通道同时请求）

MODEL_PROVIDER=zhipu
ZHIPU_API_KEY=智谱Key
FALLBACK_CHAIN=siliconflow
FALLBACK_STRATEGY=race
SILICONFLOW_API_KEY=硅基Key

效果：智谱和硅基同时发起请求，谁先返回用谁的结果——更快更可靠。

全部环境变量

变量	默认值	说明
MODEL_PROVIDER	zhipu	主 Provider
FALLBACK_CHAIN	(空)	备用 Provider 链，逗号分隔
FALLBACK_STRATEGY	sequential	sequential 或 race
FOCUS_HINT	true	Focus Hint 上下文感知开关
MULTI_CROP	true	大图自动裁剪
MULTI_CROP_MAX_TILES	5	最大裁剪数
ENABLE_THINKING	true	视觉模型深度思考
MAX_TOKENS	8192	最大输出 token
TEMPERATURE	0.7	温度
TOP_P	0.95	Top-P
INCLUDE_META	false	结果末尾附加调用元信息
LUMA_DEBUG	(空)	设为 1 开启调试日志

支持的 Provider

Provider	默认模型	环境变量	免费情况
zhipu (智谱)	glm-4.6v	ZHIPU_API_KEY	永久免费
siliconflow	DeepSeek-OCR	SILICONFLOW_API_KEY	有免费额度
qwen (阿里)	qwen3-vl-flash	DASHSCOPE_API_KEY	新用户免费
volcengine	doubao-seed	VOLCENGINE_API_KEY	有限免费
hunyuan (腾讯)	hunyuan-t1-vision	HUNYUAN_API_KEY	有限免费
custom	用户自定义	CUSTOM_* 系列	取决于端点

使用自定义 Provider

MODEL_PROVIDER=custom
CUSTOM_API_KEY=sk-your-key
CUSTOM_BASE_URL=https://your-endpoint.com/v1
CUSTOM_MODEL_NAME=your-model-name

---

使用方式

工具 1: image_understand（通用图片理解）

用户："看一下这个界面截图的布局"
模型 → 调用 image_understand(image_source="截图路径", prompt="看一下这个界面截图的布局")
     → Focus Hint 匹配到 "layout" 维度
     → 视觉模型聚焦描述布局信息
     → 返回结构化的界面分析

可选 task_type：

• auto（默认）：自动推断
• general：通用分析
• ocr：文字提取
• ui：界面结构
• debug：报错诊断
• describe：简短描述

工具 2: image_ocr（专用 OCR）

用户："提取这张图片里的所有文字"
模型 → 调用 image_ocr(image_source="文档路径", language_hint="zh", output_format="markdown")
     → 单图高保真模式（不裁剪）
     → 返回格式化的文字内容

工具 3: image_compare（图片对比）

用户："对比设计稿和实现，找出差异"
模型 → 调用 image_compare(image_source_a="设计稿", image_source_b="实现截图")
     → 两张图同时传入视觉模型
     → 返回差异表格（类型/严重级别/描述）

---

与 PDF 文档解析的配合

本项目的 OCR 工具专注于图片中的文字。如果是 PDF 文档解析，建议配合本地 MinerU skill 使用：

• 图片截图 / 代码截图 / 表单照片 → 使用 image_ocr
• PDF 文档 / 扫描书籍 / 论文 → 使用 MinerU skill

两者互为补充，覆盖全部文档处理场景。

---

技术架构

用户上传图片
  ↓
image_understand / image_ocr / image_compare
  ↓
Focus Hint 引擎（10维度上下文感知匹配）
  ↓
图片预处理（验证 → 压缩 → 自适应裁剪 → LRU缓存）
  ↓
Fallback Manager
  ├─ Primary:  智谱 GLM-4.6V（免费）
  ├─ Fallback: 硅基 DeepSeek-OCR
  └─ Fallback: 阿里 Qwen-VL
  ↓
视觉模型返回文字描述 → 纯文本模型获得"视觉"

安全特性

• SSRF 防护：DNS 解析 + 私有 IP 检测 + 禁止重定向
• 路径遍历防护：symlink 解析 + 白名单目录
• 像素限制：最大 1600 万像素，防止 OOM
• 错误脱敏：Bearer token / API Key 自动遮蔽

---

开发

# 安装依赖
npm install

# 编译
npm run build

# 类型检查
npm run typecheck

# 开发模式（监听变更）
npm run dev

项目结构

src/
├── config.ts               # 多 Provider 配置 + Fallback 链解析
├── constants.ts             # 提示词常量（含 OCR/对比专用 Prompt）
├── focus-hint.ts            # Focus Hint 引擎（10 维度匹配）
├── image-processor.ts       # 图片预处理（压缩/裁剪/SSRF/缓存）
├── index.ts                 # 主入口（3 个 MCP 工具注册）
├── task-types.ts            # 任务类型路由
├── vision-client.ts         # 客户端接口定义
├── providers/
│   ├── fallback-manager.ts  # Fallback 降级管理器
│   ├── openai-compatible.ts # OpenAI 兼容客户端基类
│   └── index.ts             # Provider 工厂
└── utils/
    ├── helpers.ts           # 重试/响应构建/错误脱敏
    └── logger.ts            # stderr 日志器

---

License

MIT — 见 LICENSE

本项目基于 luma-mcp（MIT License）迭代开发，感谢原作者的贡献。

调研报告

完整的行业调研报告和方案对比见项目根目录的调研文档，涵盖了 20+ 个同类开源项目的详细分析。