vision-bridge-mcp

Dale ojos a tu agente OpenCode solo de texto.

Los modelos solo de texto de OpenCode (p. ej. DeepSeek V4) no pueden leer imágenes, así que si adjuntas una captura de pantalla de un error, un boceto de pizarra o una foto de un mockup de interfaz, el agente no tiene ni idea de lo que contiene. vision-bridge-mcp es un pequeño servidor MCP que se conecta directamente a OpenCode y le proporciona dos nuevas herramientas: analyze_image (descripción general / preguntas y respuestas visuales) y ocr_image (transcripción exacta de texto), ambas respaldadas por la API de Gemini (gemini-3.6-flash por defecto; puedes sobrescribirlo con GEMINI_MODEL si Google lo retira más adelante; consulta https://ai.google.dev/gemini-api/docs/models para ver los IDs de modelos actuales).

Una vez configurado, solo tienes que decirle al agente que mire un archivo:

Look at ./screenshots/error.png and tell me what's failing.

y él mismo llamará a analyze_image — sin copiar y pegar manualmente en una ventana de chat, sin pasos adicionales de CLI.

Requisitos

• Node.js 18 o superior

• Una clave de API de Gemini gratuita — consíguela en https://aistudio.google.com/apikey (plan gratuito: 1.500 solicitudes/día, sin necesidad de tarjeta de crédito)

Related MCP server: Vision MCP Server

Instalación

No es necesario clonar el repositorio. Añade esto a tu configuración de OpenCode (opencode.json en la raíz de tu proyecto, o ~/.config/opencode/opencode.json para una configuración global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision-bridge": {
      "type": "local",
      "command": ["npx", "-y", "vision-bridge-mcp"],
      "environment": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Reinicia OpenCode (o ejecuta opencode mcp para reconectar) y las herramientas analyze_image y ocr_image aparecerán automáticamente. npx descarga y almacena en caché el paquete la primera vez que se ejecuta — no hay nada que compilar ni instalar manualmente.

¿Prefieres una variable de entorno en lugar de codificar la clave en el archivo de configuración? Establece GEMINI_API_KEY en tu perfil de shell y elimina el bloque "environment" — el servidor la leerá del entorno del proceso de cualquier forma.

Ejecutarlo de forma independiente (para desarrollo o pruebas)

git clone https://github.com/YOUR_GITHUB_USERNAME/vision-bridge-mcp.git
cd vision-bridge-mcp
npm install
cp .env.example .env   # then fill in GEMINI_API_KEY
npm start

El servidor habla MCP sobre stdio, así que por sí solo se queda esperando a que un cliente (como OpenCode) se conecte — eso es lo esperado.

Herramientas

analyze_image

Comprensión de imágenes de propósito general. Dale una ruta y, opcionalmente, un prompt personalizado.

ocr_image

Transcribe el texto visible tal cual — útil para diálogos de error, capturas de terminal o notas fotografiadas.

Ambas herramientas admiten PNG, JPEG, WEBP, GIF y HEIC/HEIF, hasta 20MB por defecto.

Configuración

Toda la configuración se realiza mediante variables de entorno (establécelas directamente, en un archivo .env para uso independiente, o en el bloque "environment" de tu entrada MCP en opencode.json):

El servidor se inicia incluso sin GEMINI_API_KEY configurada (para que opencode mcp pueda seguir listando las herramientas) — solo da error, con un mensaje claro, en el momento en que se llama a una herramienta sin tener una clave configurada.

Manejo de errores

Cada llamada a una herramienta o bien tiene éxito con un resultado de texto, o bien falla con isError: true y un mensaje específico y accionable — un archivo inexistente, un formato no compatible, un archivo que supera el límite de tamaño, una clave de API faltante o inválida, o un error de la API de Gemini. El servidor nunca se bloquea ante una llamada incorrecta.

Desarrollo

npm install
npm test    # unit tests (node's built-in test runner, no network needed)
npm run lint

La suite de pruebas cubre la resolución de rutas, la detección de tipos MIME y la validación de archivos (archivos inexistentes, directorios, archivos vacíos, archivos sobredimensionados) — la lógica de manejo de entrada con más probabilidad de fallar en el uso real. La llamada a la API de Gemini en sí no está simulada ni probada aquí, ya que requiere una clave activa; si quieres verificar esa parte, establece GEMINI_API_KEY y ejecuta npm start, y luego conéctate con cualquier cliente MCP (o el MCP Inspector).

Publicación (mantenedores)

npm login
npm publish --access public

Primero incrementa la version en package.json — npx -y vision-bridge-mcp siempre se resuelve a la última versión publicada.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT — consulta LICENSE.