PrestaShop MCP Server

Um servidor para gerenciar lojas de e-commerce PrestaShop através de uma API de produtos unificada.

Documentação

PrestaShop MCP Server

Um servidor profissional de Model Context Protocol (MCP) para gerenciamento completo de lojas de e-commerce PrestaShop com funcionalidades estendidas.

🚀 Visão Geral

Este MCP Server permite o gerenciamento completo da sua loja PrestaShop por meio de aplicações de IA como o Claude Desktop. Com ferramentas especializadas, você pode gerenciar todos os aspectos do seu negócio de e-commerce — desde produtos e categorias até clientes, pedidos, módulos, cache, temas e menus de navegação.

✨ Recursos

🛍️ Gerenciamento Completo da Loja — Ferramentas para todas as áreas do e-commerce
🔧 Gerenciamento de Módulos — Instalar, ativar e desativar módulos
💾 Gerenciamento de Cache — Limpar e monitorar o status do cache
🎨 Gerenciamento de Temas — Configurar temas e definições
📋 Gerenciamento de Menu — Gerenciar a navegação principal (ps_mainmenu)
🏗️ Conformidade com o Protocolo MCP para integração perfeita com IA
⚡ Arquitetura Async/Await para máximo desempenho
🛡️ Tratamento Abrangente de Erros e validação
🔧 Pronto para Produção com suíte de testes completa
📖 Documentação Abrangente com exemplos práticos

🛠️ Ferramentas Disponíveis

📦 Gerenciamento Unificado de Produtos

get_products — Recuperação de produtos UNIFICADA com suporte a todos os casos de uso:
- Produto Único por ID: Detalhes completos do produto, incluindo informações de estoque e categoria
- Múltiplos Produtos: Lista com filtragem e enriquecimento opcionais
- Enriquecimento Flexível: Informações de estoque opcionais, detalhes de categoria, seleção de campos personalizados
- Filtragem Inteligente: Por categoria, nome ou critérios personalizados
create_product — Criar novos produtos com configuração completa
update_product — Editar informações do produto
delete_product — Remover produtos
update_product_stock — Gerenciar níveis de estoque
update_product_price — Atualizar preços

🏷️ Gerenciamento de Categorias

get_categories — Recuperar categorias (com filtro de hierarquia)
create_category — Criar novas categorias
update_category — Editar categorias
delete_category — Remover categorias

👥 Gerenciamento de Clientes

get_customers — Recuperar e filtrar clientes
create_customer — Criar novos clientes
update_customer — Editar dados do cliente

📋 Gerenciamento de Pedidos

get_orders — Recuperar e filtrar pedidos
update_order_status — Alterar o status do pedido
get_order_states — Recuperar status disponíveis

🔧 Gerenciamento de Módulos NOVO

get_modules — Listar todos os módulos do PrestaShop
get_module_by_name — Obter detalhes de um módulo específico
install_module — Instalar novos módulos
update_module_status — Ativar/desativar módulos

📋 Gerenciamento do Menu Principal NOVO

get_main_menu_links — Recuperar links de navegação do ps_mainmenu
update_main_menu_link — Editar links de menu existentes
add_main_menu_link — Adicionar novos links de navegação

💾 Gerenciamento de Cache NOVO

clear_cache — Limpar o cache do PrestaShop (todos os tipos)
get_cache_status — Monitorar a configuração do cache

🎨 Gerenciamento de Temas NOVO

get_themes — Obter informações do tema atual
update_theme_setting — Configurar definições do tema

⚙️ Administração da Loja

test_connection — Testar a conexão com a API
get_shop_info — Estatísticas abrangentes da loja

📋 Instalação

⚠️ Instalação Recomendada (Ambiente Virtual)

Esta abordagem evita conflitos de módulos e garante uma instalação confiável:

Windows:

# Clone repository
git clone https://github.com/latinogino/prestashop-mcp.git
cd prestashop-mcp

# Create virtual environment
python -m venv venv_prestashop

# Activate virtual environment
.\venv_prestashop\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Install package in development mode
pip install -e .

# Verify installation
python -c "import prestashop_mcp; print('✅ Installation successful')"

# Note the Python path for Claude Desktop configuration
Write-Host "Python Path: $((Get-Command python).Source)"

Linux/macOS:

# Clone repository
git clone https://github.com/latinogino/prestashop-mcp.git
cd prestashop-mcp

# Create virtual environment
python3 -m venv venv_prestashop

# Activate virtual environment
source venv_prestashop/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install package in development mode
pip install -e .

# Verify installation
python -c "import prestashop_mcp; print('✅ Installation successful')"

# Note the Python path for Claude Desktop configuration
which python

⚙️ Configuração

Crie um arquivo .env com base em .env.example:

# PrestaShop Configuration
PRESTASHOP_SHOP_URL=https://your-shop.example.com
PRESTASHOP_API_KEY=YOUR_API_KEY

# Logging
LOG_LEVEL=INFO

🎯 Uso

🤖 Com o Claude Desktop

Usando Ambiente Virtual (Recomendado)

Adicione esta configuração ao claude_desktop_config.json:

Windows:

{
  "mcpServers": {
    "prestashop": {
      "command": "C:\\\\path\\\\to\\\\prestashop-mcp\\\\venv_prestashop\\\\Scripts\\\\python.exe",
      "args": ["-m", "prestashop_mcp.prestashop_mcp_server"],
      "cwd": "C:\\\\path\\\\to\\\\prestashop-mcp",
      "env": {
        "PRESTASHOP_SHOP_URL": "https://your-shop.example.com",
        "PRESTASHOP_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Linux/macOS:

{
  "mcpServers": {
    "prestashop": {
      "command": "/path/to/prestashop-mcp/venv_prestashop/bin/python",
      "args": ["-m", "prestashop_mcp.prestashop_mcp_server"],
      "cwd": "/path/to/prestashop-mcp",
      "env": {
        "PRESTASHOP_SHOP_URL": "https://your-shop.example.com",
        "PRESTASHOP_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

💻 Uso via CLI

# Activate virtual environment first (if using venv)
source venv_prestashop/bin/activate  # Linux/macOS
.\venv_prestashop\Scripts\Activate.ps1  # Windows

# With environment variables
prestashop-mcp

# With direct parameters
prestashop-mcp --shop-url https://your-shop.com --api-key YOUR_API_KEY

# Debug mode
prestashop-mcp --log-level DEBUG

🆕 Exemplos de Funcionalidades Estendidas

Gerenciamento de Módulos

"Show me all modules in my PrestaShop store"
"Activate the ps_mainmenu module"
"Deactivate the blockcart module"
"Get details for the ps_featuredproducts module"

Gerenciamento do Menu Principal

"Show me all main menu links"
"Add a new menu link called 'Special Offers' pointing to /special-offers"
"Update menu link 3 to point to /new-products"
"Make menu link 5 inactive"

Gerenciamento de Cache

"Clear all PrestaShop cache"
"Show me the current cache status"
"Check if CSS cache is enabled"

Gerenciamento de Temas

"Show me current theme settings"
"Update the PS_LOGO setting to /img/new-logo.png"
"Change the PS_THEME_NAME to my-custom-theme"

🆕 API Unificada de Produtos

A ferramenta get_products lida com todos os cenários de recuperação de produtos com uma interface única e poderosa:

Casos de Uso:

Cenário	Parâmetros	Resultado
Detalhes de Produto Único	`product_id="15", include_stock=true, include_category_info=true`	Informações completas do produto com estoque e categoria
Lista de Produtos	`limit=20, category_id="5"`	Lista de produtos na categoria 5
Lista Aprimorada	`limit=10, include_details=true, include_stock=true`	Detalhes completos do produto com estoque para 10 produtos
Busca Filtrada	`name_filter="laptop", include_details=true`	Todos os produtos de laptop com informações completas
Campos Personalizados	`display="id,name,price", limit=50`	Apenas campos específicos para 50 produtos

🛠️ Recursos Avançados

Integração com ps_mainmenu

O gerenciamento do módulo ps_mainmenu permite que você:

Recupere todos os links de navegação principal
Adicione itens de navegação personalizados
Atualize links de menu existentes (nome, URL, status)
Controle o posicionamento dos links do menu

Otimização de Desempenho do Cache

O gerenciamento de cache inclui:

Limpar todos os tipos de cache (CSS, JS, Template, Geral)
Monitorar o status do cache para otimização de desempenho
Alternar configurações de cache para desenvolvimento/produção

Gerenciamento do Ciclo de Vida de Módulos

Controle completo de módulos:

Listar todos os módulos instalados com status
Instalar novos módulos programaticamente
Ativar/desativar módulos conforme necessário
Obter informações detalhadas do módulo

Personalização de Temas

Recursos de gerenciamento de temas:

Visualizar a configuração atual do tema
Atualizar definições específicas do tema
Gerenciar logotipos e elementos visuais
Configurar definições do PrestaShop relacionadas ao tema

🔧 Solução de Problemas

❌ Problemas Comuns

"ModuleNotFoundError: No module named 'prestashop_mcp'"

Solução: Use ambiente virtual e garanta que o pacote esteja instalado:

# Check if in virtual environment
python -c "import sys; print(sys.prefix)"

# Reinstall package
pip install -e .

# Verify installation
python -c "import prestashop_mcp; print('Module found')"

Problemas de Gerenciamento de Módulos

Verifique as Permissões dos Módulos:

# Ensure your API key has module management permissions
curl -u "YOUR_API_KEY:" https://your-shop.com/api/modules?output_format=JSON

Limpeza de Cache Não Funcionando

Limpeza de Cache Alternativa: Se a limpeza de cache baseada em API não funcionar, talvez seja necessário:

Verificar as permissões do PrestaShop para o usuário da API
Usar a limpeza manual de cache no administrador do PrestaShop
Verificar as permissões de gravação do diretório de cache

🔍 Modo de Depuração

Ative o registro de depuração na configuração do Claude Desktop:

{
  "mcpServers": {
    "prestashop": {
      "command": "path/to/python",
      "args": ["-m", "prestashop_mcp.prestashop_mcp_server"],
      "cwd": "path/to/prestashop-mcp",
      "env": {
        "PRESTASHOP_SHOP_URL": "https://your-shop.example.com",
        "PRESTASHOP_API_KEY": "YOUR_API_KEY",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

📊 Estrutura do Projeto

prestashop-mcp/
├── src/prestashop_mcp/                  # Main Package
│   ├── prestashop_mcp_server.py         # MCP Server (Extended)
│   ├── prestashop_client.py             # PrestaShop API Client (Extended)
│   ├── config.py                        # Configuration Management
│   └── cli.py                          # Command Line Interface
├── tests/                               # All Tests
│   ├── test_config.py                   # Unit Tests
│   └── test_crud_operations.py          # CRUD Integration Tests
├── venv_prestashop/                     # Virtual Environment (after setup)
├── README.md                            # Documentation
├── CHANGELOG.md                         # Version History
├── pyproject.toml                       # Package Configuration
└── requirements.txt                     # All Dependencies

📖 Documentação da API

API do PrestaShop

Documentação completa da API do PrestaShop:

PrestaShop DevDocs - Webservice

Autenticação

curl -u "API_KEY:" https://your-shop.com/api/configurations?output_format=JSON

Endpoints Importantes

Produtos: /api/products
Categorias: /api/categories
Clientes: /api/customers
Pedidos: /api/orders
Estoque: /api/stock_availables
Status do Pedido: /api/order_states
Módulos: /api/modules NOVO
Configurações: /api/configurations NOVO

🧪 Desenvolvimento

🏗️ Ambiente de Desenvolvimento

# Activate virtual environment
source venv_prestashop/bin/activate  # Linux/macOS
.\venv_prestashop\Scripts\Activate.ps1  # Windows

# All dependencies (including test dependencies) are in requirements.txt
pip install -r requirements.txt

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/prestashop_mcp --cov-report=html

# Run comprehensive integration tests
python tests/test_crud_operations.py

📖 Recursos

📄 Licença

Licença MIT — consulte LICENSE para obter detalhes.

📝 Registro de Alterações

Consulte CHANGELOG.md para obter um histórico detalhado de alterações.

🏗️ Status do Projeto e Notas de Desenvolvimento

📋 Status de Manutenção

⚠️ Manutenção Limitada: Atualmente, não pretendo manter ativamente este repositório. O PrestaShop MCP Server foi mais um teste de como um servidor MCP pode ser criado sem experiência significativa em programação e amplamente baseado em LLMs e MCPs.

🧪 Natureza Experimental

Este projeto serviu como uma Prova de Conceito para:

Desenvolvimento Assistido por LLM: Desenvolvimento de soluções complexas de integração de software com programação manual mínima
Arquitetura de Servidor MCP: Implementação prática da especificação do Model Context Protocol
Integração de E-Commerce Impulsionada por IA: Gerenciamento automatizado do PrestaShop por meio de linguagem natural
Abordagem No-Code/Low-Code: Uso máximo de ferramentas de IA para desenvolvimento profissional de software

🐳 Distribuição Docker Planejada

Recursos Futuros: Ainda está planejado fornecer todo o servidor MCP como um contêiner Docker pronto assim que todas as funções forem implementadas conforme desejado.

Benefícios da implantação com Docker:

✅ Configuração Zero: Instalação fácil sem ambiente Python complexo
✅ Ambiente Consistente: Comportamento idêntico em todas as plataformas
✅ Dependências Isoladas: Sem conflitos com instalações Python locais
✅ Pronto para Produção: Otimizado para uso produtivo
✅ Atualizações Automáticas: Atualização fácil para novas versões

Uso planejado do Docker:

# Future Docker installation (planned)
docker pull latinogino/prestashop-mcp:latest
docker run -e PRESTASHOP_SHOP_URL=https://your-shop.com \
           -e PRESTASHOP_API_KEY=your-key \
           -p 8080:8080 \
           latinogino/prestashop-mcp:latest

🎯 Gerencie sua loja PrestaShop completa, incluindo módulos, cache, temas e navegação, por meio de linguagem natural com o Claude Desktop!