MCP 服务器

tray-mcp-server

Connects AI agents like Claude to the Tray Commerce platform, enabling natural language management of products, orders, and customers.

README

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)