Wikimedia Image Search

Servidor MCP de Busca de Imagens Wikimedia

Este servidor MCP (Model Context Protocol) permite que assistentes de IA pesquisem imagens no Wikimedia Commons. Ele fornece metadados detalhados e composições opcionais de miniaturas para ajudar modelos de IA a comparar visualmente os resultados.

Visão Geral

Este servidor foi projetado para dar "olhos" aos assistentes de IA ao pesquisar conteúdo visual. Em vez de adivinhar com base apenas em nomes de arquivos ou descrições de texto, a IA pode recuperar uma lista estruturada de metadados de imagens e uma imagem composta contendo miniaturas dos resultados da pesquisa.

Esse recurso é particularmente útil quando um assistente de IA precisa:

• Encontrar imagens adequadas para criar sites, artigos ou apresentações.
• Selecionar imagens para materiais educacionais ou livros.
• Verificar o conteúdo visual de uma imagem antes de recomendá-la.
• Comparar várias imagens para escolher a mais relevante para um contexto específico.

Ao fornecer tanto metadados (licença, autor, descrição, dimensões) quanto uma prévia visual, a IA pode tomar decisões informadas sobre quais imagens usar ou baixar.

Configuração

Pré-requisitos

• Node.js: Versão 18 ou superior.
• Cliente MCP: Um cliente compatível, como VS Code, Cursor, Claude Code, Windsurf, Cline, Claude Desktop...

Instalação

Para usar este servidor, configure seu cliente MCP para executá-lo usando npx.

{
  "mcpServers": {
    "wikimedia-image-search": {
      "command": "npx",
      "args": [
        "-y",
        "wikimedia-image-search-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "wikimedia-image-search": {
      "command": "npx",
      "args": [
        "-y",
        "wikimedia-image-search-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "wikimedia-image-search": {
      "command": "npx",
      "args": [
        "-y",
        "wikimedia-image-search-mcp"
      ]
    }
  }
}

claude mcp add wikimedia-image-search -- npx -y wikimedia-image-search-mcp

Uso da Ferramenta

Este servidor expõe uma única ferramenta: wikimedia_search_images.

Esquema da Ferramenta

A ferramenta aceita os seguintes parâmetros:

• query (string, obrigatório): Os termos de pesquisa (ex.: "pôr do sol no oceano", "torre eiffel").
• limit (número, opcional): Número máximo de resultados a retornar (padrão: 9, máximo: 50).
• offset (número, opcional): Número de resultados a pular para paginação.
• license (string, opcional): Filtrar por licença. Opções: "all" (padrão) ou "no_restrictions" (CC0/Domínio Público).
• include_thumbnails (booleano, opcional): Se deve gerar e retornar uma imagem composta de miniaturas (padrão: true).

Como Funciona

1. Busca: A ferramenta consulta a API do Wikimedia Commons usando os termos de pesquisa e filtros fornecidos. Ela recupera dados JSON brutos contendo URLs de imagens, metadados e informações de licença.
2. Processamento: A resposta JSON bruta é analisada e transformada em uma lista estruturada e limpa de objetos ImageMetadata.
3. Formatação:
   • Texto: A lista de metadados é convertida em uma string formatada em YAML. Isso fornece à IA uma visão geral estruturada e legível dos resultados (incluindo tamanho do arquivo, dimensões, autor e licença).
   • Visual: Se include_thumbnails for verdadeiro, a ferramenta baixa a miniatura de cada resultado. Em seguida, usa a biblioteca sharp para compor essas miniaturas em uma única imagem em grade, com números de índice sobrepostos em cada imagem.
4. Resposta: A ferramenta retorna uma mensagem de múltiplos conteúdos contendo o texto YAML e a imagem composta (tipo MIME image/jpeg).

Você pode ver exemplos dos arquivos de saída no diretório test-output/:

• wikimediaSearchResults.json: A resposta JSON bruta da API do Wikimedia.
• formattedSearchResults.txt: A resposta de texto formatada em YAML.
• thumbnailComposite.jpeg: A grade visual gerada dos resultados da pesquisa.

Demonstração

Desenvolvimento

Para contribuir com este projeto ou executá-lo localmente a partir do código-fonte:

1. Clone o repositório:

   git clone https://github.com/yanexr/wikimedia-image-search-mcp.git
   cd wikimedia-image-search-mcp
   

2. Instale as dependências:

   npm install
   # or
   pnpm install
   

3. Compile o projeto:

   npm run build
   # or
   pnpm run build
   

4. Configuração Local: Para testar o servidor localmente com um cliente MCP, aponte a configuração para o seu arquivo compilado.

   {
     "mcpServers": {
       "wikimedia-local": {
         "command": "node",
         "args": [
           "C:/path/to/wikimedia-image-search-mcp/dist/index.js"
         ]
       }
     }
   }
   

5. Testes e Depuração: Você pode usar o MCP Inspector para testar o servidor interativamente:

   npm run inspect
   # or
   pnpm run inspect