MCP OpenVision

Análise de imagens usando os modelos de visão do OpenRouter.

GitHub
16
Experimente este MCPPatrocinado

Documentação

MCP OpenVision

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

Visão Geral

O MCP OpenVision é um servidor Model Context Protocol (MCP) que fornece capacidades de análise de imagens alimentadas por modelos de visão da OpenRouter. Ele permite que assistentes de IA analisem imagens por meio de uma interface simples dentro do ecossistema MCP.

Instalação

Instalando via Smithery

Para instalar o mcp-openvision para Claude Desktop automaticamente via 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

Configuração

O MCP OpenVision requer uma chave de API da OpenRouter e pode ser configurado por meio de variáveis de ambiente:

  • OPENROUTER_API_KEY (obrigatório): Sua chave de API da OpenRouter
  • OPENROUTER_DEFAULT_MODEL (opcional): O modelo de visão a ser usado

Modelos de Visão da OpenRouter

O MCP OpenVision funciona com qualquer modelo da OpenRouter que suporte capacidades de visão. O modelo padrão é qwen/qwen2.5-vl-32b-instruct:free, mas você pode especificar qualquer outro modelo compatível.

Alguns modelos de visão populares disponíveis por meio da OpenRouter incluem:

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

Você pode especificar modelos personalizados definindo a variável de ambiente OPENROUTER_DEFAULT_MODEL ou passando o parâmetro model diretamente para a função image_analysis.

Uso

Testando com o MCP Inspector

A maneira mais fácil de testar o MCP OpenVision é com a ferramenta MCP Inspector:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Integração com Claude Desktop ou Cursor

  1. Edite seu arquivo de configuração do MCP:

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

  2. Adicione a seguinte configuração:

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

Executando Localmente para Desenvolvimento

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

# Run the server module directly
python -m mcp_openvision

Recursos

O MCP OpenVision fornece a seguinte ferramenta principal:

  • image_analysis: Analisa imagens com modelos de visão, suportando vários parâmetros:
    • image: Pode ser fornecido como:
      • Dados de imagem codificados em Base64
      • URL da imagem (http/https)
      • Caminho de arquivo local
    • query: Instrução do usuário para a tarefa de análise de imagem
    • system_prompt: Instruções que definem o papel e o comportamento do modelo (opcional)
    • model: Modelo de visão a ser usado
    • temperature: Controla a aleatoriedade (0.0-1.0)
    • max_tokens: Comprimento máximo da resposta

Elaborando Consultas Eficazes

O parâmetro query é crucial para obter resultados úteis da análise de imagem. Uma consulta bem elaborada fornece contexto sobre:

  1. Propósito: Por que você está analisando esta imagem
  2. Áreas de foco: Elementos ou detalhes específicos aos quais prestar atenção
  3. Informações necessárias: O tipo de informação que você precisa extrair
  4. Preferências de formato: Como você deseja que os resultados sejam estruturados

Exemplos de Consultas Eficazes

Consulta BásicaConsulta Aprimorada
"Descreva esta imagem""Identifique todos os produtos de varejo visíveis nesta imagem de prateleira de loja e estime sua faixa de preço"
"O que há nesta imagem?""Analise este exame médico em busca de anormalidades, focando na área destacada e fornecendo possíveis diagnósticos"
"Analise este gráfico""Extraia os dados numéricos deste gráfico de barras que mostra vendas trimestrais e identifique as principais tendências de 2022-2023"
"Leia o texto""Transcreva todo o texto visível neste cardápio de restaurante, preservando os nomes dos itens, descrições e preços"

Ao fornecer contexto sobre por que você precisa da análise e quais informações específicas você está buscando, você ajuda o modelo a focar em detalhes relevantes e produzir insights mais valiosos.

Exemplo 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 Imagem

A ferramenta image_analysis aceita vários tipos de entradas de imagem:

  1. Strings codificadas em Base64
  2. URLs de imagem - devem começar com http:// ou https://
  3. Caminhos de arquivo:
    • Caminhos absolutos: caminhos completos começando com / (Unix) ou letra de unidade (Windows)
    • Caminhos relativos: caminhos relativos ao diretório de trabalho atual
    • Caminhos relativos com project_root: use o parâmetro project_root para especificar um diretório base

Usando Caminhos Relativos

Ao usar caminhos de arquivo relativos (como "examples/image.jpg"), você tem duas opções:

  1. O caminho deve ser relativo ao diretório de trabalho atual onde o servidor está em execução
  2. Ou você pode especificar um 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?"
)

Isso é particularmente útil em aplicações onde o diretório de trabalho atual pode não ser previsível ou quando você deseja referenciar arquivos usando caminhos relativos a um diretório específico.

Desenvolvimento

Configurando o Ambiente de Desenvolvimento

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

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

Formatação de Código

Este projeto usa Black para formatação automática de código. A formatação é aplicada por meio do GitHub Actions:

  • Todo o código enviado ao repositório é formatado automaticamente com Black
  • Para pull requests de colaboradores do repositório, o Black formata o código e faz commit diretamente no branch do PR
  • Para pull requests de forks, o Black cria um novo PR com o código formatado que pode ser mesclado no PR original

Você também pode executar o Black localmente para formatar seu código antes de fazer commit:

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

Executar Testes

pytest

Processo de Lançamento

Este projeto usa um processo de lançamento automatizado:

  1. Atualize a versão em pyproject.toml seguindo os princípios de Semantic Versioning
    • Você pode usar o script auxiliar: python scripts/bump_version.py [major|minor|patch]
  2. Atualize o CHANGELOG.md com detalhes sobre a nova versão
    • O script também cria uma entrada de modelo no CHANGELOG.md que você pode preencher
  3. Faça commit e envie essas alterações para o branch main
  4. O fluxo de trabalho do GitHub Actions irá:
    • Detectar a mudança de versão
    • Criar automaticamente um novo release do GitHub
    • Acionar o fluxo de trabalho de publicação que publica no PyPI

Essa automação ajuda a manter um processo de lançamento consistente e garante que cada release seja devidamente versionado e documentado.

Suporte

Se você achar este projeto útil, considere me pagar um café para apoiar o desenvolvimento e a manutenção contínuos.

Buy Me A Coffee

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.