mcp-plus: Claude Code Qwen Vision

Permite que Claude Code, que utiliza modelos de solo texto como DeepSeek, obtenga capacidad de comprensión de imágenes de forma transparente.

Modelo visual predeterminado: qwen3.8-max Dirección Qwen predeterminada: https://dashscope.aliyuncs.com/compatible-mode/v1

El proyecto proporciona dos rutas:

1. Puerta de enlace transparente (recomendada): El usuario pega la imagen normalmente, la puerta de enlace la envía automáticamente a Qwen y luego entrega el resultado visual estructurado a DS. Durante la ejecución, no es necesario ingresar comandos ni depender de que DS invoque herramientas activamente.

2. Complemento MCP de Claude Code: Proporciona la herramienta analyze_image y una Skill explícita, adecuada para leer directamente archivos de imagen en el proyecto o como plan de respaldo.

Por qué se necesita una puerta de enlace transparente

El Hook UserPromptSubmit de Claude Code solo proporciona el prompt de texto actualmente, no entrega el Base64 original de la imagen pegada ni la ruta temporal al Hook. El Hook tampoco puede determinar de manera confiable el modelo al que el usuario ha cambiado en la sesión. Por lo tanto, confiar únicamente en Skill, Hook o MCP no garantiza el "procesamiento automático después de pegar una imagen".

La puerta de enlace transparente funciona entre Claude Code y la interfaz del modelo principal, pudiendo ver tanto el model en la solicitud como los bloques de contenido de la imagen:

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

La misma imagen se almacena en caché dentro del proceso de la puerta de enlace mediante SHA-256. Cuando Claude Code reenvía mensajes del historial, no se vuelve a llamar a Qwen. La caché solo se guarda en memoria y no escribe la imagen ni los resultados de OCR en el disco.

Instalación permanente y discreta en Windows (recomendada para VS Code)

Requisitos previos:

• Claude Code 2.1.128 o superior

• Python 3.10+

• Clave API de Bailian que pueda invocar qwen3.8-max

• Interfaz compatible con DS/Claude Anthropic ya configurada

Clonar el repositorio:

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

Primero, configure la clave Qwen como variable de entorno de usuario en Windows. Se recomienda ingresarla de forma interactiva en PowerShell para evitar que la clave quede en el historial de comandos:

$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)
}

Instalar la puerta de enlace permanente:

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

El instalador:

1. Copia los archivos de ejecución a %LOCALAPPDATA%\mcp-plus\qwen-vision;

2. Registra una entrada de inicio automático de Windows mcp-plus Qwen Vision Gateway para el usuario actual al iniciar sesión;

3. Escucha fijamente en http://127.0.0.1:15722;

4. Guarda la dirección upstream original de DS/Claude, pero no copia ni escribe la clave API;

5. Cambia ANTHROPIC_BASE_URL en ~/.claude/settings.json a la puerta de enlace local.

Después de la instalación, recargue la ventana de VS Code o ciérrela por completo y vuelva a abrir Claude Code. Verifique el servicio:

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

Debería ver ok: true, qwen_model: qwen3.8-max y la dirección upstream original.

Inicio temporal de Claude Code CLI

Si no desea modificar la configuración de forma permanente, puede usar el lanzador temporal solo para la sesión CLI actual. Establezca la clave Qwen en la sesión actual de PowerShell:

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

Ingrese a Claude Code a través del lanzador. -UpstreamBaseUrl debe ser la interfaz del modelo principal original; si usa CC Switch local, podría ser una dirección similar a la siguiente:

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

El lanzador:

1. Inicia una puerta de enlace visual oculta en un puerto local aleatorio;

2. Modifica temporalmente ANTHROPIC_BASE_URL solo para el proceso de Claude Code actual;

3. Conserva y reenvía los encabezados de solicitud existentes ANTHROPIC_AUTH_TOKEN, X-Api-Key y Anthropic Beta;

4. Cuando Claude Code se cierra, detiene la puerta de enlace y restaura las variables de entorno de PowerShell actual.

No modifica permanentemente ~/.claude/settings.json. Luego, simplemente pegue la imagen y haga la pregunta como de costumbre, no necesita el comando /qwen-vision:*.

Paso directo de modelos multimodales

El modo always predeterminado procesa todas las imágenes. Esto es más confiable en entornos donde CC Switch asigna alias como claude-sonnet-* a DS, ya que el nombre del modelo en la solicitud no necesariamente representa el modelo upstream real.

Si el ID del modelo puede reflejar con precisión la capacidad, se puede configurar el paso directo de modelos multimodales:

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

• always: Todas las imágenes son procesadas primero por Qwen, valor predeterminado.

• allowlist: Los modelos que coinciden con QWEN_VISION_DIRECT_MODELS reciben la imagen original directamente; otros modelos usan Qwen.

• never: Desactiva completamente el preprocesamiento transparente de imágenes, solo realiza el reenvío de solicitudes.

Instalación del complemento MCP de Claude Code

El complemento proporciona capacidad de análisis de imágenes de archivos del proyecto, pero no puede reemplazar a la puerta de enlace transparente para manejar imágenes pegadas desde el portapapeles.

Instalar desde GitHub Marketplace:

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

Ejecute /mcp, debería ver qwen_vision como Connected. Ejemplo de uso:

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

O invocación explícita:

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

Si la puerta de enlace DS no puede devolver tool_use de MCP, use la Skill de respaldo determinista:

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

Desarrollo y verificación local

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

La prueba de la API de imágenes reales requiere que la imagen esté en el proyecto actual:

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

Elementos de configuración

Notas de seguridad

• Las imágenes se envían a Alibaba Cloud Bailian. Antes de enviarlas, se deben eliminar las credenciales de producción, la información personal y los datos confidenciales.

• La clave API solo se lee desde las variables de entorno, no se escribe en el complemento, los registros ni las respuestas.

• El MCP de archivos del proyecto solo permite leer PNG, JPEG y WebP dentro de CLAUDE_PROJECT_DIR.

• La puerta de enlace transparente solo escucha en 127.0.0.1 de forma predeterminada.

• El texto reconocido en las imágenes siempre se trata como datos no confiables y no puede anular las instrucciones del usuario o del sistema.

• Cuando falla el preprocesamiento de la puerta de enlace, se devuelve un error claro y no se solicita a DS en silencio perdiendo la información de la imagen.

Actualización y desinstalación

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

Desinstalación:

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

Desinstalar la puerta de enlace permanente de Windows y restaurar el upstream original:

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

El desinstalador no elimina DASHSCOPE_API_KEY ni detiene programas desconocidos que ocupen el mismo puerto. El lanzador temporal de CLI no modifica la configuración permanente; la puerta de enlace se detiene al salir de Claude Code iniciado por él.

Referencias

• Claude Code MCP

• Claude Code Hooks

• Claude Code Plugin Marketplace

• Comprensión visual de Alibaba Cloud Bailian

Licencia

MIT