visionMCP 👁️

Глаза более крупной рассуждающей LLM.

visionMCP — это сервер Model Context Protocol, который предоставляет любому агенту, совместимому с MCP, настоящее зрение. Текстовый рассуждающий LLM может делегировать этому серверу всё, что не может увидеть сам: описать скриншот, ответить на вопрос по фотографии, распознать текст на документе или сравнить два изображения — сервер выполняет функции зрения и возвращает текст.

Он работает со всеми тремя основными бэкендами для зрения, выбираемыми во время выполнения из одного файла config.json:

Возможности

• 🔍 Четыре инструмента для зрения, которые может вызывать рассуждающий LLM:

  • describe_image — полное описание на естественном языке

  • ask_about_image — целевой вопрос-ответ по любому изображению

  • extract_text — OCR / распознавание текста

  • compare_images — сравнение двух изображений

• 🖼️ Принимается любой источник: локальные пути к файлам, http(s) URL и base64 data: URI.

• 📦 Нулевая подготовка изображений: изображения большого размера автоматически уменьшаются и перекодируются в JPEG, чтобы соответствовать ограничениям размера полезной нагрузки провайдера.

• 🔌 Три транспорта: stdio (по умолчанию, для локальных MCP-клиентов), http (Streamable HTTP для удаленного хостинга) или sse (устаревшие Server-Sent Events).

• ⚙️ Один config.json управляет провайдером, ключом API, URL API и моделью. Переменные окружения и флаги командной строки могут переопределить любой параметр.

• 🚀 Управляется с помощью uv, устанавливаемый, запускаемый и размещаемый.

Related MCP server: depu-img-mcp

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

1. Установка

Требуется uv и Python ≥ 3.10.

cd visionMCP
uv sync

2. Настройка

Поставляемый config.json уже работает с локальным Ollama. Смените провайдера, отредактировав файл:

// config.json
{
  "provider": "openai",                  // "ollama" | "openai" | "anthropic"
  "api_key": "sk-...",                   // or leave "" and export OPENAI_API_KEY
  "api_url": "",                         // "" = provider default
  "model": ""                            // "" = provider default
}

Смотрите docs/configuration.md для всех опций и docs/providers.md для настройки каждого провайдера.

Безопасность: не храните настоящие ключи API в git — скопируйте config.json в config.local.json (автоматически игнорируется) или используйте переменные окружения. Сервер никогда не логирует ваш ключ.

3. Запуск

uv run vision-mcp                        # stdio transport (default)
uv run vision-mcp --transport http --host 0.0.0.0 --port 8100   # host remotely
uv run vision-mcp --show-config          # print resolved config (key masked)

Подключение к MCP-клиенту

opencode (opencode.json)

{
  "mcpServers": {
    "visionMCP": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "visionMCP": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/visionMCP", "vision-mcp"]
    }
  }
}

Универсальный MCP-клиент (stdio)

{
  "mcpServers": {
    "visionMCP": {
      "command": "/path/to/visionMCP/.venv/bin/vision-mcp",
      "args": ["--config", "/path/to/visionMCP/config.json"]
    }
  }
}

Сервер никогда не отправляет содержимое изображения в API для зрения за пределами того, что предоставляет вызов инструмента. Байты изображения хранятся в памяти и никогда не записываются на диск.

Справочник по инструментам

Аргумент image принимает любой из:

/path/to/photo.png          # local file
https://example.com/x.jpg   # URL (downloaded at call time)
data:image/png;base64,iVBORw0KGgo...   # base64 data URI

Принцип работы

Всё проходит через одну функцию в src/vision_mcp/pipeline.py:

image (path / URL / data URI)  →  base64 + mime  →  vision model  →  text
        _read()                     _encode()         API[provider]    look()

Инструменты сервера — это тонкие обертки: pipeline.look(cfg, [image], prompt).

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

• Справочник по настройке — каждая опция конфигурации, переменная окружения и правила приоритета

• Настройка провайдера — Ollama, OpenAI и Anthropic, пошагово

• Развертывание — хостинг через HTTP/SSE, Docker, защита

Разработка

uv sync --group dev
uv run ruff check .
uv run pytest

Лицензия

MIT