Metadata-Version: 2.4
Name: iflow-mcp_latinogino_prestashop-mcp
Version: 3.0.0
Summary: Professional Model Context Protocol server for complete PrestaShop e-commerce management with extended functionality: modules, cache, themes, and navigation
Author: PrestaShop MCP Team
Project-URL: Homepage, https://github.com/latinogino/prestashop-mcp
Project-URL: Bug Reports, https://github.com/latinogino/prestashop-mcp/issues
Project-URL: Source, https://github.com/latinogino/prestashop-mcp
Project-URL: Documentation, https://github.com/latinogino/prestashop-mcp#readme
Keywords: prestashop,mcp,model-context-protocol,ecommerce,api,shop-management,business-intelligence,automation,unified-api,module-management,cache-management,theme-management,navigation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: click>=8.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typing-extensions>=4.8.0
Dynamic: license-file

# PrestaShop MCP Server

A professional Model Context Protocol (MCP) Server for complete management of PrestaShop e-commerce stores with **extended functionality**.

## 🚀 Overview

This MCP Server enables complete management of your PrestaShop store through AI applications like Claude Desktop. With specialized tools, you can manage all aspects of your e-commerce business - from products and categories to customers, orders, **modules, cache, themes, and navigation menus**.

## ✨ Features

- **🛍️ Complete Store Management** - Tools for all e-commerce areas
- **🔧 Module Management** - Install, activate, deactivate modules
- **💾 Cache Management** - Clear and monitor cache status
- **🎨 Theme Management** - Configure themes and settings
- **📋 Menu Management** - Manage main navigation (ps_mainmenu)
- **🏗️ MCP Protocol Compliance** for seamless AI integration
- **⚡ Async/Await Architecture** for maximum performance
- **🛡️ Comprehensive Error Handling** and validation
- **🔧 Production-Ready** with complete test suite
- **📖 Comprehensive Documentation** with practical examples

## 🛠️ Available Tools

### 📦 Unified Product Management
- `get_products` - **UNIFIED** Product retrieval supporting all use cases:
  - **Single Product by ID**: Complete product details including stock and category info
  - **Multiple Products**: List with optional filtering and enhancement
  - **Flexible Enhancement**: Optional stock info, category details, custom field selection
  - **Smart Filtering**: By category, name, or custom criteria
- `create_product` - Create new products with complete configuration
- `update_product` - Edit product information
- `delete_product` - Remove products
- `update_product_stock` - Manage inventory levels
- `update_product_price` - Update pricing

### 🏷️ Category Management
- `get_categories` - Retrieve categories (with hierarchy filter)
- `create_category` - Create new categories
- `update_category` - Edit categories
- `delete_category` - Remove categories

### 👥 Customer Management
- `get_customers` - Retrieve and filter customers
- `create_customer` - Create new customers
- `update_customer` - Edit customer data

### 📋 Order Management
- `get_orders` - Retrieve and filter orders
- `update_order_status` - Change order status
- `get_order_states` - Retrieve available statuses

### 🔧 Module Management **NEW**
- `get_modules` - List all PrestaShop modules
- `get_module_by_name` - Get specific module details
- `install_module` - Install new modules
- `update_module_status` - Activate/deactivate modules

### 📋 Main Menu Management **NEW**
- `get_main_menu_links` - Retrieve ps_mainmenu navigation links
- `update_main_menu_link` - Edit existing menu links
- `add_main_menu_link` - Add new navigation links

### 💾 Cache Management **NEW**
- `clear_cache` - Clear PrestaShop cache (all types)
- `get_cache_status` - Monitor cache configuration

### 🎨 Theme Management **NEW**
- `get_themes` - Get current theme information
- `update_theme_setting` - Configure theme settings

### ⚙️ Store Administration
- `test_connection` - Test API connection
- `get_shop_info` - Comprehensive store statistics

## 📋 Installation

### ⚠️ Recommended Installation (Virtual Environment)

**This approach prevents module conflicts and ensures reliable installation:**

#### Windows:
```powershell
# 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:
```bash
# 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
```

### ⚙️ Configuration

Create a `.env` file based on `.env.example`:

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

# Logging
LOG_LEVEL=INFO
```

## 🎯 Usage

### 🤖 With Claude Desktop

#### Using Virtual Environment (Recommended)

Add this configuration to `claude_desktop_config.json`:

**Windows:**
```json
{
  "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:**
```json
{
  "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"
      }
    }
  }
}
```

### 💻 CLI Usage

```bash
# 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
```

## 🆕 Extended Functionality Examples

### **Module Management**
```
"Show me all modules in my PrestaShop store"
"Activate the ps_mainmenu module"
"Deactivate the blockcart module"
"Get details for the ps_featuredproducts module"
```

### **Main Menu Management**
```
"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"
```

### **Cache Management**
```
"Clear all PrestaShop cache"
"Show me the current cache status"
"Check if CSS cache is enabled"
```

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

## 🆕 Unified Product API

The `get_products` tool handles **all product retrieval scenarios** with a single, powerful interface:

### **Use Cases:**

| Scenario | Parameters | Result |
|----------|------------|--------|
| **Single Product Details** | `product_id="15", include_stock=true, include_category_info=true` | Complete product info with stock & category |
| **Product List** | `limit=20, category_id="5"` | List of products in category 5 |
| **Enhanced List** | `limit=10, include_details=true, include_stock=true` | Full product details with stock for 10 products |
| **Filtered Search** | `name_filter="laptop", include_details=true` | All laptop products with complete information |
| **Custom Fields** | `display="id,name,price", limit=50` | Specific fields only for 50 products |

## 🛠️ Advanced Features

### **ps_mainmenu Integration**
The ps_mainmenu module management allows you to:
- Retrieve all main navigation links
- Add custom navigation items
- Update existing menu links (name, URL, status)
- Control menu link positioning

### **Cache Performance Optimization**
Cache management includes:
- Clear all cache types (CSS, JS, Template, General)
- Monitor cache status for performance optimization
- Toggle cache settings for development/production

### **Module Lifecycle Management**
Complete module control:
- List all installed modules with status
- Install new modules programmatically
- Activate/deactivate modules as needed
- Get detailed module information

### **Theme Customization**
Theme management capabilities:
- View current theme configuration
- Update theme-specific settings
- Manage logos and visual elements
- Configure theme-related PrestaShop settings

## 🔧 Troubleshooting

### ❌ Common Issues

#### "ModuleNotFoundError: No module named 'prestashop_mcp'"

**Solution:** Use virtual environment and ensure package is installed:
```bash
# 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')"
```

#### Module Management Issues

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

#### Cache Clear Not Working

**Alternative Cache Clear:**
If the API-based cache clear doesn't work, you may need to:
1. Check PrestaShop permissions for API user
2. Use manual cache clearing in PrestaShop admin
3. Verify cache directory write permissions

### 🔍 Debug Mode

Enable debug logging in Claude Desktop configuration:
```json
{
  "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"
      }
    }
  }
}
```

## 📊 Project Structure

```
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
```

## 📖 API Documentation

### PrestaShop API

Complete PrestaShop API documentation:
- **[PrestaShop DevDocs - Webservice](https://devdocs.prestashop-project.org/8/webservice/)**

### Authentication

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

### Important Endpoints

- **Products**: `/api/products`
- **Categories**: `/api/categories`
- **Customers**: `/api/customers`
- **Orders**: `/api/orders`
- **Stock**: `/api/stock_availables`
- **Order Status**: `/api/order_states`
- **Modules**: `/api/modules` **NEW**
- **Configurations**: `/api/configurations` **NEW**

## 🧪 Development

### 🏗️ Development Environment

```bash
# 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
```

## 📖 Resources

- **[PrestaShop Official Documentation](https://devdocs.prestashop-project.org/)**
- **[Model Context Protocol Specification](https://modelcontextprotocol.io/)**
- **[Claude Desktop MCP Integration](https://docs.anthropic.com/)**
- **[GitHub Repository](https://github.com/latinogino/prestashop-mcp)**

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.

## 🏗️ Project Status & Development Notes

### 📋 **Maintenance Status**

**⚠️ Limited Maintenance**: I currently do not plan to actively maintain this repository. The PrestaShop MCP Server was rather a test of how an MCP server can be created without significant own programming experience and largely based on LLMs and MCPs.

### 🧪 **Experimental Nature**

This project served as a **Proof of Concept** for:
- **LLM-Assisted Development**: Development of complex software integration solutions with minimal manual programming
- **MCP Server Architecture**: Practical implementation of the Model Context Protocol specification
- **AI-Driven E-Commerce Integration**: Automated PrestaShop management through natural language
- **No-Code/Low-Code Approach**: Maximum use of AI tools for professional software development

### 🐳 **Planned Docker Distribution**

**Upcoming Features:**
It is still planned to provide the entire MCP server as a **ready-made Docker container** as soon as all functions are implemented as desired.

**Benefits of Docker deployment:**
- ✅ **Zero-Configuration Setup**: Easy installation without complex Python environment
- ✅ **Consistent Environment**: Identical behavior on all platforms
- ✅ **Isolated Dependencies**: No conflicts with local Python installations
- ✅ **Production-Ready**: Optimized for productive use
- ✅ **Auto-Updates**: Easy update to new versions

**Planned Docker usage:**
```bash
# 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
```

---

**🎯 Manage your complete PrestaShop store including modules, cache, themes, and navigation through natural language with Claude Desktop!**
