MCP OpenVision

Обзор

MCP OpenVision — это сервер Model Context Protocol (MCP), который предоставляет возможности анализа изображений на основе моделей зрения OpenRouter. Он позволяет помощникам ИИ анализировать изображения через простой интерфейс в экосистеме MCP.

Related MCP server: MCP Read Images

Установка

Установка через Smithery

Чтобы автоматически установить mcp-openvision для Claude Desktop через Smithery :

npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

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

pip install mcp-openvision

Использование УФ (рекомендуется)

uv pip install mcp-openvision

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

MCP OpenVision требует API-ключа OpenRouter и может быть настроен с помощью переменных среды:

• OPENROUTER_API_KEY (обязательно): Ваш ключ API OpenRouter

• OPENROUTER_DEFAULT_MODEL (необязательно): модель зрения, которую следует использовать

Модели видения OpenRouter

MCP OpenVision работает с любой моделью OpenRouter, которая поддерживает возможности Vision. Модель по умолчанию — qwen/qwen2.5-vl-32b-instruct:free , но вы можете указать любую другую совместимую модель.

Некоторые популярные модели машинного зрения, доступные через OpenRouter, включают:

• qwen/qwen2.5-vl-32b-instruct:free (по умолчанию)

• anthropic/claude-3-5-sonnet

• anthropic/claude-3-opus

• anthropic/claude-3-sonnet

• openai/gpt-4o

Вы можете указать пользовательские модели, установив переменную среды OPENROUTER_DEFAULT_MODEL или передав параметр model непосредственно в функцию image_analysis .

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

Тестирование с помощью MCP Inspector

Самый простой способ протестировать MCP OpenVision — использовать инструмент MCP Inspector:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Интеграция с Claude Desktop или Cursor

1. Отредактируйте файл конфигурации MCP:

   • Windows: %USERPROFILE%\.cursor\mcp.json

   • macOS: ~/.cursor/mcp.json или ~/Library/Application Support/Claude/claude_desktop_config.json

2. Добавьте следующую конфигурацию:

{
  "mcpServers": {
    "openvision": {
      "command": "uvx",
      "args": ["mcp-openvision"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

Локальный запуск для разработки

# Set the required API key
export OPENROUTER_API_KEY="your_api_key"

# Run the server module directly
python -m mcp_openvision

Функции

MCP OpenVision предоставляет следующий основной инструмент:

• image_analysis : Анализ изображений с помощью моделей зрения, поддерживающих различные параметры:

  • image : Может быть предоставлено как:

    • Данные изображения, закодированные в Base64

    • URL-адрес изображения (http/https)

    • Локальный путь к файлу

  • query : Инструкция пользователя для задачи анализа изображения

  • system_prompt : Инструкции, определяющие роль и поведение модели (необязательно)

  • model : модель видения для использования

  • temperature : контролирует случайность (0,0-1,0)

  • max_tokens : Максимальная длина ответа

Создание эффективных запросов

Параметр query имеет решающее значение для получения полезных результатов анализа изображения. Хорошо составленный запрос предоставляет контекст о:

1. Цель : Почему вы анализируете это изображение

2. Области внимания : Конкретные элементы или детали, на которые следует обратить внимание.

3. Требуемая информация : тип информации, которую вам необходимо извлечь.

4. Настройки формата : как вы хотите структурировать результаты

Примеры эффективных запросов

Предоставляя контекст относительно того, зачем вам нужен анализ и какую конкретную информацию вы ищете, вы помогаете модели сосредоточиться на важных деталях и вырабатывать более ценную информацию.

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

# Analyze an image from a URL
result = await image_analysis(
    image="https://example.com/image.jpg",
    query="Describe this image in detail"
)

# Analyze an image from a local file with a focused query
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Identify all traffic signs in this street scene and explain their meanings for a driver education course"
)

# Analyze with a base64-encoded image and a specific analytical purpose
result = await image_analysis(
    image="SGVsbG8gV29ybGQ=...",  # base64 data
    query="Examine this product packaging design and highlight elements that could be improved for better visibility and brand recognition"
)

# Customize the system prompt for specialized analysis
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Analyze the composition and artistic techniques used in this painting, focusing on how they create emotional impact",
    system_prompt="You are an expert art historian with deep knowledge of painting techniques and art movements. Focus on formal analysis of composition, color, brushwork, and stylistic elements."
)

Типы входных изображений

Инструмент image_analysis принимает несколько типов входных изображений:

1. Строки в кодировке Base64

2. URL-адреса изображений должны начинаться с http:// или https://

3. Пути к файлам :

   • Абсолютные пути : полные пути, начинающиеся с / (Unix) или буквы диска (Windows)

   • Относительные пути : пути относительно текущего рабочего каталога.

   • Относительные пути с project_root : используйте параметр project_root для указания базового каталога.

Использование относительных путей

При использовании относительных путей к файлам (например, «examples/image.jpg») у вас есть два варианта:

1. Путь должен быть относительным к текущему рабочему каталогу, в котором запущен сервер.

2. Или вы можете указать параметр project_root :

# Example with relative path and project_root
result = await image_analysis(
    image="examples/image.jpg",
    project_root="/path/to/your/project",
    query="What is in this image?"
)

Это особенно полезно в приложениях, где текущий рабочий каталог может быть непредсказуемым или когда вы хотите ссылаться на файлы, используя пути относительно определенного каталога.

Разработка

Настройка среды разработки

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-openvision.git
cd mcp-openvision

# Install development dependencies
pip install -e ".[dev]"

Форматирование кода

Этот проект использует Black для автоматического форматирования кода. Форматирование осуществляется через GitHub Actions:

• Весь код, отправленный в репозиторий, автоматически форматируется черным цветом.

• Для запросов на извлечение от участников репозитория Блэк форматирует код и фиксирует его непосредственно в ветке PR.

• Для запросов на извлечение из форков Блэк создает новый PR с отформатированным кодом, который можно объединить с исходным PR.

Вы также можете запустить Black локально, чтобы отформатировать свой код перед фиксацией:

# Format all Python code in the src and tests directories
black src tests

Проведение тестов

pytest

Процесс выпуска

В этом проекте используется автоматизированный процесс выпуска:

1. Обновите версию в pyproject.toml , следуя принципам семантического версионирования.

   • Вы можете использовать вспомогательный скрипт: python scripts/bump_version.py [major|minor|patch]

2. Обновите CHANGELOG.md подробностями о новой версии.

   • Скрипт также создает шаблонную запись в CHANGELOG.md, которую вы можете заполнить.

3. Зафиксируйте и отправьте эти изменения в main ветку.

4. Рабочий процесс GitHub Actions будет:

   • Обнаружить изменение версии

   • Автоматически создавать новый релиз GitHub

   • Запустите рабочий процесс публикации, который будет публиковаться в PyPI

Такая автоматизация помогает поддерживать согласованный процесс выпуска и гарантирует, что каждый выпуск имеет надлежащую версию и документируется.

Поддерживать

Если вы считаете этот проект полезным, рассмотрите возможность угостить меня кофе, чтобы поддержать текущую разработку и поддержку.

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .