# 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`, а результат (текстовое описание) отдаёт основной модели как обычный текст.

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

```
Пользователь прикладывает изображение
        │
        ▼
Основная (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. Клонирование (рекомендуется)

```bash
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 не сможет запустить сервер.

Обновление:

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

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

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

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

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

| Переменная | Описание |
|---|---|
| `VISION_BASE_URL` | Базовый URL OpenAI-compatible API, например `https://your-provider.com/v1` |
| `VISION_API_KEY` | API-ключ провайдера |
| `VISION_MODEL` | ID vision-модели |

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

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

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

```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` на:

```json
"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](LICENSE)