MCP OpenVision

Análisis de imágenes utilizando los modelos de visión de OpenRouter.

GitHub
16
Prueba este MCPPatrocinado

Documentación

MCP OpenVision

CI PyPI version Python Versions License: MIT Buy Me A Coffee smithery badge

Resumen

MCP OpenVision es un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades de análisis de imágenes impulsadas por los modelos de visión de OpenRouter. Permite a los asistentes de IA analizar imágenes a través de una interfaz simple dentro del ecosistema MCP.

Instalación

Instalación mediante Smithery

Para instalar mcp-openvision para Claude Desktop automáticamente mediante Smithery:

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

Usando pip

pip install mcp-openvision

Usando UV (recomendado)

uv pip install mcp-openvision

Configuración

MCP OpenVision requiere una clave de API de OpenRouter y se puede configurar mediante variables de entorno:

  • OPENROUTER_API_KEY (obligatorio): Tu clave de 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 que admita capacidades de visión. El modelo predeterminado es qwen/qwen2.5-vl-32b-instruct:free, pero puedes 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

Puedes 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 fácil de probar MCP OpenVision es con la herramienta MCP Inspector:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Integración con Claude Desktop o Cursor

  1. Edita tu archivo de configuración de MCP:

    • Windows: %USERPROFILE%\.cursor\mcp.json
    • macOS: ~/.cursor/mcp.json o ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Añade 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"
      }
    }
  }
}

Ejecución Local para 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 imagen (http/https)
      • Ruta de archivo local
    • query: Instrucción del usuario para la tarea de análisis de imagen
    • system_prompt: Instrucciones que definen el rol y 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 Efectivas

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

  1. Propósito: Por qué estás analizando esta imagen
  2. Áreas de enfoque: Elementos o detalles específicos a los que prestar atención
  3. Información requerida: El tipo de información que necesitas extraer
  4. Preferencias de formato: Cómo quieres que se estructuren los resultados

Ejemplos de Consultas Efectivas

Consulta BásicaConsulta Mejorada
"Describe esta imagen""Identifica todos los productos minoristas visibles en esta imagen de estante de tienda y estima su rango de precios"
"¿Qué hay en esta imagen?""Analiza esta exploración médica en busca de anomalías, centrándote en el área resaltada y proporcionando posibles diagnósticos"
"Analiza este gráfico""Extrae los datos numéricos de este gráfico de barras que muestra ventas trimestrales e identifica las tendencias clave de 2022-2023"
"Lee el texto""Transcribe todo el texto visible en este menú de restaurante, conservando los nombres de los platos, descripciones y precios"

Al proporcionar contexto sobre por qué necesitas el análisis y qué información específica buscas, ayudas al modelo a centrarse en 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 Imagen

La herramienta image_analysis acepta varios tipos de entradas de imagen:

  1. Cadenas codificadas en Base64
  2. URLs de imagen - deben comenzar con http:// o https://
  3. 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: usa el parámetro project_root para especificar un directorio base

Uso de Rutas Relativas

Al usar rutas de archivo relativas (como "examples/image.jpg"), tienes dos opciones:

  1. La ruta debe ser relativa al directorio de trabajo actual donde se ejecuta el servidor
  2. O puedes 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 deseas hacer referencia a archivos usando rutas relativas a un directorio específico.

Desarrollo

Configuración del 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 usa Black para el formato automático de código. El formato se aplica mediante GitHub Actions:

  • Todo el código enviado al repositorio se formatea automáticamente con Black
  • Para solicitudes de extracción de colaboradores del repositorio, Black formatea el código y realiza commits directamente en la rama del PR
  • Para solicitudes de extracción de bifurcaciones (forks), Black crea un nuevo PR con el código formateado que se puede fusionar en el PR original

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

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

Ejecutar Pruebas

pytest

Proceso de Publicación

Este proyecto utiliza un proceso de publicación automatizado:

  1. Actualiza la versión en pyproject.toml siguiendo los principios de Versionado Semántico
    • Puedes usar el script auxiliar: python scripts/bump_version.py [major|minor|patch]
  2. Actualiza CHANGELOG.md con detalles sobre la nueva versión
    • El script también crea una entrada de plantilla en CHANGELOG.md que puedes completar
  3. Haz commit y envía estos cambios a la rama main
  4. El flujo de trabajo de GitHub Actions:
    • Detectará el cambio de versión
    • Creará automáticamente una nueva versión de GitHub
    • Activarás el flujo de trabajo de publicación que publica en PyPI

Esta automatización ayuda a mantener un proceso de publicación consistente y asegura que cada versión esté correctamente versionada y documentada.

Soporte

Si encuentras útil este proyecto, considera invitarme a un café para apoyar el desarrollo y mantenimiento continuo.

Buy Me A Coffee

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.