Beaconed

@beaconed/mcp

Servidor MCP que expõe a API v1 do Beaconed para Claude Desktop, Cursor e qualquer cliente compatível com MCP. Peça ao Claude para listar seus produtos, enfileirar otimizações, aprovar textos gerados por IA e gerenciar webhooks — tudo por meio de linguagem natural.

Requer Node.js 22 ou posterior.

Instalação

npm install -g @beaconed/mcp

Configuração

Adicione ao seu Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "beaconed": {
      "command": "beaconed-mcp",
      "env": {
        "BEACONED_API_KEY": "your-api-key"
      }
    }
  }
}

Obtenha sua chave de API em beaconed.ai em Configurações > Chaves de API.

Defina BEACONED_BASE_URL para substituir o padrão https://beaconed.ai (útil para desenvolvimento local ou staging).

Ferramentas

Ferramentas de leitura

• beaconed_products_list — lista produtos com filtros por status, pontuação, nota e busca por título
• beaconed_products_get — detalhes completos do produto, incluindo imagens, histórico de pontuação e otimização mais recente
• beaconed_products_scores — histórico de pontuação de um produto específico
• beaconed_products_optimizations — lista otimizações vinculadas a um produto
• beaconed_optimizations_list — lista todas as otimizações geradas por IA em todos os produtos
• beaconed_optimizations_get — detalhes completos da otimização (conteúdo original vs. sugerido)
• beaconed_scores_list — pontuações de prontidão em todos os produtos
• beaconed_scores_latest — pontuação mais recente por produto
• beaconed_settings_get — configurações de otimização da conta (voz da marca, palavras-chave, configuração de envio automático)
• beaconed_webhooks_list — lista assinaturas de webhook
• beaconed_webhooks_get — detalhes do webhook, incluindo informações do último erro
• beaconed_webhooks_events — catálogo global de todos os tipos de eventos de webhook disponíveis

Ferramentas de mutação

• beaconed_products_create — cria um produto a partir de dados externos (não-Shopify)
• beaconed_products_update — atualiza campos do produto (atualização parcial)
• beaconed_products_sync — atualiza todos os produtos da loja do produto selecionado a partir do Shopify (limite de requisições: 10/min)
• beaconed_products_optimize — enfileira otimização de IA para um ou mais campos do produto (limite de requisições: 10/min)
• beaconed_products_calculate_score — recalcula a pontuação de prontidão de um produto (limite de requisições: 10/min)
• beaconed_optimizations_approve — aprova uma otimização pendente; pode publicar conteúdo ao vivo quando o envio automático estiver ativado (limite de requisições: 10/min)
• beaconed_optimizations_reject — rejeita uma otimização pendente com um motivo opcional
• beaconed_optimizations_apply — solicita a aplicação de uma otimização aprovada ao produto ao vivo (DESTRUTIVO, limite de requisições: 10/min)
• beaconed_optimizations_revert — solicita a reversão de uma otimização aplicada para o conteúdo original (DESTRUTIVO, limite de requisições: 10/min)
• beaconed_webhooks_create — cria uma assinatura de webhook (o segredo de assinatura é retornado apenas uma vez)
• beaconed_webhooks_update — atualiza URL, eventos ou status de um webhook
• beaconed_webhooks_delete — remove permanentemente uma assinatura de webhook (DESTRUTIVO)
• beaconed_webhooks_test — envia um evento de teste para verificar a entrega
• beaconed_bulk_optimize — enfileira otimização de IA para vários produtos em uma única requisição (limite de requisições: 10/min)

Este pacote usa stdio e requer Node.js 20+. As ferramentas operam na conta associada a BEACONED_API_KEY.

A otimização usa créditos da conta; o limite de requisições acima é um limite de taxa, não um preço. A aceitação na fila não confirma a conclusão. Leia os detalhes do produto ou da otimização para verificar o resultado. A aprovação pode publicar imediatamente ou enfileirar uma gravação no Shopify quando auto_push_on_approve estiver ativado; inspecione as configurações da conta e o conteúdo proposto antes de aprovar. Aplicar ou reverter pode substituir o conteúdo ao vivo.

As anotações das ferramentas descrevem efeitos somente leitura, de substituição, de chamada repetida e de sistemas externos. Os clientes podem usar essas dicas ao solicitar confirmação; as anotações não impõem confirmação.

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, pois aceitá-los sem um limite de proxy autenticado permitiria que chamadores falsificassem a identidade do limite de taxa.

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

Licença

MIT — consulte LICENSE.

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 do lançamento enviado. 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 um lançamento npm.