# Luma Vision MCP

> 为纯文本大模型（DeepSeek 等）补齐视觉理解能力的 MCP Server
>
> 基于 [luma-mcp](https://github.com/JochenYang/luma-mcp) (v1.7.0) 迭代增强

---

## 致谢与来源

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

**衷心感谢原作者 [@JochenYang](https://github.com/JochenYang) 的开源贡献。** 原项目 [luma-mcp](https://github.com/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](https://bigmodel.cn/) 注册账号
2. 进入控制台 → API Keys → 创建新 Key
3. 复制你的 API Key

### 第二步：安装

```bash
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`）：

```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`：

```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（命令行快捷添加）

```bash
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 个环境变量：

```env
MODEL_PROVIDER=zhipu
ZHIPU_API_KEY=你的Key
```

### 多 Provider Fallback（推荐配置）

```json
{
  "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"
      }
    }
  }
}
```

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

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

```env
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

```env
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 自动遮蔽

---

## 开发

```bash
# 安装依赖
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](LICENSE)

本项目基于 [luma-mcp](https://github.com/JochenYang/luma-mcp)（MIT License）迭代开发，感谢原作者的贡献。

## 调研报告

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