vision-bridge-mcp

Vision sidecar MCP сервер — даёт текстовым LLM возможность видеть изображения. Нативно поддерживает форматы API OpenAI И Anthropic. Включает навык маршрутизации на основе возможностей модели.

Зачем?

Большинство LLM работают только с текстом — они не могут видеть изображения. Этот MCP сервер устраняет этот пробел, передавая изображения модели, способной работать с визуальной информацией, и возвращая текстовые результаты. Он работает с любым API-эндпоинтом, совместимым с OpenAI или Anthropic.

В паре с навыком vision-sidecar он автоматически выполняет маршрутизацию на основе возможностей хост-модели:

Исключение: когда в системном буфере обмена есть изображение, а в разговоре нет пути/URL/вложения, даже мультимодальные хост-модели могут передать image="clipboard".

Related MCP server: Vision MCP Server

Возможности

• ✅ Три инструмента: analyze_image, ocr_image, compare_images

• ✅ Двойной протокол: формат OpenAI chat/completions И Anthropic messages

• ✅ Поддержка буфера обмена: Windows (PowerShell) + macOS (Swift)

• ✅ Файловый кеш SHA256 с настраиваемым TTL

• ✅ Повторная загрузка URL: автоматическая загрузка удалённых URL в base64 при неудаче сквозной передачи

• ✅ Резервный вариант для моделей рассуждения: извлекает reasoning_content, когда content равен null

• ✅ Таймаут полной цепочки: соединение + заголовки + чтение тела

• ✅ Ограничения безопасности: 16 МБ ответ / 20 МБ изображение / 1 МБ детали ошибки

• ✅ Типизированные ошибки: VisionInputError / VisionApiError / VisionTimeoutError

• ✅ Комплексные тесты: 30+ модульных тестов + сквозные smoke-тесты

• ✅ Ноль новых npm-зависимостей (использует workspace node_modules)

Быстрый старт

1. Убедитесь, что node ≥ 18 находится в вашем PATH.

2. Установите переменные окружения:

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. Зарегистрируйте в конфигурации вашего 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
}

Конфигурация

При запуске проверяются первые три переменные; отсутствующие вызывают понятную ошибку и завершение работы (код 1).

Инструменты

analyze_image

Предварительное условие: Вызывайте только тогда, когда хост-модель не обладает мультимодальным зрением. Если хост-модель мультимодальна, используйте её встроенное понимание изображений.

• image (обязательно, строка): Локальный путь к файлу / http(s) URL / dataURL в base64 / clipboard.

  • Локальный путь: определяет MIME по расширению (png/jpg/jpeg/gif/webp/bmp), преобразует в dataURL base64.

  • http(s) URL: передаётся напрямую как image_url.

  • dataURL: принимается только кодировка base64 для image/*.

  • clipboard / clip / pasteboard: читает текущее изображение из системного буфера обмена (Windows: scripts/clipboard.ps1, macOS: scripts/clipboard.swift), записывает во временный PNG, затем нормализует. Linux не поддерживается.

• prompt (опционально, строка): Пользовательская инструкция для распознавания. По умолчанию: "Опишите это изображение подробно."

• Возвращает: успех { content: [{ type: "text", text }] }; неудача { content: [{ type: "text", text: "[vision_error] ..." }], isError: true }.

Внутренний запрос (разделяется по VISION_API_FORMAT):

• OpenAI: POST {base}/chat/completions, изображение как часть image_url, аутентификация Authorization: Bearer.

• Anthropic: POST {base}/v1/messages, изображение как блок image (source: {type: base64, media_type, data} или {type: url, url}), аутентификация x-api-key + anthropic-version: 2023-06-01 (также отправляет Authorization: Bearer для совместимости).

Таймаут по умолчанию: 60 с (охватывает соединение + чтение тела).

Ограничения безопасности: ответ API 16 МБ, загрузка изображения 20 МБ (предварительная проверка content-length + повторная проверка фактического размера).

Примечания к поведению (из реального тестирования моделей):

• Модели рассуждения могут возвращать content: null с ответом в reasoning_content — автоматически используется резервный вариант.

• Неудача сквозной передачи http(s) URL с ошибкой медиа/загрузки → автоматическая загрузка в base64 и повторная попытка один раз.

ocr_image

• image (обязательно, строка): Та же нормализация, что и для analyze_image.

• languages (опционально, строка): Подсказки по языкам (например, zh,en).

• format (опционально, перечисление): plain (по умолчанию, обычный текст с сохранением макета) / markdown (сохраняет заголовки/списки/таблицы) / json (возвращает массив blocks с text + type).

• Внутренне использует image_url.detail = "high"; подсказка внедряется в зависимости от формата.

compare_images

• images (обязательно, массив, 2–4): Каждый поддерживает локальный путь / http(s) URL / dataURL / clipboard.

• prompt (опционально, строка): Пользовательская инструкция для сравнения. По умолчанию: "Сравните эти изображения и опишите их различия и сходства."

• Одно сообщение пользователя с текстом + несколько частей image_url (detail = "auto").

• Если какой-либо URL завершается ошибкой медиа/загрузки, все URL загружаются в base64 и повторяется попытка один раз.

Навык Vision Sidecar

Навык vision-sidecar обеспечивает маршрутизацию на основе возможностей модели. При включении в вашем MCP-клиенте:

• Хост-модель имеет мультимодальность → использует встроенное понимание изображений (без вызова MCP)

• Хост-модель только текстовая → вызывает analyze_image этого MCP

• Исключение: чтение буфера обмена доступно для мультимодальных хост-моделей

Без навыка поведение хост-модели полностью неизменно — нулевое вторжение.

См. файл навыка skill/vision-sidecar.md.

Кеширование

Включено по умолчанию. Кеширует результаты API зрения для одинаковых комбинаций "изображение + подсказка".

• Ключ: SHA256(идентификатор изображения + "::" + подсказка). Локальные файлы/dataURL хешируются по содержимому base64; http(s) URL хешируются по строке URL.

• Хранение: Один JSON-файл на ключ ({ result, cachedAt }), хранится в директории кеша.

• TTL: По умолчанию 1 час. Просроченные записи автоматически удаляются при следующем обращении.

• Отключение: VISION_CACHE_TTL=0 (или отрицательное значение).

• Примечание: Ключ не включает имя модели. После переключения VISION_MODEL в течение периода TTL могут возвращаться кешированные результаты от старой модели — очищайте директорию кеша при переключении моделей.

Тестирование

cd vision-bridge-mcp
node --test

• test/vision.test.js: Модульные тесты основной библиотеки (нормализация ввода / тело сообщения / вызовы API / сопоставление ошибок / таймаут / кеш / повтор URL / OCR / буфер обмена).

• test/cache.test.js: Тесты модуля кеша (стабильность ключа / попадание / истечение / повреждённый JSON / обратная совместимость).

• test/smoke.test.mjs: Сквозной smoke-тест — запускает реальный server.js через stdio, использует локальный HTTP-заглушку для имитации модели зрения, проверяет tools/list и вызовы инструментов.

Сравнение с другими Vision MCP

См. docs/COMPARISON.md для подробного сравнения с другими проектами Vision MCP.

Лицензия

MIT