mcp-plus: Claude Code Qwen Vision

Позволяет Claude Code, использующему текстовые модели, такие как DeepSeek, незаметно получать возможность понимания изображений.

Модель зрения по умолчанию: qwen3.8-max Адрес Qwen по умолчанию: https://dashscope.aliyuncs.com/compatible-mode/v1

Проект предоставляет два пути:

1. Прозрачный шлюз (рекомендуется): пользователь вставляет изображение как обычно, шлюз автоматически отправляет его в Qwen, а затем передает структурированный результат видения в DS. Во время работы не требуется вводить команды и не зависит от активного вызова инструментов DS.

2. Плагин MCP для Claude Code: предоставляет инструмент analyze_image и явные навыки, подходит для прямого чтения файлов изображений в проекте или в качестве резервного варианта.

Зачем нужен прозрачный шлюз

Хук UserPromptSubmit Claude Code в настоящее время предоставляет только текстовый prompt и не передает исходные Base64 или временные пути вставленных изображений в хук. Хук также не может надежно определить модель, выбранную пользователем в сессии. Поэтому только навыки, хуки или MCP не могут гарантировать "автоматическую обработку после вставки изображения".

Прозрачный шлюз работает между Claude Code и интерфейсом основной модели и может одновременно видеть model и блоки содержимого изображений в запросе:

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+

• API-ключ Bailian, вызывающий qwen3.8-max

• Уже настроенный совместимый интерфейс DS/Claude Anthropic

Клонируйте репозиторий:

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

Сначала установите ключ Qwen как переменную окружения пользователя Windows. Рекомендуется вводить интерактивно в 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 -ExecutionPolicy Bypass -File .\scripts\install-windows-gateway.ps1

Установщик:

1. Копирует файлы запуска в %LOCALAPPDATA%\mcp-plus\qwen-vision;

2. Регистрирует элемент автозапуска mcp-plus Qwen Vision Gateway для текущего пользователя при входе в систему;

3. Фиксирует прослушивание на http://127.0.0.1:15722;

4. Сохраняет исходный адрес DS/Claude, но не копирует и не записывает ключ API;

5. Переключает ANTHROPIC_BASE_URL в ~/.claude/settings.json на локальный шлюз.

После установки перезагрузите окно VS Code или полностью выйдите и снова откройте Claude Code. Проверьте службу:

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

Должно быть видно ok: true, qwen_model: qwen3.8-max и исходный адрес вышестоящего сервера.

Временный запуск Claude Code CLI

Если вы не хотите постоянно изменять конфигурацию, вы можете использовать временный запускатор только для текущей сессии CLI. Установите ключ Qwen в текущей сессии PowerShell:

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

Войдите в Claude Code через запускатор. -UpstreamBaseUrl заполните исходным интерфейсом основной модели; если вы используете локальный CC Switch, адрес может быть похож на следующий:

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

Запускатор:

1. Запускает скрытый шлюз видения на случайном локальном порту;

2. Временно изменяет ANTHROPIC_BASE_URL только для текущего процесса Claude Code;

3. Сохраняет и перенаправляет существующие ANTHROPIC_AUTH_TOKEN, X-Api-Key и заголовки Anthropic Beta;

4. После выхода из Claude Code закрывает шлюз и восстанавливает переменные окружения текущего PowerShell.

Он не изменяет ~/.claude/settings.json постоянно. После этого вставляйте изображения и задавайте вопросы как обычно, не требуется команда /qwen-vision:*.

Прямой проход для мультимодальных моделей

Режим always по умолчанию обрабатывает все изображения. Это наиболее надежно для окружений, где через CC Switch псевдонимы, такие как claude-sonnet-*, отображаются на DS, так как имя модели в запросе не обязательно отражает реальную модель вышестоящего сервера.

Если идентификатор модели точно отражает возможности, можно настроить прямой проход для мультимодальных моделей:

$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: полное отключение прозрачной предварительной обработки изображений, только перенаправление запросов.

Установка плагина MCP для Claude Code

Плагин предоставляет возможность анализа изображений в файлах проекта, но не может заменить прозрачный шлюз для обработки вставленных из буфера обмена изображений.

Установка из GitHub Marketplace:

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

Запустите /mcp, должно отобразиться qwen_vision как Connected. Пример использования:

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

Или явный вызов:

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

Если шлюз DS не может вернуть MCP tool_use, используйте детерминированный резервный навык:

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

Локальная разработка и проверка

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

Для тестирования API с реальными изображениями требуется, чтобы изображение находилось в текущем проекте:

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

Параметры конфигурации

Замечания по безопасности

• Изображения отправляются на Alibaba Cloud Bailian. Перед отправкой необходимо удалить производственные учетные данные, личную информацию и конфиденциальные данные.

• Ключ API считывается только из переменных окружения, не записывается в плагины, журналы или ответы.

• MCP для файлов проекта разрешает чтение только PNG, JPEG, WebP из CLAUDE_PROJECT_DIR.

• Прозрачный шлюз по умолчанию прослушивает только 127.0.0.1.

• Текст, распознанный на изображениях, всегда считается ненадежными данными и не может переопределять инструкции пользователя или системы.

• При сбое предварительной обработки шлюз возвращает четкую ошибку и не отправляет запрос DS без информации об изображении.

Обновление и удаление

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

Удаление:

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

Удаление постоянного шлюза Windows и восстановление исходного вышестоящего сервера:

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

Деинсталлятор не удаляет DASHSCOPE_API_KEY и не останавливает неизвестные программы, занимающие тот же порт. Временный запускатор CLI не изменяет постоянную конфигурацию; выход из Claude Code, запущенного им, останавливает шлюз.

Ссылки

• Claude Code MCP

• Claude Code Hooks

• Claude Code Plugin Marketplace

• Alibaba Cloud Bailian Vision Understanding

Лицензия

MIT