analyze-image-mcp

Минимальный MCP-сервер (пример подключения ниже — для OpenCode, но подойдёт любому MCP-клиенту), который даёт text-only модели доступ к отдельной vision-модели через один инструмент — analyze_image. Работает с любым OpenAI-compatible vision API (включая провайдеров с ограниченной поддержкой tool calling), так как обращается к нему напрямую, минуя механизм tools/tool_choice самого OpenCode.

Зачем это нужно

Если у тебя:

• основная модель — только текстовая;

• вторая модель — с поддержкой изображений, но у провайдера не включён --enable-auto-tool-choice (частая ошибка "auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set);

то стандартная отправка картинки напрямую в OpenCode ломается. Этот MCP-сервер решает проблему: он вызывает vision-модель отдельным чистым HTTP-запросом без полей tools/tool_choice, а результат (текстовое описание) отдаёт основной модели как обычный текст.

Related MCP server: vision-bridge-mcp

Как это работает

Пользователь прикладывает изображение
        │
        ▼
Основная (text-only) модель видит инструкцию:
"если есть изображение — вызови analyze_image"
        │
        ▼
MCP-сервер (analyze_image):
  1. читает файл / URL / data-URI
  2. кодирует в data:image/...;base64,...
  3. отправляет чистый OpenAI-compatible запрос
     (без tools, без tool_choice) в vision-провайдера
        │
        ▼
Текстовое описание возвращается основной модели
        │
        ▼
Основная модель отвечает пользователю

Установка

Нужен Node.js 18+ (используется встроенный fetch) и git. Пакет в npm не публикуется — ставится из GitHub. Выбери один из вариантов.

Вариант 1. Клонирование (рекомендуется)

git clone https://github.com/iljyxa/analyze-image-mcp.git ~/analyze-image-mcp
cd ~/analyze-image-mcp
npm install --omit=dev

npm install скачивает @modelcontextprotocol/sdk — официальную библиотеку протокола MCP (JSON-RPC через stdio). Папка node_modules/ должна оставаться рядом с index.js, иначе OpenCode не сможет запустить сервер.

Обновление:

cd ~/analyze-image-mcp && git pull && npm install --omit=dev

Вариант 2. Без клонирования, через npx

Ничего ставить заранее не нужно: npx сам скачает репозиторий из GitHub и зависимости при первом запуске (кэшируется). Команда для конфига приведена ниже. Чтобы зафиксировать версию, добавь тег или коммит: github:iljyxa/analyze-image-mcp#v1.0.0.

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

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

Сервер сам не читает .env — значения передаются через блок environment в конфиге OpenCode (см. ниже).

Подключение к OpenCode

В opencode.json (глобальный конфиг OpenCode — ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["node", "/home/<пользователь>/analyze-image-mcp/index.js"],
      "environment": {
        "VISION_BASE_URL": "https://твой-провайдер.com/v1",
        "VISION_API_KEY": "твой-ключ",
        "VISION_MODEL": "твоя-vision-модель"
      }
    }
  }
}

Путь в command — абсолютный (~ в конфиге не раскрывается). Для варианта 2 (npx) замени command на:

"command": ["npx", "-y", "github:iljyxa/analyze-image-mcp"]

Инструкция для агента

Чтобы основная модель сама вызывала инструмент при появлении изображения, добавь правило в системный промпт / AGENTS.md / настройки агента:

Если пользователь прикладывает изображение, а активная модель не может видеть изображения напрямую, всегда сначала вызывай инструмент analyze_image с путём к изображению, затем формируй ответ на основе полученного описания.

Проверка работы

1. Перезапусти OpenCode после изменения конфига.

2. Спроси у агента: "есть ли у тебя инструмент analyze_image?"

3. Приложи изображение и задай вопрос по нему — модель должна вызвать analyze_image и ответить на основе полученного описания.

Известные ограничения

• MCP-инструмент не перехватывает изображение автоматически — модель должна сама решить вызвать analyze_image. Надёжность зависит от инструкции в системном промпте и от того, насколько хорошо основная модель следует правилам вызова инструментов.

• Поддерживаемые форматы изображений: PNG, JPEG, GIF, WebP.

• Максимальный размер ответа vision-модели ограничен max_tokens: 2048 — при необходимости увеличь в index.js.

Лицензия

MIT