# Shopee Agentic MCP Server

![Shopee MCP Server](doc/image.png)

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.*