Tray MCP Server

Servidor MCP (Model Context Protocol) que conecta agentes de IA como Claude à plataforma Tray Commerce. Permite gerenciar produtos, pedidos e clientes em linguagem natural, sem abrir o painel administrativo.

Demonstração

Você: "Quais pedidos aprovados ainda não foram enviados hoje?"

Claude: Encontrei 3 pedidos aprovados pendentes de envio:
  - #12340 — João Silva — R$ 299,90 — aprovado às 09:15
  - #12345 — Maria Souza — R$ 149,00 — aprovado às 11:30
  - #12350 — Carlos Lima — R$ 599,90 — aprovado às 14:00

Você: "Manda o 12345 como Enviado com rastreio BR999888777BR"

Claude: Pedido #12345 atualizado para "Enviado" com rastreio BR999888777BR ✓

Requisitos

• Node.js 20+
• Credenciais de parceiro Tray (Consumer Key + Consumer Secret)
• Claude Desktop, Claude Code ou outro cliente MCP

Instalação e Autenticação

Passo 1 — Autenticar (uma única vez):

npx @tray/mcp-server auth

O assistente interativo vai pedir suas credenciais de parceiro e o code gerado quando o lojista instala o app na loja. Ao final, salva os tokens em ~/.tray-mcp/tokens.json e imprime o bloco de configuração pronto para usar.

Passo 2 — Adicionar ao Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "tray": {
      "command": "npx",
      "args": ["-y", "@tray/mcp-server"],
      "env": {
        "TRAY_API_HOST": "https://loja.com.br/web_api",
        "TRAY_ACCESS_TOKEN": "SEU_ACCESS_TOKEN",
        "TRAY_REFRESH_TOKEN": "SEU_REFRESH_TOKEN",
        "TRAY_CONSUMER_KEY": "SUA_CONSUMER_KEY",
        "TRAY_CONSUMER_SECRET": "SEU_CONSUMER_SECRET",
        "TRAY_TOKEN_EXPIRATION": "2024-03-02 14:58:21"
      }
    }
  }
}

Se tiver rodado tray-mcp auth, pode omitir o bloco env — o servidor lê os tokens do arquivo salvo automaticamente.

Passo 3 — Reiniciar o Claude Desktop. O servidor aparece como conjunto de ferramentas "tray".

Ferramentas disponíveis

Produtos

Ferramenta	O que faz
list_products	Lista produtos com filtros (disponibilidade, estoque, categoria)
get_product	Detalha um produto pelo ID
update_product	Altera preço, estoque, promoção, disponibilidade etc.

Pedidos

Ferramenta	O que faz
list_orders	Lista pedidos com filtros por status e período
get_order	Detalha um pedido pelo ID
update_order_status	Atualiza status e código de rastreamento

Clientes

Ferramenta	O que faz
list_customers	Lista clientes com filtro por e-mail
get_customer	Detalha um cliente pelo ID

Recursos de contexto (Resources)

URI	Conteúdo
tray://store/info	Configurações gerais da loja
tray://store/statuses	Status de pedido disponíveis

Exemplos de uso

"Quais produtos têm menos de 5 unidades em estoque?"
"Coloca o produto 84 em promoção por R$ 199,90"
"Me mostra os detalhes do pedido 12345"
"Atualiza o status do pedido 99999 para Cancelado"
"O cliente joao@email.com já cadastrou na loja?"

Variáveis de ambiente

Variável	Descrição
TRAY_API_HOST	URL base da API, ex: https://loja.com.br/web_api
TRAY_ACCESS_TOKEN	Token de acesso atual
TRAY_REFRESH_TOKEN	Token para renovação automática
TRAY_CONSUMER_KEY	Identificador do aplicativo parceiro
TRAY_CONSUMER_SECRET	Segredo do aplicativo parceiro
TRAY_TOKEN_EXPIRATION	Data de expiração do access token (YYYY-MM-DD HH:MM:SS)

O servidor renova o access_token automaticamente 5 minutos antes de expirar — nenhuma intervenção manual necessária.

Limites de API

A Tray impõe os seguintes limites, respeitados automaticamente pelo servidor:

• 180 requisições/minuto por loja
• 10.000 requisições/dia por loja

O servidor avisa quando 80% do limite diário for consumido.

Desenvolvimento local

git clone https://github.com/seu-usuario/tray-mcp-server
cd tray-mcp-server
npm install
npm run build       # compila TypeScript → dist/
npm run dev         # roda direto via tsx (sem compilar)

Roadmap

• [x] Fase 1 — MVP: produtos, pedidos, clientes, auth + rate limiter
• [ ] Fase 2 — Catálogo completo: variações, categorias, marcas, kits
• [ ] Fase 3 — Promoções: cupons, listas de preço B2B, NF-e, multi-loja

Referências

• Documentação da API Tray — referência técnica coletada
• PRD do projeto — especificação de produto
• Tray Developers
• MCP TypeScript SDK