内容
# qwen-vision-mcp
让任何**文本模型**（Claude、GLM、GPT、Gemini...）通过 MCP 按需"看图"。后端走阿里云 DashScope 的 qwen 视觉模型，通过 Anthropic 兼容接口调用。
## 为什么需要这个
文本模型（GLM-4、Claude Haiku、GPT-4o-mini 等便宜/快的模型）不会直接看图。但很多任务（截图报错、UI 调试、图表分析、文档 OCR）需要视觉理解。
`qwen-vision-mcp` 把 qwen 视觉模型包装成一个 MCP 工具 `look(image, question)`，让任何 MCP 兼容的 Agent 按需调用——只在需要时才"看一眼"，主对话仍由你便宜的文本模型驱动。
## 特色
- **🧠 有状态多轮持久**：同一会话内 qwen 会记得之前所有图片和问答，支持"再看一眼刚才那张图"。
- **🚆 自动 trim 防超限**：单次请求体超过 DashScope 6MB 上限时，自动把较早的 image block 替换成文字指针（保留文字 question + assistant 回复），长程多图对话不崩。
- **🔌 按进程隔离**：每个客户端会话独立一个 MCP server 进程，messages 不串台。
- **📦 极简依赖**：只依赖 `@modelcontextprotocol/sdk`，Bun 直接跑 .ts，无编译步骤。
- **🔁 失败干净回滚**：网络异常 / HTTP 错误时自动 pop 掉刚 push 的 user message，历史不污染。
## 工作原理
```
文本模型 (GLM/Claude/GPT) ──MCP stdio──▶ qwen-vision-mcp server
│
▼
DashScope qwen 视觉模型
(Anthropic 兼容接口)
```
主模型决定"什么时候需要看图、问什么"，qwen 只负责"看一眼并回答具体问题"。模型行为由工具 `description` 引导（要拆解、要聚焦、要多轮追问）。
## 安装
需要 [Bun](https://bun.sh/) 运行时 + DashScope API Key（[阿里云百炼控制台](https://bailian.console.aliyun.com/) 获取）。
```bash
git clone <your-fork-url> qwen-vision-mcp
cd qwen-vision-mcp
bun install # 装 @modelcontextprotocol/sdk
cp .env.example .env # 填入 QWEN_API_KEY
```
`.env` 内容：
```env
QWEN_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic/v1
QWEN_API_KEY=sk-你的-key
QWEN_MODEL=qwen3.7-plus
QWEN_MAX_TOKENS=1024
QWEN_MAX_REQUEST_BYTES=5000000
```
## 接入 MCP 客户端
### Claude Code
在 `~/.claude.json`（或项目级 `.mcp.json`）的 `mcpServers` 里加：
```json
{
"mcpServers": {
"qwen-vision": {
"command": "bun",
"args": ["run", "/absolute/path/to/qwen-vision-mcp/index.ts"],
"env": { "QWEN_API_KEY": "sk-..." }
}
}
}
```
### Cursor / Continue / 其它 MCP 客户端
任何支持 stdio MCP server 的客户端都能接入，配置格式大同小异——指定 `bun` 为 command，`run /path/to/index.ts` 为 args，把 `QWEN_API_KEY` 放到 env 里。
### Proma
在 Proma 工作区的 `mcp.json` 里加：
```json
"qwen-vision": {
"type": "stdio",
"command": "bun",
"args": ["run", "/absolute/path/to/qwen-vision-mcp/index.ts"],
"env": { "QWEN_API_KEY": "sk-...", "QWEN_MODEL": "qwen3.7-plus" },
"enabled": true
}
```
## 暴露的工具
### `look(image, question)` — 有状态
让 qwen 看一张图片回答你提出的具体问题。
- **image**: 本地绝对路径 / http(s) URL / `data:image;base64,...`
- **question**: 针对该图片的具体、聚焦的问题
**重要**：这个工具是**有状态的**。同一会话内 qwen 会记得前面所有图片和问答。
- 同一张图追问细节 → 直接连续调用，qwen 自带上下文
- 切换到**完全无关的新图** → 先调 `reset_vision_session` 清空历史，避免旧图污染
### `reset_vision_session()` — 清空历史
何时调：当前图片讨论完、要切到无关新图时，或想从干净状态重启时。
何时不调：同一张图的多轮追问、相关图片延续讨论时。
## 配置项
| 环境变量 | 默认 | 说明 |
|---|---|---|
| `QWEN_BASE_URL` | `https://dashscope.aliyuncs.com/apps/anthropic/v1` | DashScope Anthropic 兼容入口 |
| `QWEN_API_KEY` | 必填 | DashScope API Key |
| `QWEN_MODEL` | `qwen3.7-plus` | 视觉模型 id（可改 `qwen-vl-max-latest` 等） |
| `QWEN_MAX_TOKENS` | `1024` | 单次回复 token 上限 |
| `QWEN_MAX_REQUEST_BYTES` | `5000000` | 单次请求体字节上限（DashScope 硬上限 6MB） |
| `QWEN_ENABLE_THINKING` | `false` | 推理模型 thinking 开关。默认关（视觉问答 7-10x 提速）；复杂图表分析/推理题场景设 `true` |
## 已知限制
- **进程隔离 ≠ 跨重启持久化**：进程被杀（客户端退出、crash）→ 内存里的 messages 丢失 = 自动 reset。同一会话**活跃期间**的持久化没问题，跨重启做不到。
- **URL 图片需 DashScope 服务端能访问**：内网图床 / 被墙的 URL 会报 `Failed to download multimodal content`，**用本地路径最稳**。
- **历史图片 trim 策略**：超过 `QWEN_MAX_REQUEST_BYTES` 时从最早的 image 开始替换成文字指针，保留最后 1 张图和所有文字。这意味着 qwen 对"很久之前的图"会失去视觉记忆（但仍能从对话历史里"读"自己之前的描述）。
## 故障排查
| 错误 | 原因 | 解决 |
|---|---|---|
| `404` | BASE_URL 错了 | 确认用 `/apps/anthropic/v1` 而不是 `/compatible-mode/v1` |
| `model not found` | QWEN_MODEL id 错了 | 查 [DashScope 文档](https://help.aliyun.com/zh/model-studio/) 确认 id |
| `Failed to download multimodal content` | URL 图片 DashScope 服务端访问不到 | 改用本地路径 |
| `Exceeded limit on max bytes to request body : 6291456` | 请求体超 6MB | 已自动 trim；若仍报错，调小 `QWEN_MAX_REQUEST_BYTES` 或主动调 `reset_vision_session` |
| 响应慢（每次 10s+） | `qwen3.7-plus` 是推理模型，默认每轮生成几百 token thinking | 已默认关 thinking；确认 `QWEN_ENABLE_THINKING=false`（或换非推理模型如 `qwen-vl-max-latest`） |
## 开发与测试
```bash
# 启动 server（stdio 模式，等待客户端连接）
bun run index.ts
# 协议层冒烟测试（发 initialize + tools/list）
( \
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ; \
sleep 2 \
) | bun run index.ts
# 端到端测试（看一张本地图）
( \
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"look","arguments":{"image":"/tmp/test.png","question":"一句话描述这张图"}}}' ; \
sleep 15 \
) | bun run index.ts
```
## License
[MIT](./LICENSE)
