vision-bridge-mcp

Servidor MCP sidecar para visión: permite que los LLM solo de texto puedan ver imágenes. Soporta de forma nativa los formatos de API de OpenAI y Anthropic. Incluye habilidad de enrutamiento según capacidades del modelo.

¿Por qué?

La mayoría de los LLM son solo de texto: no pueden ver imágenes. Este servidor MCP cierra esa brecha enviando imágenes a un modelo con capacidad de visión y devolviendo resultados de texto. Funciona con cualquier endpoint de API compatible con OpenAI o Anthropic.

Cuando se combina con la habilidad vision-sidecar, enruta automáticamente según las capacidades del modelo anfitrión:

Excepción: cuando el portapapeles del sistema tiene una imagen y la conversación no tiene ruta/URL/adjunto, incluso los modelos anfitriones multimodales pueden pasar image="clipboard".

Related MCP server: Vision MCP Server

Características

• ✅ Tres herramientas: analyze_image, ocr_image, compare_images

• ✅ Protocolo dual: formato chat/completions de OpenAI Y messages de Anthropic

• ✅ Soporte de portapapeles: Windows (PowerShell) + macOS (Swift)

• ✅ Caché de archivos SHA256 con TTL configurable

• ✅ Reintento de descarga de URL: descarga automáticamente URLs remotas a base64 cuando falla el paso directo

• ✅ Fallback para modelos de razonamiento: extrae reasoning_content cuando content es nulo

• ✅ Tiempo de espera completo de la cadena: conexión + cabeceras + lectura del cuerpo

• ✅ Límites de seguridad: 16 MB de respuesta / 20 MB de imagen / 1 MB de detalle de error

• ✅ Errores tipados: VisionInputError / VisionApiError / VisionTimeoutError

• ✅ Pruebas exhaustivas: más de 30 pruebas unitarias + pruebas de humo de extremo a extremo

• ✅ Cero nuevas dependencias npm (usa node_modules del espacio de trabajo)

Inicio rápido

1. Asegúrate de que node ≥ 18 esté en tu PATH.

2. Establece las variables de entorno:

export VISION_API_BASE_URL=https://api.example.com/v1   # OpenAI: ends with /v1; Anthropic: base without /v1
export VISION_API_KEY=sk-...                             # API key
export VISION_MODEL=gpt-4o                               # Vision model name
# Optional: export VISION_API_FORMAT=anthropic            # openai (default) or anthropic

3. Regístrate en la configuración de tu cliente MCP:

{
  "id": "vision-bridge-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "cwd": "/path/to/vision-bridge-mcp",
  "env": {
    "VISION_API_BASE_URL": "https://api.example.com/v1",
    "VISION_API_KEY": "your-key",
    "VISION_MODEL": "gpt-4o"
  },
  "enabled": true
}

Configuración

El inicio valida las tres primeras variables; si faltan, se muestra un error legible y se sale (código 1).

Herramientas

analyze_image

Requisito previo: Solo llamar cuando el modelo anfitrión carece de visión multimodal. Si el modelo anfitrión es multimodal, usa su comprensión nativa de imágenes.

• image (obligatorio, cadena): Ruta de archivo local / URL http(s) / dataURL base64 / clipboard.

  • Ruta local: infiere el tipo MIME de la extensión (png/jpg/jpeg/gif/webp/bmp), convierte a dataURL base64.

  • URL http(s): se pasa directamente como image_url.

  • dataURL: solo se acepta codificación base64 de image/*.

  • clipboard / clip / pasteboard: lee la imagen actual del portapapeles del sistema (Windows: scripts/clipboard.ps1, macOS: scripts/clipboard.swift), escribe a un PNG temporal y luego normaliza. Linux no soportado.

• prompt (opcional, cadena): Instrucción de reconocimiento personalizada. Por defecto: "Describe esta imagen en detalle."

• Devuelve: éxito { content: [{ type: "text", text }] }; fallo { content: [{ type: "text", text: "[vision_error] ..." }], isError: true }.

Solicitud interna (dividida por VISION_API_FORMAT):

• OpenAI: POST {base}/chat/completions, imagen como parte image_url, autenticación Authorization: Bearer.

• Anthropic: POST {base}/v1/messages, imagen como bloque image (source: {type: base64, media_type, data} o {type: url, url}), autenticación x-api-key + anthropic-version: 2023-06-01 (también envía Authorization: Bearer por compatibilidad).

Tiempo de espera por defecto: 60 s (cubre conexión + lectura del cuerpo).

Límites de seguridad: respuesta de API 16 MB, descarga de imagen 20 MB (precomprobación de content-length + nueva comprobación de tamaño real).

Notas de comportamiento (de pruebas con modelos reales):

• Los modelos de razonamiento pueden devolver content: null con la respuesta en reasoning_content — se hace fallback automáticamente.

• Fallo de paso directo de URL http(s) con error de medios/descarga → descarga automática a base64 y reintento una vez.

ocr_image

• image (obligatorio, cadena): Misma normalización que analyze_image.

• languages (opcional, cadena): Sugerencias de idioma (ej. zh,en).

• format (opcional, enumerado): plain (por defecto, texto plano conservando el diseño) / markdown (conserva encabezados/listas/tablas) / json (devuelve un array blocks con text + type).

• Usa internamente image_url.detail = "high"; el prompt se inyecta según el formato.

compare_images

• images (obligatorio, array, 2–4): Cada uno admite ruta local / URL http(s) / dataURL / portapapeles.

• prompt (opcional, cadena): Instrucción de comparación personalizada. Por defecto: "Compara estas imágenes y describe sus diferencias y similitudes."

• Un único mensaje de usuario con texto + múltiples partes image_url (detail = "auto").

• Si alguna URL falla con error de medios/descarga, todas las URLs se descargan a base64 y se reintentan una vez.

Habilidad Vision Sidecar

La habilidad vision-sidecar proporciona enrutamiento según capacidades del modelo. Cuando está habilitada en tu cliente MCP:

• El modelo anfitrión tiene capacidad multimodal → usa comprensión nativa de imágenes (sin llamada MCP)

• El modelo anfitrión es solo texto → llama a analyze_image de este MCP

• Excepción: lectura de portapapeles disponible para modelos anfitriones multimodales

Sin la habilidad, el comportamiento del modelo anfitrión no cambia en absoluto — cero intrusión.

Consulta skill/vision-sidecar.md para el archivo de la habilidad.

Caché

Habilitada por defecto. Almacena en caché los resultados de la API de visión para combinaciones idénticas de "imagen + prompt".

• Clave: SHA256(identificador de imagen + "::" + prompt). Los archivos locales/dataURLs se hashean por el contenido base64; las URLs http(s) se hashean por la cadena de la URL.

• Almacenamiento: Un archivo JSON por clave ({ result, cachedAt }), almacenado en el directorio de caché.

• TTL: Por defecto 1 hora. Las entradas caducadas se eliminan automáticamente en el próximo acceso.

• Desactivar: VISION_CACHE_TTL=0 (o negativo).

• Nota: La clave no incluye el nombre del modelo. Después de cambiar VISION_MODEL, el período TTL puede devolver resultados en caché del modelo anterior — limpia el directorio de caché al cambiar de modelo.

Pruebas

cd vision-bridge-mcp
node --test

• test/vision.test.js: Pruebas unitarias de la biblioteca principal (normalización de entrada / cuerpo del mensaje / llamadas a la API / mapeo de errores / tiempo de espera / caché / reintento de URL / OCR / portapapeles).

• test/cache.test.js: Pruebas del módulo de caché (estabilidad de clave / acierto / caducidad / JSON corrupto / compatibilidad hacia atrás).

• test/smoke.test.mjs: Prueba de humo de extremo a extremo — inicia server.js real a través de stdio, usa un stub HTTP local para simular el modelo de visión, valida tools/list y llamadas a herramientas.

Comparación con otros MCP de visión

Consulta docs/COMPARISON.md para una comparación detallada con otros proyectos MCP de visión.

Licencia

MIT