# Shopee Agentic MCP Server
Um servidor leve e autônomo baseado no **Model Context Protocol (MCP)**, desenhado especificamente para atuar como ponte de integração em **tempo real** entre Agentes de Inteligência Artificial (LLMs) e a plataforma da **Shopee**.
Ele encapsula as chamadas da API de Afiliados e do Seller Center numa interface de "tools", permitindo que os agentes conversem com a Shopee para buscar produtos, filtrar por comissão e consultar categorias nativamente.
---
## 🛠️ Ferramentas (Tools) Expostas para o LLM
Ao plugar este MCP em seu Agente, as seguintes ferramentas se tornam imediatamente disponíveis:
- **`search_shopee_products`**
- **Descrição:** Busca produtos diretamente no catálogo da Shopee.
- **Filtros suportados:** Por palavra-chave (`keyword`), ID de Categoria (`category_id`).
- **Ordenação suportada:** Relevância, Mais Vendidos (padrão), Maior Preço, Menor Preço e **Maior Comissão**.
- **Retorno:** Informações detalhadas com imagens, preços, volumes de vendas, avaliação e links de afiliado.
- **`search_shopee_categories`**
- **Descrição:** Mapeia palavras-chaves (ex: "celulares") e busca pelas categorias oficiais globais da plataforma, útil para descobrir IDs exatos de categoria necessários na busca de produtos.
---
## ⚙️ Pré-Requisitos e Instalação
O projeto é mantido puramente através do gerenciador de pacotes **Poetry**, utilizando a arquitetura do **FastMCP**.
1. **Instale as dependências essenciais do projeto:**
```bash
poetry install
```
2. **Configure suas Credenciais da Shopee API:**
Renomeie, copie ou crie o seu `.env` na raiz do projeto contendo as suas chaves de acesso ao painel de Afiliados da Shopee OpenAPI.
```env
SHOPEE_APP_ID=seu_app_id
SHOPEE_SECRET=sua_secret_aqui
```
---
## 🚀 Como Executar
O projeto foi projetado para subir através do protocolo **Server-Sent Events (SSE)**, ideal para comunicação remota Agent-to-Agent (A2A).
**Inicie o servidor localmente:**
```bash
make dev
```
*(ou manualmente com `poetry run python mcp_server.py sse 8002`)*
O sistema fará o bind na porta local **8002**. O endpoint do seu MCP para fornecer as ferramentas as outras aplicações passará a ser:
`http://localhost:8002/sse`
---
## 🔌 Consumindo as Ferramentas (Integração)
Este módulo foi feito para ser plug-and-play em dezenas de orquestradores modernos. Alguns exemplos:
### Usando o Google ADK (A2A)
Se você estiver rodando o seu "Agent Estoque" ou "SalesAgent", basta cadastrar a URL SSE recém criada no gerenciador de provedores de contexto ou tools-registry do ADK. A descoberta das rotas de shoppings da shopee serão embutidas automaticamente ao prompt planner.
### Claude Desktop / Cursor (via STDIO)
Para acoplar nativamente à sua IDE (Cursor) ou Client Offline com Standard I/O (stdio):
Basta configurar no JSON do MCP as rotas indicando este módulo rodando via poetry:
```json
{
"mcpServers": {
"shopee-mcp": {
"command": "poetry",
"args": ["run", "python", "/caminho/absoluto/do/projeto/mcp_server.py"]
}
}
}
```
---
*Clean architecture - Sem necessidade de Bancos de Dados locais. Todo tráfego funciona em tempo-real em proxy com as APIs oficiais.*
