# qwen-vision-mcp

Claude Code 视觉降级识别 —— 通过 MCP 让**纯文本模型**（如 DeepSeek 系列）调用**千问视觉模型**（DashScope 阿里云百炼）识别图片，把返回的文字描述喂回当前模型继续推理。

当你的 Claude Code 使用了一个没有视觉能力的模型（收到图片只能看到 `[Unsupported Image]`），本工具会在模型收到图片时自动降级：调用千问视觉模型识别图片内容，再以文字形式交回模型。

## 功能特性

- **`recognize_image` MCP 工具**：读本地图片 → base64 → 调千问视觉模型 → 返回文字描述
- **配套 Skill**：收到图片但模型看不了时自动触发，引导模型调用工具
- **模型可配置**：默认模型 `qwen3.5-omni-plus-2026-03-15`，可通过环境变量 `QWEN_VISION_DEFAULT_MODEL` 修改，也可在单次调用时传 `model` 参数
- **Windows 环境变量兜底**：进程未继承用户级环境变量时，自动从注册表 `HKCU\Environment` 读取
- **友好错误提示**：无 key / 文件不存在 / 图片过大 / API 调用失败均返回可读中文错误

## 架构

```
模型收到图片但自己无法查看
   │  (Skill: recognize-image 触发)
   ▼
MCP 工具 recognize_image(path, prompt, model)
   │  读图 → base64 → data URI
   ▼
DashScope OpenAI 兼容端点（千问视觉模型 Qwen-VL）
   │  返回文字描述
   ▼
模型把返回文字当作"看"到的内容，继续回答用户
```

## 环境要求

- Python 3.10+
- [Claude Code](https://docs.anthropic.com/claude-code)（或任意支持 MCP 与 Skill 的客户端）
- 阿里云百炼（DashScope）API Key：<https://bailian.console.aliyun.com/>

## 安装

```bash
# 1. 克隆仓库
git clone <你的仓库地址> qwen-vision-mcp
cd qwen-vision-mcp

# 2. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows:
.venv\Scripts\python -m pip install -r requirements.txt
# macOS / Linux:
# .venv/bin/python -m pip install -r requirements.txt

# 3. 设置 API Key（任选其一）
#    方式 A：设置到当前环境
export DASHSCOPE_API_KEY=sk-xxxx
#    方式 B：写入 ~/.claude/settings.json 的 env 段
#    方式 C（Windows）：系统"环境变量"（用户级）

# 4. 注册 MCP server（用户级，所有项目可用）
claude mcp add qwen-vision --scope user -- \
  <venv-python 绝对路径> <仓库绝对路径>/server.py
# 例如 Windows：
# claude mcp add qwen-vision --scope user -- \
#   D:/qwen-vision-mcp/.venv/Scripts/python D:/qwen-vision-mcp/server.py

# 5. 安装配套 Skill（复制到 Claude Code 的 skills 目录）
#    Windows / macOS / Linux: ~/.claude/skills/
cp -r skill/recognize-image ~/.claude/skills/
```

安装完成后**重启 Claude Code**，运行 `claude mcp list` 应能看到 `qwen-vision ✓ Connected`。

## 使用说明

1. 重启 Claude Code 后，直接向模型发送一张图片（粘贴路径、拖拽附件等）。
2. 模型自己无法查看图片时，`recognize-image` Skill 会自动触发，引导模型调用 `recognize_image` 工具。
3. 工具返回的文字描述就是模型"看到"的内容，模型会基于它继续回答你。

也可以直接要求模型手动调用：

```
请用 recognize_image 识别 <图片路径>，我想了解 ...
```

工具参数：

| 参数 | 说明 |
|---|---|
| `path` | 图片绝对路径（png / jpg / jpeg / webp / bmp / gif） |
| `prompt` | 想从图片中了解什么，默认"请详细描述这张图片的内容" |
| `model` | 千问视觉模型名，默认取 `QWEN_VISION_DEFAULT_MODEL`，未设置则用 `qwen3.5-omni-plus-2026-03-15` |

## 配置

| 环境变量 | 必填 | 说明 |
|---|---|---|
| `DASHSCOPE_API_KEY` | 是 | 阿里云百炼 DashScope API Key |
| `QWEN_VISION_DEFAULT_MODEL` | 否 | 默认视觉模型名（如 `qwen-vl-max`），缺省 `qwen3.5-omni-plus-2026-03-15` |

单次调用模型优先顺序：显式 `model` 参数 > `QWEN_VISION_DEFAULT_MODEL` 环境变量 > 内置默认值。

## 卸载

```bash
# 1. 移除 MCP 注册
claude mcp remove qwen-vision

# 2. 删除 Skill
rm -rf ~/.claude/skills/recognize-image

# 3. 删除仓库目录
rm -rf qwen-vision-mcp

# 4. （可选）移除环境变量 DASHSCOPE_API_KEY / QWEN_VISION_DEFAULT_MODEL
```

## 常见问题（FAQ）

### 为什么 requirements.txt 固定 `mcp<2`？

mcp 2.0.0 移除了 `mcp.server.fastmcp.FastMCP`，本工具基于 FastMCP 编写，因此固定到 1.x。

### Windows 下设置了用户环境变量但进程读不到？

本工具会通过注册表 `HKCU\Environment` 兜底读取 `DASHSCOPE_API_KEY` 和 `QWEN_VISION_DEFAULT_MODEL`，即使 Claude Code 进程早于环境变量设置而启动，也能读到。

### 图片大小限制？

单张图片上限 8MB（`server.py` 中 `MAX_BYTES`）。超大图片请先压缩或裁剪。

### 支持视频吗？

暂不支持。后续版本计划 `recognize_video`（ffmpeg 抽帧后逐帧识别）。

## License

[MIT](LICENSE)