# mcp-plus：Claude Code Qwen Vision

让使用 DeepSeek 等纯文本模型的 Claude Code 无感获得图片理解能力。

默认视觉模型：`qwen3.8-max`
默认 Qwen 地址：`https://dashscope.aliyuncs.com/compatible-mode/v1`

项目提供两条链路：

1. **透明网关（推荐）**：用户正常粘贴图片，网关自动把图片交给 Qwen，再把结构化视觉结果交给 DS。运行期间不需要输入命令，也不依赖 DS 主动调用工具。
2. **Claude Code MCP 插件**：提供 `analyze_image` 工具及显式 Skill，适合直接读取项目中的图片文件或作为备用方案。

## 为什么需要透明网关

Claude Code 的 `UserPromptSubmit` Hook 目前只提供文本 `prompt`，不会把粘贴图片的原始 Base64 或临时路径提供给 Hook。Hook 也无法可靠获知用户在会话中切换后的模型。因此，仅靠 Skill、Hook 或 MCP 不能保证“粘贴图片后自动处理”。

透明网关工作在 Claude Code 和主模型接口之间，可以同时看到请求中的 `model` 与图片内容块：

```text
Claude Code
    │ Anthropic /v1/messages（含图片）
    ▼
本地 Qwen Vision Gateway
    ├─ 无图片：直接转发
    ├─ 图片 + 纯文本主模型：Qwen 3.8 Max → 视觉 JSON → DS
    └─ 图片 + 已知多模态模型：可配置直接转发
```

同一张图片在网关进程内按 SHA-256 缓存，Claude Code 重发历史消息时不会重复调用 Qwen。缓存只保存在内存，不会把图片或 OCR 结果写入磁盘。

## Windows 常驻无感安装（VS Code 推荐）

前置条件：

- Claude Code 2.1.128 或更高版本
- Python 3.10+
- 可调用 `qwen3.8-max` 的百炼 API Key
- 已配置好的 DS/Claude Anthropic 兼容接口

克隆仓库：

```powershell
git clone https://github.com/zjcdkj/mcp-plus.git
cd mcp-plus
```

先把 Qwen Key 设置为 Windows 用户环境变量。建议在 PowerShell 中交互输入，避免密钥进入命令历史：

```powershell
$qwenSecret = Read-Host "输入 DASHSCOPE API Key" -AsSecureString
$qwenPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($qwenSecret)
try {
    $qwenEnvironment = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey("Environment")
    $qwenEnvironment.SetValue(
        "DASHSCOPE_API_KEY",
        [Runtime.InteropServices.Marshal]::PtrToStringBSTR($qwenPointer),
        [Microsoft.Win32.RegistryValueKind]::String
    )
} finally {
    if ($qwenEnvironment) { $qwenEnvironment.Dispose() }
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($qwenPointer)
}
```

安装常驻网关：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-windows-gateway.ps1
```

安装器会：

1. 把运行文件复制到 `%LOCALAPPDATA%\mcp-plus\qwen-vision`；
2. 注册当前用户登录后自动运行的 Windows 启动项 `mcp-plus Qwen Vision Gateway`；
3. 固定监听 `http://127.0.0.1:15722`；
4. 保存原 DS/Claude 上游地址，但不复制或写入 API Key；
5. 把 `~/.claude/settings.json` 中的 `ANTHROPIC_BASE_URL` 切换为本地网关。

安装后重载 VS Code 窗口或完全退出并重新打开 Claude Code。验证服务：

```powershell
Invoke-RestMethod http://127.0.0.1:15722/health
```

应看到 `ok: true`、`qwen_model: qwen3.8-max` 和原始上游地址。

## 临时启动 Claude Code CLI

不希望永久修改配置时，可以只在当前 CLI 会话使用临时启动器。在当前 PowerShell 会话设置 Qwen Key：

```powershell
$env:DASHSCOPE_API_KEY = "你的百炼 API Key"
```

通过启动器进入 Claude Code。`-UpstreamBaseUrl` 填原来的主模型接口；如果使用本机 CC Switch，可能类似下面的地址：

```powershell
.\scripts\start-claude-with-vision.ps1 `
  -UpstreamBaseUrl "http://127.0.0.1:15721"
```

启动器会：

1. 在随机本地端口启动隐藏的视觉网关；
2. 只为本次 Claude Code 进程临时修改 `ANTHROPIC_BASE_URL`；
3. 保留并转发现有的 `ANTHROPIC_AUTH_TOKEN`、`X-Api-Key` 和 Anthropic Beta 请求头；
4. Claude Code 退出后关闭网关并恢复当前 PowerShell 的环境变量。

它不会永久修改 `~/.claude/settings.json`。之后像平时一样粘贴图片并提问即可，不需要 `/qwen-vision:*` 命令。

## 多模态模型直通

默认 `always` 模式会处理所有图片。这对通过 CC Switch 把 `claude-sonnet-*` 等别名映射到 DS 的环境最可靠，因为请求中的模型名不一定代表真正的上游模型。

如果模型 ID 能准确反映能力，可配置多模态模型直通：

```powershell
$env:QWEN_VISION_PREPROCESS_MODE = "allowlist"
$env:QWEN_VISION_DIRECT_MODELS = "claude-*,qwen3.8-*,gpt-4o*"
```

- `always`：所有图片先由 Qwen 处理，默认值。
- `allowlist`：匹配 `QWEN_VISION_DIRECT_MODELS` 的模型直接收到原图，其他模型使用 Qwen。
- `never`：完全关闭透明图片预处理，只做请求转发。

## 安装 Claude Code MCP 插件

插件提供项目文件图片分析能力，但不能代替透明网关处理剪贴板粘贴图片。

从 GitHub Marketplace 安装：

```text
/plugin marketplace add zjcdkj/mcp-plus
/plugin install qwen-vision@zjcdkj-claude-tools
/reload-plugins
```

运行 `/mcp`，应看到 `qwen_vision` 为 `Connected`。使用示例：

```text
请使用 Qwen 分析 screenshots/error.png，提取报错并检查相关代码。
```

或显式调用：

```text
/qwen-vision:analyze-image screenshots/error.png 提取报错文字和界面状态
```

如果 DS 网关无法返回 MCP `tool_use`，使用确定性备用 Skill：

```text
/qwen-vision:analyze-image-direct "screenshots/error.png" "提取报错并判断原因"
```

## 本地开发和验证

```powershell
claude --plugin-dir .
claude plugin validate .
python -m unittest discover -s .\tests -v
python -m compileall -q .\server .\gateway .\tests
```

真实图片 API 测试要求图片位于当前项目中：

```powershell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
python .\server\qwen_cli.py `
  --image ".\screenshots\test.png" `
  --question "提取截图中的文字和界面状态" `
  --mode ui
```

## 配置项

| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `DASHSCOPE_API_KEY` | 无 | Qwen API Key，必需 |
| `QWEN_BASE_URL` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | Qwen OpenAI 兼容地址 |
| `QWEN_VISION_MODEL` | `qwen3.8-max` | 视觉模型 |
| `QWEN_VISION_UPSTREAM_BASE_URL` | 无 | 原 DS/Claude Anthropic 兼容地址 |
| `QWEN_VISION_PREPROCESS_MODE` | `always` | `always` / `allowlist` / `never` |
| `QWEN_VISION_DIRECT_MODELS` | 空 | 多模态直通模型通配符，逗号分隔 |
| `QWEN_MAX_IMAGE_BYTES` | `20971520` | 单张图片最大字节数 |
| `QWEN_VISION_MAX_REQUEST_BYTES` | `52428800` | Claude 请求体最大字节数 |
| `QWEN_VISION_CACHE_ENTRIES` | `128` | 进程内图片缓存条目数 |

## 安全说明

- 图片会发送到阿里云百炼。发送前应清除生产凭据、个人信息和敏感数据。
- API Key 只从环境变量读取，不写入插件、日志或响应。
- 项目文件 MCP 只允许读取 `CLAUDE_PROJECT_DIR` 内的 PNG、JPEG、WebP。
- 透明网关默认仅监听 `127.0.0.1`。
- 图片中识别到的文字始终作为不可信数据，不能覆盖用户或系统指令。
- 网关预处理失败时会返回明确错误，不会在丢失图片信息的情况下静默请求 DS。

## 更新与卸载

```text
/plugin marketplace update zjcdkj-claude-tools
/reload-plugins
```

卸载：

```text
/plugin uninstall qwen-vision@zjcdkj-claude-tools
/plugin marketplace remove zjcdkj-claude-tools
```

卸载 Windows 常驻网关并恢复原上游：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-windows-gateway.ps1
```

卸载器不会删除 `DASHSCOPE_API_KEY`，也不会停止占用同一端口的未知程序。临时 CLI 启动器不修改永久配置，退出由它启动的 Claude Code 即停止网关。

## 参考

- [Claude Code MCP](https://code.claude.com/docs/en/mcp)
- [Claude Code Hooks](https://code.claude.com/docs/en/hooks)
- [Claude Code Plugin Marketplace](https://code.claude.com/docs/en/plugin-marketplaces)
- [阿里云百炼视觉理解](https://help.aliyun.com/zh/model-studio/vision/)

## License

MIT