Moondream

Um modelo de linguagem visual para análise de imagens, incluindo legendagem, VQA e detecção de objetos.

GitHub
47
Experimente este MCPPatrocinado

Documentação

Servidor MCP Moondream

Um servidor FastMCP para Moondream, um modelo de linguagem de visão por IA. Este servidor fornece capacidades de análise de imagens, incluindo legendagem, resposta a perguntas visuais, detecção de objetos e apontamento visual através do Model Context Protocol (MCP).

Recursos

  • 🖼️ Legendagem de Imagens: Gere legendas curtas, normais ou detalhadas para imagens
  • ❓ Resposta a Perguntas Visuais: Faça perguntas em linguagem natural sobre imagens
  • 🔍 Detecção de Objetos: Detecte e localize objetos específicos com caixas delimitadoras
  • 📍 Apontamento Visual: Obtenha coordenadas precisas de objetos em imagens
  • 🔗 Suporte a URL: Processe imagens de arquivos locais e URLs remotas
  • ⚡ Processamento em Lote: Analise várias imagens de forma eficiente
  • 🚀 Otimização de Dispositivo: Detecção e otimização automáticas para CPU, CUDA e MPS (Apple Silicon)

Instalação

Pré-requisitos

  • Python 3.10 ou superior
  • PyTorch 2.0+ (com suporte adequado ao dispositivo)

Usando uvx (Recomendado para Claude Desktop)

# Run without installation
uvx moondream-mcp

# Or specify a specific version
uvx moondream-mcp==1.0.2

Instalar a partir do PyPI

pip install moondream-mcp

Instalar a partir do Código Fonte

git clone https://github.com/ColeMurray/moondream-mcp.git
cd moondream-mcp
pip install -e .

Instalação para Desenvolvimento

git clone https://github.com/ColeMurray/moondream-mcp.git
cd moondream-mcp
pip install -e ".[dev]"

Início Rápido

Executando o Servidor

# Using uvx (no installation needed)
uvx moondream-mcp

# Using pip-installed command
moondream-mcp

# Or run directly with Python
python -m moondream_mcp.server

Integração com Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Usando uvx (Recomendado)

{
  "mcpServers": {
    "moondream": {
      "command": "uvx",
      "args": ["moondream-mcp"],
      "env": {
        "MOONDREAM_DEVICE": "auto"
      }
    }
  }
}

Usando comando instalado via pip

{
  "mcpServers": {
    "moondream": {
      "command": "moondream-mcp",
      "env": {
        "MOONDREAM_DEVICE": "auto"
      }
    }
  }
}

Configuração

O servidor pode ser configurado usando variáveis de ambiente:

Configurações do Modelo

  • MOONDREAM_MODEL_NAME: Nome do modelo (padrão: vikhyatk/moondream2)
  • MOONDREAM_MODEL_REVISION: Revisão do modelo (padrão: 2025-01-09)
  • MOONDREAM_TRUST_REMOTE_CODE: Confiar em código remoto (padrão: true)

Configurações do Dispositivo

  • MOONDREAM_DEVICE: Forçar dispositivo específico (cpu, cuda, mps ou auto)

Processamento de Imagens

  • MOONDREAM_MAX_IMAGE_SIZE: Dimensões máximas da imagem (padrão: 2048x2048)
  • MOONDREAM_MAX_FILE_SIZE_MB: Tamanho máximo do arquivo em MB (padrão: 50)

Desempenho

  • MOONDREAM_TIMEOUT_SECONDS: Tempo limite de processamento (padrão: 120)
  • MOONDREAM_MAX_CONCURRENT_REQUESTS: Máximo de solicitações simultâneas (padrão: 5)
  • MOONDREAM_ENABLE_STREAMING: Habilitar streaming para legendas (padrão: true)
  • MOONDREAM_MAX_BATCH_SIZE: Tamanho máximo do lote para operações em lote (padrão: 10)
  • MOONDREAM_BATCH_CONCURRENCY: Limite de processamento em lote simultâneo (padrão: 3)
  • MOONDREAM_ENABLE_BATCH_PROGRESS: Habilitar relatório de progresso para operações em lote (padrão: true)

Rede (para URLs)

  • MOONDREAM_REQUEST_TIMEOUT_SECONDS: Tempo limite de solicitação HTTP (padrão: 30)
  • MOONDREAM_MAX_REDIRECTS: Máximo de redirecionamentos HTTP (padrão: 5)
  • MOONDREAM_USER_AGENT: Cabeçalho HTTP User-Agent

Ferramentas Disponíveis

1. caption_image

Gere legendas para imagens.

Parâmetros:

  • image_path (string): Caminho para arquivo de imagem ou URL
  • length (string): Comprimento da legenda - "short", "normal" ou "detailed"
  • stream (boolean): Se deve transmitir a geração de legendas

Exemplo:

{
  "image_path": "https://example.com/image.jpg",
  "length": "detailed",
  "stream": false
}

2. query_image

Faça perguntas sobre imagens.

Parâmetros:

  • image_path (string): Caminho para arquivo de imagem ou URL
  • question (string): Pergunta a fazer sobre a imagem

Exemplo:

{
  "image_path": "/path/to/image.jpg",
  "question": "How many people are in this image?"
}

3. detect_objects

Detecte objetos específicos em imagens.

Parâmetros:

  • image_path (string): Caminho para arquivo de imagem ou URL
  • object_name (string): Nome do objeto a detectar

Exemplo:

{
  "image_path": "https://example.com/photo.jpg",
  "object_name": "person"
}

4. point_objects

Obtenha coordenadas de objetos em imagens.

Parâmetros:

  • image_path (string): Caminho para arquivo de imagem ou URL
  • object_name (string): Nome do objeto a localizar

Exemplo:

{
  "image_path": "/path/to/image.jpg",
  "object_name": "car"
}

5. analyze_image

Ferramenta de análise de imagens multiuso.

Parâmetros:

  • image_path (string): Caminho para arquivo de imagem ou URL
  • operation (string): Tipo de operação ("caption", "query", "detect", "point")
  • parameters (string): String JSON com parâmetros específicos da operação

Exemplo:

{
  "image_path": "https://example.com/image.jpg",
  "operation": "query",
  "parameters": "{\"question\": \"What is the weather like?\"}"
}

6. batch_analyze_images

Processe várias imagens em lote.

Parâmetros:

  • image_paths (string): Matriz JSON de caminhos de imagens
  • operation (string): Operação a ser executada em todas as imagens
  • parameters (string): String JSON com parâmetros específicos da operação

Exemplo:

{
  "image_paths": "[\"image1.jpg\", \"image2.jpg\"]",
  "operation": "caption",
  "parameters": "{\"length\": \"short\"}"
}

Exemplos de Uso

Legendagem Básica de Imagens

# Using the caption_image tool
result = await caption_image(
    image_path="https://example.com/sunset.jpg",
    length="detailed"
)

Resposta a Perguntas Visuais

# Ask about image content
result = await query_image(
    image_path="/path/to/family_photo.jpg",
    question="How many children are in this photo?"
)

Detecção de Objetos

# Detect faces in an image
result = await detect_objects(
    image_path="https://example.com/group_photo.jpg",
    object_name="face"
)

Processamento em Lote

# Process multiple images
result = await batch_analyze_images(
    image_paths='["img1.jpg", "img2.jpg", "img3.jpg"]',
    operation="caption",
    parameters='{"length": "normal"}'
)

Suporte a Dispositivos

O servidor detecta e otimiza automaticamente para o hardware disponível:

Apple Silicon (MPS)

  • Desempenho ideal em Macs M1/M2/M3
  • Gerenciamento automático de memória
  • Aceleração nativa

NVIDIA CUDA

  • Aceleração de GPU para placas NVIDIA
  • Gerenciamento automático de memória CUDA
  • Suporte a precisão mista

Fallback de CPU

  • Funciona em qualquer sistema
  • Otimizado para processamento multi-core
  • Menores requisitos de memória

Tratamento de Erros

O servidor fornece informações detalhadas de erro:

{
  "success": false,
  "error_message": "Image file not found: /path/to/missing.jpg",
  "error_code": "IMAGE_PROCESSING_ERROR",
  "processing_time_ms": 15.2
}

Códigos de erro comuns:

  • MODEL_LOAD_ERROR: Problemas ao carregar o modelo Moondream
  • IMAGE_PROCESSING_ERROR: Problemas com arquivos de imagem ou URLs
  • INFERENCE_ERROR: Falhas na inferência do modelo
  • INVALID_REQUEST: Parâmetros ou solicitações inválidos

Dicas de Desempenho

  1. Use tamanhos de imagem adequados: Redimensione imagens grandes antes do processamento
  2. Processamento em lote: Use batch_analyze_images para várias imagens
  3. Otimização de dispositivo: Deixe o servidor detectar automaticamente o melhor dispositivo
  4. Solicitações simultâneas: Ajuste MOONDREAM_MAX_CONCURRENT_REQUESTS com base no seu hardware
  5. Gerenciamento de memória: Monitore o uso de memória, especialmente com imagens grandes

Solução de Problemas

Problemas de Carregamento do Modelo

# Check PyTorch installation
python -c "import torch; print(torch.__version__)"

# Check device availability
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}, MPS: {torch.backends.mps.is_available()}')"

Problemas de Memória

  • Reduza MOONDREAM_MAX_IMAGE_SIZE
  • Diminua MOONDREAM_MAX_CONCURRENT_REQUESTS
  • Use CPU em vez de GPU para imagens grandes

Problemas de Rede

  • Verifique as configurações do firewall para acesso a URLs
  • Aumente MOONDREAM_REQUEST_TIMEOUT_SECONDS
  • Verifique os certificados SSL para URLs HTTPS

Desenvolvimento

Executando Testes

pytest tests/

Qualidade do Código

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Type checking
mypy src/

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Adicione testes
  5. Execute verificações de qualidade
  6. Envie um pull request

Licença

Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para obter detalhes.

Agradecimentos

Suporte

Nota: Este servidor requer o download do modelo Moondream no primeiro uso, o que pode levar algum tempo dependendo da sua conexão com a internet.