MCP Image Validator

Python MCP (Model Context Protocol) сервер для описания изображений с использованием модели Qwen3-VL через Ollama Cloud.

Что это?

MCP сервер, который позволяет Claude Code и другим MCP клиентам анализировать изображения с помощью облачной vision модели Qwen3-VL (235B параметров) от Ollama Cloud.

Основные возможности:

• 🖼️ Анализ изображений - Детальное описание с помощью Qwen3-VL (235B параметров)
• ☁️ Облачные вычисления - Работает через Ollama Cloud API (не требует GPU)
• 🔌 MCP совместимость - Готов к использованию в Claude Code
• 🎨 Поддержка форматов - JPEG, PNG, GIF, WebP, BMP
• 🛠️ Простота - Построен на FastMCP для лёгкой настройки
• ⚡ Проверено - Протестировано и готово к работе

---

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

Требования

• Python 3.10 или выше
• API ключ Ollama Cloud (получить здесь)

Установка

# Клонируйте репозиторий
git clone <url-репозитория>
cd mcp-image-validator

# Установите зависимости
pip install -r requirements.txt

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

# Скопируйте шаблон
cp .env.example .env

# Отредактируйте .env и добавьте ваш API ключ
# Получить ключ: https://ollama.com/settings/keys

Содержимое .env:

OLLAMA_API_KEY=ваш_api_ключ_здесь
VISION_MODEL=qwen3-vl:235b-cloud
OLLAMA_BASE_URL=https://ollama.com/v1
VISION_TEMPERATURE=0.2
VISION_MAX_TOKENS=1000

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

После настройки .env проверьте работу сервиса:

python test_full.py

Скрипт выполнит:

• ✅ Проверку подключения к Ollama Cloud
• ✅ Поиск тестового изображения в директории (test.jpg, test.png, sample.jpg, sample.png)
• ✅ Анализ изображения с помощью Qwen3-VL
• ✅ Вывод детального описания

Если тестовое изображение не найдено, скрипт предложит ввести путь к вашему изображению.

Использование с Claude Code

Добавьте в настройки MCP Claude Code (.claude/mcp_settings.json или claude_desktop_config.json):

{
  "mcpServers": {
    "image-validator": {
      "command": "python",
      "args": ["c:\\GIT\\mcp-image-validator\\server.py"],
      "env": {
        "OLLAMA_API_KEY": "ваш_api_ключ_здесь"
      }
    }
  }
}

Важно:

• Используйте абсолютные пути
• Укажите API ключ в секции env
• Перезапустите Claude Code после добавления конфигурации

Затем в диалоге с Claude Code:

Опиши изображение по пути C:\Users\user\Pictures\photo.jpg

---

Доступный инструмент

describe_image

Анализирует изображение и предоставляет детальное описание с использованием Qwen3-VL.

Параметры:

• image_path (строка, обязательно) - Абсолютный путь к файлу изображения
• prompt (строка, опционально) - Пользовательский промпт для модели

Примеры использования:

Опиши изображение по пути C:\Photos\landscape.jpg

Проанализируй изображение C:\Docs\diagram.png и перечисли все компоненты

Что изображено на фото /home/user/pictures/sunset.jpg?

Поддерживаемые форматы: JPEG, PNG, GIF, WebP, BMP

---

Переменные окружения

Переменная	По умолчанию	Описание
OLLAMA_API_KEY	-	Обязательно. API ключ от Ollama Cloud
VISION_MODEL	qwen3-vl:235b-cloud	Vision модель для использования
OLLAMA_BASE_URL	https://ollama.com/v1	Адрес Ollama Cloud API
VISION_TEMPERATURE	0.2	Температура генерации (0.0-1.0, меньше = детерминированнее)
VISION_MAX_TOKENS	1000	Максимальное количество токенов в ответе

Примечание: Модели Ollama Cloud должны иметь суффикс -cloud (например, qwen3-vl:235b-cloud).

---

Архитектура

Сервер использует FastMCP (фреймворк от Anthropic) и OpenAI SDK, настроенный для работы с Ollama Cloud.

Компоненты:

• MCP Server (server.py) - FastMCP сервер с stdio транспортом
• Ollama Client (ollama_vision_client.py) - Клиент API для обработки изображений
• Qwen3-VL Model - Vision модель на 235B параметров на Ollama Cloud

Поток данных:

Claude Code → MCP Protocol → server.py → ollama_vision_client.py
                                              ↓
                                         OpenAI SDK
                                              ↓
                                    Ollama Cloud API
                                              ↓
                                       Qwen3-VL Model

Основано на проверенных паттернах:

• comfyui-mcp-server - архитектура MCP сервера
• doc-chatbot - интеграция с Ollama Cloud

---

Структура проекта

mcp-image-validator/
├── server.py                   # MCP сервер (stdio transport)
├── ollama_vision_client.py     # Клиент Ollama Cloud API
├── test_full.py                # Полный функциональный тест
├── requirements.txt            # Python зависимости
├── .env.example                # Шаблон переменных окружения
├── .gitignore                  # Правила для git
└── README.md                   # Этот файл

---

Разработка

Запуск сервера напрямую

python server.py

Сервер запустится и будет ожидать MCP протокольные сообщения на stdin.

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

# Полный функциональный тест
python test_full.py

# С конкретным изображением
python test_full.py
# Введите путь к изображению когда будет предложено

Логирование

Логи сервера выводятся в stderr. При запуске через Claude Code логи доступны в панели MCP серверов.

Для более детального логирования измените в server.py:

logging.basicConfig(level=logging.DEBUG)

---

Устранение неполадок

"OLLAMA_API_KEY not set"

Решение:

• Убедитесь, что файл .env существует с корректным ключом
• При использовании с Claude Code укажите ключ в env секции настроек MCP

"Image file not found"

Решение:

• Используйте только абсолютные пути к изображениям
• Проверьте существование файла: dir "C:\path\to\image.jpg" (Windows) или ls -la /path/to/image.jpg (Linux/Mac)

"Unsupported image format"

Решение:

• Поддерживаются только: JPEG, PNG, GIF, WebP, BMP
• Проверьте, что расширение файла соответствует реальному формату

Медленные ответы (10-30+ секунд)

Это нормально!

• Vision модели с 235B параметров требуют времени на обработку
• Облачные модели имеют сетевую задержку
• Для более быстрой работы можно попробовать модели меньшего размера

Сервер не загружается в Claude Code

Проверьте:

• Путь в настройках MCP абсолютный и корректный
• Используется команда python (или python3 на некоторых системах)
• Claude Code перезапущен после изменения конфигурации
• Логи MCP сервера на наличие ошибок

"Connection refused" или "Network error"

Проверьте:

• Интернет соединение активно
• Доступ к ollama.com не заблокирован фаерволом
• API ключ действителен и имеет активные кредиты

---

Примеры использования

Базовое описание

Опиши изображение по пути C:\Users\user\Pictures\photo.jpg

С кастомным промптом

Проанализируй изображение C:\Docs\screenshot.png и перечисли все видимые элементы интерфейса

Множественные аспекты

Для изображения /home/user/vacation.jpg:
1. Опиши главный объект
2. Какие цвета преобладают?
3. Какая атмосфера или настроение?

Claude Code автоматически использует инструмент describe_image на основе вашего запроса.

---

Технические характеристики

Требования

• Python 3.10 или выше
• Интернет соединение (для Ollama Cloud API)
• API ключ Ollama Cloud

Зависимости

• mcp ≥1.0.0 - FastMCP фреймворк
• openai ≥1.0.0 - OpenAI SDK (совместимость с Ollama Cloud)
• python-dotenv ≥1.0.0 - Управление переменными окружения
• Pillow ≥10.0.0 - Валидация и обработка изображений

Установка:

pip install -r requirements.txt

Производительность

• Время ответа: 10-30 секунд (зависит от изображения и загрузки сервера)
• Качество: Высокое (модель 235B параметров)
• Стабильность: Production-ready

---

Расширение функциональности

Добавление новых инструментов

Пример добавления нового инструмента:

@mcp.tool()
def analyze_colors(image_path: str) -> dict:
    """Анализирует цветовую палитру изображения"""
    # Ваша реализация
    pass

Использование других моделей

Измените VISION_MODEL в .env:

# Другие vision модели с суффиксом -cloud
VISION_MODEL=llava:7b-cloud
VISION_MODEL=bakllava:7b-cloud

---

Вклад в проект

Приветствуются любые вклады! Интересные направления:

• 📦 Пакетная обработка изображений
• 🔍 Дополнительные инструменты анализа (OCR, определение объектов)
• 🎨 Поддержка других vision моделей
• 📊 Потоковая передача прогресса
• 🧪 Unit и интеграционные тесты
• 📚 Примеры использования

Создавайте Issues или Pull Requests на GitHub.

---

Документация

• README.md - Этот файл (основная документация)
• test_full.py - Исходный код теста с примерами

---

Лицензия

MIT License - См. файл LICENSE для деталей.

---

Ссылки

• Ollama Cloud - Облачная платформа для AI моделей
• Ollama API Keys - Получить API ключ
• MCP Protocol - Спецификация Model Context Protocol
• Claude Code - AI ассистент для разработки
• FastMCP - Фреймворк для MCP серверов

---

Поддержка

Для получения помощи:

1. 📖 Проверьте раздел Устранение неполадок
2. 🐛 Создайте Issue на GitHub с:
   • Версией Python (python --version)
   • Сообщениями об ошибках из логов
   • Шагами для воспроизведения проблемы

---