# MCP Server — Mercado Livre (Vendedor)

Servidor MCP (Model Context Protocol) que integra com a API do Mercado Livre, disponibilizando ferramentas para gestão de vendas, envios e etiquetas diretamente pelo Claude.

## Pré-requisitos

- **Node.js** v18+
- **App do Mercado Livre** criado no [Portal de Desenvolvedores](https://developers.mercadolivre.com.br/)
  - Com as permissões: `offline_access`, `read`, `orders-shipments`

## Instalação

```bash
git clone https://github.com/seu-usuario/rg-mcp-mercadolivre.git
cd rg-mcp-mercadolivre
npm install
npm run build
```

## Obter credenciais

### 1. Criar App no Mercado Livre

Acesse o [Portal de Desenvolvedores](https://developers.mercadolivre.com.br/) e crie um aplicativo. Anote o **Client ID** e **Client Secret**.

### 2. Autorizar o App

Abra no navegador (substitua `CLIENT_ID` e `REDIRECT_URI` pelos seus valores):

```
https://auth.mercadolivre.com.br/authorization?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
```

Após autorizar, você será redirecionado para uma URL com um parâmetro `?code=TG-XXXXXXX`. Copie esse código.

### 3. Trocar o código por tokens

```bash
curl -X POST "https://api.mercadolibre.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "code=TG-XXXXXXX" \
  -d "redirect_uri=REDIRECT_URI"
```

A resposta conterá o `refresh_token` necessário para a configuração.

## Configuração no Claude Code

Crie um arquivo `.mcp.json` na raiz do projeto:

```json
{
  "mcpServers": {
    "mcp-mercadolivre": {
      "command": "node",
      "args": ["/caminho/completo/para/rg-mcp-mercadolivre/build/index.js"],
      "env": {
        "ML_CLIENT_ID": "seu_client_id",
        "ML_CLIENT_SECRET": "seu_client_secret",
        "ML_REFRESH_TOKEN": "seu_refresh_token"
      }
    }
  }
}
```

> **Importante:** O arquivo `.mcp.json` contém credenciais sensíveis e já está no `.gitignore`. Nunca o commite no repositório.

Após criar o arquivo, reinicie o Claude Code para que o MCP server seja carregado. O Claude vai pedir aprovação na primeira vez.

### Persistência de tokens

O servidor persiste automaticamente o `refresh_token` mais recente em `.ml_token.json`. Como o Mercado Livre invalida o refresh token a cada uso (single-use), essa persistência garante que o servidor continue funcionando entre reinícios sem precisar reautorizar.

## Ferramentas disponíveis

### `listar_vendas`

Lista as vendas do vendedor com filtros.

| Parâmetro   | Tipo   | Descrição |
|-------------|--------|-----------|
| `status`    | string | Status do pedido: `paid`, `cancelled`, `confirmed`, etc. |
| `tags`      | string | Tags: `paid`, `not_delivered`, `delivered` |
| `q`         | string | Busca por ID do pedido, item, título ou nickname |
| `date_from` | string | Data início (ISO 8601) |
| `date_to`   | string | Data fim (ISO 8601) |
| `sort`      | string | `date_asc` ou `date_desc` |
| `limit`     | number | Quantidade por página (max 50) |
| `offset`    | number | Offset para paginação |

### `vendas_para_enviar`

Lista vendas pagas que estão prontas para despacho (`ready_to_ship`).

| Parâmetro     | Tipo    | Descrição |
|---------------|---------|-----------|
| `apenas_hoje` | boolean | Se `true`, filtra apenas envios com prazo para hoje |
| `limit`       | number  | Quantidade máxima de pedidos |

### `gerar_etiquetas`

Gera etiquetas de envio em PDF ou ZPL para impressão.

| Parâmetro      | Tipo   | Descrição |
|----------------|--------|-----------|
| `shipment_ids` | string | **(obrigatório)** IDs dos shipments separados por vírgula (max 50) |
| `formato`      | string | `pdf` ou `zpl2` |

### `detalhes_venda`

Retorna os detalhes completos de um pedido.

| Parâmetro  | Tipo   | Descrição |
|------------|--------|-----------|
| `order_id` | number | **(obrigatório)** ID do pedido |

### `detalhes_envio`

Retorna detalhes de um envio: endereço, rastreio, status, logística.

| Parâmetro     | Tipo   | Descrição |
|---------------|--------|-----------|
| `shipment_id` | number | **(obrigatório)** ID do envio |

### `historico_envio`

Retorna o histórico completo de status de um envio.

| Parâmetro     | Tipo   | Descrição |
|---------------|--------|-----------|
| `shipment_id` | number | **(obrigatório)** ID do envio |

### `salvar_pdf`

Converte uma string base64 em arquivo PDF e salva no caminho especificado. Útil para salvar etiquetas geradas pela tool `gerar_etiquetas`.

| Parâmetro | Tipo   | Descrição |
|-----------|--------|-----------|
| `base64`  | string | **(obrigatório)** Conteúdo do PDF codificado em base64 |
| `caminho` | string | **(obrigatório)** Caminho absoluto onde salvar o arquivo (deve terminar com `.pdf`) |

## Exemplos de prompts

### Consultar vendas

```
Liste minhas últimas 10 vendas
```

```
Quais vendas eu fiz hoje?
```

```
Busque vendas do produto "Tecido Tricoline"
```

```
Mostre minhas vendas canceladas do último mês
```

### Envios pendentes

```
Quais vendas preciso enviar hoje?
```

```
Liste todas as vendas prontas para despacho
```

```
Tenho algum envio pendente?
```

### Etiquetas

```
Gere as etiquetas dos envios pendentes em PDF
```

```
Gere a etiqueta ZPL do shipment 46688889102
```

```
Gere etiquetas para os shipments 46688889102, 46688889103, 46688889104
```

### Detalhes e rastreio

```
Mostre os detalhes do pedido 2000015624114436
```

```
Qual o status do envio 46688889102?
```

```
Mostre o histórico de rastreio do envio 46688889102
```

### Salvar etiquetas em PDF

```
Gere as etiquetas dos envios pendentes e salve o PDF na minha área de trabalho
```

```
Gere a etiqueta do shipment 46688889102 e salve em /Users/usuario/Desktop/etiqueta.pdf
```

### Combinações

```
Liste as vendas que preciso enviar hoje, gere todas as etiquetas e salve o PDF no Desktop
```

```
Mostre minhas vendas de hoje com os detalhes de cada envio
```

## Desenvolvimento

```bash
# Rodar em modo dev (com hot reload)
npm run dev

# Build
npm run build

# Rodar o servidor
npm start
```

## Licença

MIT