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:

   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.

   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:

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:

{
  "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.