IIIF Images Server

MCP para IIIF Images

Um servidor Model Context Protocol (MCP) para trabalhar com manifests e imagens do IIIF (International Image Interoperability Framework). Veja este vídeo para uma demonstração.

Recursos

Este servidor MCP contém as seguintes ferramentas:

• fetch_iiif_manifest: Busca um manifest IIIF a partir de uma URL. (Observe que os clientes podem ter dificuldade em processar grandes quantidades de JSON.)
• fetch_iiif_image: Recupera uma imagem IIIF a partir de uma URI base, buscando o info.json e retornando os dados da imagem (padrão: máximo 1500px de dimensão, máximo 800.000 pixels no total)
• fetch_iiif_image_region: Recupera uma região específica de uma imagem IIIF usando coordenadas percentuais, com a região redimensionada para caber dentro das mesmas restrições

Ressalvas

• O código redimensiona as imagens para dimensões aceitáveis pelo Claude. Não funcionará com uma implementação da Image API de Nível 0.
• O Claude pode não processar alguns Manifests IIIF devido ao tamanho do arquivo.

Configuração do Claude Desktop

Instalar a partir do arquivo de Extensão do Claude Desktop (DXT)

1. Instale e faça login no Claude Desktop
2. Baixe o arquivo .dxt da última versão
3. Clique duas vezes no arquivo .dxt
4. Instale a extensão quando o Claude solicitar

Instalar a partir do Código Fonte

1. Clone este repositório
2. Instale as dependências: npm install
3. Torne o servidor executável: chmod +x server/server.js

Para usar este servidor MCP com o Claude Desktop, adicione a seguinte configuração ao seu arquivo de configuração do Claude Desktop. Ajuste o caminho do arquivo conforme necessário. Talvez você também precise fornecer o caminho completo para o seu comando node.

macOS

Edite o ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["/PATH/TO/mcp-iiif-images/server/server.js"]
    }
  }
}

Windows

Edite o %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-iiif-images\\server\\server.js"]
    }
  }
}

Linux

Edite o ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["/path/to/mcp-iiif-images/server/server.js"]
    }
  }
}

Uso Geral do MCP

O servidor suporta dois modos de transporte:

Modo Padrão (stdio)

Execute o servidor usando o transporte stdio (padrão):

npm start
# or
node server/server.js

Modo HTTP Streaming

Execute o servidor usando transporte HTTP streaming:

node server/server.js --http
# or with custom port
node server/server.js --http --port 8080

Opções de Linha de Comando

• --http: Usa transporte HTTP streaming em vez de stdio
• --port PORT: Número da porta para o servidor HTTP (padrão: 3000)
• --help: Mostra mensagem de ajuda

Ao usar o modo HTTP, o servidor iniciará um servidor HTTP com os seguintes endpoints:

• GET /sse: Estabelece conexão Server-Sent Events
• POST /messages?sessionId=<id>: Envia mensagens MCP

Modo HTTP Streaming

Para o modo HTTP streaming, você precisará iniciar o servidor manualmente com a flag --http e depois configurar o Claude Desktop para se conectar via HTTP:

node server/server.js --http --port 3000

Em seguida, configure o Claude Desktop para usar o transporte HTTP (consulte a documentação do Claude Desktop para configuração do transporte HTTP).

Nota: Atualize o caminho no array args para corresponder ao local real onde você instalou este servidor.

Após atualizar a configuração, reinicie o Claude Desktop para que as alterações entrem em vigor.

Testes

Para executar os testes:

# Run tests once
npm test

# Run tests in watch mode (automatically re-runs on file changes)
npm run test:watch

# Run tests with coverage
npm test -- --coverage

O projeto usa Vitest como framework de testes, que oferece:

• Execução rápida com suporte a módulos ES
• API compatível com Jest com melhores mensagens de erro
• Relatório de cobertura integrado
• Modo de observação (watch) para desenvolvimento

Ferramentas Disponíveis

fetch_iiif_manifest

Busca e valida um manifest IIIF a partir de uma URL.

Parâmetros:

• url (obrigatório): A URL do manifest IIIF a ser buscado

Exemplo de uso:

Please fetch the IIIF manifest from https://example.com/manifest.json

fetch_iiif_image

Recupera uma imagem IIIF a partir de uma URI base, buscando o info.json e retornando os dados da imagem.

Parâmetros:

• baseUri (obrigatório): URI base do recurso da IIIF Image API (sem /info.json)

Exemplo de uso:

Fetch the IIIF image at https://example.com/iiif/image123

fetch_iiif_image_region

Recupera uma região específica de uma imagem IIIF usando coordenadas percentuais, com a região redimensionada para caber dentro das mesmas restrições. Use esta ferramenta para buscar regiões de interesse em maior detalhe para uma descrição e análise de imagem mais precisas.

Parâmetros:

• baseUri (obrigatório): URI base do recurso da IIIF Image API (sem /info.json)
• region (obrigatório): Região no formato pct: (por exemplo, 'pct:20,20,50,50' para x,y,largura,altura como percentuais)

Exemplo de uso:

Fetch a region from the IIIF image at https://example.com/iiif/image123 with region pct:10,10,50,50

Observe que você pode usar estas ferramentas em conjunto durante uma conversa, por exemplo:

Fetch the IIIF image at https://example.com/iiif/image123 and describe it.
...
Zoom in on the text at the bottom of the page and transcribe it.