Content
# MCP Extra Mercado Server
Este é um servidor MCP (Model Context Protocol) escrito em Python que interage diretamente com a API do Extra Mercado (`api.vendas.gpa.digital`). Ele permite realizar buscas, criar carrinhos, adicionar itens ao carrinho, ver o conteúdo do carrinho atual e listar/ver detalhes de pedidos antigos sem a necessidade de automação visual ou interação direta com o navegador Chrome.
Este servidor armazena de forma persistente suas credenciais de autenticação e preferências (como loja e endereço padrão) em `~/.mcp-extramercado.json` para facilitar o uso no dia a dia.
## Ferramentas Disponíveis
1. `set_auth`: Salva o token JWT de autenticação em `~/.mcp-extramercado.json`.
2. `set_preferences`: Salva preferências de entrega (`storeId`, `addressId`, `storeDeliveryTypeId`, `zipCode`) no arquivo de configuração local.
3. `list_addresses`: Retorna os endereços de entrega cadastrados na conta do usuário para facilitar a escolha de preferências.
4. `list_stores`: Retorna as lojas e tipos de entrega disponíveis para um determinado CEP (`zipCode`).
5. `search_products`: Busca produtos no Extra Mercado por palavra-chave.
6. `create_basket`: Cria um novo carrinho de compras. Se omitidos, utiliza o `storeId`, `addressId` e `storeDeliveryTypeId` configurados em `set_preferences`.
7. `add_to_cart`: Adiciona um produto com uma quantidade específica ao carrinho.
8. `get_cart`: Retorna o conteúdo e produtos do carrinho atual.
9. `list_orders`: Lista o histórico de pedidos efetuados.
10. `get_order_details`: Retorna os detalhes de um pedido específico (incluindo a lista de produtos comprados).
## Instalação e Execução
O servidor utiliza comunicação padrão via Stdio e não possui dependências externas (utiliza apenas a biblioteca padrão do Python 3).
### Configuração no Claude Desktop
Adicione a seguinte configuração ao seu arquivo de configuração MCP (ex: `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"mcp-extramercado": {
"command": "/Users/igormspc/Projects/labs/mcp-extramercado/server.py"
}
}
}
```
## Como Configurar Autenticação e Preferências
Como o Extra Mercado exige uma conta e seleção de local para gerenciar o carrinho, você deve seguir estes passos de configuração na primeira execução:
1. **Defina a Autenticação:**
Acesse o site do Extra Mercado no navegador logado, abra o console de desenvolvedor (F12) e obtenha seu token de sessão executando:
```javascript
localStorage.getItem("USER_TOKEN")
```
Em seguida, chame a ferramenta `set_auth` passando este token:
```json
{
"token": "seu_token_jwt_aqui"
}
```
2. **Descubra os IDs de Endereço:**
Após definir o token, chame a ferramenta `list_addresses` para retornar seus endereços cadastrados. Identifique o ID do endereço de sua preferência (`id`).
3. **Descubra as Lojas e Tipos de Entrega:**
Chame a ferramenta `list_stores` com o CEP do seu endereço de entrega:
```json
{
"zipCode": "<>"
}
```
Escolha a opção de loja desejada no retorno e pegue os valores de `storeid` (ex: 839) e `typeid` (ex: 1058).
4. **Salve suas Preferências:**
Chame a ferramenta `set_preferences` informando os IDs que você escolheu:
```json
{
"storeId": 839,
"addressId": <id>,
"storeDeliveryTypeId": <>,
"zipCode": "<>"
}
```
5. **Pronto!**
Agora você pode usar a ferramenta `create_basket` sem passar nenhum argumento; ela utilizará automaticamente os dados salvos em suas preferências para iniciar o carrinho de compras.
