MODEL CONTEXT PROTOCOL (MCP) · MEDIA RETRIEVAL

imageHub-MCP

Equipa assistentes e agentes autônomos de IA com acesso programático nativo a milhões de imagens, ilustrações vetoriais e fotos de alta resolução.

Protocolo

MCP Specification 2024-11

Linguagem

TypeScript / Node.js

Ferramentas

27 Tools Especializadas

Transporte

stdio (JSON-RPC 2.0)

TL;DR Executivo — Resumo da Engenharia

O imageHub-MCP é um servidor oficial do ecossistema Model Context Protocol (MCP) criado por Alex Santos. Ele expõe um arsenal de 27 ferramentas granulares que permitem a agentes de IA (como Claude Desktop, Cursor, Cline e Antigravity) pesquisar imagens com filtros complexos (cores hexadecimais, proporção de aspecto, categorias editoriais), baixar mídias em múltiplas resoluções, gerenciar coleções de favoritos e exportar moodboards estruturados em Markdown.

DIAGRAMA & WORKFLOW

Arquitetura de Fluxo do Sistema

Visão macro de como o projeto processa requisições, gerencia dados e entrega valor técnico com máxima eficiência.

Fluxo Lógico & Pipeline de Execução

+------------------------+        +---------------------------+        +----------------------+
| Agente de IA (Claude / |  stdio |       imageHub-MCP        |  REST  |     Pixabay API      |
| Cursor / Antigravity)  | <====> | (JSON-RPC 2.0 / 27 Tools) | <====> | (Milhões de Imagens) |
+------------------------+        +---------------------------+        +----------------------+
                                                |
                                                v
                                  +---------------------------+
                                  | Storage Local / Downloads |
                                  |  (Streaming Resiliente)   |
                                  +---------------------------+

ENGENHARIA DETALHADA

Os Pilares Técnicos Fundamentais

Decisões de design, algoritmos e técnicas aplicadas para garantir confiabilidade, segurança e excelência operacional.

Arquitetura MCP Estrita com 27 Ferramentas Granulares

Ferramentas com schemas tipados via Zod para execução sem alucinações

Em vez de uma ferramenta genérica de busca, o servidor implementa métodos específicos: `search_images`, `search_by_color`, `search_similar`, `get_image_details`, `download_image`, `download_to_multiple_sizes`, `create_moodboard` e `export_favorites`. Cada ferramenta possui schemas Zod estritos com validações de limites, prevenindo chamadas inválidas pelos LLMs.

Filtragem Cromática e Taxonomia Multidimensional

Busca precisa por paletas de cores, orientações e categorias editoriais

Permite que o agente encontre ativos com harmonia visual específica para interfaces web ou campanhas de marketing, suportando parâmetros como `colors` (grayscale, transparent, red, blue...), `orientation` (horizontal, vertical), `image_type` (photo, illustration, vector) e classificação etária segura (safesearch).

Streaming Assíncrono de Download em Alta Resolução

Transferência de arquivos em chunks sem sobrecarga de heap

Para suportar imagens 4K e vetores de grande porte, as ferramentas de download utilizam streams assíncronos do Node.js (`stream/promises`), gravando os bytes diretamente no disco do usuário sem manter o arquivo inteiro no buffer de memória, evitando estouro de limite de memória no processo stdio.

Coleções e Moodboards com Exportação Estruturada

Organização de referências visuais com saída direta em Markdown e JSON

O servidor mantém gerenciamento de estado leve para moodboards locais. O agente pode salvar candidatos a logo ou hero image, listar favoritos e gerar relatórios completos com links de atribuição legal e metadados de licenciamento royalty-free.

IMPLEMENTAÇÃO EM CÓDIGO

Código em Prática

Exemplo concreto de uso, configuração e integração técnica.

mcpServers.json — Configuração no Claude Desktop ou Antigravity JSON

{
  "mcpServers": {
    "imagehub": {
      "command": "node",
      "args": ["C:/code/imageHub-MCP/dist/index.js"],
      "env": {
        "PIXABAY_API_KEY": "sua_chave_pixabay_aqui"
      }
    }
  }
}

DÚVIDAS & DECISÕES

Perguntas Frequentes & Respostas Técnicas

Esclarecimentos detalhados sobre funcionamento, licenças, compatibilidade e privacidade.

Como o imageHub-MCP é instalado nos clientes MCP?

Basta compilar o repositório TypeScript (`npm run build`) e registrar o executável no arquivo `mcpServers.json` do seu cliente compatível (Claude Desktop, Cursor, Antigravity).

As imagens baixadas podem ser usadas comercialmente?

Sim. Todas as imagens obtidas via Pixabay API possuem a licença padrão Pixabay Content License, livre de royalties para uso pessoal e comercial sem necessidade obrigatória de atribuição.

O servidor exige conexão constante com a internet?

Para buscas e downloads novos, sim. No entanto, o gerenciamento de moodboards, favoritos e histórico local opera inteiramente offline no disco do usuário.

Quantas requisições por minuto são suportadas?

O imageHub-MCP respeita nativamente os limites da API do Pixabay (100 requisições/minuto), com enfileiramento automático para evitar erros 429.