# MCP Image Validator

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
---

## Что это?

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 ([получить здесь](https://ollama.com/settings/keys))

### Установка

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

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

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

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

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

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

```bash
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` проверьте работу сервиса:

```bash
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`):

```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](server.py)) - FastMCP сервер с stdio транспортом
- **Ollama Client** ([ollama_vision_client.py](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](https://github.com/your-org/comfyui-mcp-server) - архитектура MCP сервера
- [doc-chatbot](https://github.com/your-org/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                   # Этот файл
```

---

## Разработка

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

```bash
python server.py
```

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

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

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

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

### Логирование

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

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

```python
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 - Валидация и обработка изображений

Установка:

```bash
pip install -r requirements.txt
```

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

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

---

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

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

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

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

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

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

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

---

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

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

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

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

---

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

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

---

## Лицензия

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

---

## Ссылки

- **[Ollama Cloud](https://ollama.com)** - Облачная платформа для AI моделей
- **[Ollama API Keys](https://ollama.com/settings/keys)** - Получить API ключ
- **[MCP Protocol](https://modelcontextprotocol.io)** - Спецификация Model Context Protocol
- **[Claude Code](https://claude.ai/code)** - AI ассистент для разработки
- **[FastMCP](https://github.com/jlowin/fastmcp)** - Фреймворк для MCP серверов

---

## Поддержка

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

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

---