# 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):**

```bash
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`):

```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

```bash
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](./README-API-DOCS.md) — referência técnica coletada
- [PRD do projeto](./PRD-TRAY-MCP.md) — especificação de produto
- [Tray Developers](https://developers.tray.com.br/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)