vision-bridge-mcp

Дайте глаза вашему текстовому агенту OpenCode.

Текстовые модели OpenCode (например, DeepSeek V4) не умеют читать изображения — так что если вы прикрепите скриншот ошибки, набросок на доске или фото макета интерфейса, агент понятия не имеет, что на нём. vision-bridge-mcp — это небольшой MCP-сервер, который подключается напрямую к OpenCode и даёт ему два новых инструмента: analyze_image (общее описание / визуальные вопросы и ответы) и ocr_image (точное распознавание текста), оба работают на базе Gemini API (gemini-3.6-flash по умолчанию — можно переопределить через GEMINI_MODEL, если Google позже уберёт эту модель; актуальные идентификаторы моделей смотрите на https://ai.google.dev/gemini-api/docs/models).

После настройки достаточно сказать агенту посмотреть на файл:

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

и он сам вызовет analyze_image — без ручного копирования в окно чата и без отдельного шага через CLI.

Требования

• Node.js 18 или новее

• Бесплатный ключ Gemini API — получите его на https://aistudio.google.com/apikey (бесплатный тариф: 1500 запросов в день, кредитная карта не требуется)

Related MCP server: Vision MCP Server

Установка

Клонирование не требуется. Добавьте это в конфиг OpenCode (opencode.json в корне проекта или ~/.config/opencode/opencode.json для глобальной настройки):

{
  "$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"
      }
    }
  }
}

Перезапустите OpenCode (или выполните opencode mcp для переподключения), и инструменты analyze_image и ocr_image появятся автоматически. При первом запуске npx загружает и кэширует пакет — ничего не нужно собирать или устанавливать вручную.

Предпочитаете переменную окружения вместо жёстко заданного ключа в конфиге? Установите GEMINI_API_KEY в профиле оболочки и удалите блок "environment" — сервер всё равно прочитает его из окружения процесса.

Запуск отдельно (для разработки или тестирования)

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

Сервер общается через MCP по stdio, поэтому сам по себе он просто ждёт подключения клиента (например, OpenCode) — это ожидаемо.

Инструменты

analyze_image

Универсальное понимание изображений. Передайте путь и, при необходимости, свой промпт.

ocr_image

Дословно распознаёт видимый текст — полезно для диалогов ошибок, скриншотов терминала или сфотографированных заметок.

Оба инструмента поддерживают PNG, JPEG, WEBP, GIF и HEIC/HEIF, по умолчанию до 20 МБ.

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

Вся конфигурация задаётся через переменные окружения (устанавливайте их напрямую, в файле .env для автономного использования или в блоке "environment" в ваш opencode.json MCP):

Сервер запускается даже без установленного GEMINI_API_KEY (поэтому opencode mcp всё равно может перечислить инструменты) — ошибка с понятным сообщением возникает только при фактическом вызове инструмента без настроенного ключа.

Обработка ошибок

Каждый вызов инструмента либо завершается успешно с текстовым результатом, либо падает с isError: true и конкретным, полезным сообщением — отсутствующий файл, неподдерживаемый формат, файл сверх лимита, отсутствующий/недействительный ключ API или ошибка вышестоящего сервиса Gemini. Сам сервер никогда не падает при некорректном вызове.

Разработка

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

Набор тестов покрывает разрешение путей, определение MIME-типов и проверку файлов (отсутствующие файлы, каталоги, пустые файлы, превышающие размер) — то есть логику обработки входных данных, которая чаще всего ломается при реальном использовании. Сам вызов Gemini API здесь не имитируется и не тестируется, так как требует рабочего ключа; если хотите проверить этот путь, установите GEMINI_API_KEY и запустите npm start, затем подключитесь с любым MCP-клиентом (или MCP Inspector).

Публикация (для сопровождающих)

npm login
npm publish --access public

Сначала увеличьте version в package.json — npx -y vision-bridge-mcp всегда разрешается в последнюю опубликованную версию.

Участие в разработке

Смотрите CONTRIBUTING.md.

Лицензия

MIT — см. LICENSE.