AltText.ai

Servidor MCP AltText.ai

Um servidor MCP que permite que assistentes de IA gerem texto alternativo, gerenciem bibliotecas de imagens e coloquem em fila a geração de texto alternativo para imagens de páginas da web usando a API AltText.ai.

Funciona com Claude Desktop, Claude Code, Cursor, Windsurf e qualquer cliente compatível com MCP.

Verifique este pacote

Este servidor executa npx -y @alttext_ai/alttext-mcp, que baixa e executa código com sua chave de API em seu ambiente. Vale a pena um momento de verificação antes de instalar — por você ou por um agente de IA que esteja fazendo a configuração. Tudo abaixo deve corresponder:

Sinal	Valor
Pacote npm	@alttext_ai/alttext-mcp
Repositório de origem	github.com/alttextai/alttext-mcp
Editor	AltText.ai
Proveniência	Publicado a partir do CI deste repositório com proveniência npm — o npm mostra um selo de build verificado vinculando o pacote a este commit exato

O escopo npm é @alttext_ai (com sublinhado), enquanto a organização GitHub é alttextai (sem sublinhado). Isso é intencional, não é typosquatting: o escopo npm @alttextai já estava ocupado, então publicamos sob @alttext_ai. Os dois nomes referem-se ao mesmo pacote oficial AltText.ai.

Para verificar criptograficamente que o pacote publicado foi construído pelo CI deste repositório — não apenas confiar nos metadados — execute:

npm audit signatures

a partir de um projeto onde o pacote está instalado. Isso valida a assinatura do registro e a atestação de proveniência do npm, que vincula o tarball a um commit específico e a um build do GitHub Actions. Um pacote falsificado pode forjar repository.url e outros metadados, mas não pode forjar a atestação de proveniência — então esta é a verificação que realmente importa.

(Para uma referência cruzada rápida e mais fraca da suposta origem, você pode executar npm view @alttext_ai/alttext-mcp repository.url, mas observe que esse campo é metadados controlados pelo editor e não prova nada por si só.)

Fixando uma versão

O trecho de configuração usa npx -y @alttext_ai/alttext-mcp, que sempre resolve para a versão publicada mais recente e a executa novamente a cada inicialização. Isso mantém você atualizado, mas também significa que uma versão futura será executada automaticamente sem revisão. Se você quiser uma instalação reproduzível e auditada, fixe uma versão específica:

"args": ["-y", "@alttext_ai/alttext-mcp@1.0.5"]

Execute npm audit signatures contra a versão fixada e aumente-a deliberadamente quando estiver pronto para adotar uma nova versão.

Configuração

Requisitos: Node.js 22+ e uma chave de API AltText.ai

Adicione o servidor à configuração do seu cliente MCP:

{
  "mcpServers": {
    "alttext-ai": {
      "command": "npx",
      "args": ["-y", "@alttext_ai/alttext-mcp"],
      "env": {
        "ALTTEXT_API_KEY": "your-api-key"
      }
    }
  }
}

Onde adicionar:

Cliente	Arquivo de configuração
Claude Desktop	claude_desktop_config.json
Claude Code	.mcp.json na raiz do seu projeto
Cursor	Configurações de MCP nas preferências do Cursor
Windsurf	Configurações de MCP nas preferências do Windsurf

Ferramentas

Gerenciamento de Conta

Ferramenta	Descrição
get_account	Verifique seu saldo de créditos, uso e configurações da conta.
update_account	Atualize o nome da conta, URL do webhook ou e-mail de notificação.

Gerar Texto Alternativo

Ferramenta	Descrição
generate_alt_text	Gere texto alternativo para uma URL de imagem. Suporta saída multilíngue, prompts personalizados, palavras-chave e limites de caracteres. Usa créditos da conta.
generate_alt_text_from_file	Gere texto alternativo a partir de um arquivo de imagem local. Codifica automaticamente em base64 e faz upload. Usa créditos da conta.
translate_image	Adicione texto alternativo em um novo idioma para uma imagem existente (por asset_id). Usa créditos da conta.

Gerenciar Biblioteca de Imagens

Ferramenta	Descrição
list_images	Liste imagens na sua biblioteca com paginação.
search_images	Pesquise sua biblioteca de imagens por conteúdo de texto alternativo.
get_image	Obtenha detalhes de uma imagem específica por ID do ativo.
update_image	Atualize texto alternativo, tags ou metadados de uma imagem.
delete_image	Exclua uma imagem da sua biblioteca.

Operações em Lote

Ferramenta	Descrição
bulk_create	Gere texto alternativo em lote a partir de um arquivo CSV com URLs de imagens e metadados opcionais.
scrape_page	Analise uma página da web, encontre imagens sem texto alternativo e coloque a geração na fila. Os resultados são assíncronos — use list_images para verificar o progresso.

Efeitos e processamento

Este pacote usa stdio e é executado na máquina que inicia o cliente MCP. Os caminhos de imagens e CSV referem-se a essa máquina; o conteúdo dos arquivos selecionados é enviado para AltText.ai.

Geração e tradução usam seus créditos da conta. Idiomas adicionais e conversão de imagens podem aumentar o total. Verifique get_account antes de trabalho pago. A geração pode sobrescrever texto alternativo existente quando solicitado; atualizações substituem os campos fornecidos e a exclusão remove a imagem da biblioteca.

Importações de CSV e raspagem de páginas colocam o processamento em segundo plano. Uma solicitação aceita não significa que a geração foi concluída; inspecione a biblioteca de imagens e quaisquer notificações de conclusão configuradas. As anotações das ferramentas descrevem efeitos para os clientes; elas não impõem confirmação.

Exemplos de Prompts

Uma vez configurado, basta pedir ao seu assistente de IA:

Conta e Créditos

• "Quantos créditos ainda tenho?"
• "Atualize minha URL de webhook para https://example.com/webhook"

Gerar Texto Alternativo

• "Gere texto alternativo para https://example.com/photo.jpg"
• "Gere texto alternativo para esta imagem" (com arquivo local)
• "Gere texto alternativo em francês e espanhol para esta imagem"
• "Traduza a imagem abc123 para alemão"

Gerenciar Biblioteca

• "Pesquise minhas imagens por 'foto de produto'"
• "Liste minhas imagens"
• "Obtenha detalhes da imagem abc123"
• "Atualize o texto alternativo do ativo abc123"
• "Exclua a imagem xyz789"

Operações em Lote

• "Gere texto alternativo para imagens sem ele em https://example.com"
• "Processe este arquivo CSV de URLs de imagens" (bulk_create)

Variáveis de Ambiente

Variável	Obrigatória	Descrição
ALTTEXT_API_KEY	Sim	Sua chave de API AltText.ai
ALTTEXT_API_BASE_URL	Não	Substitua a URL base da API (padrão: https://alttext.ai/api/v1)

Desenvolvimento

npm install
npm run build
npm test
npm run lint

Os testes usam chamadas fetch simuladas — nenhuma chave de API ou acesso à rede é necessário.

Implantações hospedadas devem limitar a taxa de POST /register em uma borda confiável usando o endereço verificado do cliente. O serviço Node deliberadamente ignora cabeçalhos de endereço de cliente encaminhados porque aceitá-los sem um limite de proxy autenticado permitiria que chamadores falsificassem a identidade de limitação de taxa.

O contêiner de produção e as configurações necessárias estão documentados em docs/deployment.md.

Licença

MIT

Publicação no Registro

server.json descreve o pacote npm stdio. Seu nome corresponde a mcpName em package.json; ambas as versões devem corresponder à versão sendo submetida. Publique e verifique essa versão npm exata antes de executar mcp-publisher publish. A aceitação no registro e a aprovação do diretório são separadas de uma versão npm.