README.md•14.4 kB
# MCP Image Validator
Python MCP (Model Context Protocol) сервер для описания изображений с использованием модели Qwen3-VL через Ollama Cloud.
[](https://www.python.org/downloads/)
[](LICENSE)
[](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`)
- Сообщениями об ошибках из логов
- Шагами для воспроизведения проблемы
---