MCP OpenVision

Descripción general

MCP OpenVision es un servidor de Protocolo de Contexto de Modelo (MCP) que ofrece funciones de análisis de imágenes basadas en modelos de visión de OpenRouter. Permite a los asistentes de IA analizar imágenes mediante una interfaz sencilla dentro del ecosistema MCP.

Instalación

Instalación mediante herrería

Para instalar mcp-openvision para Claude Desktop automáticamente a través de Smithery :

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

Usando pip

pip install mcp-openvision

Uso de UV (recomendado)

uv pip install mcp-openvision

Configuración

MCP OpenVision requiere una clave API de OpenRouter y se puede configurar a través de variables de entorno:

OPENROUTER_API_KEY (obligatorio): Su clave API de OpenRouter
OPENROUTER_DEFAULT_MODEL (opcional): El modelo de visión a utilizar

Modelos de visión de OpenRouter

MCP OpenVision funciona con cualquier modelo de OpenRouter compatible con funciones de visión. El modelo predeterminado es qwen/qwen2.5-vl-32b-instruct:free , pero puede especificar cualquier otro modelo compatible.

Algunos modelos de visión populares disponibles a través de OpenRouter incluyen:

qwen/qwen2.5-vl-32b-instruct:free (predeterminado)
anthropic/claude-3-5-sonnet
anthropic/claude-3-opus
anthropic/claude-3-sonnet
openai/gpt-4o

Puede especificar modelos personalizados configurando la variable de entorno OPENROUTER_DEFAULT_MODEL o pasando el parámetro model directamente a la función image_analysis .

Uso

Pruebas con MCP Inspector

La forma más sencilla de probar MCP OpenVision es con la herramienta MCP Inspector:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Integración con Claude Desktop o Cursor

Edite su archivo de configuración MCP:
- Windows: %USERPROFILE%\.cursor\mcp.json
- macOS: ~/.cursor/mcp.json o ~/Library/Application Support/Claude/claude_desktop_config.json
Agregue la siguiente configuración:

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

Corriendo localmente por el desarrollo

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

# Run the server module directly
python -m mcp_openvision

Características

MCP OpenVision proporciona la siguiente herramienta principal:

image_analysis : Analiza imágenes con modelos de visión, admitiendo varios parámetros:
- image : Se puede proporcionar como:
  - Datos de imagen codificados en Base64
  - URL de la imagen (http/https)
  - Ruta de archivo local
- query : Instrucciones de usuario para la tarea de análisis de imágenes
- system_prompt : Instrucciones que definen el rol y el comportamiento del modelo (opcional)
- model : Modelo de visión a utilizar
- temperature : controla la aleatoriedad (0,0-1,0)
- max_tokens : Longitud máxima de respuesta

Elaboración de consultas eficaces

El parámetro query es crucial para obtener resultados útiles del análisis de imágenes. Una consulta bien elaborada proporciona contexto sobre:

Propósito : ¿Por qué estás analizando esta imagen?
Áreas de enfoque : Elementos o detalles específicos a los que prestar atención
Información requerida : El tipo de información que necesita extraer
Preferencias de formato : cómo desea que se estructuren los resultados

Ejemplos de consultas efectivas

Consulta básica	Consulta mejorada
"Describe esta imagen"	Identifica todos los productos minoristas visibles en la imagen del estante de esta tienda y calcula su rango de precios.
"¿Qué hay en esta imagen?"	Analice esta exploración médica en busca de anomalías, centrándose en el área resaltada y brindando posibles diagnósticos.
"Analiza este gráfico"	Extraiga los datos numéricos de este gráfico de barras que muestra las ventas trimestrales e identifique las tendencias clave de 2022 a 2023.
"Lea el texto"	Transcriba todo el texto visible del menú de este restaurante, conservando los nombres de los platos, las descripciones y los precios.

Al proporcionar contexto sobre por qué necesita el análisis y qué información específica está buscando, ayuda al modelo a centrarse en los detalles relevantes y producir información más valiosa.

Ejemplo de uso

# 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."
)

Tipos de entrada de imágenes

La herramienta image_analysis acepta varios tipos de entradas de imágenes:

Cadenas codificadas en Base64
URL de imágenes : deben comenzar con http:// o https://
Rutas de archivo :
- Rutas absolutas : rutas completas que comienzan con / (Unix) o letra de unidad (Windows)
- Rutas relativas : rutas relativas al directorio de trabajo actual
- Rutas relativas con project_root : use el parámetro project_root para especificar un directorio base

Uso de rutas relativas

Al utilizar rutas de archivos relativas (como "ejemplos/imagen.jpg"), tiene dos opciones:

La ruta debe ser relativa al directorio de trabajo actual donde se ejecuta el servidor.
O bien, puede especificar un parámetro 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?"
)

Esto es particularmente útil en aplicaciones donde el directorio de trabajo actual puede no ser predecible o cuando desea hacer referencia a archivos utilizando rutas relativas a un directorio específico.

Desarrollo

Configurar el entorno de desarrollo

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

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

Formato de código

Este proyecto utiliza Black para el formato automático del código. El formato se aplica mediante GitHub Actions:

Todo el código enviado al repositorio se formatea automáticamente con Black
Para las solicitudes de extracción de los colaboradores del repositorio, Black formatea el código y lo confirma directamente en la rama de extracción.
Para las solicitudes de extracción de bifurcaciones, Black crea una nueva PR con el código formateado que se puede fusionar con la PR original.

También puedes ejecutar Black localmente para formatear tu código antes de confirmar:

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

Ejecutar pruebas

pytest

Proceso de liberación

Este proyecto utiliza un proceso de lanzamiento automatizado:

Actualice la versión en pyproject.toml siguiendo los principios de control de versiones semántico
- Puede utilizar el script auxiliar: python scripts/bump_version.py [major|minor|patch]
Actualice el CHANGELOG.md con detalles sobre la nueva versión
- El script también crea una entrada de plantilla en CHANGELOG.md que puedes completar.
Confirme y envíe estos cambios a la rama main
El flujo de trabajo de GitHub Actions hará lo siguiente:
- Detectar el cambio de versión
- Crear automáticamente una nueva versión de GitHub
- Activar el flujo de trabajo de publicación que publica en PyPI

Esta automatización ayuda a mantener un proceso de lanzamiento consistente y garantiza que cada lanzamiento esté versionado y documentado correctamente.

Apoyo

Si este proyecto te resulta útil, considera comprarme un café para apoyar el desarrollo y mantenimiento continuos.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

mcp-openvision

Integrations